[nedtwigg]

dor split, dor ensure, dor tool, and dor open now report command_state beside status. status says how the Surface was found or made. command_state says what the reply can prove about the launched command:

• unconfirmed: a new Surface whose command has not been seen starting
• running: the shell reported the command running
• awaiting_approval: an unapproved project Tool waiting on the user; nothing ran
• queued: not started yet. A takeover is one: it answers before its command is typed, so dor can exit and free the shell. So is a reused or retargeted Tool whose run has not started.
• ended: the command already ended, perhaps with a nonzero exit, or a newer preview superseded this one

Neither field promises a successful exit or a ready service. The host computes the state from evidence present when it replies (toolCommandState and observedCommandState in lib/src/components/wall/use-dor-control.ts). Shell integration alone proves no startup, and an earlier completed run never proves a retarget or restart. A new Surface whose first command already finished reports ended.

JSON output carries command_state. In text output, ensure, tool, and open show it as a tag after the handle: existing surface:3 [running] "npm run dev". split can only be unconfirmed, so its text output is unchanged. CommandState in dor/src/commands/types.ts owns the values. Each response type narrows them to what its command can return, and each command's --help lists only those, with what each means there.

A browser-provider command that succeeds but whose Surface cannot then be opened or reused now exits 4, not 0. The provider's output is kept, and stderr says the command already ran and must not be repeated blindly. dor emits no JSON error object on the browser path, since provider output belongs to the provider, so there is no error code for it. The fixed-DPR Playwright open, which binds before navigating, still fails with exit 1 and leaves the page unopened.

Root dor --help, the agent-browser and playwright help, the skill, and docs/specs/dor-cli.md (new "Command state" section; the browser bind rule and the exit-status list) describe the contract.

Stack: 6/8, based on #1742. Breaking change for Dormouse 2.0.

Validation:

• dor: build and 354 tests (347 passed, 7 platform skips), help and output snapshots regenerated
• lib: tsc -b; the Wall, wall/ (use-dor-control, preview-slot, workspace-control, and the rest), and WorkspaceWindow suites, 71 files and 1504 tests
• website: pnpm test (tsc --noEmit plus the full vitest suite, 486 tests, including the 16 playground CLI tests)
• lint:specs (dor-cli budget ratcheted to 6150) and its 58 self-checks, lint:md, lint:public-docs, git diff --check

Mutation checks:

• setting the bind-failure exit back to 1, or leaving the provider's 0, fails the agent-browser and playwright exit-4 tests. Dropping the "already ran" stderr sentence fails the agent-browser one.
• dropping the text tag fails the tool, open --preview, and ensure text tests and snapshots. Renaming the JSON field back to completion fails the tool JSON snapshot and the command_state test.
• in the host, dropping the pending case fails the unit test and the Wall pending-reuse test. Dropping the takeover case, or reporting a new Surface's ended command as unconfirmed, fails the toolCommandState unit test.

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	8eac6cb
Status:	✅  Deploy successful!
Preview URL:	https://b4343f32.mouseterm.pages.dev
Branch Preview URL:	https://dor-v2-06-completion.mouseterm.pages.dev

View logs

[dormouse-bot]

The "Text output" examples in dor ensure --help and dor tool --help no longer match what the renderers print. When completion differs from status, the renderers now add a [completion] tag, so existing and restarted print existing surface:3 [started] "npm run dev" (see the updated ensure-text.snap and ensure-restart.snap), and a takeover prints takeover surface:1 [requested] "pnpm storybook". The help still shows the old untagged lines (ensure.ts: existing surface:3 "npm run dev" / restarted surface:3 "npm run dev"; tool.ts: existing surface:3 "pnpm storybook" / takeover surface:1 "pnpm storybook"). Help is where agents learn the format, so a script that copies its line shape will misparse the real output. split is unaffected because its completion is always created.

launchCompletionHelp is also added to the dor split and dor ensure help. split only ever returns created, and ensure never returns pending or a takeover, so in their help the takeover sentence and the values those commands can't return describe behavior that doesn't apply to them.

[nedtwigg]

Re: dormouse-bot review —

stale "Text output" examples; launchCompletionHelp shared verbatim

Fixed both, and the field is renamed while I was there. completion is now command_state (commandState on the wire), with values that describe the command rather than the Surface: unconfirmed, running, awaiting_approval, queued, ended.

Text output: ensure, tool, and open now always print the state as a tag, e.g. existing surface:3 [running] "npm run dev". The old values sometimes matched status, so the tag was skipped when they were equal; the new values never match, so that condition is gone. The help examples now show the tag: dor/src/commands/ensure.ts:136 (created/existing/restarted) and dor/src/commands/tool.ts:153 (created/existing/takeover, plus a pending … [awaiting_approval] line). split prints no tag, because it can only ever report unconfirmed.

Per-command help: the shared constant is replaced by commandStateHelp(states) (dor/src/commands/shared.ts:235). Each command passes only the states it can return, each with what it means for that command:

• ensure (ensure.ts:30): unconfirmed, running, queued, ended. It has no approval gate, and --restart is always running.
• tool (tool.ts:37): all five. Only tool can be awaiting_approval.
• open (open.ts:11): unconfirmed, running, queued, ended. It only runs user Tools and built-ins, which need no approval. ended also covers a superseded preview.
• split (split.ts:118): one sentence saying its JSON command_state is always unconfirmed.

The types enforce the same lists. SplitSurfaceResponse.commandState is 'unconfirmed', and EnsureSurfaceResponse.commandState excludes 'awaiting_approval' (dor/src/commands/types.ts:269, :290). The ensure help list is typed against the ensure response, and the host's observedCommandState returns the ensure type (lib/src/components/wall/use-dor-control.ts:405).

[dormouse-bot]

A Tool re-run that has already finished is reported as command_state: queued instead of ended; details inline.

[dormouse-bot]

The new "Command state" paragraph in docs/specs/dor-cli.md restates rules that dor-tool.md → "Take-over" and the "dor app" section already own; suggestion inline.