Test persistent tmux pane workers for `<Terminal.Grid>`

[taras]

Story

As a maintainer preparing <Terminal.Grid>, I want an executable proof that an
XMD-controlled worker can live inside each tmux pane, so #717 can adopt a process
topology that supports reliable readiness, pane output, sequential native
launches, and complete teardown without guessing about terminal behavior.

The proof runs one 2-by-2 workspace. Each pane starts with a persistent worker
that owns the terminal tmux created for it. The parent XMD process can display
text in a pane, ask its worker to start an interactive child, learn whether that
child actually started, wait for its exit, display more text, and then start
another child in the same pane. The fourth worker starts an ordinary interactive
shell through the same boundary.

This is a prerequisite evaluation for #717, not the terminal-grid feature
itself. Its result decides whether the pane-worker topology enters the
implementation plan or the architecture returns to provider research.

Current gap

Tmux can create the required per-pane pseudo-terminals, but a tmux pane process
ID does not establish that the requested executable started. Tmux completes its
spawn command after forkpty; the child attempts exec afterwards. On tmux
3.6a, /definitely/missing x and a real /bin/sh -c "exit 1" both leave a dead
pane with status 1 and a pane PID. A %begin/%end response plus #{pane_pid}
therefore cannot implement #717's readiness boundary.

Starting the native process directly as the tmux pane command also leaves no
persistent endpoint for document text rendered before or after that process, or
for a later sequential launch in the same pane. send-keys and tmux buffers
inject process input; they are not a pane display sink.

The ordinary @effectionx/process operation is not the missing primitive. It
pipes stdout and stderr through process middleware and starts a detached process
group. A native UI must inherit the pane worker's terminal without capture. The
current native launcher already models that distinction, but it does not expose
a separate successful-spawn acknowledgement.

Evaluation contract

Tmux starts one persistent worker as the initial process in each pane. The worker
inherits that pane's controlling terminal and remains alive for the pane's
lifetime. The parent communicates with it through invocation-private IPC rather
than passing arbitrary native command vectors through tmux's textual command
parser.

The worker starts an interactive child through an Effection-owned process
resource derived from the existing native-launch semantics. Its host adapter may
use the same asynchronous child-process API as the current native launcher; the
proof does not put a direct Deno.Command.spawn() call or ordinary
@effectionx/process execution on the product boundary. The resource:

1. inherits the worker's terminal for stdin, stdout, and stderr;
2. distinguishes the child-process spawn event from its error event;
3. acknowledges readiness only after successful spawn;
4. reports exact exit code or signal independently of readiness; and
5. owns cancellation, escalation, reaping, and finalization through its
   Effection scope.

The IPC transports a structured command vector, cwd, filtered environment, pane
display bytes, cancellation, readiness, and settlement. It is private to one
invocation, admits only the worker assigned to that pane, and is removed on
success, failure, and cancellation. Raw instruction text never enters argv or
environment. Provider socket paths, tmux identifiers, process identifiers, and
IPC credentials stay in temporary diagnostic evidence and do not become public
or durable values.

The proof constructs the authored column geometry explicitly. Tmux's
select-layout tiled may choose its column count from terminal dimensions and
does not by itself implement the columns prop.

Reader-visible sequence

The successful proof performs this sequence:

1. Create a hidden invocation-private tmux server and a 2-by-2 layout.
2. Start one worker in every pane and establish each private IPC channel.
3. Send visible prelude text to at least one paired pane.
4. Start interactive test children in all paired panes and the default shell in
   the shell pane.
5. Wait until every worker reports successful child spawn, then attach the
   complete grid once.
6. Interact with at least two children concurrently.
7. Let one child exit while its siblings remain interactive, display its status,
   render epilogue text in that pane, and start a second child there.
8. Close the grid, cancel the remaining children, await worker and provider
   teardown, restore the original terminal, and only then finish the proof.

No real Agent CLI or model turn is required. A deterministic interactive child
stands in for a native Agent UI and verifies terminal ownership, input, output,
readiness, settlement, and cancellation.

Acceptance

• Every worker and interactive child reports that stdin, stdout, and stderr are
  terminals associated with the expected pane. The shell demonstrates ordinary
  interactive job control rather than merely printing through a PTY.
• A missing executable produces a startup failure and never acknowledges pane
  readiness. A real executable that starts and immediately exits 1 acknowledges
  readiness and then reports exit 1. The evidence distinguishes those paths.
• Command arguments containing spaces, quotes, newlines, semicolons, dollar
  signs, and backticks arrive byte-for-byte unchanged. They travel through
  structured IPC rather than tmux command-string interpolation.
• The parent renders pane text before and after an interactive child without
  injecting that text as the child's input. Native child terminal bytes are not
  copied back through the parent.
• One pane runs two interactive children sequentially without replacing its tmux
  pane or worker. Attempting two simultaneously on that pane refuses, while
  children in distinct panes remain concurrent.
• A 2-by-2 layout and a five-pane layout with columns={2} preserve authored
  row-major placement at materially different terminal dimensions. The proof
  does not rely on select-layout tiled choosing the desired column count.
• The visible attach begins only after every pane's interactive child has
  acknowledged successful spawn. A startup failure in any pane exposes no
  partial grid and tears down every worker and child already started.
• Detaching the visible client is distinguishable from losing the control or IPC
  connection and from the tmux server stopping. None of those signals alone is
  treated as proof that pane work ended.
• Reader close and parent cancellation each stop accepting launches, cancel the
  active child in every pane, await each worker's quiescence acknowledgement,
  stop the tmux server and its attach/control clients, remove the private IPC and
  socket paths, and restore the original terminal before the probe reports
  completion.
• A negative child ignores the first interruption and forks a descendant in its
  inherited process group. Teardown escalates and establishes that neither can
  continue. A second negative child escapes that group; the result records
  whether the architecture can prove it stopped rather than silently treating
  initial-process or process-group disappearance as complete teardown.
• Startup, all-pane readiness, attach, reader-close detection, and teardown are
  measured for 2, 4, and 8 panes over at least 20 runs on the same host. The
  report gives medians and ranges rather than inventing a pass threshold before
  measurement.
• Cancellation is exercised at provider preparation, worker readiness, visible
  attachment, and active-child execution. Every acquired resource has one named
  Effection scope and finalizer in the evidence report.

Evidence and decision

The proof provides one documented command that runs from a prepared checkout,
plus a report containing:

• the exact commit, operating system, architecture, tmux version, Deno version,
  and command used;
• the observed terminal session and process-group relationships;
• successful and negative-path results for every acceptance item;
• startup and teardown measurements;
• a resource-ownership diagram; and
• the smallest provider and interactive-process interfaces the evidence
  supports.

The result changes #717 planning as follows:

• If readiness, display, sequential reuse, job control, and teardown all hold,
  the Planner uses the persistent pane-worker topology and its measured lifecycle
  boundary.
• If the terminal and IPC behavior holds but complete teardown cannot be proven,
  Quest: Add interactive terminal grids to executable documents #717 remains blocked while the Architect narrows or replaces the lifecycle
  contract. The implementation does not weaken it silently.
• If a worker cannot host the native child with correct controlling-terminal or
  job-control behavior, the topology is rejected and Quest: Add interactive terminal grids to executable documents #717 returns to provider
  research.

The proof may live on a dedicated branch and does not need to ship in the product
binary. This issue closes when the exact evidence commit and report are linked
and the resulting architecture decision is recorded.

Out of scope

• Shipping <Terminal.Grid> or <Terminal> syntax.
• Durable grid identity, completed replay, or partial replay.
• Real Agent-session preparation, ownership, attachment, or provider proofs.
• Production status styling, key bindings, diagnostic wording, or terminal
  compatibility beyond what discriminates the topology.
• Adding a native PTY dependency or a separate compiled helper binary.
• Treating tmux-specific identifiers as public component, provider, durable, or
  diagnostic data.

[taras]

Evidence commit b0fcee9 on spike/tmux-pane-workers (PR #727); report at plans/tmux-pane-workers-proof.md with the run's evidence beside it (824538a). Host: macOS arm64 (darwin 25.5.0), tmux 3.6a, Deno 2.9.5. Command: deno task proof:tmux-pane-workers.

Result: 8/8 checks, 115 claims. Readiness (spawn event, never pane_pid), pane display before/after a child without becoming its input, argv byte-for-byte over private IPC, sequential reuse of one pane with a concurrent second launch refused, real job control in the shell pane (ps -o tpgid), explicit row-major layout at 80×24 and 200×60 without tiled, attach only after every pane is ready with startup failure tearing everything down, the three close signals kept distinct, cancellation at five phases, and 2/4/8-pane timings over 20 runs (8 panes: ~1.1 s to all-ready, ~0.1 s attach, ~45 ms close detection, ~3.9 s teardown, dominated by lsof).

Recommended decision for #717: adopt the persistent pane-worker topology, with the teardown claim narrowed. Teardown proves that nothing remains in any pane's process group, nothing is a descendant of a child alive when teardown began, and nothing holds a pane terminal. The one honest negative: a descendant that setsid()s away, closes the pane terminal and outlives its parent is invisible to every fact a parent can observe on this platform; the report records it rather than claiming otherwise. The report also names the tmux facts the Planner should not rediscover (leaf ids ignored in layout strings, pane_dead_status 1 vs 127, attach exit codes not classifying a close, -f no-output, the 104-byte socket path limit, pty revoke on pane death) and two obligations for the worker/host: start with Effection run() rather than main() (which binds SIGINT to exit 130), and treat SIGHUP as cancellation.

The Architect records the decision; the proof and report are ready for review.

[taras]

Architect review of PR #727: REQUEST CHANGES at head 824538a8c393478714ad08c55bcc44250fc525bd, reviewed against base a7f60c024a3566e259226d99c4bb26b71a0c5048 and evidence commit b0fcee9ff1221b947b0a8bac431caf905519972e.

The persistent pane-worker topology is accepted for #717, including spawn-event readiness, private byte-exact IPC, inherited terminal ownership and job control, explicit layout plus swap-pane, independent visible/control clients, atomic attach, and the bounded teardown claim. The architecture now states the honest macOS limit: a descendant that has started a new session, closed the pane terminal, and lost its parent is outside the observable parent boundary.

One structural consequence is not yet proved. In worker.ts, natural child exit calls child.stop(), clears active, and reports exited; that sweep covers ancestry and process-group members. sweepTerminalHolders() runs only in the later shutdown branch. The negative check itself demonstrates the consequence: orphan-escape outlives its parent after exited while still holding the pane terminal, and is found only during worker shutdown. A subsequent launch can therefore be admitted while a process from the prior launch still holds and can write that same terminal. That violates the one-owner pane lease and the report's claim that exited makes the pane free after its sweep.

The smallest correction is to perform the worker-owned terminal-holder sweep after each launch settles and before active is cleared or exited is sent, then add the crossed negative path: the parent exits, a setsid() descendant retains the terminal, and a second launch is not admitted until that holder is gone. Keep the detached-and-terminal-closed case as the recorded unprovable boundary.

#726 remains open for that exact evidence. This does not reopen the topology decision; it closes the pane-reuse proof needed by #717.

[taras]

Follow-up on review: the worker now sweeps the pane terminal at every child settlement — natural exit, cancel and shutdown — after the escalation and before active clears or exited is sent; exited carries the settlement proof (terminalHolders beside descendants).

Evidence commit: 650510b5 on spike/tmux-pane-workers (PR #727); report and redacted evidence updated at 80770ea. Full run: deno task proof:tmux-pane-workers → 9/9 checks, 127 claims.

Focused regression: deno task proof:tmux-pane-workers --only sequential-handoff

• first child forks a descendant that setsid()s, keeps the pane pty open, and outlives its parent (parent told exit 0);
• a launch sent immediately after → refused busy, observed before exited (order: ready, refused, exited);
• exited arrives with the descendant absent from the ancestry snapshot (descendants: []) and named in terminalHolders: [{pid, gone: true}]; it is unreachable;
• the next launch is admitted, and lsof on that pty then names only the worker and the new child;
• handoff (exit requested → exited) 443 ms; relaunch (launch → ready) 1 ms.
  Removing the settlement sweep fails exactly those claims (checked).

The setsid() + closed-terminal orphan remains the recorded unprovable boundary (negative-children): invisible to ancestry, group and terminal-holder sweeps; killed afterwards by the check from the child's own record.

Measurements now include the sweep's cost, medians over 20 runs: handoff 616 / 814 / 1500 ms at 2 / 4 / 8 panes (dominated by lsof -t, ~0.4 s and growing with process count), relaunch ~2 ms, teardown 1.2 / 2.0 / 4.4 s.

[taras]

Architect re-review: PASS at PR #727 head/report 80770ea3e20748109b05583d5292d6160cccc398, evidence commit 650510b553111c9a46a8205f09fbe0ff2c797a9f, against base a7f60c024a356d6bd75d3bba4a693019693f6466.

The requested structural correction holds. Settlement is single-flight across natural exit, cancel, and shutdown; escalation precedes the terminal-holder sweep; active clears only after that sweep; and exited is sent afterwards with the complete proof. The crossed sequential-handoff regression proves an early launch is refused, the escaped terminal holder is named and stopped outside ancestry before exited, and the admitted next child shares the existing pane only with its worker. The closed-terminal detached orphan remains the explicit bounded-observability case.

Reviewed evidence: the committed full run records 9/9 checks and 127 claims. Focused verification run: deno task proof:tmux-pane-workers --inner --only sequential-handoff → 1/1 check passed in 3.12 s. The ordinary outer wrapper could not create its private Unix socket inside the review sandbox; the identical inner check passed when granted the required temporary-socket access, so this was an environment restriction rather than an intermittent proof failure.

The persistent pane-worker topology and narrowed teardown claim are accepted for #717. #726's evidence-and-decision closure condition is satisfied.