OK Desktop fresh-project launch times out after 15s with no surfaced child-process error

[kinpoe-ray]

Summary

Opening a newly initialized OpenKnowledge project in OK Desktop failed with:

Unable to open project

/Users/example/Project/agent-multica

OpenKnowledge server did not bind a port within 15000ms after spawn (pid=69953).

The spawned process had already become a zombie (<defunct>), but Desktop did not surface its exit reason or stderr. Running ok start manually once initialized the shadow repo and fixed all subsequent starts.

Environment

• OK Desktop: 0.35.0-beta.4
• Desktop bundled CLI: 0.35.0-beta.4
• Global CLI also installed: 0.29.1
• macOS arm64
• Electron 41.2.1
• Existing Git repository
• Project content scope: docs/wiki

Project state before first Desktop open

The project had just been initialized and seeded:

agent-multica/
├── .git/
├── .ok/config.yml       # content.dir = docs/wiki
└── docs/wiki/           # codebase-wiki starter pack

ok diagnose health immediately after the Desktop failure reported:

[✓] git
[✓] bun
[✓] config-yaml: parses; content.dir = docs/wiki
[✓] content-dir: writable
[✓] server-lock: no server holding the lock
[!] shadow-repo: .git/ok not yet initialized
    → Run `ok start` once to initialize the shadow repo.
[!] shadow-health: shadow repo not yet initialized

Other observations:

• PID 69953, the process named in the Desktop error, was already <defunct>.
• .ok/local/last-spawn-error.log existed but was empty.
• The Desktop log showed opening project and healthy MCP wiring, but no useful child-process exit/error record and no project window created event.
• There was no stale server lock.

Recovery

Running the global CLI manually:

ok --cwd /Users/example/Project/agent-multica start

started successfully and initialized .git/ok.

After stopping it, the Desktop-bundled CLI also started successfully:

/Applications/OpenKnowledge.app/Contents/Resources/cli/bin/ok.sh \
  --cwd /Users/example/Project/agent-multica start

A final health check then reported:

[✓] shadow-repo: .git/ok (HEAD: ref: refs/heads/main)
[✓] shadow-health
All checks passed

Opening the project in Desktop subsequently worked.

Expected behavior

A newly initialized project should open successfully in Desktop without requiring the user to run ok start manually first.

If the server child exits before binding a port, Desktop should show the real exit reason/stderr rather than only reporting the 15-second timeout.

Notes on causality

The missing shadow repo is strongly correlated with the failure and the manual initialization fixed it, but the available logs do not prove it was the only root cause. The empty last-spawn-error.log makes the underlying child-process failure impossible to determine conclusively.

Suggested improvements

1. Initialize or validate the shadow repo as an explicit preflight step before spawning the managed server.
2. Capture and surface child exit code, signal, stdout, and stderr when it exits before binding.
3. Populate last-spawn-error.log reliably.
4. Reap failed child processes instead of leaving a zombie.
5. Show the current startup stage in the UI, such as:
   • validating configuration
   • initializing shadow repo
   • starting collaboration server
   • waiting for port
6. Provide Retry and Run diagnostics actions in the error dialog.
7. Consider a longer/adaptive timeout for the first cold start while keeping later starts fast.