Workspace tools: stop_workspace, delete_workspace #157

New issue

Open

opened 2026-09-15 18:25:13 +02:00 by lz · 0 comments

lz commented

2026-09-15 18:25:13 +02:00

Owner

The two workspace-lifecycle operations that need no vault key — verified: stopWorker and removeWorker take no masterKey, while spawnWorker and startWorker do (those are slice 2, #159).

Depends on #154. Scope: nexus:write.

`stop_workspace`

Wraps stopWorker.

Note the asymmetry it creates and reflect it in the tool's output: stopWorker writes workers.status and never touches a session row, so every session of a stopped workspace still reads status: 'running' while its probe reports the container down. That is exactly the trap #155's roll-up has to handle — do not let this tool report those sessions as healthy.

Once stopped, the workspace cannot be restarted through MCP until slice 2, because startWorker needs the vault key. Say so in the tool description rather than letting Claude discover it by failing.

`delete_workspace`

Wraps removeWorker, and removal is asynchronous (AGENTS.md fact #27). DELETE /api/workers/:id calls beginRemoval (row → removing), returns 202, and reaps in the background; the row hard-deletes itself at the end, so removing is the one phase that ends with the row disappearing.

The tool reports accepted, never gone. Measured: docker volume rm runs at ~4s per 50k files, so a clone with node_modules per worktree is tens of seconds. A tool that claims completion on return is lying for most of that window, and the natural follow-up — Claude immediately listing workspaces and still seeing it — reads as a bug.

isRunning is false while removing, so a listing during teardown should show it as going away rather than as a running workspace with a failing health entry.

A failed teardown parks in remove-error, a phase distinct from error. Don't collapse them: error is what retryWorker accepts, and offering to re-provision a workspace whose removal failed means an empty re-clone against a half-reaped volume.

Watch for

Both tools are destructive and reachable from a phone. The consent screen already lists "Stop and delete workspaces" as a granted capability, but consider whether delete_workspace should require confirmation in its description so the model treats it as weightier than stop_workspace.

Done when

Claude can stop and delete a workspace; the delete returns promptly with an accepted-not-done result; and a listing during teardown reports the workspace as being removed rather than as running-and-unhealthy.

The two workspace-lifecycle operations that need no vault key — verified: `stopWorker` and `removeWorker` take no `masterKey`, while `spawnWorker` and `startWorker` do (those are slice 2, #159). Depends on #154. Scope: `nexus:write`. ## `stop_workspace` Wraps `stopWorker`. Note the asymmetry it creates and reflect it in the tool's output: `stopWorker` writes `workers.status` and **never touches a session row**, so every session of a stopped workspace still reads `status: 'running'` while its probe reports the container down. That is exactly the trap #155's roll-up has to handle — do not let this tool report those sessions as healthy. Once stopped, the workspace cannot be restarted through MCP until slice 2, because `startWorker` needs the vault key. Say so in the tool description rather than letting Claude discover it by failing. ## `delete_workspace` Wraps `removeWorker`, and **removal is asynchronous** (AGENTS.md fact #27). `DELETE /api/workers/:id` calls `beginRemoval` (row → `removing`), returns 202, and reaps in the background; the row hard-deletes itself at the end, so `removing` is the one phase that ends with the row **disappearing**. **The tool reports *accepted*, never *gone*.** Measured: `docker volume rm` runs at ~4s per 50k files, so a clone with `node_modules` per worktree is tens of seconds. A tool that claims completion on return is lying for most of that window, and the natural follow-up — Claude immediately listing workspaces and still seeing it — reads as a bug. `isRunning` is false while `removing`, so a listing during teardown should show it as going away rather than as a running workspace with a failing health entry. A failed teardown parks in `remove-error`, a phase distinct from `error`. Don't collapse them: `error` is what `retryWorker` accepts, and offering to re-provision a workspace whose *removal* failed means an empty re-clone against a half-reaped volume. ## Watch for Both tools are destructive and reachable from a phone. The consent screen already lists "Stop and delete workspaces" as a granted capability, but consider whether `delete_workspace` should require confirmation in its description so the model treats it as weightier than `stop_workspace`. ## Done when Claude can stop and delete a workspace; the delete returns promptly with an accepted-not-done result; and a listing during teardown reports the workspace as being removed rather than as running-and-unhealthy.

lz added this to the MCP support (#140) milestone

2026-09-15 18:25:13 +02:00