vgxness 1.9.2 → 1.9.4

package/docs/cli.md

@@ -49,7 +49,7 @@ Release defaults used by the guided setup are:
 - Install mode: MCP plus manager/SDD agents (`mcp-plus-agents`).
 - Public CLI language: English.
 
-Recommended user flow after `npm install -g vgxness`:
+Recommended bootstrap and diagnostic flow after `npm install -g vgxness`:
 
 ```bash
 vgxness --help
@@ -59,14 +59,34 @@ vgxness setup plan           # human-readable, read-only plan
 vgxness setup status         # human-readable, read-only setup status
 vgxness setup apply --yes    # writes OpenCode config only after explicit consent
 vgxness doctor               # human-readable readiness checks
-vgxness sdd next --project <project> --change <change>
+vgxness status --project <project> --change <change>   # diagnostic cockpit
+vgxness next --project <project> --change <change>     # diagnostic/recovery next step
+vgxness sdd continue --project <project> --change <change> # read-only manual continuation plan
+vgxness resume --project <project> --run-id <id>
 vgxness setup rollback --backup <path>
 ```
 
+Daily SDD phase progression is OpenCode-first: talk to OpenCode with the VGXNESS MCP server installed, and let the hidden SDD subagents use MCP tools for phase work. The CLI and TUI remain supported for bootstrap/setup, diagnostics, recovery, manual fallback, and scripting; they are not the primary daily surface.
+
 `setup plan`, `setup status`, and non-TTY `init` planning do not write provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
 
 `vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
 
+## Daily workflow front doors
+
+Use OpenCode conversation + VGXNESS MCP + hidden SDD subagents for normal daily SDD work. Use these top-level commands when you need diagnostics, recovery, manual fallback, or scriptable state inspection:
+
+| Question | Command | Purpose |
+|---|---|---|
+| Where am I? | `vgxness status --project <project> --change <change>` | Diagnostic cockpit state, blockers, next recommendation, and safety notes. |
+| What should I do now? | `vgxness next --project <project> --change <change>` | Recovery/diagnostic next action and why it is safe or blocked. |
+| How do I continue a change manually? | `vgxness sdd continue --project <project> --change <change>` | Builds a read-only continuation plan and manual fallback commands for the selected SDD change. |
+| How do I continue interrupted work? | `vgxness resume --project <project> [--run-id <id>]` | Lists or inspects interrupted runs and suggests manual continuation commands without retrying anything. |
+
+Without `--change`, `--project`, or `--run-id`, these commands stay orientation-only and do not open the local memory store. With a selected change, project, or run, top-level `status`, `next`, and `resume` inspect SQLite read-only; formal `sdd` commands are non-provider, non-run-executing planning/artifact commands that may use the normal local store path. Pass `--json` for automation.
+
+The usual SDD operator loop happens inside OpenCode: continue the phase in conversation while VGXNESS MCP and hidden SDD subagents inspect readiness, persist artifacts, and report evidence. CLI commands remain fallback/recovery tools: inspect `status`, ask `next`, run `sdd continue` for a copyable manual continuation plan, then either run `vgxness code sdd ...` as an explicit fallback or `vgxness resume ...` for interrupted work. After a draft is ready, use `sdd accept-artifact` for explicit human acceptance; if an artifact was rejected, use `sdd reopen-artifact` before revising it. Related interrupted run hints in `status`, `next`, and `sdd continue` are advisory only; they help avoid duplicate work but do not retry or execute runs.
+
 ## Bun-first repository verification
 
 VGXNESS uses Bun as the canonical installed runtime and verification path for repository development and CI. Node.js `>=22` remains development/build/test tooling for TypeScript, `node:test`, and helper scripts. npm package consumer metadata remains supported, but the product runtime engine is `engines.bun`.
@@ -220,13 +240,15 @@ bun run cli:bun --
 
 The installed `vgxness`/`vgx` binary opens the OpenTUI main menu when run with no arguments in a TTY. With no TTY, no-args prints deterministic safe setup guidance, exits 0, and does not infer a project, open project state, toggle raw mode, or write provider/config artifacts. Use `vgxness --help` or `vgxness -h` to print command help without starting the main menu; explicit subcommands keep their normal behavior.
 
-The top-level menu is: **Installation, Doctor / recovery, SDD / workflow guidance, Advanced CLI, Exit**. Terminal controls are `↑/↓` or `j/k` to move, `Enter` to open the focused item, `?` for help, and `q` to quit.
+The top-level menu is: **Installation, Doctor / recovery, SDD / workflow guidance, Advanced CLI, Exit**. It is a read-only setup, diagnostics, recovery, and fallback surface; daily SDD progression stays in OpenCode with VGXNESS MCP. Terminal controls are `↑/↓` or `j/k` to move, `Enter` to open the focused item, `?` for help, and `q` to quit.
 
 For scriptable status, use explicit read-only commands:
 
 ```bash
 bun run cli:bun -- setup status --project vgxness
-bun run cli:bun -- sdd status --project vgxness --change my-change
+bun run cli:bun -- status --project vgxness --change my-change
+bun run cli:bun -- next --project vgxness --change my-change
+bun run cli:bun -- resume --project vgxness --run-id <id>
 ```
 
 Provider support shown in the Installation surface is:
@@ -236,7 +258,7 @@ Provider support shown in the Installation surface is:
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
-Setup and main-menu TUI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. Any operational next action is copied for explicit execution outside the TUI.
+Setup and main-menu TUI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. They print diagnostics, recovery hints, and manual fallback commands; daily SDD work should continue in OpenCode.
 
 ## Natural-language orchestrator preview
 
@@ -283,7 +305,7 @@ vgxness code inspect "<question>"   \
   --memory off|ask|auto
 ```
 
-SDD-aware mode is exposed through `vgxness code sdd <change> <phase>`; pass `--save-artifact` only when persistence is intended, and pass `--change-id`/`--phase` to scope work. Read-only phases stay artifact-oriented; `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools.
+SDD-aware mode is exposed through `vgxness code sdd <change> <phase>`; pass `--save-artifact` only when persistence is intended, and pass `--change-id`/`--phase` to scope work. Read-only phases stay artifact-oriented; `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools. `--draft-run` lets planning phases use draft prerequisites for planning only; human acceptance is still required, and `apply-progress` remains gated. `apply` is accepted as a user-facing alias for `apply-progress`.
 
 Useful events-only output for piping into the OpenTUI shell or your own tooling:
 
@@ -433,7 +455,7 @@ A rejected approval is recorded in the run audit trail and prevents the matching
 
 ### SDD workflow commands vs formal SDD commands
 
-`sdd preview`, `sdd run`, and `sdd execute` are workflow commands and use the three-mode workflow contract above. `sdd status`, `sdd ready`, `sdd save-artifact`, `sdd accept-artifact`, `sdd get-artifact`, `sdd list-artifacts`, and `sdd next` are formal SDD artifact/status commands. Formal SDD commands read or write SDD artifact state in the selected local SQLite store; they do not execute providers or continue workflow runs.
+`sdd preview`, `sdd run`, and `sdd execute` are workflow commands and use the three-mode workflow contract above. `sdd status`, `sdd ready`, `sdd continue`, `sdd save-artifact`, `sdd accept-artifact`, `sdd reopen-artifact`, `sdd get-artifact`, `sdd list-artifacts`, and `sdd next` are formal SDD artifact/status commands. Formal SDD commands read or write SDD artifact state in the selected local SQLite store; they do not execute providers or retry workflow runs. `sdd continue` is read-only and returns a continuation plan; it does not create runs, mutate artifacts, or call providers.
 
 ## MCP setup preview and doctor
 
@@ -543,24 +565,30 @@ Manual/opt-in runtime validation checklist (not normal CI):
 
 ## SDD workflow examples
 
-Use `sdd` commands to inspect local SDD artifact state and save, read, or list phase artifacts. These commands read and write only the selected `vgxness` local SQLite memory store: `--db <path>` when passed, `VGXNESS_DB_PATH` when set, or the global default database when neither override is present.
+Use OpenCode conversation with VGXNESS MCP and hidden SDD subagents for normal daily SDD progression. Use `sdd` commands to inspect local SDD artifact state and save, read, or list phase artifacts for diagnostics, recovery, scripting, or manual fallback. These commands read and write only the selected `vgxness` local SQLite memory store: `--db <path>` when passed, `VGXNESS_DB_PATH` when set, or the global default database when neither override is present.
 
 ```bash
 bun run cli:bun -- sdd status --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd ready --project vgxness --change sdd-workflow-engine --phase spec --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd save-artifact --project vgxness --change sdd-workflow-engine --phase proposal --content "# Proposal" --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd continue --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- code sdd sdd-workflow-engine spec --project vgxness --draft-run --save-artifact --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd accept-artifact --project vgxness --change sdd-workflow-engine --phase proposal --actor user --note "Approved for spec" --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- resume --project vgxness --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd get-artifact --project vgxness --change sdd-workflow-engine --phase proposal --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd next --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd reopen-artifact --project vgxness --change sdd-workflow-engine --phase design --actor user --note "Revise rejected design" --db /tmp/vgxness-memory.sqlite
 VGXNESS_DB_PATH=/tmp/vgxness-memory.sqlite bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine
 ```
 
-Current phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present and the next ready missing phase. `sdd next` reports the next SDD action for a project/change. `sdd status`, `sdd next`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
+Current canonical phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. `apply` is accepted as a user-facing input alias, but artifacts, topic keys, readiness/status/cockpit JSON, and internal metadata continue to use canonical `apply-progress`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present, blocker-specific next actions, and related interrupted run hints when available. `sdd next` reports the next SDD action for a project/change and frames runnable phase work as OpenCode-first while preserving fallback command fields. `sdd continue` turns that state into a read-only continuation plan, including manual fallback commands, draft-run suggestions for planning phases, and related interrupted run context when a matching stopped run exists. `sdd status`, `sdd next`, `sdd continue`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
+
+`sdd accept-artifact` records explicit human-only acceptance of an existing artifact through the same SDD workflow service used by MCP. It requires `--project`, `--change`, `--phase`, and `--actor`; `--display-name` defaults to the actor id. `--accepted-at` is optional, but when supplied it must be an ISO date-time with an explicit timezone (`Z` or offset) and is normalized to UTC `toISOString()` output. The default output is a human-readable confirmation with a JSON hint; `--json` returns a content-free success object with project/change/phase/topic key/artifact id/status/acceptedBy/acceptedAt and optional note. `save-artifact` creates or updates draft content only and does not imply acceptance. `sdd reopen-artifact` moves a rejected artifact back to draft after an explicit human decision, so the artifact can be revised and accepted again.
 
-`sdd accept-artifact` records explicit human-only acceptance of an existing artifact through the same SDD workflow service used by MCP. It requires `--project`, `--change`, `--phase`, and `--actor`; `--display-name` defaults to the actor id. `--accepted-at` is optional, but when supplied it must be an ISO date-time with an explicit timezone (`Z` or offset) and is normalized to UTC `toISOString()` output. The default output is a human-readable confirmation with a JSON hint; `--json` returns a content-free success object with project/change/phase/topic key/artifact id/status/acceptedBy/acceptedAt and optional note. `save-artifact` creates or updates draft content only and does not imply acceptance.
+Use `resume --project <project>` when you do not know the run id. It lists recent interrupted candidates for that project from the selected database. Use `resume --project <project> --run-id <id>` to inspect one candidate; this is still read-only and advisory.
 
-The SDD CLI is status/persistence only. It does **not** execute providers, continue workflows, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
+The SDD CLI is status, planning, artifact persistence, diagnostics, recovery, scripting, and manual fallback only. It does **not** execute providers, retry workflow runs, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
 
 ## Agent resolution
 
@@ -953,7 +981,7 @@ For more on schema, scopes, and lifecycle, see [Storage](./storage.md).
 
 - [Architecture](./architecture.md) — current-state architecture and core domain model.
 - [Code runtime](./code-runtime.md) — `vgxness code` modes, tools, providers, and approval flow.
-- [MCP tools](./mcp.md) — full reference for the 38 MCP tools exposed to agents.
+- [MCP tools](./mcp.md) — full reference for the 41 MCP tools exposed to agents.
 - [Safety model](./safety.md) — permission categories, approval flow, redactors, and runtime gates.
 - [Storage](./storage.md) — SQLite schema, scopes, and lifecycle.
 - [Providers](./providers.md) — adapter contract and how to add a new provider.

package/docs/code-runtime.md

@@ -35,6 +35,7 @@ Common flags across modes:
 | Flag | Effect |
 |---|---|
 | `--save-artifact` | Persist the phase artifact when explicit persistence is intended. |
+| `--draft-run` | Let planning phases use draft prerequisites for planning only; human acceptance is still required and `apply-progress` remains gated. |
 | `--change-id <id>` | Override change id. |
 | `--approval-policy`, `--approval-channel`, `--memory` | Same as the other modes. |
 
@@ -172,6 +173,8 @@ Prompts, reports, checkpoints, transcripts, and memory saves redact secret-like
 
 `vgxness code sdd <change> <phase>` loads existing artifacts for the requested change/phase and exposes phase-appropriate tools. Non-implementation phases stay read/artifact oriented. `apply-progress` may expose edit and shell tools. `verify` may expose verification shell tools. Artifact saves require explicit `--save-artifact` (or the equivalent runtime flag); passing it is the only way persistence is triggered.
 
+Use `vgxness sdd continue --project <project> --change <change>` first when you want the read-only continuation plan. It may suggest `vgxness code sdd ... --draft-run --save-artifact` for planning phases when draft prerequisites exist. `--draft-run` does not accept a value, does not weaken human acceptance, and does not unblock `apply-progress`; it only lets planning phases produce or revise draft artifacts before a human accepts them.
+
 ## Project detection
 
 `detectProject()` (in `src/code/runtime/project-detection.ts`) reports repository root, stack hints, config files, and verification presets such as `npm run typecheck` or `npm run test` when package scripts exist. The fake provider is deterministic for local tests.

package/docs/glossary.md

@@ -80,7 +80,7 @@ A redacted, structured report over SDD state, runs, and approvals. Surfaced thro
 
 ## MCP
 
-Model Context Protocol. The agent-facing transport. VGXNESS exposes 38 typed tools over stdio through `vgxness mcp start`. The tool list lives in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`) and is documented in [MCP tools](./mcp.md).
+Model Context Protocol. The agent-facing transport. VGXNESS exposes 41 typed tools over stdio through `vgxness mcp start`. The tool list lives in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`) and is documented in [MCP tools](./mcp.md).
 
 ## Memory observation
 

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP tools
 
-VGXNESS exposes 38 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
+VGXNESS exposes 41 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
 
 Tools are exposed under the `vgxness_*` prefix. Some MCP hosts strip the prefix and accept the short form (`sdd_status`, `memory_save`, etc.). The schema accepts both.
 
@@ -11,16 +11,18 @@ All tools:
 - Return either a typed result or a `VgxMcpError` with a `code` and `message`.
 - Do not require the agent to import or instantiate anything; pass JSON, get JSON.
 
-## SDD workflow (10)
+## SDD workflow (12)
 
 | Tool | Purpose | Required inputs | Notes |
 |---|---|---|---|
 | `vgxness_sdd_status` | Report per-phase artifact presence and the next ready missing phase. | `project`, `change` | |
 | `vgxness_sdd_next` | Recommend the next phase decision for a change. | `project`, `change` | |
+| `vgxness_sdd_continue` | Build a read-only continuation plan for a blocked or interrupted SDD change. | `project`, `change`; optional `payloadMode` (`compact`/`verbose`) | Complements `vgxness_sdd_next` and `vgxness_sdd_cockpit` with copyable next steps. Does not mutate artifacts or runs, execute providers, write provider config, create `openspec/`, or bypass human acceptance. |
 | `vgxness_sdd_ready` | Check whether a specific phase is ready. | `project`, `change`, `phase`; optional `runId`, `agentId` | Returns structured `SddReadiness` with `blockedPrerequisites`. |
 | `vgxness_sdd_get_readiness` | Same as `ready` with explicit output shape. | same as `ready` | |
 | `vgxness_sdd_save_artifact` | Persist phase content under canonical topic key `sdd/{change}/{phase}`. | `project`, `change`, `phase`, `content` | Saving does not imply acceptance. |
 | `vgxness_sdd_accept_artifact` | Record explicit human acceptance for a phase. | `project`, `change`, `phase`, `acceptedBy` (`{type:"human", id, displayName?}`); optional `acceptedAt`, `note`, `runId`, `agentId` | `acceptedBy.type` must be `"human"`. Runtime rejects agent or anonymous acceptance. Only `note` is accepted; `notes` and `rationale` are rejected as unexpected fields. |
+| `vgxness_sdd_reopen_artifact` | Move a rejected artifact back to draft for revision. | `project`, `change`, `phase`, `reopenedBy` (`{type:"human", id, displayName?}`); optional `reopenedAt`, `note`, `runId`, `agentId` | Human-only recovery path. Does not imply acceptance or bypass downstream gates. |
 | `vgxness_sdd_get_artifact` | Read one full artifact. | `project`, `change`, `phase`; optional `payloadMode` (`compact`/`verbose`) | |
 | `vgxness_sdd_list_artifacts` | List all artifacts for a change in canonical phase order. | `project`, `change`; optional `payloadMode` | |
 | `vgxness_sdd_cockpit` | Aggregate per-phase status, blockers, and recommended next action. | `project`, `change` | Returns `SddCockpit` with `aggregateBlockers` of kinds `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. |
@@ -64,7 +66,7 @@ All tools:
 | `vgxness_opencode_manager_payload` | Build the OpenCode manager payload envelope. | `OpenCodeManagerPayloadInput` shape (project, scope, agent, workflow/phase, workspaceRoot, maxSourceBytes, payloadMode) | `installable: false`, `readOnly: true`. |
 | `vgxness_opencode_handoff_preview` | Compose a full handoff preview: provider artifacts + skill diagnostics + SDD status + provider status + safety flags. | `project`; optional `scope`, `agentId`, `agentName`, `workspaceRoot`, `maxSourceBytes`, `change`, `phase` | Read-only preview. Does not execute OpenCode, install hooks, or write provider config. |
 
-## Runs (8)
+## Runs (9)
 
 | Tool | Purpose | Required inputs | Notes |
 |---|---|---|---|
@@ -74,6 +76,7 @@ All tools:
 | `vgxness_run_checkpoint` | Append a resumable JSON state. | `AppendRunCheckpointInput` shape | |
 | `vgxness_run_finalize` | Finalize a run with `outcome` and `outcomeReason`. | `FinalizeRunInput` shape | `outcome` must match a terminal `status`. Re-finalization is rejected. |
 | `vgxness_run_preflight` | Run policy evaluation and return the decision + planned execution isolation strategy. | `PreflightRunOperationInput` shape | May create a pending approval when the decision is `ask`. Does not invoke an executor. |
+| `vgxness_run_resume_candidates` | List recent interrupted runs for a project when the run id is unknown. | `project`; optional `limit` (1-100, default 5) | Returns failed, blocked, and needs-human candidates with `inspectInput` for `run_resume_inspect`. Does not retry, resume, mutate runs, create sandboxes/worktrees, invoke providers, or write artifacts/config. |
 | `vgxness_run_resume_inspect` | Plan-only resume advisory. | `runId` | Returns `RunResumeOrchestrationPlan` with blockers and `nextAction` (`resolve-approval`/`inspect-run`/`retry-check`/`manual-recovery`/`no-action`). |
 | `vgxness_run_resume_gate` | Evaluate retry policy for an approval without executing. | `approvalId`; optional `policy` | Default policy is `never`. See [Safety model](./safety.md) for the policy table. |
 
@@ -107,10 +110,11 @@ Inspecting SDD before doing any work:
 
 ```text
 vgxness_sdd_cockpit    { project: "vgxness", change: "new-flow" }
+vgxness_sdd_continue   { project: "vgxness", change: "new-flow" }
 vgxness_sdd_get_readiness { project: "vgxness", change: "new-flow", phase: "proposal" }
 ```
 
-The cockpit returns `aggregateBlockers`; if any are `unaccepted-phase`, the agent should not run the next phase until a human accepts the prerequisite.
+The cockpit returns `aggregateBlockers`; if any are `unaccepted-phase`, the agent should not run the next phase until a human accepts the prerequisite. `vgxness_sdd_continue` uses the same SDD state to explain how to continue; it is advisory only.
 
 Recording a phase with explicit human acceptance:
 
@@ -130,6 +134,16 @@ vgxness_run_checkpoint  { runId, label: "after-step-1", state: {...} }
 vgxness_run_finalize    { runId, outcome: "success", outcomeReason: "..." }
 ```
 
+Finding interrupted runs when the run id is unknown:
+
+```text
+vgxness_run_resume_candidates { project: "vgxness", limit: 5 }
+vgxness_run_resume_inspect    { runId }
+vgxness_run_resume_gate       { approvalId, policy }
+```
+
+`vgxness_run_resume_candidates` is discovery only. It points to `run_resume_inspect` for a selected candidate and does not admit a retry or resume execution; `run_resume_gate` remains the advisory retry-policy check for a known approval id.
+
 ## Safety boundary
 
 MCP tools do not:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {