fix(cli): Cursor sessionType=worktree crashes ACP on "Using worktree" stdout banner

[heavygee]

Summary

Remote spawn of Cursor with sessionType: "worktree" (runner adds --cursor-worktree) crashes ACP within ~5s. Session never gets cursorSessionId, so later reopen fails with 422 missing cursorSessionId.

Environment

• Host: oos-linux (Linux), HAPI driver soup on :3006
• Agent: Cursor ACP
• Confirmed 2026-07-18

Repro

1. Machine-spawn Cursor with worktree session type, e.g.:

{
  "directory": "/home/heavygee/coding/hapi/driver",
  "agent": "cursor",
  "yolo": true,
  "sessionType": "worktree"
}

2. Observe session briefly running, then archived / "Session crashed" within ~5s.
3. Metadata has no cursorSessionId.

Expected

Cursor ACP initializes; worktree banner (if any) does not kill the transport; session stays live and records cursorSessionId.

Actual

1. Runner passes --cursor-worktree for Cursor worktree sessions (cli/src/runner/run.ts / buildCliArgs).
2. Cursor Agent ACP prints a human stdout line, e.g. Using worktree: /home/heavygee/.cursor/worktrees/driver/acp.
3. cli/src/agent/backends/acp/AcpStdioTransport.ts handleLine treats any non-JSON stdout as a fatal protocol error (Failed to parse JSON-RPC from ACP agent), ends stdin, kills the process.
4. Same transport already ignores non-object JSON (Gemini) but does not ignore plain-text banners.

Log receipts (oos ~/.hapi/logs/)

• 2026-07-18-14-28-08-pid-60481.log (session 0aedaaf1-dfed-4d6d-bbcc-7cd627940217)
• 2026-07-18-14-28-35-pid-61084.log (session 098ec462-ef86-4983-b4a0-62f759b0bea0)

Both:

[ACP] Failed to parse JSON-RPC line {"line":"Using worktree: /home/heavygee/.cursor/worktrees/driver/acp",...}
Error: Failed to parse JSON-RPC from ACP agent
  at handleLine (.../AcpStdioTransport.ts:234)

Suggested fix direction

Fail-soft: ignore non-JSON ACP stdout lines (log + continue) and/or specifically isolate Cursor's Using worktree: … banner. Add a regression test that feeds that line through the transport without killing the session. Preserve real protocol errors.

Workaround

Spawn sessionType: "simple" with directory set to an existing git worktree path (skip Cursor nested --worktree). Confirmed live.

Not the same as

• Fleet runner version governance: skew banner, self-upgrade, soft-fail Cursor reopen #1084 — hub/runner version skew / reopen fail-closed
• [Bug] --worktree flag hangs on Windows - Git probe miss, no SessionStart hook #292 — Windows --worktree hang (Claude), different symptom

[github-actions]

Confirmed from the code path. For Cursor sessionType: "worktree", the runner keeps the original directory and uses Cursor-native worktree mode, then buildCliArgs() passes --cursor-worktree. That reaches the Cursor ACP backend as --worktree before acp.

The likely crash point also matches: AcpStdioTransport reads ACP stdout line-by-line, parses each non-empty line as JSON, and on JSON.parse() failure records Failed to parse JSON-RPC from ACP agent, rejects pending requests, ends stdin, and kills the child process. It already ignores JSON primitives, but I did not find equivalent handling for plain-text stdout banners such as Using worktree: ....

The later reopen 422 is consistent with hub validation: archived Cursor sessions with messages require metadata.cursorSessionId; if it is missing, /api/sessions/:id/reopen returns 422 with missing: ["cursorSessionId"].

Suggested fix direction looks right: make ACP stdout fail-soft for non-JSON banner/log lines, with a focused regression test in AcpStdioTransport.test.ts that feeds Using worktree: ...\n and verifies the transport continues instead of rejecting/killing.

Relevant code:

• cli/src/runner/run.ts:338 - Cursor worktree sessions use Cursor-native worktree mode instead of HAPI-created sibling worktrees.
• cli/src/runner/run.ts:1139 - buildCliArgs() adds --cursor-worktree for Cursor worktree sessions.
• cli/src/cursor/cursorAcpRemoteLauncher.ts:80 - Cursor ACP backend receives session.cursorWorktree.
• cli/src/cursor/utils/cursorAcpBackend.ts:43 - Cursor ACP argv emits --worktree before acp.
• cli/src/agent/backends/acp/AcpStdioTransport.ts:203 - stdout is processed line-by-line.
• cli/src/agent/backends/acp/AcpStdioTransport.ts:225 - each stdout line is parsed as JSON.
• cli/src/agent/backends/acp/AcpStdioTransport.ts:228 - non-object JSON is ignored.
• cli/src/agent/backends/acp/AcpStdioTransport.ts:233 - plain-text / invalid JSON currently becomes a fatal protocol error and kills the ACP process.
• cli/src/cursor/session.ts:55 - Cursor session IDs are written into metadata as cursorSessionId once known.
• cli/src/cursor/cursorAcpRemoteLauncher.ts:154 - fresh Cursor ACP sessions call session/new; if stdout parsing kills the process before this completes, no ACP session id is recorded.
• hub/src/sync/syncEngine.ts:1379 - archived Cursor reopen rejects sessions missing cursorSessionId when messages exist.
• hub/src/web/routes/sessions.ts:221 - incomplete reopen result is returned as HTTP 422.

---

HAPI Bot

[heavygee]

Follow-up on residual hang (banner ignore alone insufficient): PR #1087 now also skips --cursor-worktree when spawn directory is already a linked git worktree (isLinkedGitWorktree). That matches the oos hang receipts (d94f259e / 5008ed0e) where cwd was effectively a linked tree and ACP never initialized.

Ready for re-dogfood after soup rematerialize of tip (post-push).