Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

refactor: remove engine process validation from tmux pane stream opening

0xken1554cdfb94e307
diff --git a/cli/src/lib/tmuxBackend.ts b/cli/src/lib/tmuxBackend.ts
index c5db68663..b578a1a38 100644
--- a/cli/src/lib/tmuxBackend.ts
+++ b/cli/src/lib/tmuxBackend.ts
@@ -205,17 +205,34 @@ export class TmuxBackend implements TerminalBackend<TmuxRuntimeRef> {
return legacyActionResult(ok, 'tmux notification')
}
+ /**
+ * Stream a pane's bytes. Deliberately NOT gated on identifying the engine process in it.
+ *
+ * Streaming and injection need different thresholds, and they used to share one. This path
+ * addresses the PANE — `capture-pane -t %N` out, `send-keys -t %N` in — and a tmux pane id is
+ * monotonic and never reused within a server, so the id alone is a safe address. Injection is the
+ * one that types into whatever process owns the pane, and it keeps validating: see
+ * `TerminalBackendCoordinator.validateLease` and the lease dispatch fallbacks. The reaper
+ * (`coordinator.validate`) keeps validating too.
+ *
+ * Requiring a match here made the pane unviewable in exactly the situations where seeing it is the
+ * whole point: an engine that crashed, one stopped at a first-run prompt under a process the
+ * matcher does not cover, or a pane that has fallen back to a bare shell. The agent was listed, and
+ * clicking it produced "TERMINAL FROZEN · no <engine> process under tmux pane" instead of the
+ * screen that would have explained why. A pane that is genuinely gone still fails, one line later:
+ * `TmuxControlStream.open` reads `paneMeta` first and refuses a missing pane and a multi-pane
+ * window. Dropping the check also takes a whole-process-table `ps` scan off every terminal open.
+ *
+ * `expected` stays in the signature because `TerminalBackend` defines it and Herdr may still want
+ * it; it is intentionally unused here.
+ */
async openStream(
runtime: TmuxRuntimeRef,
expected: TerminalProcessExpectation,
size: TerminalStreamSize,
sink: TerminalStreamSink,
): Promise<TerminalReadResult<TerminalStreamHandle<TmuxRuntimeRef>>> {
- const validation = await this.validate(runtime, expected)
- if (validation.state !== 'alive') return {
- state: 'failed',
- reason: validation.state === 'gone' ? validation.reason : 'tmux runtime validation failed',
- }
+ void expected
return TmuxControlStream.open(runtime.paneId, size, sink)
}
}
diff --git a/docs/plans/2026-08-28-002-pane-is-the-agent-plan.md b/docs/plans/2026-08-28-002-pane-is-the-agent-plan.md
new file mode 100644
index 000000000..69699ff9f
--- /dev/null
+++ b/docs/plans/2026-08-28-002-pane-is-the-agent-plan.md
@@ -0,0 +1,126 @@
+# Pane is the agent: stop gating creation and terminal on process discovery
+
+Status: proposed · 2026-08-28
+
+## Context
+
+Creating an agent from the desktop app fails, and a listed agent sometimes cannot render its
+terminal. Both symptoms have one cause: **two separate code paths gate on the same thing — being
+able to identify the engine PROCESS inside the pane** — while the product model is that the unit is
+the pane. If an agent is in the list, clicking it must show its terminal, whatever state the engine
+is in.
+
+Measured on 2026-08-28 (all numbers from this machine, `resolvePaneEngineProcess` used as the
+oracle):
+
+| fact | value |
+|---|---|
+| `zsh -lic` startup before `exec` of the engine | ~0.9s |
+| engine first identifiable — grok / codex / claude | 1.38s / 1.41s / 1.52s (another run: ~1.19–1.22s) |
+| old discovery budget in `onCreateAgent` | 150+400+800 = **1.35s** |
+| claude identifiable while its trust dialog is on screen | **yes, at 1.10s** |
+
+So the engine lands within ±200ms of the old deadline: the failure is a flaky race, not a broken
+engine. A create that "failed" leaves a working pane that the 5s reconcile registers moments later —
+observed live (agent `d372 · tmp`).
+
+Two findings shape this plan:
+
+1. **A blocking first-run prompt does not hide the engine.** Discovery matches on `ps` argv, not on
+ screen content, and `registry.openProcessAgent` needs no `sessionId`/transcript. Claude sitting at
+ "Do you trust this folder?" is fully discoverable. Codex sitting at its update prompt was NOT —
+ there the pane held a `node` process that is not codex's entrypoint (`engineProcessMatchScore`
+ covers every real codex install layout; only a non-entrypoint child misses).
+2. **Opening a terminal requires the same match.** `TmuxBackend.openStream` calls `validate()` first,
+ which is `resolvePaneEngineProcess(pane, engine)` plus an exact pid/startMarker comparison. A pane
+ that is alive but whose engine is unmatchable (crashed, replaced, unusual install) renders
+ "TERMINAL FROZEN" instead of its contents — the user cannot see or fix what happened.
+
+Intended outcome: an agent that exists in the list always renders its pane, and creating an agent
+succeeds as soon as the pane is running the engine, regardless of how long discovery takes.
+
+## Design principle
+
+Streaming and injection deserve different thresholds, and today they share one.
+
+- **Streaming + raw keys** address the **pane** (`tmux send-keys -t %N`, `capture-pane -t %N`). Pane
+ ids are monotonic and never reused within a server, so the pane id alone is a safe address. If the
+ pane is gone, `TmuxControlStream.open` already fails on `paneMeta()`.
+- **Lease-based injection** (`submitText`/`typeLiteral`, the composer's `message` path) types into
+ whatever process owns the pane. That one must keep validating.
+
+## Change 1 — a listed agent always renders its terminal (core)
+
+`cli/src/lib/tmuxBackend.ts` — `openStream` (line ~208):
+
+Drop the hard `validate()` gate. Open the stream on pane existence alone; `TmuxControlStream.open`
+already rejects a missing pane and a multi-pane window. Keep the identity check as non-fatal
+information if we want it in a log line, never as a refusal.
+
+Do **not** touch the other `validate()` call sites — they are unaffected by this change and must stay
+strict:
+
+- `cli/src/cli.ts:960` (via `terminalBackendCoordinator.validate`) — reaper liveness
+- `cli/src/lib/terminalBackendCoordinator.ts:165` — `validateLease`
+- `cli/src/lib/terminalBackendCoordinator.ts:238,274` — lease dispatch fallback
+
+Leave `terminalBackendCoordinator.openStream`'s `if (!session.active)` guard (line 193) as is: a
+dormant agent is filtered out of `registry.active()` and therefore is not in the list, so it is
+outside this change's premise. Revisit only if a pane is observed freezing on dormancy while open.
+
+## Change 2 — creation stops losing the startup race (already written, uncommitted)
+
+`cli/src/cli.ts` — `backend.onCreateAgent`. Already implemented and tested in the working tree:
+
+- discovery budget 1.35s → **8s**, probes at 150 → 450 → 1050 → 1800 → 2550 … (`delayMs` doubling,
+ capped at 750ms). The app's own RPC timeout is 20s, so this stays well inside it.
+- **early exit** when the pane is dead — a failed engine reports in ~160ms rather than waiting out
+ the budget.
+- the failure `detail` (shipped earlier) keeps naming which of the four states the pane was in.
+
+## Change 3 — pane-based registration (larger, do only if Change 1+2 leave a real gap)
+
+Only needed for an engine that never becomes matchable at all. Requires two edits, not one, and the
+second is the risky half:
+
+1. `cli/src/lib/registry.ts` — a creator that accepts `processIdentity: null`. `openProcessAgent`
+ hard-rejects it today (`if (!runtimes.length || !validProcessIdentity(processIdentity)) return null`),
+ but the surrounding model already supports it: the field is `ProcessIdentity | null`,
+ `strictPersistedRow` accepts an explicit `null` so the row survives restart, `index()` simply skips
+ `processIndex`, and `openProcessAgent`'s `routeAgent` lookup deliberately tolerates
+ `!agent?.processIdentity` so discovery can **backfill** identity later. `projectFrame` /
+ `toProject` never read `processIdentity`, and `sessionId: ''` already yields a valid Agent payload.
+2. `cli/src/lib/terminalAgentReconciler.ts` (~line 167) — today an agent whose runtime is present but
+ whose process is unmatched falls to the final `else` → `onDormant` → `cli.ts` sends
+ `agent_deleted`, so a pane-registered agent would appear and then vanish within 5s. It must treat
+ "pane alive, identity not yet known" as alive.
+
+Step 2 touches the eviction logic that carries a documented history of evicting live agents. Do it as
+its own change, with its own verification, never bundled with Change 1.
+
+## Verification
+
+Change 1:
+1. `cd cli && npx tsc --noEmit && npx vitest run` (baseline is 1389 passing / 51 skipped).
+2. Manual, isolated so it cannot touch the user's own tmux server:
+ `TMUX_TMPDIR=$(mktemp -d)`, create a pane running a NON-engine command (`sleep 600`), register
+ nothing, and call `TmuxBackend.openStream` on it — it must now succeed and stream, where it
+ previously failed with `no <engine> process under tmux pane`.
+3. Regression: with a real engine in the pane, the stream still opens and a keyframe arrives.
+4. Confirm injection still refuses a mismatched process: `validateLease` behaviour unchanged.
+
+Change 2 (already verified, re-run after any edit):
+- Poll `resolvePaneEngineProcess` on the new schedule for claude/codex/grok — each must be found
+ (measured 1214 / 1215 / 1189 ms), and a pane whose command exits immediately must break out in
+ ~160ms rather than 8s.
+
+End-to-end, on the machine that reproduces it:
+- New agent → Claude → a folder that has never been trusted. The dialog must close without an error,
+ the agent must appear, and clicking it must render the pane showing the trust prompt. Answer it in
+ the terminal. Note that some Claude builds default to `❯ No, exit` — read the screen before typing.
+
+## Non-goals
+
+Auto-answering or pre-empting an engine's first-run prompt (trust folder, update, login). The agent is
+created, its terminal is shown, and the user acts. Choosing for them is not recoverable: a stray Enter
+on a build that defaults to "No, exit" kills the engine.