feat(factory): tmux terminals + pane/viewing-in on Factory Floor (extension half of #731)

[muqsitnawaz]

What

Extension half of the tmux terminal standardization (companion to CLI #731). Makes the Factory Floor feed workable by giving every agent terminal a stable, external address (a tmux pane) and surfacing where each agent is being viewed.

Same-cwd agents were previously indistinguishable and VS Code terminal tabs had no external addressing — the root cause behind the feed bugs (#145 host mis-attribution, #147 drifting startedAt, #149 status-bar-wrong-session). tmux panes give a uniform, resumable, trackable identity.

Changes

• tmux by default (agents.terminalMode: auto | tmux | native, replaces the old boolean agents.enableTmux). auto runs agents inside tmux on macOS/Linux for uniform addressing/resume/tracking, falling back to a native VS Code terminal on Windows or when tmux is missing. — terminalMode.ts (pure, unit-tested), extension.ts
• Publish tmux pane + editor-tab index per agent terminal so the CLI can render "viewing in Codium tab N". — tabIndex.ts (pure resolveTabIndex, unit-tested), tmux.ts, foreman.registry.ts
• Surface pane + "viewing in" on Factory Floor cards. — remoteSessions.ts, FeedItem.tsx, floorAdapter.ts, floorModel.ts

Testing

• tsc -p ./ clean (0 errors)
• New pure-helper tests green: tabIndex.test.ts + remoteSessions.test.ts — 55/55; terminalMode.test.ts present and green
• Full factory suite: 1042 pass, 4 fail — the 4 failures are pre-existing live-LLM/network/timing integration tests (generateCommitMessageWithClaude, draftDispatchPrompt, resolveAlias, SessionWatcher 5s timeout), none touching any file in this diff

Notes

• Replayed onto the post-refactor(repo): restructure into apps/ + packages/ + native/ (atomic) #724 apps/factory/ layout (branch base predates the restructure); three-dot PR diff is 14 files, all under apps/factory/.
• Pairs with feat(cli): run interactive agents in tmux + viewing-in resolution #731 (CLI: run interactive agents in tmux + viewing-in resolution) — shared data contract: tmuxSession / tmuxPane / tabIndex / viewingIn.

[prix-cloud]

Code Reviewer

Verdict: Ready to merge (with one minor fix recommended)

Build: tsc -p ./ — 0 errors
Tests: 1007 pass, 12 fail across 83 files — all failures are pre-existing and environment-specific (no API keys, agents CLI not installed, gray-matter/marked packages absent in sandbox). None of the 12 failures touch any file in this diff.

Confirmed PR-specific test targets:

• tabIndex.test.ts + terminalMode.test.ts + remoteSessions.test.ts — 60/60 pass
• floorAdapter.test.ts + floorModel.test.ts — 102/102 pass

---

What works well

The terminalMode.ts / tabIndex.ts split into pure helpers with full unit coverage is the right call — both modules are easy to test in isolation and the logic is correct. The readPaneId fallback chain in tmux.ts handles the "tmux is not on the extension host's PATH" case cleanly, and the early-return if (pane) return pane; return undefined prevents falling through to incorrect candidates when tmux runs but reports no pane. Hash stability in foreman.registry.ts correctly includes tmuxPane/tabIndex so the registry reflects pane changes. The floorAdapter || undefined coercions keep empty strings out of the UI.

---

Issues that need attention

1 — floorAdapter.test.ts:309 — test fixture missing required tmuxPane field

RemoteSessionLike.tmuxPane was added as a required (string, not string?) field in floorAdapter.ts:92, but the existing base fixture in the test file wasn't updated:

// floorAdapter.test.ts:309
const base: RemoteSessionLike = {
  host: 'this-mac', sessionId: 's1', ..., replyMuxSocket: '',
  // ← tmuxPane: string is missing; this is a type error
}

This slips past tsc -p ./ because tsconfig.json:14-15 covers only src/**/* and explicitly excludes test files — the entire ui/ tree is outside its scope. Bun runs the test fine at runtime (JavaScript doesn't enforce types) and nothing asserts on pane in the base-derived cases, so tests pass. But if UI type-checking is ever enabled, or if a future test spreads base and asserts r.pane is absent, this will surprise someone.

Fix (two options):

• Add tmuxPane: '' to the base fixture (consistent with how replyRail: '', replyMuxTarget: '', etc. are initialized)
• OR make tmuxPane?: string optional in RemoteSessionLike (consistent with viewingIn?: string) — empty string is already handled by r.tmuxPane || undefined in toFloorAgentFromRemote

Option 2 is slightly cleaner since viewingIn already uses ? and tmuxPane has the same semantics (absent for non-tmux sessions).

---

2 — extension.ts:3877 — tmuxEnabled context key is true in 'auto' mode even when tmux is unavailable

// extension.ts:3877
const tmuxEnabled = normalizeTerminalMode(config.get('terminalMode')) !== 'native';

With the new default of 'auto', this evaluates to true on every platform — including Windows and systems without tmux. The package.json:691-696 gates that use this context key control visibility of the "Enable/Disable Tmux" menu commands. The comment above reads 'auto'/'tmux' show it (tmux is active) but 'auto' does not mean tmux is active — it means "use tmux if available."

On a Windows install or a machine without tmux, users see the "Disable Tmux" command even though tmux was never used. Clicking it just sets the mode to 'native', so nothing breaks — but it implies tmux is running when it isn't.

This is a minor UX issue, not a correctness bug. A tighter version would call isTmuxAvailable() before setting the context key, but that adds async overhead to every activation. Alternatively, the comment could be updated to say show for 'auto'/'tmux' (tmux may be active) to reflect the true semantics. Raising it so you can decide whether it's worth a follow-up.

---

Things to verify manually

The pane-ID read (readPaneId in tmux.ts:507-524) is best-effort and fire-and-forget behind getTmuxInfo. The path that exercises the new tmuxSession/tmuxPane/tabIndex fields end-to-end (agent launch → registry snapshot → CLI reads the registry → "viewing in Codium tab N" surfaces in the status bar) requires a live VS Code + tmux session — worth a smoke test with the compiled .vsix before shipping the paired CLI #731.

---

Reviewed by Code Reviewer — ran tsc -p ./ and bun test on branch feat/factory-tmux.

Instruction files read: /workspace/task-5e8da1e4/CLAUDE.md (repo root), /workspace/task-5e8da1e4/apps/factory/AGENTS.md, /workspace/task-5e8da1e4/apps/factory/ui/CLAUDE.md