fix + feat: surface activation failures; builder terminal lifecycle improvements

[amrmelsayed]

Four commits on this branch:

1. [Spec 0602] feat: emit and handle builder-spawned SSE event (1c6285e)

Tower broadcasts a builder-spawned notification from handleTerminalCreate after a new builder terminal is registered, carrying terminalId, roleId, and workspacePath. The VS Code extension subscribes via the existing SSE wiring, filters by active workspace, dedups by terminalId, and dispatches based on the new codev.autoOpenBuilderTerminal setting:

• notify (default): show a toast with an Open Terminal button
• auto: open the terminal in the right editor group immediately
• off: ignore (sidebar still updates via overview-changed)

Older clients silently ignore the new event; older Tower instances never emit it. No version handshake required.

Sample

2. fix: surface architect spawn failures from workspace activation (ae427a8)

launchInstance used to swallow architect spawn errors and return success, so clients saw "workspace activated" even when the architect never started. It now returns { success: false, error, adopted } and logs at ERROR. The VS Code extension's ConnectionManager.activateWorkspace surfaces activation failures via vscode.window.showErrorMessage in addition to writing them to the output channel.

Why

Reproduced on a workspace with a legacy af-config.json: extension logged "Workspace activated" successfully, then the user got the generic "No architect terminal found" warning when opening the architect. Tower's log had the real cause — af-config.json is no longer supported. Run 'codev update' ... — thrown from buildArchitectArgs and swallowed by the outer catch.

Two layers of silent failure combined:

1. tower-instances.ts:470-473 — outer catch logged WARN but still returned success: true.
2. connection-manager.ts:147-159 — activation errors only went to the Codev output channel, which users rarely open.

Sample

3. [Spec 0602] fix: dispose stale builder terminal on re-spawn (6566d82)

When a builder is re-spawned (same roleId, new Tower terminalId), TerminalManager.openBuilder previously focused the cached terminal — which still pointed at the dead Tower session. The user saw a disconnected terminal even though Tower had a live session at the new id.

Now openBuilder compares the cached terminal's id against the incoming terminalId; on mismatch it closes the PTY, disposes the VS Code terminal, and opens a fresh one against the new session. Same-id case still just focuses (no flicker for benign repeats).

4. [Spec 0602] feat: clickable builder names in terminal output (0af4b9e)

Adds a TerminalLinkProvider that matches Codev builder role names (builder-spir-153, builder-bugfix-42, etc.) in any terminal and opens the corresponding builder terminal on click.

Resolves the role to a live terminalId via TowerClient.getWorkspaceState and delegates to TerminalManager.openBuilder (which handles stale terminals correctly thanks to commit 3). Works in the architect's own terminal — when Claude prints a list of builders, each name becomes a one-click target.

Sample

Test plan

• pnpm --filter @cluesmith/codev test -- tower-instances tower-routes — 2473 passed, 13 skipped, 0 failed.
• Manual: built extension, reopened a workspace with legacy af-config.json. Toast appears: Codev: Workspace activation failed: Failed to create architect terminal: af-config.json is no longer supported. Run 'codev update' to migrate to .codev/config.json.
• Sanity: reopen a healthy workspace and confirm no toast appears and the architect opens normally.
• Builder auto-open: spawn a builder via afx spawn, confirm the three modes (notify/auto/off) behave as described.
• Clickable builder names: in any terminal, type or paste builder-spir-153 (or any active builder role); confirm the name is underlined and Cmd-click opens that builder's terminal.

[waleedkadous]

Thanks for this — the activation-failure surfacing alone is a real UX win, and the builder-spawned / click-to-open / stale-terminal improvements together make the extension feel much more coherent. Three reviewers (Codex, Claude, Gemini) did full integration passes.

Two things I'd like to see addressed before merge:

1. SSE rate-limiter can drop builder-spawned events. sse-client.ts coalesces dispatches behind pendingRefresh — if another SSE event is already pending when a builder-spawned arrives, the toast and auto-open path is skipped (the sidebar still updates via the coalesced overview-changed, but the new UX is lost). Codex and Claude both flagged this. Suggestion: dispatch payload-carrying events out-of-band from the refresh coalescer, or exempt builder-spawned from drop-on-pending. This is the first SSE event with a unique payload that can't just be replayed via overview-changed, so worth addressing now rather than later.

2. TerminalLinkProvider — confirm TowerClient.getWorkspaceState() is not called inside provideTerminalLinks. That hook runs on every terminal paint; calling Tower there would spam state requests. Safer: underline all role-name matches blindly during render and only resolve the live terminalId in handleTerminalLink (click handler). Worth a quick grep to confirm the current placement. (Gemini.)

Non-blocking follow-ups:

3. Terminal race in openBuilder — onDidCloseTerminal for a disposed stale terminal can fire after the replacement is registered under the same key, dropping it. One-line guard: if (t === terminal && this.terminals.get(mapKey)?.terminal === terminal). (Claude.)
4. VS Code logic untested — BuilderSpawnHandler, link-provider, stale-terminal replacement lack automated coverage. The parsing/dedup/workspace-filtering in BuilderSpawnHandler is pure enough to unit-test without the full VS Code API.
5. Normalize workspace paths in BuilderSpawnHandler — Tower passes raw workspacePath, so symlink/path-form mismatches could cause events to be silently ignored.
6. Error toast on SSE reconnect — if the workspace is persistently broken (e.g. legacy af-config.json), the activation-failure toast may re-fire each reconnect. Probably fine but worth watching. (Gemini.)

Everything else checked out: launchInstance behavior change is correct and all three callsites handle it; error chain traces end-to-end; SSE additive wire change is backward-safe.

[waleedkadous]

Approving — concerns above are pre-merge asks, not blockers on my end. Merge when you've addressed #1 and confirmed #2.