Skip to content

Windows: console flash when Pi auto-starts engram serve (startup and subagents) #536

Description

@viniraioli

📋 Pre-flight Checks

  • I have searched existing issues and this is not a duplicate
  • I understand this issue needs status:approved before a PR can be opened

📝 Bug Description

On Windows, when the Pi extension auto-starts engram serve, users can see brief terminal/console flashes during PI startup. The same flash can happen again when a subagent starts, because a child PI process re-runs the extension bootstrap path.

The issue is not the Engram server behavior itself; it is the Windows process launch behavior when the console binary is started on demand from the PI extension.

🔄 Steps to Reproduce

  1. On Windows, install and use the Engram PI extension with automatic local server startup enabled.
  2. Make sure no engram serve process is already running.
  3. Start PI.
  4. Observe a brief console/terminal flash while the extension starts Engram.
  5. Start a PI subagent that triggers the same bootstrap path.
  6. Observe the flash again.

✅ Expected Behavior

engram serve should still auto-start on demand, but without any visible console flash on Windows, both for the main PI process and for subagent processes.

❌ Actual Behavior

The server starts successfully, but Windows can briefly show a console flash during startup. This degrades startup UX and becomes more noticeable when subagents trigger the same path.

🖥️ Environment

  • Operating System: Windows
  • Engram Version: 1.17.0
  • Agent / Client: Other (PI)

📋 Relevant Logs

Observed process path during reproduction:
- PI extension checks health
- PI extension starts `engram serve` when server is not already running
- On Windows, a visible console flash can occur during this startup
- Subagent startup can retrigger the same bootstrap path in a separate PI process

💡 Additional Context

A local fix that resolved the issue in practice was:

  • use a Windows-specific hidden launcher instead of spawning engram.exe directly from the PI process
  • add a cross-process startup lock/mutex so PI and subagents do not race to start the server simultaneously

That preserves current behavior:

  • still auto-starts on demand
  • no manual server startup required
  • avoids visible startup flashes on Windows
  • prevents concurrent bootstrap races across PI/subagents

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions