listTmuxWindows mixes stderr into the window list and cannot see a non-zero exit #178

Closed
opened 2026-09-18 07:49:16 +02:00 by lz · 0 comments
Owner

Found while auditing the fleet-status spec, and verified by reading nexus/src/lib/server/sessions/service.ts.

Two defects in one helper

listTmuxWindows (service.ts:1356) runs tmux list-windows -t nexus -F '#W' with AttachStderr: true, collects the stream, and hands it to stripFraming. It never calls exec.inspect().

stripFraming (service.ts:1377) tests only the first frame's stream byte:

if (buf.length >= 8 && (buf[0] === 0 || buf[0] === 1 || buf[0] === 2) && buf[1] === 0 …) {
  while (i + 8 <= buf.length) {
    const size = buf.readUInt32BE(i + 4);
    out.push(buf.subarray(i + 8, i + 8 + size));   // every frame, whatever its stream id
    i += 8 + size;
  }

So:

  1. stderr is concatenated into the window-name set. Every stderr frame's payload is appended alongside stdout, split on newlines, and returned as window names.
  2. A failed listing is indistinguishable from a successful one. With no inspect(), a non-zero exit is invisible. tmux list-windows against a dead server writes no server running on … to stderr and exits 1 — which arrives as a non-empty set containing that sentence.

Why it matters

convergeSessions consumes this set to decide whether a session's tmux window is missing, and a missing window with a surviving worktree triggers a relaunch. Today a failed listing therefore reads as "every window is missing" rather than as "we could not look" — the opposite of the rule fact #15 states for the sibling worktree listing, where uncertainty never triggers deletion.

It gets worse under the fleet status layer, where this listing becomes an input to a store that other subsystems read as truth. Fix it before then — seeding a new source of truth from a read that cannot report failure is the worst possible order.

Fix

Route it through execAndCapture, which already separates the streams and inspects the exit code. Zero test churn is expected: makeConvergeDocker's fake already exposes exactly the two methods execAndCapture drives.

Two guard tests, each of which must be shown to fail against the current implementation before the fix lands:

  • stderr content on the stream must not appear as a window name
  • a non-zero exit must not read as an empty window list

Scope note

stripFraming may have other callers — check before deleting it rather than assuming this is the only one.

Found while auditing the fleet-status spec, and verified by reading `nexus/src/lib/server/sessions/service.ts`. ## Two defects in one helper `listTmuxWindows` (`service.ts:1356`) runs `tmux list-windows -t nexus -F '#W'` with `AttachStderr: true`, collects the stream, and hands it to `stripFraming`. It never calls `exec.inspect()`. `stripFraming` (`service.ts:1377`) tests **only the first frame's** stream byte: ```ts if (buf.length >= 8 && (buf[0] === 0 || buf[0] === 1 || buf[0] === 2) && buf[1] === 0 …) { while (i + 8 <= buf.length) { const size = buf.readUInt32BE(i + 4); out.push(buf.subarray(i + 8, i + 8 + size)); // every frame, whatever its stream id i += 8 + size; } ``` So: 1. **stderr is concatenated into the window-name set.** Every stderr frame's payload is appended alongside stdout, split on newlines, and returned as window names. 2. **A failed listing is indistinguishable from a successful one.** With no `inspect()`, a non-zero exit is invisible. `tmux list-windows` against a dead server writes `no server running on …` to stderr and exits 1 — which arrives as a non-empty set containing that sentence. ## Why it matters `convergeSessions` consumes this set to decide whether a session's tmux window is missing, and a missing window with a surviving worktree triggers a relaunch. Today a failed listing therefore reads as "every window is missing" rather than as "we could not look" — the opposite of the rule fact #15 states for the sibling worktree listing, where *uncertainty never triggers deletion*. It gets worse under the fleet status layer, where this listing becomes an input to a store that other subsystems read as truth. **Fix it before then** — seeding a new source of truth from a read that cannot report failure is the worst possible order. ## Fix Route it through `execAndCapture`, which already separates the streams and inspects the exit code. Zero test churn is expected: `makeConvergeDocker`'s fake already exposes exactly the two methods `execAndCapture` drives. Two guard tests, each of which must be shown to fail against the current implementation before the fix lands: - stderr content on the stream must not appear as a window name - a non-zero exit must not read as an empty window list ## Scope note `stripFraming` may have other callers — check before deleting it rather than assuming this is the only one.
lz added this to the MCP support (#140) milestone 2026-09-21 16:38:28 +02:00
lz closed this issue 2026-09-21 19:10:28 +02:00
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus#178
No description provided.