Make convergence read what it thinks it reads #185

Merged
lz merged 1 commit from fix/converge-reads into main 2026-09-21 19:10:28 +02:00
Owner

Closes #178. Closes #179.

Two defects in one pass, collapsed into one PR because they are the same shape — convergence acting on a value that is not what it appears to be — and because both live in the same twenty lines of convergeSessions. Both are sequencing dependencies of #177, which turns this pass into an input to a store other subsystems read as truth.

1 · The window listing could not report failure (#178)

listTmuxWindows read the exec stream itself and hand-stripped Docker's framing with stripFraming, which tested only the first frame's stream byte and then walked every frame regardless — so stderr payloads were concatenated into the window-name set. It also never called exec.inspect(), so a non-zero exit was invisible.

tmux list-windows against a dead server writes a diagnostic to stderr and exits 1. That arrived either as a set of nonsense names or as an empty set meaning every window is missing — and a missing window with a surviving worktree is exactly what triggers a relaunch. The sibling worktree listing follows the opposite rule, and AGENTS.md fact #15 states it: uncertainty never triggers an action.

Now it goes through execAndCapture (which separates the streams and inspects the exit code) and returns { names, ok } shaped like listWorktrees; convergence skips the pass when ok is false. stripFraming had exactly one caller — checked with git grep across nexus/src rather than assumed, as the issue's scope note asked — and is deleted.

2 · Convergence alone never minted a conversation id (#179)

Three paths relaunch a session, and they handled the empty claude_session_id that migration 0012 left on every pre-existing row three different ways:

path before
openWorkspaceSession mints, and persists as part of its row write
setSessionAgent restart mints and writes it back
convergeSessions neither

Since resumeFlag emits nothing at all for an empty id, a restored legacy session launched with no --session-id and no --resume, and the row stayed empty — so it could never become resumable. The conversation was lost on every restore, silently, permanently.

ensureClaudeSessionId now states the rule once and both relaunch paths read through it. openWorkspaceSession keeps its own mint deliberately: it may have no row to update yet, and it persists after the respawn succeeds rather than before, which is the safer order — its comment now points at the helper instead of at convergence's old Boolean(row.claude_session_id), a cross-reference this change would otherwise have left stale.

Guards, proven to fail first

All three were written against the unfixed code and observed red before anything was fixed — the failure output is the control, not a claim:

guard what it did against the old code
a stderr frame is not a window name the framed stderr payload landed in the set, so the session looked alive and the relaunch it needed never fired
a failed listing is not an empty window set exit 1 read as "no windows", and convergence relaunched a session whose window was fine
a legacy row comes out of convergence pinned expected '' to match /^[0-9a-f-]{36}$/

The launch assertion checks for --session-id and the absence of --resume. Asserting the id alone cannot tell a fresh pin from a resumed conversation — the mistake the restart path's own test calls out in a comment.

The test fake needed no restructuring, as #178 predicted: it already exposed the two methods execAndCapture drives. It gained a frameStderr helper beside the existing frameStdout, and two options on makeConvergeDocker for what the listing writes to stderr and what it exits with.

Deliberately left

resumeFlag's empty-id branch stays. After this no production path can reach it — createSession inserts a uuid, openWorkspaceSession mints, and both relaunch paths now go through the helper — and only the launch-builder unit tests still pass ''. Deleting it means editing a dozen expectation strings that exist to pin quoting, flag order and the agent-teams flag, which would bury those assertions under an unrelated change. Worth its own small PR.

Verification

Each gate its own command, output redirected, $? read before the log — never piped to tail.

  • typecheck 5177 files, 0 errors
  • vitest 201 files, 2238 tests, 0 failures (sessions/service.test.ts: 69 → 72)
  • lint 0 · build 0

One self-inflicted defect caught before commit: the helper was first inserted between resumeFlag's docblock and resumeFlag, orphaning that rationale onto the wrong function — the same displacement a review caught on #180. Moved below it, and the gates re-run after the move.

Closes #178. Closes #179. Two defects in one pass, collapsed into one PR because they are the same shape — convergence acting on a value that is not what it appears to be — and because both live in the same twenty lines of `convergeSessions`. Both are sequencing dependencies of #177, which turns this pass into an input to a store other subsystems read as truth. ## 1 · The window listing could not report failure (#178) `listTmuxWindows` read the exec stream itself and hand-stripped Docker's framing with `stripFraming`, which tested only the **first** frame's stream byte and then walked every frame regardless — so stderr payloads were concatenated into the window-name set. It also never called `exec.inspect()`, so a non-zero exit was invisible. `tmux list-windows` against a dead server writes a diagnostic to stderr and exits 1. That arrived either as a set of nonsense names or as an empty set meaning *every window is missing* — and a missing window with a surviving worktree is exactly what triggers a relaunch. The sibling worktree listing follows the opposite rule, and AGENTS.md fact #15 states it: uncertainty never triggers an action. Now it goes through `execAndCapture` (which separates the streams and inspects the exit code) and returns `{ names, ok }` shaped like `listWorktrees`; convergence skips the pass when `ok` is false. `stripFraming` had exactly one caller — checked with `git grep` across `nexus/src` rather than assumed, as the issue's scope note asked — and is deleted. ## 2 · Convergence alone never minted a conversation id (#179) Three paths relaunch a session, and they handled the empty `claude_session_id` that migration 0012 left on every pre-existing row three different ways: | path | before | |---|---| | `openWorkspaceSession` | mints, and persists as part of its row write | | `setSessionAgent` restart | mints and writes it back | | `convergeSessions` | neither | Since `resumeFlag` emits *nothing at all* for an empty id, a restored legacy session launched with no `--session-id` and no `--resume`, and the row stayed empty — so it could never become resumable. The conversation was lost on every restore, silently, permanently. `ensureClaudeSessionId` now states the rule once and both relaunch paths read through it. `openWorkspaceSession` keeps its own mint deliberately: it may have no row to update yet, and it persists after the respawn succeeds rather than before, which is the safer order — its comment now points at the helper instead of at convergence's old `Boolean(row.claude_session_id)`, a cross-reference this change would otherwise have left stale. ## Guards, proven to fail first All three were written against the unfixed code and observed red before anything was fixed — the failure output is the control, not a claim: | guard | what it did against the old code | |---|---| | a stderr frame is not a window name | the framed stderr payload landed in the set, so the session looked alive and the relaunch it needed never fired | | a failed listing is not an empty window set | exit 1 read as "no windows", and convergence relaunched a session whose window was fine | | a legacy row comes out of convergence pinned | `expected '' to match /^[0-9a-f-]{36}$/` | The launch assertion checks for `--session-id` **and** the absence of `--resume`. Asserting the id alone cannot tell a fresh pin from a resumed conversation — the mistake the restart path's own test calls out in a comment. The test fake needed no restructuring, as #178 predicted: it already exposed the two methods `execAndCapture` drives. It gained a `frameStderr` helper beside the existing `frameStdout`, and two options on `makeConvergeDocker` for what the listing writes to stderr and what it exits with. ## Deliberately left `resumeFlag`'s empty-id branch stays. After this no production path can reach it — `createSession` inserts a uuid, `openWorkspaceSession` mints, and both relaunch paths now go through the helper — and only the launch-builder unit tests still pass `''`. Deleting it means editing a dozen expectation strings that exist to pin quoting, flag order and the agent-teams flag, which would bury those assertions under an unrelated change. Worth its own small PR. ## Verification Each gate its own command, output redirected, `$?` read before the log — never piped to `tail`. - **typecheck** 5177 files, 0 errors - **vitest** 201 files, 2238 tests, 0 failures (`sessions/service.test.ts`: 69 → 72) - **lint** 0 · **build** 0 One self-inflicted defect caught before commit: the helper was first inserted *between* `resumeFlag`'s docblock and `resumeFlag`, orphaning that rationale onto the wrong function — the same displacement a review caught on #180. Moved below it, and the gates re-run after the move.
lz added this to the MCP support (#140) milestone 2026-09-21 17:19:06 +02:00
fix(sessions): make convergence read what it thinks it reads
All checks were successful
ci / nexus (pull_request) Successful in 10m20s
ci / images (pull_request) Successful in 32m13s
pr-image-cleanup / delete-pr-images (pull_request) Successful in 13s
352728eb4d
Closes #178. Closes #179.

Two defects in the same pass, both of which make convergence act on a value
that is not what it appears to be.

**The window listing could not report failure** (#178). `listTmuxWindows` read
the exec stream itself and hand-stripped Docker's framing with a helper that
tested only the FIRST frame's stream byte, then walked every frame regardless
— so stderr payloads were concatenated into the window-name set — and it never
called `exec.inspect()`, so a non-zero exit was invisible. `tmux list-windows`
against a dead server writes a diagnostic to stderr and exits 1, which arrived
as a non-empty set of nonsense, or as an empty set meaning "every window is
missing" — and a missing window with a live worktree is what triggers a
relaunch. That is the opposite of the rule the sibling worktree listing
follows, where uncertainty changes nothing.

It now goes through `execAndCapture`, which separates the streams and inspects
the exit code, and returns `{ names, ok }` shaped like `listWorktrees`, with
convergence skipping the pass when `ok` is false. `stripFraming` had exactly
one caller and is deleted (checked, rather than assumed — the issue asked).

**Convergence alone never minted a conversation id** (#179). Three paths
relaunch a session and they handled an empty `claude_session_id` — what
migration 0012 left on every pre-existing row — three ways:
`openWorkspaceSession` minted and persisted, the restart path minted and
persisted, and convergence did neither. Since `resumeFlag` emits nothing at
all for an empty id, a restored legacy session launched unpinned and the row
stayed empty, so it could never become resumable: the conversation was lost on
every restore, silently, forever.

`ensureClaudeSessionId` now states the rule once and both relaunch paths read
through it. `openWorkspaceSession` keeps its own mint because it may have no
row to update yet, and persists as part of the row write it already makes;
its comment now points at the helper instead of at convergence's old
`Boolean(row.claude_session_id)`.

Both guards were written first and shown to fail against the unfixed code:
stderr framed onto the stream suppressed a needed relaunch, a non-zero exit
relaunched a session whose window was fine, and the legacy row came out of
convergence still holding `''`. The launch assertion checks `--session-id`
specifically and that `--resume` is absent — asserting the id alone cannot
tell a fresh pin from a resumed conversation, which is the mistake the restart
path's own test calls out.

`resumeFlag`'s empty-id branch survives: after this, no production path can
reach it, and only the launch-builder unit tests still pass `''`. Deleting it
means touching a dozen expectation strings that exist to pin quoting and flag
order, so it is left as its own small change rather than folded in here.
lz merged commit 9ede7183cb into main 2026-09-21 19:10:28 +02:00
lz deleted branch fix/converge-reads 2026-09-21 19:10:29 +02:00
Sign in to join this conversation.
No reviewers
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!185
No description provided.