vgxness 1.9.2 → 1.9.3

package/dist/skills/skill-resolver.js

@@ -1,3 +1,4 @@
+import { normalizeSddPhaseInput } from '../sdd/schema.js';
 export class SkillResolver {
     skills;
     agents;
@@ -113,10 +114,13 @@ export class SkillResolver {
             targets.push({ targetType: agent.mode, targetKey: agent.name });
             targets.push({ targetType: agent.mode, targetKey: `${agent.project}/${agent.scope}/${agent.name}` });
         }
-        if (input.workflow !== undefined && input.phase !== undefined)
-            targets.push({ targetType: 'workflow-phase', targetKey: `${input.workflow}:${input.phase}` });
-        if (input.phase !== undefined)
-            targets.push({ targetType: 'workflow-phase', targetKey: input.phase });
+        const phases = phaseTargetKeys(input.workflow, input.phase);
+        if (input.workflow !== undefined) {
+            for (const phase of phases)
+                targets.push({ targetType: 'workflow-phase', targetKey: `${input.workflow}:${phase}` });
+        }
+        for (const phase of phases)
+            targets.push({ targetType: 'workflow-phase', targetKey: phase });
         if (input.providerAdapter !== undefined)
             targets.push({ targetType: 'provider-adapter', targetKey: input.providerAdapter });
         return dedupeTargets(targets);
@@ -212,6 +216,19 @@ function dedupeTargets(targets) {
         return true;
     });
 }
+function phaseTargetKeys(workflow, phase) {
+    if (phase === undefined)
+        return [];
+    if (!isSddWorkflow(workflow))
+        return [phase];
+    const normalized = normalizeSddPhaseInput(phase);
+    if (normalized === 'apply-progress')
+        return ['apply-progress', 'apply'];
+    return normalized === undefined || normalized === phase ? [phase] : [normalized, phase];
+}
+function isSddWorkflow(workflow) {
+    return workflow?.trim().toLowerCase() === 'sdd';
+}
 function stringMetadata(value) {
     return typeof value === 'string' && value.trim() ? value : undefined;
 }

package/dist/status/product-status.js

@@ -0,0 +1,117 @@
+import { basename, resolve } from 'node:path';
+export function buildProductStatus(input) {
+    const project = resolveProject(input);
+    const baseSafety = [
+        'Read-only cockpit: does not execute providers, edit files, write provider config, or mutate SDD artifacts.',
+        'Human acceptance remains explicit; saved artifacts do not imply acceptance.',
+    ];
+    if (input.change === undefined) {
+        return {
+            version: 1,
+            kind: 'product-status',
+            project,
+            status: [`Project: ${project.value} (${project.source === 'flag' ? 'from --project' : 'inferred from cwd'})`, 'Change: not selected'],
+            blockers: ['No --change was provided, so VGXNESS cannot inspect SDD phase state yet.'],
+            next: ['Choose the active change id, then re-run status for the SDD cockpit view.'],
+            command: `vgxness status --project ${project.value} --change <change>`,
+            safety: ['Did not open the local memory store because no change was selected.', ...baseSafety],
+        };
+    }
+    if (input.databaseError !== undefined) {
+        return blockedStatus({
+            project,
+            change: input.change,
+            blocker: `Unable to read local memory store${input.databasePath === undefined ? '' : ` at ${input.databasePath}`}: ${input.databaseError}`,
+            next: 'Check --db, VGXNESS_DB_PATH, or run setup/status commands with the installed Bun runtime.',
+            command: `vgxness status --project ${project.value} --change ${input.change} --db <path>`,
+            safety: baseSafety,
+        });
+    }
+    if (input.sdd === undefined) {
+        return blockedStatus({
+            project,
+            change: input.change,
+            blocker: 'SDD cockpit service is not available for this status request.',
+            next: 'Use the installed CLI or provide a readable local memory store.',
+            command: `vgxness sdd cockpit --project ${project.value} --change ${input.change}`,
+            safety: baseSafety,
+        });
+    }
+    const cockpit = input.sdd.getCockpit({ project: project.value, change: input.change });
+    if (!cockpit.ok) {
+        return blockedStatus({
+            project,
+            change: input.change,
+            blocker: cockpit.error.message,
+            next: 'Review the project/change flags and local memory store, then re-run status.',
+            command: `vgxness sdd cockpit --project ${project.value} --change ${input.change}`,
+            safety: baseSafety,
+        });
+    }
+    const relatedRunContext = findRelatedRunContext({
+        project: project.value,
+        change: input.change,
+        ...(input.runs === undefined ? {} : { runs: input.runs }),
+        ...(input.explicitDatabasePath === undefined ? {} : { explicitDatabasePath: input.explicitDatabasePath }),
+    });
+    return fromSddCockpit(cockpit.value, project, baseSafety, relatedRunContext);
+}
+function resolveProject(input) {
+    if (input.project !== undefined && input.project.trim().length > 0)
+        return { value: input.project.trim(), source: 'flag' };
+    const directoryName = basename(resolve(input.cwd));
+    return { value: directoryName.length > 0 ? directoryName : 'unknown-project', source: 'cwd' };
+}
+function fromSddCockpit(cockpit, project, baseSafety, relatedRunContext) {
+    const nextLabel = cockpit.next.nextPhase === undefined ? cockpit.next.status : `${cockpit.next.status} / ${cockpit.next.nextPhase}`;
+    const command = cockpit.next.status === 'runnable' && cockpit.next.nextPhase !== undefined
+        ? `vgxness code sdd ${cockpit.change} ${cockpit.next.nextPhase} --project ${cockpit.project} --save-artifact`
+        : `vgxness sdd cockpit --project ${cockpit.project} --change ${cockpit.change} --json`;
+    return {
+        version: 1,
+        kind: 'product-status',
+        project,
+        change: cockpit.change,
+        status: [
+            `Project: ${cockpit.project}`,
+            `Change: ${cockpit.change}`,
+            `Next: ${nextLabel}`,
+            `Accepted: ${cockpit.acceptedCount}/${cockpit.phases.length}`,
+            `Legacy artifacts: ${cockpit.legacyCount}`,
+        ],
+        blockers: cockpit.aggregateBlockers.length === 0
+            ? ['none']
+            : cockpit.aggregateBlockers.map((blocker) => `${blocker.phase}: ${blocker.reason} at ${blocker.topicKey}${blocker.action === undefined ? '' : `; action=${blocker.action}`}`),
+        next: [cockpit.recommendedAction],
+        command,
+        sddNextStatus: cockpit.next.status,
+        ...(relatedRunContext === undefined ? {} : { relatedRunContext }),
+        safety: baseSafety,
+    };
+}
+function findRelatedRunContext(input) {
+    if (input.runs === undefined)
+        return undefined;
+    const relatedRun = input.runs.findRelatedInterruptedSddRun({ project: input.project, change: input.change });
+    if (!relatedRun.ok || relatedRun.value === undefined)
+        return undefined;
+    const dbFlag = input.explicitDatabasePath === undefined ? '' : ` --db ${input.explicitDatabasePath}`;
+    return {
+        ...relatedRun.value,
+        recommendation: 'Related interrupted run found by checkpoint changeId; inspect or resume it before starting duplicate SDD work. Advisory only.',
+        resumeCommand: `vgxness resume --project ${input.project} --run-id ${relatedRun.value.runId}${dbFlag}`,
+    };
+}
+function blockedStatus(input) {
+    return {
+        version: 1,
+        kind: 'product-status',
+        project: input.project,
+        change: input.change,
+        status: [`Project: ${input.project.value}`, `Change: ${input.change}`, 'Status: blocked'],
+        blockers: [input.blocker],
+        next: [input.next],
+        command: input.command,
+        safety: input.safety,
+    };
+}

package/docs/architecture.md

@@ -625,7 +625,7 @@ The code runtime layers a second, finer-grained decision on top of the policy ev
 
 CLI surface groups are documented in [CLI reference](./cli.md). The plural form is canonical — singular shortcuts are not added.
 
-MCP tools mirror the same core services for agent use. The full, current list of 38 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations and the code runtime sit on the execution plane.
+MCP tools mirror the same core services for agent use. The full, current list of 41 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations and the code runtime sit on the execution plane.
 
 ## Evaluation strategy
 

package/docs/cli.md

@@ -59,7 +59,9 @@ 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>
+vgxness next --project <project> --change <change>
+vgxness resume --project <project> --run-id <id>
 vgxness setup rollback --backup <path>
 ```
 
@@ -67,6 +69,21 @@ vgxness setup rollback --backup <path>
 
 `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 these top-level commands before dropping into lower-level SDD or run inspection commands:
+
+| Question | Command | Purpose |
+|---|---|---|
+| Where am I? | `vgxness status --project <project> --change <change>` | Shows the SDD cockpit state, blockers, next recommendation, and safety notes. |
+| What should I do now? | `vgxness next --project <project> --change <change>` | Narrows the cockpit to the next action and why it is safe or blocked. |
+| How do I continue a change? | `vgxness sdd continue --project <project> --change <change>` | Builds a read-only continuation plan 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 is: inspect `status`, ask `next`, run `sdd continue` for the copyable continuation plan, then either run `vgxness code sdd ...` for phase work or `vgxness resume ...` for an interrupted run. 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`.
@@ -226,7 +243,9 @@ 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:
@@ -283,7 +302,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 +452,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
 
@@ -549,18 +568,24 @@ Use `sdd` commands to inspect local SDD artifact state and save, read, or list p
 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. `sdd continue` turns that state into a read-only continuation plan, including 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, and artifact persistence only. It does **not** execute providers, retry workflow runs, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
 
 ## Agent resolution
 
@@ -953,7 +978,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.3",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {