vgxness 1.9.1 → 1.9.3

package/dist/mcp/validation.js

@@ -1,6 +1,6 @@
 import { isRiskyPermissionCategory, permissionCategories } from '../permissions/schema.js';
 import { parseOperationRetryPolicy } from '../runs/operation-retry.js';
-import { isSddPhase, sddPhases } from '../sdd/schema.js';
+import { normalizeSddPhaseInput, sddPhases } from '../sdd/schema.js';
 import { workflowIds } from '../workflows/schema.js';
 import { supportedTypeMessage, verificationChangeTypes } from '../verification/index.js';
 import { errorEnvelope, isVgxMcpToolName, } from './schema.js';
@@ -42,6 +42,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSddSaveArtifactInput(input, tool.value));
         case 'vgxness_sdd_accept_artifact':
             return validationSuccess(tool.value, validateSddAcceptArtifactInput(input, tool.value));
+        case 'vgxness_sdd_reopen_artifact':
+            return validationSuccess(tool.value, validateSddReopenArtifactInput(input, tool.value));
         case 'vgxness_sdd_get_artifact':
             return validationSuccess(tool.value, validateSddGetArtifactInput(input, tool.value));
         case 'vgxness_sdd_list_artifacts':
@@ -50,6 +52,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSddNextInput(input, tool.value));
         case 'vgxness_sdd_cockpit':
             return validationSuccess(tool.value, validateSddCockpitInput(input, tool.value));
+        case 'vgxness_sdd_continue':
+            return validationSuccess(tool.value, validateSddContinueInput(input, tool.value));
         case 'vgxness_governance_report':
             return validationSuccess(tool.value, validateGovernanceReportInput(input, tool.value));
         case 'vgxness_memory_save':
@@ -96,6 +100,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateRunCheckpointInput(input, tool.value));
         case 'vgxness_run_finalize':
             return validationSuccess(tool.value, validateRunFinalizeInput(input, tool.value));
+        case 'vgxness_run_resume_candidates':
+            return validationSuccess(tool.value, validateRunResumeCandidatesInput(input, tool.value));
         case 'vgxness_run_resume_inspect':
             return validationSuccess(tool.value, validateRunResumeInspectInput(input, tool.value));
         case 'vgxness_run_resume_gate':
@@ -238,6 +244,21 @@ function validateSddCockpitInput(input, tool) {
         return record;
     return readProjectAndChange(record.value, tool);
 }
+function validateSddContinueInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'change', 'payloadMode']);
+    if (!record.ok)
+        return record;
+    const base = readProjectAndChange(record.value, tool);
+    if (!base.ok)
+        return base;
+    const payloadMode = readOptionalOneOf(record.value, 'payloadMode', payloadModes, tool);
+    if (!payloadMode.ok)
+        return payloadMode;
+    const result = { ...base.value };
+    if (payloadMode.value !== undefined)
+        result.payloadMode = payloadMode.value;
+    return { ok: true, value: result };
+}
 function validateContextCockpitInput(input, tool) {
     const record = inputRecord(input, tool, ['project', 'change', 'directory', 'limit', 'level']);
     if (!record.ok)
@@ -312,7 +333,7 @@ function validateSddSaveArtifactInput(input, tool) {
     return { ok: true, value: { ...base.value, phase: phase.value, content: content.value } };
 }
 function validateSddAcceptArtifactInput(input, tool) {
-    const record = inputRecord(input, tool, ['project', 'change', 'phase', 'acceptedBy', 'acceptedAt', 'note', 'notes', 'rationale', 'runId', 'agentId']);
+    const record = inputRecord(input, tool, ['project', 'change', 'phase', 'acceptedBy', 'acceptedAt', 'note', 'runId', 'agentId']);
     if (!record.ok)
         return record;
     const base = readProjectAndChange(record.value, tool);
@@ -340,7 +361,41 @@ function validateSddAcceptArtifactInput(input, tool) {
     if (displayName.value !== undefined)
         acceptedBy.displayName = displayName.value;
     const result = { ...base.value, phase: phase.value, acceptedBy };
-    const copied = copyOptionalLimitedStrings(result, record.value, tool, ['acceptedAt', 'note', 'notes', 'rationale', 'runId', 'agentId'], undefined);
+    const copied = copyOptionalLimitedStrings(result, record.value, tool, ['acceptedAt', 'note', 'runId', 'agentId'], undefined);
+    if (!copied.ok)
+        return copied;
+    return { ok: true, value: result };
+}
+function validateSddReopenArtifactInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'change', 'phase', 'reopenedBy', 'reopenedAt', 'note', 'runId', 'agentId']);
+    if (!record.ok)
+        return record;
+    const base = readProjectAndChange(record.value, tool);
+    if (!base.ok)
+        return base;
+    const phase = readPhase(record.value, tool);
+    if (!phase.ok)
+        return phase;
+    const reopenedByRecord = asRecord(record.value.reopenedBy, tool, 'reopenedBy is required');
+    if (!reopenedByRecord.ok)
+        return reopenedByRecord;
+    const reopenedByExtra = Object.keys(reopenedByRecord.value).find((key) => !['type', 'id', 'displayName'].includes(key));
+    if (reopenedByExtra !== undefined)
+        return validationFailure(`Unexpected field: reopenedBy.${reopenedByExtra}`, tool);
+    const type = readRequiredOneOf(reopenedByRecord.value, 'type', ['human'], tool);
+    if (!type.ok)
+        return type;
+    const id = readNonEmptyString(reopenedByRecord.value, 'id', tool);
+    if (!id.ok)
+        return id;
+    const displayName = readOptionalNonEmptyString(reopenedByRecord.value, 'displayName', tool);
+    if (!displayName.ok)
+        return displayName;
+    const reopenedBy = { type: type.value, id: id.value };
+    if (displayName.value !== undefined)
+        reopenedBy.displayName = displayName.value;
+    const result = { ...base.value, phase: phase.value, reopenedBy };
+    const copied = copyOptionalLimitedStrings(result, record.value, tool, ['reopenedAt', 'note', 'runId', 'agentId'], undefined);
     if (!copied.ok)
         return copied;
     return { ok: true, value: result };
@@ -935,6 +990,22 @@ function validateRunFinalizeInput(input, tool) {
         return copied;
     return { ok: true, value: result };
 }
+function validateRunResumeCandidatesInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'limit']);
+    if (!record.ok)
+        return record;
+    const project = readNonEmptyString(record.value, 'project', tool);
+    if (!project.ok)
+        return project;
+    const result = { project: project.value };
+    if (record.value.limit !== undefined) {
+        const limit = readBoundedLimit(record.value, tool);
+        if (!limit.ok)
+            return limit;
+        result.limit = limit.value;
+    }
+    return { ok: true, value: result };
+}
 function validateRunResumeInspectInput(input, tool) {
     const record = inputRecord(input, tool, ['runId']);
     if (!record.ok)
@@ -1017,9 +1088,10 @@ function readPhase(record, tool) {
     const phase = readNonEmptyString(record, 'phase', tool);
     if (!phase.ok)
         return phase;
-    if (!isSddPhase(phase.value))
+    const normalized = normalizeSddPhaseInput(phase.value);
+    if (normalized === undefined)
         return validationFailure(`phase must be one of: ${sddPhases.join(', ')}`, tool);
-    return { ok: true, value: phase.value };
+    return { ok: true, value: normalized };
 }
 function copyOptionalStrings(target, record, tool, fields) {
     for (const field of fields) {

package/dist/memory/sqlite/migrations/016_agent_seed_history.sql

@@ -0,0 +1,15 @@
+CREATE TABLE agent_seed_history (
+  id TEXT PRIMARY KEY,
+  applied_at TEXT NOT NULL,
+  from_version INTEGER,
+  to_version INTEGER NOT NULL,
+  agent_name TEXT NOT NULL,
+  project TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  reason TEXT,
+  source TEXT NOT NULL
+);
+
+CREATE INDEX idx_agent_seed_history_applied_at ON agent_seed_history(applied_at);
+CREATE INDEX idx_agent_seed_history_project_scope_name ON agent_seed_history(project, scope, agent_name);

package/dist/resume/product-resume.js

@@ -0,0 +1,166 @@
+import { basename, resolve } from 'node:path';
+const candidateLimit = 5;
+const baseSafety = [
+    'Read-only resume cockpit: does not execute providers, retry operations, edit files, write provider config, create sandboxes, or create worktrees.',
+    'This command only helps inspect interrupted work; any continuation remains an explicit human decision.',
+];
+export function buildProductResume(input) {
+    const initialProject = resolveProject(input);
+    if (input.runId === undefined) {
+        return buildOrientationResume(input, initialProject);
+    }
+    if (input.databaseError !== undefined) {
+        return blockedResume({
+            project: initialProject,
+            runId: input.runId,
+            blocker: `Unable to read local memory store${input.databasePath === undefined ? '' : ` at ${input.databasePath}`}: ${input.databaseError}`,
+            why: 'Run inspection requires a readable local memory store.',
+            command: `vgxness resume --project ${initialProject.value} --run-id ${input.runId} --db <path>`,
+            safety: baseSafety,
+        });
+    }
+    if (input.runs?.getRunOperatorResumePlan === undefined) {
+        return blockedResume({
+            project: initialProject,
+            runId: input.runId,
+            blocker: 'Run resume inspection service is not available for this request.',
+            why: 'Use the installed CLI or provide a readable local memory store.',
+            command: `vgxness resume --project ${initialProject.value} --run-id ${input.runId}`,
+            safety: baseSafety,
+        });
+    }
+    const inspected = input.runs.getRunOperatorResumePlan(input.runId);
+    if (!inspected.ok) {
+        return blockedResume({
+            project: initialProject,
+            runId: input.runId,
+            blocker: inspected.error.message,
+            why: 'VGXNESS could not find or inspect the requested run.',
+            command: `vgxness runs list --project ${initialProject.value}`,
+            safety: baseSafety,
+        });
+    }
+    return fromRunOperatorResumePlan(inspected.value, initialProject, input.databasePath !== undefined);
+}
+function buildOrientationResume(input, project) {
+    const dbHint = input.databasePath === undefined ? '' : ` --db ${input.databasePath}`;
+    const command = `vgxness runs list --project ${project.value} --status failed${dbHint}`;
+    const manualNextCommands = [
+        `vgxness runs list --project ${project.value} --status failed${dbHint}`,
+        `vgxness runs list --project ${project.value} --status blocked${dbHint}`,
+        `vgxness runs list --project ${project.value} --status needs-human${dbHint}`,
+        `vgxness resume --project ${project.value} --run-id <id>${dbHint}`,
+    ];
+    if (input.databaseError !== undefined) {
+        return {
+            version: 1,
+            kind: 'product-resume',
+            mode: 'orientation',
+            project,
+            resumable: false,
+            resume: ['Find an interrupted run, then inspect it before deciding whether to continue manually.'],
+            why: ['No --run-id was provided, so VGXNESS cannot inspect checkpoint, approval, or blocker state for a selected run yet.'],
+            blockers: [`Unable to read local memory store${input.databasePath === undefined ? '' : ` at ${input.databasePath}`}: ${input.databaseError}`],
+            command,
+            manualNextCommands,
+            safety: baseSafety,
+            candidateRuns: [],
+        };
+    }
+    const listed = input.runs?.listRecentInterruptedRuns?.({ project: project.value, limit: candidateLimit });
+    if (listed !== undefined && !listed.ok) {
+        return {
+            version: 1,
+            kind: 'product-resume',
+            mode: 'orientation',
+            project,
+            resumable: false,
+            resume: ['Find an interrupted run, then inspect it before deciding whether to continue manually.'],
+            why: ['No --run-id was provided, so VGXNESS cannot inspect checkpoint, approval, or blocker state for a selected run yet.'],
+            blockers: [listed.error.message],
+            command,
+            manualNextCommands,
+            safety: baseSafety,
+            candidateRuns: [],
+        };
+    }
+    const candidateRuns = (listed?.value ?? []).map((candidate) => ({
+        ...candidate,
+        ...(candidate.userIntent === undefined ? {} : { userIntent: shorten(candidate.userIntent, 72) }),
+        command: `vgxness resume --project ${project.value} --run-id ${candidate.runId}${dbHint}`,
+    }));
+    const why = listed === undefined
+        ? ['No --run-id was provided, so VGXNESS cannot inspect checkpoint, approval, or blocker state for a selected run yet.']
+        : ['No --run-id was provided, so VGXNESS is showing recent failed, blocked, or needs-human runs for this project.'];
+    return {
+        version: 1,
+        kind: 'product-resume',
+        mode: 'orientation',
+        project,
+        resumable: false,
+        resume: candidateRuns.length === 0
+            ? ['Find an interrupted run, then inspect it before deciding whether to continue manually.']
+            : ['Recent interrupted runs were found. Inspect one before deciding whether to continue manually.'],
+        why,
+        blockers: [],
+        command,
+        manualNextCommands,
+        safety: [listed === undefined ? 'Did not open the local memory store because no project-specific run lookup was requested.' : 'Opened the local memory store read-only to list recent interrupted runs.', ...baseSafety],
+        candidateRuns,
+    };
+}
+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 fromRunOperatorResumePlan(inspect, fallbackProject, includeDbHint) {
+    const project = { value: inspect.run.project || fallbackProject.value, source: 'run' };
+    const blockerLines = inspect.blockers.map((blocker) => (blocker.relatedId === undefined ? blocker.message : `${blocker.message} (${blocker.relatedId})`));
+    const latestCheckpoint = inspect.latestCheckpoint === null ? 'none' : `${inspect.latestCheckpoint.label} (${inspect.latestCheckpoint.id})`;
+    const dbHint = includeDbHint ? ' --db <path>' : '';
+    return {
+        version: 1,
+        kind: 'product-resume',
+        mode: 'inspect',
+        project,
+        runId: inspect.run.id,
+        resumable: inspect.resumePlan.resumable,
+        resume: [inspect.resumePlan.recommendedAction],
+        why: [
+            `Run: ${inspect.run.id}`,
+            `Status: ${inspect.run.status}`,
+            `Workflow: ${inspect.run.workflow} / ${inspect.run.phase}`,
+            `Latest checkpoint: ${latestCheckpoint}`,
+            inspect.debug.summary,
+        ],
+        blockers: blockerLines,
+        command: `vgxness resume --project ${project.value} --run-id ${inspect.run.id}${dbHint}`,
+        manualNextCommands: inspect.manualNextCommands,
+        safety: baseSafety,
+        candidateRuns: [],
+        inspect,
+    };
+}
+function blockedResume(input) {
+    return {
+        version: 1,
+        kind: 'product-resume',
+        mode: 'inspect',
+        project: input.project,
+        runId: input.runId,
+        resumable: false,
+        resume: ['Resolve the blocker, then inspect the run again before deciding whether to continue manually.'],
+        why: [`Run: ${input.runId}`, input.why],
+        blockers: [input.blocker],
+        command: input.command,
+        manualNextCommands: [input.command],
+        safety: input.safety,
+        candidateRuns: [],
+    };
+}
+function shorten(value, maxLength) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3)}...`;
+}

package/dist/runs/repositories/runs.js

@@ -70,13 +70,24 @@ export class RunRepository {
                 where.push('status=@status');
                 parameters.status = filters.status;
             }
+            if (filters.statuses !== undefined && filters.statuses.length > 0) {
+                const statusPlaceholders = filters.statuses.map((_, index) => `@status${index}`);
+                where.push(`status IN (${statusPlaceholders.join(', ')})`);
+                for (const [index, status] of filters.statuses.entries())
+                    parameters[`status${index}`] = status;
+            }
+            const limitClause = filters.limit === undefined ? '' : 'LIMIT @limit';
+            const queryParameters = { ...parameters };
+            if (filters.limit !== undefined)
+                queryParameters.limit = filters.limit;
             const rows = this.db.connection
                 .prepare(`
         SELECT * FROM runs
         ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
         ORDER BY created_at DESC
+        ${limitClause}
       `)
-                .all(parameters);
+                .all(queryParameters);
             return ok(rows.map(mapRun));
         }
         catch (cause) {

package/dist/runs/run-service.js

@@ -1,5 +1,6 @@
 import { evaluatePermission } from '../permissions/policy-evaluator.js';
 import { isRiskyPermissionCategory } from '../permissions/schema.js';
+import { normalizeSddPhaseInput } from '../sdd/schema.js';
 import { planExecutionIsolation } from './execution-planning.js';
 import { evaluateOperationRetry as evaluateOperationRetryPolicy } from './operation-retry.js';
 import { RunRepository, } from './repositories/runs.js';
@@ -28,7 +29,7 @@ export class RunService {
         this.runs = new RunRepository(database);
     }
     createRun(input) {
-        return this.runs.create(input);
+        return this.runs.create({ ...input, phase: canonicalRunPhase(input.workflow, input.phase) ?? input.phase });
     }
     getRun(id) {
         return this.runs.getDetails(id);
@@ -44,6 +45,53 @@ export class RunService {
     listRuns(filters = {}) {
         return this.runs.list(filters);
     }
+    listRecentInterruptedRuns(input) {
+        const runs = this.runs.list({ project: input.project, statuses: ['failed', 'blocked', 'needs-human'], limit: input.limit ?? 5 });
+        if (!runs.ok)
+            return runs;
+        const candidates = [];
+        for (const run of runs.value) {
+            const details = this.runs.getDetails(run.id);
+            if (!details.ok)
+                return details;
+            const latestCheckpoint = details.value.checkpoints.at(-1);
+            const userIntent = details.value.userIntent.trim();
+            candidates.push({
+                runId: details.value.id,
+                status: details.value.status,
+                workflow: details.value.workflow,
+                phase: details.value.phase,
+                ...(userIntent.length === 0 ? {} : { userIntent }),
+                ...(latestCheckpoint === undefined ? {} : { latestCheckpointLabel: latestCheckpoint.label }),
+            });
+        }
+        return { ok: true, value: candidates };
+    }
+    findRelatedInterruptedSddRun(input) {
+        const runs = this.runs.list({ project: input.project, statuses: ['failed', 'blocked', 'needs-human'], limit: input.limit ?? 25 });
+        if (!runs.ok)
+            return runs;
+        for (const run of runs.value) {
+            const details = this.runs.getDetails(run.id);
+            if (!details.ok)
+                return details;
+            const hasMatchingCheckpoint = details.value.checkpoints.some((checkpoint) => checkpointHasChangeId(checkpoint.state, input.change));
+            if (!hasMatchingCheckpoint)
+                continue;
+            const latestCheckpoint = details.value.checkpoints.at(-1);
+            return {
+                ok: true,
+                value: {
+                    runId: details.value.id,
+                    status: details.value.status,
+                    workflow: details.value.workflow,
+                    phase: details.value.phase,
+                    ...(latestCheckpoint === undefined ? {} : { latestCheckpointLabel: latestCheckpoint.label }),
+                },
+            };
+        }
+        return { ok: true, value: undefined };
+    }
     appendEvent(input) {
         return this.runs.appendEvent(input);
     }
@@ -695,10 +743,11 @@ export class RunService {
         const run = this.runs.getById(input.runId);
         if (!run.ok)
             return { ok: false, error: run.error };
-        const phase = input.phase ?? canonicalRunPhase(run.value.phase);
+        const workflow = input.workflow ?? run.value.workflow;
+        const phase = canonicalRunPhase(workflow, input.phase) ?? canonicalRunPhase(run.value.workflow, run.value.phase);
         const merged = {
             ...input,
-            workflow: input.workflow ?? run.value.workflow,
+            workflow,
             ...(phase === undefined ? {} : { phase }),
             agentId: input.agentId ?? input.agent?.id ?? run.value.selectedAgentId,
         };
@@ -799,6 +848,9 @@ export class RunService {
         return { ok: true, value: resolved[0] };
     }
 }
+function checkpointHasChangeId(state, change) {
+    return typeof state === 'object' && state !== null && !Array.isArray(state) && state.changeId === change;
+}
 function preflightOutcome(decision) {
     if (decision.decision === 'allow')
         return 'allowed';
@@ -883,10 +935,15 @@ function resumeGateManualNextCommands(approval, details, operation) {
         commands.push(`Review operation manually: ${operation.category} ${operation.operation}`);
     return commands;
 }
-function canonicalRunPhase(phase) {
+function canonicalRunPhase(workflow, phase) {
     if (phase === undefined || phase.trim().length === 0)
         return undefined;
-    return phase === 'apply' ? 'apply-progress' : phase;
+    if (!isSddWorkflow(workflow))
+        return phase;
+    return normalizeSddPhaseInput(phase) ?? phase;
+}
+function isSddWorkflow(workflow) {
+    return workflow?.trim().toLowerCase() === 'sdd';
 }
 function operationMetadata(input) {
     const metadata = { category: input.category, name: input.operation };

package/dist/runs/schema.js

@@ -1 +1,5 @@
+export const TERMINAL_RUN_STATUSES = ['completed', 'failed', 'blocked', 'cancelled'];
+export function isTerminalRunStatus(status) {
+    return TERMINAL_RUN_STATUSES.includes(status);
+}
 export const runSnapshotPackageKind = 'vgxness.run-snapshot-package';

package/dist/sdd/schema.js

@@ -30,10 +30,22 @@ export const SddArtifactAcceptanceRecordSchema = z
     note: z.string().optional(),
 })
     .strict();
+export const SddArtifactReopenRecordSchema = z
+    .object({
+    actor: z.object({
+        type: z.literal('human'),
+        id: z.string().min(1),
+        displayName: z.string().min(1).optional(),
+    }),
+    reopenedAt: z.string().min(1),
+    note: z.string().optional(),
+})
+    .strict();
 export const SddArtifactMetadataSchema = z
     .object({
     status: SddArtifactStatusSchema,
     acceptance: SddArtifactAcceptanceRecordSchema.optional(),
+    reopen: SddArtifactReopenRecordSchema.optional(),
     supersededByTopicKey: z.string().min(1).optional(),
     updatedAt: z.string().min(1).optional(),
 })
@@ -86,6 +98,14 @@ export const sddPrerequisites = {
 export function isSddPhase(value) {
     return sddPhases.includes(value);
 }
+export function normalizeSddPhaseInput(value) {
+    const normalized = value.trim();
+    if (normalized === 'apply')
+        return 'apply-progress';
+    if (isSddPhase(normalized))
+        return normalized;
+    return undefined;
+}
 export function sddTopicKey(change, phase) {
     return `sdd/${change}/${phase}`;
 }

package/dist/sdd/sdd-continuation-plan.js

@@ -0,0 +1,81 @@
+export function sddContinuationPlanFrom(input) {
+    const nextPhase = input.next.nextPhase;
+    const dbFlag = continuationDbFlag(input.explicitDatabasePath);
+    const inspectCommand = `vgxness sdd cockpit --project ${input.project} --change ${input.next.change} --json${dbFlag}`;
+    const suggestedCommand = suggestedContinuationCommand(input.project, input.next, inspectCommand, dbFlag);
+    const blockerGuidance = input.next.blockerGuidance ?? [];
+    const blockerActions = blockerGuidance.map((blocker) => continuationBlockerAction(input.project, input.next.change, input.next.nextPhase, blocker, dbFlag));
+    const hasDraftRunAction = blockerActions.some((action) => action.draftRunCommand !== undefined);
+    const relatedRunContext = relatedRunContextView(input.project, input.relatedRunContext, dbFlag);
+    return {
+        kind: 'sdd-continuation-plan',
+        project: input.project,
+        change: input.next.change,
+        status: input.next.status,
+        ...(nextPhase === undefined ? {} : { nextPhase }),
+        ...(input.cockpit.actionablePhase === undefined ? {} : { actionablePhase: input.cockpit.actionablePhase }),
+        recommendedAction: input.cockpit.recommendedAction,
+        reason: input.next.reason,
+        suggestedCommand,
+        inspectCommand,
+        blockerActions,
+        ...(relatedRunContext === undefined ? {} : { relatedRunContext }),
+        ...(input.explicitDatabasePath === undefined ? {} : { explicitDatabasePath: input.explicitDatabasePath }),
+        safety: [
+            'Read-only planner: this command does not execute providers or mutate SDD artifacts, runs, provider config, or openspec/ files.',
+            'Human acceptance remains explicit; artifact presence is not treated as acceptance.',
+            ...(hasDraftRunAction ? [draftRunWarning()] : []),
+            'No openspec/ files are created or written.',
+        ],
+    };
+}
+function relatedRunContextView(project, relatedRunContext, dbFlag) {
+    if (relatedRunContext === undefined)
+        return undefined;
+    return {
+        ...relatedRunContext,
+        recommendation: 'Related interrupted run found by checkpoint changeId; inspect or resume it before starting duplicate SDD work. Advisory only.',
+        resumeCommand: `vgxness resume --project ${project} --run-id ${relatedRunContext.runId}${dbFlag}`,
+    };
+}
+function suggestedContinuationCommand(project, next, fallbackInspectCommand, dbFlag) {
+    if (next.status === 'runnable' && next.nextPhase !== undefined)
+        return runPhaseCommand(project, next.change, next.nextPhase, dbFlag);
+    return fallbackInspectCommand;
+}
+function continuationBlockerAction(project, change, blockedPhase, blocker, dbFlag) {
+    const draftRunCommand = blocker.reason === 'draft' && isDraftRunPlanningPhase(blockedPhase) ? draftRunPhaseCommand(project, change, blockedPhase, dbFlag) : undefined;
+    return {
+        phase: blocker.phase,
+        topicKey: blocker.topicKey,
+        reason: blocker.reason,
+        action: blocker.action,
+        command: blockerCommand(project, change, blocker, dbFlag),
+        ...(draftRunCommand === undefined ? {} : { draftRunCommand, warning: draftRunWarning() }),
+        ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
+    };
+}
+function blockerCommand(project, change, blocker, dbFlag) {
+    if (blocker.reason === 'missing')
+        return runPhaseCommand(project, change, blocker.phase, dbFlag);
+    if (blocker.reason === 'draft' || blocker.reason === 'legacy')
+        return `vgxness sdd accept-artifact --project ${project} --change ${change} --phase ${blocker.phase} --actor <human-id>${dbFlag}`;
+    if (blocker.reason === 'rejected')
+        return `vgxness sdd reopen-artifact --project ${project} --change ${change} --phase ${blocker.phase} --actor <human-id>${dbFlag}`;
+    return `vgxness sdd get-artifact --project ${project} --change ${change} --phase ${blocker.phase} --json${dbFlag}`;
+}
+function runPhaseCommand(project, change, phase, dbFlag) {
+    return `vgxness code sdd ${change} ${phase} --project ${project} --save-artifact${dbFlag}`;
+}
+function draftRunPhaseCommand(project, change, phase, dbFlag) {
+    return `vgxness code sdd ${change} ${phase} --project ${project} --draft-run --save-artifact${dbFlag}`;
+}
+function isDraftRunPlanningPhase(phase) {
+    return phase === 'explore' || phase === 'proposal' || phase === 'spec' || phase === 'design' || phase === 'tasks';
+}
+function draftRunWarning() {
+    return 'Draft-run is planning-only; human acceptance is still required; apply-progress remains gated.';
+}
+function continuationDbFlag(explicitDatabasePath) {
+    return explicitDatabasePath === undefined ? '' : ` --db ${explicitDatabasePath}`;
+}