11423676

docs: agent surface shipped — decisions recorded, deferrals named

a73x 2026-08-13 20:03

Commit message

docs: agent surface shipped — decisions recorded, deferrals named

Twelve tasks landed the agent surface; this records what was decided,
what was deliberately not built, and what the field will meet.

decisions.md gets the eight rulings worth keeping: rows as best-effort
locators rather than seqs; an await answered from `last_return` and never
from live tracker state (the `D`+`A` burst folds before any phase gate
runs — an await asks about a past event, live state describes now);
wrapping the dep's OSC 133 handler instead of patching it; resolution at
the run loop's 100ms tick; session death as an answer on run/await and an
error elsewhere; `--timeout` as the daemon's window plus bounded client
grace; reconnect at-most-once for the wire and never for input; and
`settled` meaning output went quiet, not that anything exited.

roadmap.md carries the same milestone as shipped-with-known-edges: the
zsh `.zshenv` gap, the bash DEBUG-trap displacement and its membership
guard's two limits, orphaned shim directories, the grace overshoot, and
`muxa`'s deliberate lack of an idle knob — each a named follow-up.

The quic.zig comment was stale twice: there are four binaries now, and
`muxa` has no `--quic-idle-ms` on purpose. The plan doc is annotated as
the historical execution record, with its known divergences from the code
listed rather than rewritten.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

Old		New
@@ -102,6 +102,16 @@ muxd stats # wire stats: deltas vs snapshot bytes, attached clients
102	make bench # typing-workload byte-ratio measurement	102	make bench # typing-workload byte-ratio measurement
103	```	103	```
104		104
		105	`muxa` is the agent-facing client — verbs `status`, `capture`, `send`,
		106	`run`, `await`, one JSON object each, against a local socket or
		107	`--quic HOST`. `muxa run "make test"` sends the command line, waits for the
		108	shell to return it, and prints the exit code with the output rows; no
		109	polling and no sleeps, because the daemon holds the wait. It attaches at
		110	0×0 so it never resizes the session a human is using, and every reply names
		111	the `mechanism` that answered — an exit code is real only under `marks`
		112	(OSC 133 shell integration, injected at spawn), absent under the `pgid` and
		113	`settle` fallbacks.
		114
105	Multiple clients may attach to one session; the grid follows the most	115	Multiple clients may attach to one session; the grid follows the most
106	recently active client — typing, attaching, or resizing claims it (latest	116	recently active client — typing, attaching, or resizing claims it (latest
107	wins). A session survives logout (this assumes systemd-logind's default	117	wins). A session survives logout (this assumes systemd-logind's default

docs/decisions.md

+client aborts the QUIC dial mid-handshake — probes must hold stdin
+open and detach with 0x1c, or rc=1 "did not answer" lies about the
+network.
+## 2026-08-13 (agent surface — native LLM integration)
+Twelve tasks, shipped the same day as M17: OSC 133 command boundaries in
+the daemon, three new frame pairs, and `muxa`, a fourth binary that speaks
+JSON to an agent's shell tool. An agent now *knows* when a command
+returned, with its exit code and its output span, locally or over QUIC —
+the thing `tmux send-keys` + `capture-pane` structurally cannot say. The
+spec is `docs/superpowers/specs/2026-08-13-agent-surface-design.md`; what
+follows is what the implementation decided, which is not always what the
+spec guessed.
+**Output spans are rows, not seqs — and rows are locators, not anchors.**
+The tracker's `seq` is a viewport delta generation: a whole command's
+output can share one, and a row loses its seq the moment it scrolls into
+history. So a mark records the absolute screen row (`historyRows() +
+cursor.y`) at mark time and output recovery is the existing
+`fetch_scrollback`, unchanged. The honesty is on the field, not in prose:
+`Engine.MarkEvent.row` says that pruning past `max_scrollback` shifts the
+origin (a command longer than the scrollback can leave `end_row <
+start_row`), that resize reflow renumbers history, and that alt-screen
+marks live in a coordinate space where `historyRows()` is 0. Point a human
+at output with it; never key durable state on it.
+**An await is answered from a persisted snapshot, never from live tracker
+state.** Real shell integration emits `D;code` and `A` in one burst, so
+both fold in a single pty read and the phase is back to `at_prompt` before
+any await ever looks. A gate on `cmd.phase == .returned` therefore loses
+deterministically — it was written that way first, and the test that
+caught it drives a real shell rather than a hand-built mark sequence.
+`last_return` is the fix and the one owner: stamped at the `D`, carrying
+the exit code, the span AND the seq that qualifies it, so the answer and
+the reason it qualifies are the same record and no later reading of live
+state can drift out from under it. It also answers correctly once the
+*next* command is already running, which is the general rule worth
+keeping: **an await asks about a past event; live state describes now.**
+**OSC 133 interception wraps the dependency's handler rather than patching
+it.** ghostty-vt already parses semantic prompts including the `err` code,
+but its stock handler drops the code and exposes no callback. `vt.Stream(H)`
+is generic over the handler, so `MuxHandler` intercepts `.semantic_prompt`
+and forwards every other action verbatim: terminal state stays identical,
+the pinned dep stays unmodified, and there is no byte-stream scanning
+anywhere. The engine's hardcoded `vt.TerminalStream` became
+`vt.Stream(MuxHandler)` and nothing else moved.
+**Awaits resolve at the run loop's 100ms tick, with no deadline folding
+into poll.** The spec expected settle/timeout/pgid deadlines to fold into
+`wait_ms` the way QUIC's `timeoutMs` does. They do not need to: nothing in
+`checkAwaits` blocks, the granularity bound is the tick the daemon already
+beats at, and an agent's cheapest verb costs a round trip anyway. The pass
+sits after every arm that can move the session on — so it sees this pump's
+marks, pgid and silence — and *before* the QUIC `drainAll`, because a
+resolved await queues a frame and `drainAll` is what puts it on the wire.
+The other order costs every remote await a whole extra poll cycle.
+**Session death is an answer on the lifecycle verbs and an error on the
+rest.** `muxa run` and `muxa await` print
+`{"reason":"session_ended","exit_code":N}` and exit 0 — a command that
+killed its own shell answered the question that was asked. `status`,
+`capture` and `send` have no answer to give, so they print the house's
+`{"error":…,"detail":…,"exit_code":…}` shape and exit 1. **Field note that
+cost a test:** `send`'s ack round-trip reliably WINS the race against a pty
+death, so `send` cannot be relied on to report a session that is dying —
+the next call is what sees it. That is a property of the ordering, not a
+flake.
+**`--timeout` is the daemon's window; the client adds bounded grace.** The
+daemon's clock starts when it reads the request, so a client that waits
+exactly `--timeout` always loses the race to the reply and reports a
+timeout the daemon never had. The grace is `min(30s, max(2s, 4 ×
+connect_ms))`: flat 2s over a unix socket, RTT-derived over QUIC from the
+one measurement the client already has (its own handshake), capped so a
+handshake that took a minute cannot buy a minute of grace. The cost is
+named because agents budget wall clock: a `--timeout N` wait can overshoot
+N by the grace window.
+**Reconnect is at-most-once for the wire and exactly-never for input.**
+One redial per process, on `ConnectionLost` and on nothing else (a
+`SendStalled` peer is still there and has already spent the flush bound
+proving it). What is re-sent is the attach and the `await_req` with the
+ORIGINAL `since_seq` — idempotent by construction, and the reason a return
+that landed inside the gap is answered instead of missed — and never
+`run`'s input. A command line lost with the connection surfaces as an
+honest timeout, not as `make deploy` running twice: **a wait may be
+repeated because asking twice changes nothing; an input may not, because it
+changes everything.** A redial that fails is recorded rather than
+swallowed, so the verb reports both halves — `connection lost; reconnect
+failed: <err>` — and a second tear after a spent redial says so in its own
+words.
+**`settled` means output went quiet, not that the process exited.** The
+settle and pgid resolutions carry `exit_code: null` and a `phase` derived
+from marks, which on a markless shell reads `at_prompt` — the tracker
+never saw a `C`, so it is telling the truth about what it knows. Only
+`mechanism == "marks"` carries a trustworthy exit code, which is why every
+reply names its mechanism. An agent that reads `exit_code` without reading
+`mechanism` is reading a guess.
+### Field limitations, shipped knowingly
+- **zsh under the `ZDOTDIR` shim never sources `~/.zshenv`.** zsh looks for
+  `.zshenv` under `$ZDOTDIR`, and the shim directory has none. The `.zshrc`
+  is handed back (the common case); a `.zshenv` shim that restores
+  `ZDOTDIR` the way ghostty's does is the roadmap fix.
+- **The bash shim's DEBUG trap displaces a user's own DEBUG trap** —
+  silently, and that is bash-preexec, atuin and iTerm2's integration. The
+  roadmap fix is coexistence via bash-preexec detection. Two limits of the
+  membership guard that keeps `PROMPT_COMMAND`'s own members from being
+  counted as commands: a typed command textually identical to a
+  `PROMPT_COMMAND` member loses its marks (degrading to pgid/settle, not to
+  a wrong answer), and a compound string member (`a; b`) can re-arm the
+  guard. Arrays — bash 5.1's default and what the shim prefers — are exact.
+- **A SIGKILLed daemon orphans its `mux-shellint-{pid}` directory.**
+  Bounded and per-pid, cleaned on every ordinary exit; a startup sweep of
+  dead-pid directories is the roadmap item. `prepare()` failing is degraded
+  and never fatal: the session runs on pgid and settle, and says so on
+  stderr, because refusing to start a daemon over an optional enhancement
+  would invert the module's premise.
+- **`muxa` has no idle-timeout flag, by design.** It takes
+  `quic.default_idle_ms` and lets `--timeout` be the only bound on a wait;
+  `muxd`, `mux` and `muxweb` keep `--quic-idle-ms`.
+### Deferred, and named so the deferral reads as a choice
+The spec's non-goals stand: **no MCP server** (a wrapper over `muxa` needs
+no protocol change, so it can be layered whenever someone wants it), **no
+read-only or capability-scoped auth** (one key is still full control, which
+is the same posture every other transport has), **no input attribution**
+(an attached human cannot tell which keystrokes were the agent's), **no
+semantic event subscriptions** beyond the `cmd_state` push, and no
+single-shot `muxa drive` (`send` + `await` + `capture` composes it). Added
+by the reviews: the `.zshenv` shim, bash-preexec coexistence, and the
+shim-directory startup sweep.
+**Paid in a separate commit, and only after the e2e pinned the spellings:**
+`parseQuicAddr`/`resolveHost` now live in `quic.zig` as one owner for the
+dial-address grammar, taking an allocator (`client.zig`'s copy hardcoded
+`std.heap.page_allocator`, so the fold is also a fix). A human typing
+`mux quic://HOST:PORT` and an agent typing `muxa --quic HOST:PORT` were
+parsing the same grammar through two copies, which is how one flag becomes
+two dialects.

docs/roadmap.md

+this file at each milestone close and whenever the queue reorders; the
+queue's order is set by the user, not by this file.
+**Now:** M1–M15 and M17 complete, plus the agent surface; published as a
+Linux tarball, tagged through `v0.0.1-5`; in
+field trial on real VMs, and the trial is now producing the queue.
+Trial feedback outranks everything below — what actually hurts in use is
+better data than any of this ranking, and the proof is that the three
+by the headless browser-boot automation ("the page never ran" was the
+milestone's defining defect), are listed there.
+## Agent surface — native LLM integration — complete
+Shipped 2026-08-13 (ac9373f..cbd7007 + close-out), twelve tasks. An agent
+driving a mux session now *knows* when a command returned, with its exit
+code and the rows its output occupies, over a unix socket or over QUIC —
+which is the signal `tmux send-keys` + `capture-pane` structurally cannot
+give and the reason this exists. What shipped: OSC 133 marks injected at
+spawn (`shellint.zig` — zsh `ZDOTDIR` shim, bash `--init-file`, fish
+`vendor_conf.d`), a mux-owned ghostty-vt stream handler that surfaces them
+as row-stamped events, a pure command state machine (`cmd.zig`), three
+frame pairs (`cmd_state`, `await_req`/`await_reply`,
+`status_req`/`status_reply`) that ride `muxd proxy` untouched, server-held
+awaits with a pgid edge and a settle floor under the marks path, and
+`muxa` — a fourth binary, five verbs, one JSON object per verb, attaching
+at 0×0 so an agent never claims the human's grid. e2e is `test/agent.sh`,
+**9 scenarios**, including a QUIC tear healed mid-await with the command
+proven to have run exactly once. The decisions worth reading before
+touching it are in decisions.md: rows are locators and not anchors, an
+await is answered from `last_return` and never from live tracker state,
+and only `mechanism == "marks"` carries a real exit code.
+**Field limitations, shipped knowingly** (each is a roadmap item, none is a
+blocker):
+- **zsh loses `~/.zshenv`** under the `ZDOTDIR` shim — the shim directory
+  has none. A ghostty-style `.zshenv` shim is the fix.
+- **The bash shim's DEBUG trap displaces the user's**, silently: that is
+  bash-preexec, atuin and iTerm2. Coexistence via bash-preexec detection is
+  the fix. Two membership-guard limits stand meanwhile: a typed command
+  textually identical to a `PROMPT_COMMAND` member loses its marks
+  (degrading to pgid/settle), and a compound string member (`a; b`) can
+  re-arm the guard — arrays, the modern default, are exact.
+- **A SIGKILLed daemon orphans its `mux-shellint-{pid}` directory**; a
+  startup sweep of dead-pid directories is owed. Injection failing is
+  always degraded and never fatal.
+- **`--timeout N` can overshoot N** by the client's grace window (2s over a
+  socket, up to 30s over a slow QUIC handshake): an agent budgeting wall
+  clock must add it.
+- **`muxa` has no idle-timeout flag**, deliberately — `--timeout` is the
+  only bound on a wait.
+**Deferred, and named** (the spec's non-goals plus what review added): an
+MCP server wrapping `muxa`; read-only or capability-scoped auth (one key =
+full control still); input attribution; semantic event subscriptions
+beyond the `cmd_state` push; `muxa drive` as single-shot sugar; the
+`.zshenv` shim; bash-preexec coexistence; the shim-directory startup
+sweep. The `parseQuicAddr`/`resolveHost` dedup that review endorsed is
+**paid**, not deferred — one owner in `quic.zig`, landed after the e2e had
+pinned the spellings.
+## M16 candidates — and still outranked by trial feedback
+What remains is what was ranked behind M13 and M14 and survived M15,

docs/superpowers/plans/2026-08-13-agent-surface.md

Old		New
@@ -10,6 +10,17 @@
10		10
11	Spec: `docs/superpowers/specs/2026-08-13-agent-surface-design.md` — read it first.	11	Spec: `docs/superpowers/specs/2026-08-13-agent-surface-design.md` — read it first.
12		12
		13	> Status (2026-08-13, all twelve tasks shipped): this file is the
		14	> historical execution record — what was planned and in what order — and it
		15	> is deliberately not updated to match what landed. Where the two disagree,
		16	> the code and `docs/decisions.md` are the truth. The divergences worth
		17	> knowing before reading below: `returned_seq` was deleted in favour of one
		18	> owner, `last_return`, which carries the watermark inside the answer;
		19	> `checkAwaits` runs before the QUIC `drainAll` at the end of the pump, not
		20	> after it; `muxa status` nests the cursor in its JSON; and the bash shim's
		21	> final shape (array-aware `PROMPT_COMMAND`, membership guard, trap
		22	> installed last) postdates the text in Task 7.
		23
13	Conventions for every task:	24	Conventions for every task:
14	- `ZIG=~/Downloads/zig-x86_64-linux-0.15.2/zig` — run from the worktree root (`.worktrees/agent-surface`).	25	- `ZIG=~/Downloads/zig-x86_64-linux-0.15.2/zig` — run from the worktree root (`.worktrees/agent-surface`).
15	- Full suite: `$ZIG build test`. It must pass before every commit.	26	- Full suite: `$ZIG build test`. It must pass before every commit.

src/quic.zig

Old		New
@@ -39,9 +39,13 @@ pub const default_port: u16 = 4433;
39	/// gone. Long enough that a quiet terminal is not a suspicious one, short	39	/// gone. Long enough that a quiet terminal is not a suspicious one, short
40	/// enough that a client which has genuinely vanished stops being served	40	/// enough that a client which has genuinely vanished stops being served
41	/// within a few seconds of keepalives failing — keepalives run at a third	41	/// within a few seconds of keepalives failing — keepalives run at a third
42	/// of it, so an idle session is never the thing that trips it. Tunable on	42	/// of it, so an idle session is never the thing that trips it.
43	/// both binaries because the reconnect tests need death declared on a	43	/// `--quic-idle-ms` tunes it on the three binaries that dial or listen for
44	/// schedule they can wait for.	44	/// a human — `muxd`, `mux`, `muxweb` — because the reconnect tests need
		45	/// death declared on a schedule they can wait for. `muxa` deliberately has
		46	/// no such flag and always takes this default: an agent's wait is bounded
		47	/// by `--timeout` already, and a second knob over the same wait is one
		48	/// more thing for a driver to get wrong.
45	///	49	///
46	/// Here for the same reason as `default_port`: two copies of a number both	50	/// Here for the same reason as `default_port`: two copies of a number both
47	/// binaries default to are two numbers, and they drift in silence.	51	/// binaries default to are two numbers, and they drift in silence.