Multi-architect conversation resume: disambiguate via per-architect session UUID

[amrmelsayed]

Context

Follow-up to #830 (architect session revival). #829 shipped builder conversation resume via on-disk jsonl discovery. That same mechanism extends cleanly to the main architect (committed on the #829 branch) because main is the only architect using Tower's automatic launchInstance path. It does not extend to named sibling architects added via afx workspace add-architect (Spec 755), because they share cwd = workspacePath with each other and with main — and the jsonl-discovery heuristic (newest *.jsonl by mtime) cannot tell which jsonl belongs to which named architect.

This issue scopes the multi-architect disambiguation work that #830 left open.

Problem

A workspace with main + named siblings (e.g., architect-2, reviewer-bob) has multiple Tower-managed Claude PTYs running in the same cwd. Each writes its session jsonl to ~/.claude/projects/<encoded-workspacePath>/. After a reboot:

• The reboot kills every architect's shellper.
• On afx workspace start, Tower's launchInstance re-spawns main. Spec 786 Phase 3 then iterates state.db.architect to re-add each persisted sibling via addArchitect().
• With Workspace recover: revive Tower-managed architects after machine reboot #830's main-only resume, main correctly picks the right jsonl. But sibling revivals would either skip the resume path entirely (current behavior in the afx workspace recover: revive builders after machine reboot/crash #829 branch's addArchitect — deliberate) or, if naively enabled, attach to whichever architect's jsonl was most recent — possibly the wrong one.

So named siblings come back as fresh sessions, losing all conversation context. Operators using multi-architect workspaces lose more on reboot than single-architect users do.

Why jsonl-discovery alone can't solve this

The jsonl filename is the Claude session UUID. The jsonl directory is encoded from cwd. There is no per-architect metadata in either the filename or the directory path. Peeking inside a jsonl to read its content for an architect-name marker is brittle (undocumented internal format, breaks on Claude version bumps).

The only robust fix is to persist a per-architect session identifier somewhere Tower controls.

Proposed approach

Add claude_session_id TEXT to the existing architect SQLite table (already created by Spec 755 for sibling persistence; Spec 786 Phase 3 extended it to main).

At spawn time (in both launchInstance for main and addArchitect for siblings):

1. Generate crypto.randomUUID().
2. Pass --session-id <uuid> to claude in cmdArgs.
3. After successful PTY creation, store the UUID in the architect row via setArchitect({ name, cmd, startedAt, terminalId, claudeSessionId }).

At revive time (launchInstance re-firing after reboot, or sibling restoration loop calling addArchitect):

1. Look up the stored UUID via the architect-by-name getter.
2. If present: pass --resume <uuid> to claude (skip role injection — the saved conversation already contains the role/system prompt).
3. If absent (legacy row): current behavior — fresh session with role injection.

Fallback chain for consistency with builders:

For architects, lookup priority becomes: stored UUID → (skip jsonl-discovery — ambiguous for shared cwd) → fresh spawn.

For builders, the chain stays: jsonl-discovery → fresh spawn. The two mechanisms coexist because the constraint differs (unique cwd for builders, shared cwd for architects). Documented in code.

Backwards compatibility

Architect rows from before this lands have no claude_session_id. On their first revival they fall back to fresh spawn (no regression vs current behavior). After that first revival their row gets a stored UUID and subsequent revivals resume cleanly.

Acceptance criteria

• After reboot of a workspace with main + N named siblings, running afx workspace start revives every architect and each lands in its own prior conversation (no cross-attachment).
• Adding a new named architect via afx workspace add-architect --name foo stores the new UUID at spawn time.
• Removing a named architect (workspace remove-architect) clears its UUID alongside the architect row.
• Legacy architect rows (no stored UUID) gracefully fall back to fresh spawn.
• Tests cover: spawn-stores-UUID, revive-reads-UUID, legacy-fallback, removal-clears-UUID, two siblings revive independently to correct conversations.

Out of scope

• Builder conversation resume — already shipped in Builder conversation resume: restore Claude session on recovery via jsonl discovery #831 via jsonl-discovery.
• Main architect conversation resume — already shipped in Workspace recover: revive Tower-managed architects after machine reboot #830 via jsonl-discovery.
• Workspace-level recovery command for architects (the existing afx workspace start flow handles re-spawn; this issue only handles the conversation-context restoration during that re-spawn).

References

• afx workspace recover: revive builders after machine reboot/crash #829 — afx workspace recover (builder process revival + conversation resume).
• Workspace recover: revive Tower-managed architects after machine reboot #830 — architect session revival follow-up (where main-only resume landed; this multi-architect work was deferred).
• Builder conversation resume: restore Claude session on recovery via jsonl discovery #831 — builder conversation resume via jsonl discovery.
• Spec 755 — multi-architect support (named siblings; persistence).
• Spec 786 Phase 3 — main + sibling architect persistence across stop+start.
• packages/codev/src/agent-farm/servers/tower-instances.ts — launchInstance (main) and addArchitect (siblings) spawn paths.
• packages/codev/src/agent-farm/utils/claude-session-discovery.ts — the jsonl-discovery helper this design intentionally bypasses for siblings.

[amrmelsayed]

Heads up @waleedkadous — PR #833 just landed a conservative guard for the collision problem described here. Context for your follow-up:

What's in place now (until your work lands):

• launchInstance in tower-instances.ts checks getArchitects().length before resuming main.
• If only one architect (or none) is persisted → resume main via jsonl-discovery normally.
• If two or more → skip the resume path; main spawns fresh with role injection, a WARN log surfaces what happened with a reference to this issue.

Effective behavior for users:

• Single-architect workspaces (probably the common case) get full conversation resume for main on reboot.
• Multi-architect workspaces lose conversation resume entirely (every architect comes up fresh on reboot) — but never silently attach main to a sibling's conversation.

The hand-off to your work: when you add per-architect session UUID storage (described in this issue body), you can drop the safeToResume = getArchitects().length <= 1 guard at tower-instances.ts (currently around line 461 on the branch). Replace it with the per-architect UUID lookup. That removes the conservative limitation and re-enables conversation resume for multi-architect workspaces.

Helpers you can reuse:

• findLatestSessionId(absolutePath) in packages/codev/src/agent-farm/utils/claude-session-discovery.ts — pure jsonl discovery. Useful if you want a fallback when the stored UUID is missing (for legacy architect rows).
• The architect table schema is in packages/codev/src/agent-farm/db/index.ts (search for CREATE TABLE.*architect).

Ping me when you start and I can walk through the existing spawn flow.