nexus_create_session and nexus_delete_session: open and close sessions from MCP (#156) #202

Merged
lz merged 33 commits from feat/mcp-session-tools into main 2026-09-24 09:25:41 +02:00
Owner

Closes #156. Spec: docs/superpowers/specs/2026-09-23-mcp-session-tools-design.md; plan: docs/superpowers/plans/2026-09-23-mcp-session-tools.md.

What it adds

nexus_create_session (nexus:write) opens a session in a running workspace.

  • initial_message becomes the agent's first turn.
  • model and effort apply to that launch.
  • agent_teams defaults to on, as in the UI.
  • It returns the session with the same derived mark as nexus_list_sessions, plus confirmed: whether claude was seen starting.

nexus_delete_session (nexus:write) deletes a session's worktree and branch.

  • It refuses when that would destroy uncommitted or untracked files, or commits no other branch or remote holds, and says how many. force: true discards them and reports what went.
  • It refuses the workspace shell.
  • It refuses any session whose workspace is not running: MCP cannot start a workspace, and deleting now would leave the branch behind (#201).

A nexus:write-only credential now reaches exactly these two tools.

Shared with the UI, not MCP-only

The behaviour lives in sessions/service.ts, so the UI routes run the same code.

  • Launch line. The create launch appends --model, --effort and then the first message, LAST and behind --. No flag can consume the message, and a leading - is not read as a flag. Nothing is stored, so a restore or restart never replays it.
  • Observing a launch. A create waits for claude to appear in its worktree and records the result in claude_alive. This is the same shape the agent restart already used, now one helper (observeClaude) for create, restart, stop and the workspace shell. A timeout records null ("not confirmed"), never absence. Waiters share one proc walk per container (claude-waiter.ts) instead of a poll per session, and each waiter's deadline runs on its own timer, so a hung exec cannot strand the rest.
  • The UI create now returns { session, confirmed }. An unconfirmed start toasts as a warning, not a failure: the session exists, and a retry would hit "already exists".
  • deleteSession takes a required { force }. The unsaved-work check runs before any side effect. The UI route passes force: true, because its confirm dialog is the consent.
  • The UI copy was wrong. The remove confirm and the Settings "Danger" row said "The branch is kept". deleteSession force-deletes the branch, and it always did. Both now say so.

Why model and effort are never stored

Measured on claude 2.1.280/281:

  • --resume restores the conversation's latest model, including a /model change made inside the session. Re-passing --model on a restart would override the operator's own choice.
  • Effort reverts to the settings effortLevel on resume. So does an in-session /effort.

The tool descriptions say both.

Concurrency, measured rather than assumed

  • Parallel git worktree add does not contend (60/60). The issue's premise that creates need serialising does not hold, and serialising would make a burst of twelve about five times slower.
  • Parallel branch -D does contend (could not lock config file .git/config). Every branch -D now runs under flock /workspace/.nexus/git.lock.
  • Parallel jq rewrites of ~/.claude.json lost trust entries: 7–10 of 12 survived. This is a pre-existing bug for UI creates and convergence restores too. The trust write now runs under flock. On current claude trust is also inherited from /workspace, which covers a per-session entry that claude's own startup rewrite drops. AGENTS.md fact #4 said trust keys were exact paths only; that is corrected.
  • tmux refuses a command over ~16 KB. The first message is bounded by its quoted byte size before anything is written. A refusal after the row insert deletes the row rather than parking it errored, so it never holds the name.

Two bugs the live run found that the suite could not

  • Deleting a session could orphan a tmux window, UI or MCP alike. Convergence lists windows and then reads rows. A pass landing between the window kill and the row delete saw "row present, window missing" and restored the session into a worktree about to be removed. deleteSession now deletes the row before killing the window, and a test pins that order.
  • Launch deadline. Under a burst of twelve starts while twelve claudes were exiting, some claudes took over 5 s to appear. The deadline is now 10 s; only a slow start waits that long.

Also fixed on the way

  • The unsaved-work check named the branch bare. A session named like a top-level path in the repo (docs, nexus, worker here) hit git's "ambiguous argument", and every delete of it refused. It now uses refs/heads/<name> … --.
  • Cleanup steps in deleteSession that exit non-zero are logged instead of vanishing.
  • CI installs git, jq and flock, so the real-shell tests for the unsaved-work check and the trust lock run there instead of skipping.

Verified live

Verified against the built server in Docker-in-Docker, with a real worker image, a real clone and MCP calls over HTTP:

  • A create with a first message on haiku ran it as the opening turn, and Remote Control was active.
  • Twelve concurrent creates came back confirmed, with every trust entry present and no pane on a trust dialog. Two further rounds of twelve concurrent creates and deletes left no orphan window, branch or worktree.
  • An unpushed commit was refused, then discarded with force and reported.
  • A session named after a repo file was deleted cleanly.
  • The stopped-workspace refusals held, and sessions restored on start.
  • In a browser: the UI create with claude broken showed the warning toast, the new confirm and Settings copy rendered, and the UI delete went through.

Not in this PR

  • MCP tools for the workspace shell.
  • The delete guard in the UI.
  • model/effort in the UI create form.
  • send_message (#158).
  • The orphaned branch after a UI delete on a stopped workspace (#201).
Closes #156. Spec: `docs/superpowers/specs/2026-09-23-mcp-session-tools-design.md`; plan: `docs/superpowers/plans/2026-09-23-mcp-session-tools.md`. ## What it adds **`nexus_create_session`** (`nexus:write`) opens a session in a running workspace. - `initial_message` becomes the agent's first turn. - `model` and `effort` apply to that launch. - `agent_teams` defaults to on, as in the UI. - It returns the session with the same derived `mark` as `nexus_list_sessions`, plus `confirmed`: whether claude was seen starting. **`nexus_delete_session`** (`nexus:write`) deletes a session's worktree and branch. - It refuses when that would destroy uncommitted or untracked files, or commits no other branch or remote holds, and says how many. `force: true` discards them and reports what went. - It refuses the workspace shell. - It refuses any session whose workspace is not running: MCP cannot start a workspace, and deleting now would leave the branch behind (#201). A `nexus:write`-only credential now reaches exactly these two tools. ## Shared with the UI, not MCP-only The behaviour lives in `sessions/service.ts`, so the UI routes run the same code. - **Launch line.** The create launch appends `--model`, `--effort` and then the first message, LAST and behind `--`. No flag can consume the message, and a leading `-` is not read as a flag. Nothing is stored, so a restore or restart never replays it. - **Observing a launch.** A create waits for claude to appear in its worktree and records the result in `claude_alive`. This is the same shape the agent restart already used, now one helper (`observeClaude`) for create, restart, stop and the workspace shell. A timeout records `null` ("not confirmed"), never absence. Waiters share one proc walk per container (`claude-waiter.ts`) instead of a poll per session, and each waiter's deadline runs on its own timer, so a hung exec cannot strand the rest. - **The UI create** now returns `{ session, confirmed }`. An unconfirmed start toasts as a warning, not a failure: the session exists, and a retry would hit "already exists". - **`deleteSession` takes a required `{ force }`.** The unsaved-work check runs before any side effect. The UI route passes `force: true`, because its confirm dialog is the consent. - **The UI copy was wrong.** The remove confirm and the Settings "Danger" row said "The branch is kept". `deleteSession` force-deletes the branch, and it always did. Both now say so. ## Why model and effort are never stored Measured on claude 2.1.280/281: - `--resume` restores the conversation's latest model, including a `/model` change made inside the session. Re-passing `--model` on a restart would override the operator's own choice. - Effort reverts to the settings `effortLevel` on resume. So does an in-session `/effort`. The tool descriptions say both. ## Concurrency, measured rather than assumed - **Parallel `git worktree add`** does not contend (60/60). The issue's premise that creates need serialising does not hold, and serialising would make a burst of twelve about five times slower. - **Parallel `branch -D`** does contend (`could not lock config file .git/config`). Every `branch -D` now runs under `flock /workspace/.nexus/git.lock`. - **Parallel jq rewrites of `~/.claude.json`** lost trust entries: 7–10 of 12 survived. This is a pre-existing bug for UI creates and convergence restores too. The trust write now runs under `flock`. On current claude trust is also inherited from `/workspace`, which covers a per-session entry that claude's own startup rewrite drops. AGENTS.md fact #4 said trust keys were exact paths only; that is corrected. - **tmux refuses a command over ~16 KB.** The first message is bounded by its quoted byte size before anything is written. A refusal after the row insert deletes the row rather than parking it `errored`, so it never holds the name. ## Two bugs the live run found that the suite could not - **Deleting a session could orphan a tmux window**, UI or MCP alike. Convergence lists windows and then reads rows. A pass landing between the window kill and the row delete saw "row present, window missing" and restored the session into a worktree about to be removed. `deleteSession` now deletes the row before killing the window, and a test pins that order. - **Launch deadline.** Under a burst of twelve starts while twelve claudes were exiting, some claudes took over 5 s to appear. The deadline is now 10 s; only a slow start waits that long. ## Also fixed on the way - The unsaved-work check named the branch bare. A session named like a top-level path in the repo (`docs`, `nexus`, `worker` here) hit git's "ambiguous argument", and every delete of it refused. It now uses `refs/heads/<name> … --`. - Cleanup steps in `deleteSession` that exit non-zero are logged instead of vanishing. - CI installs `git`, `jq` and `flock`, so the real-shell tests for the unsaved-work check and the trust lock run there instead of skipping. ## Verified live Verified against the built server in Docker-in-Docker, with a real worker image, a real clone and MCP calls over HTTP: - A create with a first message on haiku ran it as the opening turn, and Remote Control was active. - Twelve concurrent creates came back confirmed, with every trust entry present and no pane on a trust dialog. Two further rounds of twelve concurrent creates and deletes left no orphan window, branch or worktree. - An unpushed commit was refused, then discarded with `force` and reported. - A session named after a repo file was deleted cleanly. - The stopped-workspace refusals held, and sessions restored on start. - In a browser: the UI create with claude broken showed the warning toast, the new confirm and Settings copy rendered, and the UI delete went through. ## Not in this PR - MCP tools for the workspace shell. - The delete guard in the UI. - `model`/`effort` in the UI create form. - `send_message` (#158). - The orphaned branch after a UI delete on a stopped workspace (#201).
lz added this to the MCP support (#140) milestone 2026-09-24 03:35:10 +02:00
lz added 31 commits 2026-09-24 03:35:11 +02:00
A session named like a top-level path (docs, nexus, worker) made the
rev-list argument ambiguous; git exited 128 and every such delete was
refused as "could not check".
The character cap let through messages whose shell-quoted form overflows
tmux's byte limit, so the refusal came after the row and worktree were
made and the errored row held the name against a retry. Measure the
quoted bytes up front, delete the row when the launch is refused, map
only a UNIQUE violation to "already exists", and take the git lock for
the cleanup branch deletes.
execAndCapture returns a non-zero exit rather than throwing, so a failed
kill-window, worktree remove, branch -D or unsaved-work check was
invisible. Deletion stays best-effort; each failure now logs a warning.
Also covers refusal and force on each kind of unsaved work alone, and
force over a failed check.
Deadlines were only checked between probes and a probe has no timeout,
so one hung proc walk held every waiter on that container forever. Each
waiter now times out on its own, and an emptied poll leaves the map so
the next launch starts a fresh one.
createSession's trust exec must carry the flock, and twelve parallel
rewrites without it must lose entries, so the passing locked test is
evidence of the lock rather than of luck.
Also types the deleteSession fake's risk option so the typecheck passes.
The service force-deletes the row but leaves the worktree and branch on
the volume, where a later session of the same name force-deletes that
branch (#201). MCP cannot start a workspace, so the tool refuses even with
force and points at the Nexus UI.
createSession returned one string for a failed create and for a created
session whose claude had not come up yet, and both callers toasted it as
an error, so a created session read as a failed one and the retry hit
"already exists". It now returns the toast's text and type.
Unwidened, the unlocked rewrite kept all twelve entries in 3 of 6 runs on
node:22-alpine, so the negative control failed there. Both variants now
pause between read and write.
work-at-risk.test.ts and trust-lock.test.ts skip without them, and
node:22-alpine ships none. Alpine's flock is its own util-linux subpackage.
fix(sessions): give a launch 10 s to show up under a burst of starts
Some checks failed
ci / nexus (pull_request) Failing after 8m41s
ci / images (pull_request) Has been skipped
fcb9e6d069
lz added 2 commits 2026-09-24 09:22:03 +02:00
Five tools each found a workspace or session by id and refused with their
own copy of the same sentence; two copies had already drifted. They now go
through workspaceById / sessionById.
test(mcp): use the shared row fixtures instead of private copies
Some checks failed
ci / images (pull_request) Has been cancelled
ci / nexus (pull_request) Has been cancelled
pr-image-cleanup / delete-pr-images (pull_request) Successful in 38s
edf8dc2950
registry.test.ts carried a verbatim copy of fixtures.ts's workspaceRow and
sessionRow; flow.test.ts and handler.test.ts spelled the same DTOs out inline.
lz merged commit c880424bff into main 2026-09-24 09:25:41 +02:00
lz deleted branch feat/mcp-session-tools 2026-09-24 09:25:42 +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!202
No description provided.