codex-dsh-supervisor

Codex DSH Supervisor

Use the dsh_* MCP tools to supervise one DSH root session.

Start the visible session

1. Call dsh_start_or_connect first. It connects to the configured Host, or starts one when DSH_HOST_LAUNCH is explicitly configured (automatic Host startup never happens without it). Pass the existing sessionId to reconnect and reuse the same session; the Host remains independently owned and MCP restart never stops it.
2. Open the returned hostBaseUrl in a visible browser tab so the user can watch the live session (the DSH web UI), and keep that tab available for the duration of the task. If a tab is already open on that URL, reuse it. After queuing the task, select its human-readable objective in the Web session sidebar when the UI exposes it; otherwise leave the session list visible and tell the user the taskId. MCP never owns or closes the browser.

Assign and observe

1. Before assigning a writer task, establish a recoverable Git baseline and record HEAD plus git status. If the repository has no commit or the baseline would include user changes, obtain explicit human authorization before committing. Never create the baseline by stashing, resetting, discarding, or overwriting existing work. Read-only tasks do not require a new baseline.
2. Call dsh_task with a self-contained objective plus relevant context, scope, constraints, acceptance, verification, and escalation conditions. Default to writer; choose read_only for analysis. A second writer needs an independent Git worktree, not a workspace lock service. Treat ordinary in-scope edits, focused compilation/tests/builds, routine debugging, and any explicitly pre-authorized child use as execution authority: do not ask the human again. Escalate only when a missing choice would materially change the requested result, or before a security-sensitive, destructive, credentialed, external, or otherwise unauthorized side effect.
3. Call dsh_wait with the default timeout (300000 ms) — the five-minute aggregated progress cadence. One long observation arrives about every 300000 ms; do not re-poll on ordinary event churn. It returns early only for a material supervisor boundary, such as a terminal state, approval/question, checkpoint, blocker, or escalation. A WAITING/TIMEOUT return is the cadence observation: aggregate progress since the prior asOfSeq — step delta, tool counts by name, token deltas, and compact projectActivity (distinct files touched by successful edits/writes and targeted verification commands like pnpm verify). Surface the compact summary to the user; never dump raw logs, diffs, or tool outputs. Carry the returned asOfSeq into the next afterAsOfSeq; it is only an observation cursor, never a server resume cursor.
4. Resolve APPROVAL_REQUIRED and QUESTION_REQUIRED with the matching answer tool. Use dsh_steer only to transmit explicit user-authored new guidance or a user-requested correction; never synthesize a nudge merely because progress paused or a child settled. Use dsh_cancel only for the active turn.
5. Distinguish WAITING.wait.reason=TIMEOUT (cadence window expired) from worker state, and inspect workerState separately. For FAILED, report the explicit failure kind.
6. Accept success only from COMPLETED. The runtime requires a valid supervisor_handoff result and the corresponding turn/end; a turn ending alone is MISSING_HANDOFF. Terminal reporting must recap steps, tool counts, token deltas, verification results, the worker's final files, and the computed projectActivity totals — without equating every tool call with a project change.