voratiq 0.1.0-beta.21 → 0.1.0-beta.23

package/dist/cli/list.js

@@ -2,7 +2,8 @@ import { Command } from "commander";
 import { executeListCommand } from "../commands/list/command.js";
 import { resolveCliContext } from "../preflight/index.js";
 import { parsePositiveInteger } from "../utils/validators.js";
-import { resolveWorkspacePath, VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VORATIQ_VERIFICATION_FILE, } from "../workspace/structure.js";
+import { VORATIQ_INTERACTIVE_FILE, VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VORATIQ_VERIFICATION_FILE, } from "../workspace/constants.js";
+import { resolveWorkspacePath } from "../workspace/path-resolvers.js";
 import { parseListInspectionCommandOptions } from "./contract.js";
 import { writeCommandOutput } from "./output.js";
 export async function runListCommand(options) {
@@ -19,6 +20,8 @@ export async function runListCommand(options) {
             resolveWorkspacePath(root, VORATIQ_MESSAGE_FILE),
         verificationsFilePath: workspacePaths.verificationsFile ??
             resolveWorkspacePath(root, VORATIQ_VERIFICATION_FILE),
+        interactiveFilePath: workspacePaths.interactiveFile ??
+            resolveWorkspacePath(root, VORATIQ_INTERACTIVE_FILE),
         operator: options.operator,
         sessionId: options.sessionId,
         limit: options.limit,
@@ -45,6 +48,7 @@ export function createListCommand() {
         .option("--reduce [session-id]", "List reduction sessions or show one reduction session")
         .option("--verify [session-id]", "List verification sessions or show one verification session")
         .option("--message [session-id]", "List message sessions or show one message session")
+        .option("--interactive [session-id]", "List interactive sessions or show one interactive session")
         .option("--limit <count>", "Show only the N most recent sessions (default: 10)", parseLimitOption)
         .option("--verbose", "Show all statuses for the selected operator in table mode")
         .option("--json", "Emit machine-readable list output")

package/dist/cli/message.js

@@ -4,15 +4,17 @@ import { checkPlatformSupport } from "../agents/runtime/sandbox.js";
 import { executeMessageCommand } from "../commands/message/command.js";
 import { buildMarkdownPreviewLines } from "../commands/shared/preview.js";
 import { resolveExtraContextFiles } from "../competition/shared/extra-context.js";
+import { resolveInteractiveSessionEnvLineage } from "../domain/interactive/session-env.js";
 import { ensureSandboxDependencies, resolveCliContext, } from "../preflight/index.js";
 import { createMessageRenderer, formatMessageElapsed, formatMessageRecipientDuration, renderMessageTranscript, } from "../render/transcripts/message.js";
 import { renderWorkspaceAutoInitializedNotice } from "../render/transcripts/shared.js";
 import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
 import { resolvePath } from "../utils/path.js";
-import { parsePositiveInteger } from "../utils/validators.js";
-import { resolveWorkspacePath, VORATIQ_MESSAGE_FILE, } from "../workspace/structure.js";
+import { VORATIQ_MESSAGE_FILE } from "../workspace/constants.js";
+import { resolveWorkspacePath } from "../workspace/path-resolvers.js";
 import { parseMessageExecutionCommandOptions } from "./contract.js";
 import { buildMessageOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { collectRepeatedStringOption, parseMaxParallelOption, } from "./option-parsers.js";
 import { writeCommandOutput } from "./output.js";
 export async function runMessageCommand(options) {
     const { prompt, agentIds, profile, maxParallel, extraContext, json = false, stdout, stderr, writeOutput, } = options;
@@ -52,6 +54,10 @@ export async function runMessageCommand(options) {
         stdout: rendererStdout,
         stderr: rendererStderr,
     });
+    const envLineage = await resolveInteractiveSessionEnvLineage({
+        root,
+        envValue: process.env.VORATIQ_INTERACTIVE_SESSION_ID,
+    });
     const execution = await executeMessageCommand({
         root,
         messagesFilePath: workspacePaths.messagesFile ??
@@ -61,7 +67,12 @@ export async function runMessageCommand(options) {
         profileName: profile,
         maxParallel,
         extraContextFiles,
-        sourceInteractiveSessionId: process.env.VORATIQ_INTERACTIVE_SESSION_ID?.trim() || undefined,
+        target: envLineage.kind === "trusted"
+            ? {
+                kind: "interactive",
+                sessionId: envLineage.sessionId,
+            }
+            : undefined,
         renderer,
     });
     const body = renderMessageTranscript({
@@ -101,24 +112,18 @@ export async function runMessageCommand(options) {
         })),
     };
 }
-function collectStringOption(value, previous) {
-    return [...previous, value];
-}
-function parseMaxParallelOption(value) {
-    return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
-}
 export function createMessageCommand() {
     return new Command("message")
         .description("Send an isolated prompt to one or more agents")
         .requiredOption("--prompt <text>", "Prompt to send")
         .addOption(new Option("--agent <agent-id>", "Set recipient agents directly (repeatable; order preserved)")
         .default([], "")
-        .argParser(collectStringOption))
+        .argParser(collectRepeatedStringOption))
         .option("--profile <name>", 'Orchestration profile (default: "default")')
         .option("--max-parallel <count>", "Max concurrent recipients (default: all)", parseMaxParallelOption)
         .addOption(new Option("--extra-context <path>", "Stage an extra context file into each recipient workspace (repeatable)")
         .default([], "")
-        .argParser(collectStringOption))
+        .argParser(collectRepeatedStringOption))
         .option("--json", "Emit a machine-readable result envelope")
         .allowExcessArguments(false)
         .action(async (options, command) => {

package/dist/cli/operator-envelope.d.ts

@@ -1,16 +1,31 @@
 import { z } from "zod";
 import type { ReductionTarget } from "../domain/reduce/model/types.js";
+import type { RunSpecTarget } from "../domain/run/model/types.js";
 import type { SelectionDecision } from "../policy/index.js";
 import type { ReductionStatus, RunStatus, VerificationStatus } from "../status/index.js";
 import { externalExecutionOperators } from "./contract.js";
 export type EnvelopeOperator = (typeof externalExecutionOperators)[number];
-export type EnvelopeStatus = "succeeded" | "failed" | "unresolved";
+export type EnvelopeStatus = "queued" | "running" | "succeeded" | "failed" | "unresolved";
 export interface EnvelopeArtifactRef {
     kind: string;
     path: string;
     role?: string;
     agentId?: string;
 }
+export interface EnvelopeTargetRef {
+    kind: string;
+    sessionId: string;
+    lineage?: string;
+    issueCode?: string;
+    currentContentHash?: string;
+    source?: {
+        kind?: string;
+        sessionId?: string;
+        agentId?: string;
+        outputPath?: string;
+        contentHash?: string;
+    };
+}
 export interface OperatorResultEnvelope {
     version: 1;
     operator: EnvelopeOperator;
@@ -24,10 +39,7 @@ export interface OperatorResultEnvelope {
         messageId?: string;
         agentId?: string;
     };
-    target?: {
-        kind: string;
-        sessionId: string;
-    };
+    target?: EnvelopeTargetRef;
     artifacts: EnvelopeArtifactRef[];
     selection?: {
         state: "resolvable" | "unresolved";
@@ -51,14 +63,16 @@ export declare const operatorResultEnvelopeSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     operator: z.ZodEnum<{
         message: "message";
+        spec: "spec";
         reduce: "reduce";
         apply: "apply";
-        spec: "spec";
         run: "run";
         verify: "verify";
         prune: "prune";
     }>;
     status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
         succeeded: "succeeded";
         failed: "failed";
         unresolved: "unresolved";
@@ -114,7 +128,7 @@ export interface VerifyEnvelopeInput {
         sessionId: string;
     };
     outputPath: string;
-    status: VerificationStatus;
+    status: VerificationStatus | "unresolved";
     selection?: SelectionDecision;
     selectedSpecPath?: string;
     warningMessage?: string;
@@ -166,11 +180,17 @@ export declare function buildSpecOperatorEnvelope(options: {
 export declare function buildRunOperatorEnvelope(options: {
     runId: string;
     specPath: string;
+    specTarget?: RunSpecTarget;
     status: RunStatus;
 }): OperatorResultEnvelope;
 export declare function buildVerifyOperatorEnvelope(options: VerifyEnvelopeInput): OperatorResultEnvelope;
 export declare function buildReduceOperatorEnvelope(options: ReduceEnvelopeInput): OperatorResultEnvelope;
 export declare function buildMessageOperatorEnvelope(options: MessageEnvelopeInput): OperatorResultEnvelope;
+export declare function buildSwarmSessionAcknowledgementEnvelope(options: {
+    operator: Extract<EnvelopeOperator, "spec" | "run" | "reduce" | "verify" | "message">;
+    sessionId: string;
+    status: Extract<EnvelopeStatus, "queued" | "running" | "succeeded" | "failed">;
+}): OperatorResultEnvelope;
 export declare function buildApplyOperatorEnvelope(options: ApplyEnvelopeInput): OperatorResultEnvelope;
 export declare function buildPruneOperatorEnvelope(options: PruneEnvelopeInput): OperatorResultEnvelope;
 export declare function writeOperatorResultEnvelope(envelope: OperatorResultEnvelope, exitCode?: number): void;

package/dist/cli/operator-envelope.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
-import { getMessageSessionDirectoryPath, getReductionSessionDirectoryPath, getRunDirectoryPath, getSpecSessionDirectoryPath, } from "../workspace/structure.js";
+import { getMessageSessionDirectoryPath, getReductionSessionDirectoryPath, getRunDirectoryPath, getSpecSessionDirectoryPath, getVerificationSessionDirectoryPath, } from "../workspace/session-paths.js";
 import { externalExecutionOperators } from "./contract.js";
 import { toCliError } from "./errors.js";
 export const operatorResultEnvelopeSchema = z
     .object({
     version: z.literal(1),
     operator: z.enum(externalExecutionOperators),
-    status: z.enum(["succeeded", "failed", "unresolved"]),
+    status: z.enum(["queued", "running", "succeeded", "failed", "unresolved"]),
     timestamp: z.string(),
     ids: z
         .object({
@@ -131,6 +131,8 @@ export function buildSpecOperatorEnvelope(options) {
     });
 }
 export function buildRunOperatorEnvelope(options) {
+    const target = buildRunEnvelopeTarget(options.specTarget);
+    const alerts = buildRunEnvelopeAlerts(options.specTarget);
     return buildOperatorEnvelope({
         operator: "run",
         status: normalizeTerminalStatus(options.status),
@@ -149,10 +151,12 @@ export function buildRunOperatorEnvelope(options) {
                 path: options.specPath,
             },
         ],
+        target,
+        alerts,
     });
 }
 export function buildVerifyOperatorEnvelope(options) {
-    const status = options.selection?.state === "unresolved"
+    const status = options.status === "unresolved" || options.selection?.state === "unresolved"
         ? "unresolved"
         : normalizeTerminalStatus(options.status);
     const ids = {
@@ -232,6 +236,9 @@ export function buildReduceOperatorEnvelope(options) {
     if (options.target.type === "reduce") {
         ids.reductionId = options.target.id;
     }
+    if (options.target.type === "message") {
+        ids.messageId = options.target.id;
+    }
     return buildOperatorEnvelope({
         operator: "reduce",
         status: normalizeTerminalStatus(options.status),
@@ -278,6 +285,38 @@ export function buildMessageOperatorEnvelope(options) {
         ],
     });
 }
+export function buildSwarmSessionAcknowledgementEnvelope(options) {
+    const ids = options.operator === "run"
+        ? { runId: options.sessionId }
+        : { sessionId: options.sessionId };
+    const sessionPath = options.operator === "spec"
+        ? getSpecSessionDirectoryPath(options.sessionId)
+        : options.operator === "run"
+            ? getRunDirectoryPath(options.sessionId)
+            : options.operator === "reduce"
+                ? getReductionSessionDirectoryPath(options.sessionId)
+                : options.operator === "verify"
+                    ? getVerificationSessionDirectoryPath(options.sessionId)
+                    : getMessageSessionDirectoryPath(options.sessionId);
+    return buildOperatorEnvelope({
+        operator: options.operator,
+        status: options.status,
+        ids,
+        artifacts: [
+            {
+                kind: "session",
+                role: "session",
+                path: sessionPath,
+            },
+        ],
+        alerts: [
+            {
+                level: "info",
+                message: "Recorded swarm session acknowledged. Use `voratiq_list` to inspect progress instead of retrying.",
+            },
+        ],
+    });
+}
 export function buildApplyOperatorEnvelope(options) {
     return buildOperatorEnvelope({
         operator: "apply",
@@ -331,6 +370,59 @@ export function buildPruneOperatorEnvelope(options) {
             : [],
     });
 }
+function buildRunEnvelopeTarget(specTarget) {
+    if (specTarget?.kind === "spec") {
+        return {
+            kind: "spec",
+            sessionId: specTarget.sessionId,
+            ...(specTarget.provenance
+                ? buildRunEnvelopeProvenanceFields(specTarget.provenance)
+                : {}),
+        };
+    }
+    if (specTarget?.kind === "file" &&
+        specTarget.provenance?.source?.sessionId &&
+        specTarget.provenance.lineage === "invalid") {
+        return {
+            kind: "spec",
+            sessionId: specTarget.provenance.source.sessionId,
+            ...buildRunEnvelopeProvenanceFields(specTarget.provenance),
+        };
+    }
+    return undefined;
+}
+function buildRunEnvelopeAlerts(specTarget) {
+    if (specTarget?.provenance?.lineage !== "invalid") {
+        return undefined;
+    }
+    return [
+        {
+            level: "warn",
+            message: specTarget.provenance.issueCode === "stale_source"
+                ? "Run spec ancestry metadata referenced a stale or mismatched spec artifact."
+                : "Run spec ancestry metadata was malformed and was ignored.",
+        },
+    ];
+}
+function buildRunEnvelopeProvenanceFields(provenance) {
+    return {
+        lineage: provenance.lineage,
+        ...(provenance.lineage === "invalid"
+            ? { issueCode: provenance.issueCode }
+            : {}),
+        ...("currentContentHash" in provenance &&
+            typeof provenance.currentContentHash === "string"
+            ? { currentContentHash: provenance.currentContentHash }
+            : {}),
+        ...(provenance.source
+            ? {
+                source: {
+                    ...provenance.source,
+                },
+            }
+            : {}),
+    };
+}
 export function writeOperatorResultEnvelope(envelope, exitCode) {
     process.stdout.write(`${JSON.stringify(envelope)}\n`);
     if (typeof exitCode === "number") {

package/dist/cli/option-parsers.d.ts

@@ -0,0 +1,2 @@
+export declare function collectRepeatedStringOption(value: string, previous: string[]): string[];
+export declare function parseMaxParallelOption(value: string): number;

package/dist/cli/option-parsers.js

@@ -0,0 +1,7 @@
+import { parsePositiveInteger } from "../utils/validators.js";
+export function collectRepeatedStringOption(value, previous) {
+    return [...previous, value];
+}
+export function parseMaxParallelOption(value) {
+    return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
+}

package/dist/cli/output.d.ts

@@ -1,8 +1,5 @@
+import type { CliWriter } from "../render/utils/cli-writer.js";
 import { type FormatCliOutputOptions } from "../utils/output.js";
-type CliWriter = Pick<NodeJS.WriteStream, "write"> & {
-    isTTY?: boolean;
-    columns?: number;
-};
 export type AlertSeverity = "info" | "warn" | "error";
 export interface Alert {
     readonly severity: AlertSeverity;
@@ -25,4 +22,3 @@ export interface ChainedCommandOutput {
 export declare function beginChainedCommandOutput(): ChainedCommandOutput;
 export declare function writeCommandOutput(payload: CommandOutputPayload): void;
 export declare function renderCommandOutput(payload: CommandOutputPayload): void;
-export {};

package/dist/cli/reduce.js

@@ -10,10 +10,11 @@ import { ensureSandboxDependencies, resolveCliContext, } from "../preflight/inde
 import { createReduceRenderer, formatReduceElapsed, formatReducerDuration, renderReduceTranscript, } from "../render/transcripts/reduce.js";
 import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
 import { normalizePathForDisplay, relativeToRoot, resolvePath, } from "../utils/path.js";
-import { parsePositiveInteger } from "../utils/validators.js";
-import { resolveWorkspacePath, VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VORATIQ_VERIFICATION_FILE, } from "../workspace/structure.js";
+import { VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VORATIQ_VERIFICATION_FILE, } from "../workspace/constants.js";
+import { resolveWorkspacePath } from "../workspace/path-resolvers.js";
 import { parseReduceExecutionCommandOptions } from "./contract.js";
 import { buildReduceOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { collectRepeatedStringOption, parseMaxParallelOption, } from "./option-parsers.js";
 import { writeCommandOutput } from "./output.js";
 export async function runReduceCommand(options) {
     const { target, agentIds, agentOverrideFlag, profile, maxParallel, extraContext, json = false, suppressHint, writeOutput, stdout, stderr, } = options;
@@ -147,15 +148,6 @@ function formatReductionSnippet(reduction) {
     }
     return lines.join("\n");
 }
-function collectAgentOption(value, previous) {
-    return [...previous, value];
-}
-function collectExtraContextOption(value, previous) {
-    return [...previous, value];
-}
-function parseMaxParallelOption(value) {
-    return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
-}
 export function createReduceCommand() {
     return new Command("reduce")
         .description("Reduce artifact sets into a summarized form")
@@ -166,12 +158,12 @@ export function createReduceCommand() {
         .addOption(new Option("--message <message-id>", "Message session to reduce"))
         .addOption(new Option("--agent <agent-id>", "Set reducers directly (repeatable; order preserved)")
         .default([], "")
-        .argParser(collectAgentOption))
+        .argParser(collectRepeatedStringOption))
         .option("--profile <name>", 'Orchestration profile (default: "default")')
         .option("--max-parallel <count>", "Max concurrent reducers (default: all)", parseMaxParallelOption)
         .addOption(new Option("--extra-context <path>", "Stage an extra context file into each reducer workspace (repeatable)")
         .default([], "")
-        .argParser(collectExtraContextOption))
+        .argParser(collectRepeatedStringOption))
         .option("--json", "Emit a machine-readable result envelope")
         .allowExcessArguments(false)
         .action(async (options, command) => {

package/dist/cli/run.js

@@ -9,9 +9,9 @@ import { createRunRenderer } from "../render/transcripts/run.js";
 import { renderWorkspaceAutoInitializedNotice } from "../render/transcripts/shared.js";
 import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
 import { mapRunStatusToExitCode } from "../status/index.js";
-import { parsePositiveInteger } from "../utils/validators.js";
 import { parseRunExecutionCommandOptions } from "./contract.js";
 import { buildRunOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { collectRepeatedStringOption, parseMaxParallelOption, } from "./option-parsers.js";
 import { writeCommandOutput } from "./output.js";
 export async function runRunCommand(options) {
     const { specPath, agentIds, agentOverrideFlag, profile, maxParallel, branch, extraContext, json = false, suppressHint, suppressLeadingBlankLine, suppressTrailingBlankLine, stdout, stderr, writeOutput, } = options;
@@ -61,6 +61,7 @@ export async function runRunCommand(options) {
     const report = await executeRunCommand({
         root,
         runsFilePath: workspacePaths.runsFile,
+        specsFilePath: workspacePaths.specsFile,
         specAbsolutePath: absolutePath,
         specDisplayPath: displayPath,
         agentIds,
@@ -90,28 +91,19 @@ export function deriveBranchNameFromSpecPath(specPath) {
     }
     return base.slice(0, lastDotIndex);
 }
-function collectAgentOption(value, previous) {
-    return [...previous, value];
-}
-function collectExtraContextOption(value, previous) {
-    return [...previous, value];
-}
-function parseMaxParallelOption(value) {
-    return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
-}
 export function createRunCommand() {
     return new Command("run")
         .description("Execute agents against a spec")
         .requiredOption("--spec <path>", "Path to the spec file")
         .addOption(new Option("--agent <agent-id>", "Set agents directly (repeatable; order preserved)")
         .default([], "")
-        .argParser(collectAgentOption))
+        .argParser(collectRepeatedStringOption))
         .option("--profile <name>", 'Orchestration profile (default: "default")')
         .option("--max-parallel <count>", "Max concurrent agents (default: all)", parseMaxParallelOption)
         .option("--branch", "Create or checkout a branch named after the spec")
         .addOption(new Option("--extra-context <path>", "Stage an extra context file into each agent workspace (repeatable)")
         .default([], "")
-        .argParser(collectExtraContextOption))
+        .argParser(collectRepeatedStringOption))
         .option("--json", "Emit a machine-readable result envelope")
         .allowExcessArguments(false)
         .action(async (options, command) => {
@@ -131,6 +123,7 @@ export function createRunCommand() {
             writeOperatorResultEnvelope(buildRunOperatorEnvelope({
                 runId: result.report.runId,
                 specPath: result.report.spec.path,
+                specTarget: result.report.spec.target,
                 status: result.report.status,
             }), result.exitCode);
             return;

package/dist/cli/spec.js

@@ -9,10 +9,10 @@ import { renderWorkspaceAutoInitializedNotice } from "../render/transcripts/shar
 import { createSpecRenderer, formatSpecAgentDuration, formatSpecElapsed, renderSpecTranscript, } from "../render/transcripts/spec.js";
 import { createStageStartLineEmitter } from "../render/utils/stage-output.js";
 import { resolvePath } from "../utils/path.js";
-import { parsePositiveInteger } from "../utils/validators.js";
-import { getSpecSessionDirectoryPath } from "../workspace/structure.js";
+import { getSpecSessionDirectoryPath } from "../workspace/session-paths.js";
 import { parseSpecExecutionCommandOptions } from "./contract.js";
 import { buildSpecOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { collectRepeatedStringOption, parseMaxParallelOption, } from "./option-parsers.js";
 import { writeCommandOutput } from "./output.js";
 export async function runSpecCommand(options) {
     const { description, agentIds, profile, maxParallel, title, extraContext, json = false, suppressHint, suppressLeadingBlankLine, suppressTrailingBlankLine, stdout, stderr, writeOutput, } = options;
@@ -135,18 +135,12 @@ function formatSpecPreview(spec) {
     return lines.join("\n");
 }
 export function createSpecCommand() {
-    const parseMaxParallelOption = (value) => parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
-    const collectAgentOption = (value, previous) => [
-        ...previous,
-        value,
-    ];
-    const collectExtraContextOption = (value, previous) => [...previous, value];
     return new Command("spec")
         .description("Generate a spec from a task description")
         .requiredOption("--description <text>", "Task description")
         .addOption(new Option("--agent <agent-id>", "Set agents directly (repeatable; order preserved)")
         .default([], "")
-        .argParser(collectAgentOption))
+        .argParser(collectRepeatedStringOption))
         .option("--profile <name>", 'Orchestration profile (default: "default")')
         .addOption(new Option("--max-parallel <count>", "Max concurrent agents")
         .argParser(parseMaxParallelOption)
@@ -154,7 +148,7 @@ export function createSpecCommand() {
         .option("--title <text>", "Spec title; agent infers if omitted")
         .addOption(new Option("--extra-context <path>", "Stage an extra context file into the spec workspace (repeatable)")
         .default([], "")
-        .argParser(collectExtraContextOption))
+        .argParser(collectRepeatedStringOption))
         .option("--json", "Emit a machine-readable result envelope")
         .allowExcessArguments(false)
         .action(async (options, command) => {

package/dist/cli/verify.d.ts

@@ -22,7 +22,7 @@ export interface VerifyCommandOptions {
 }
 export interface VerifyCommandResult {
     verificationId: string;
-    status: VerificationRecord["status"];
+    status: VerificationRecord["status"] | "unresolved";
     target: VerificationRecord["target"];
     body: string;
     exitCode?: number;

package/dist/cli/verify.js

@@ -18,11 +18,26 @@ import { TERMINAL_VERIFICATION_STATUSES } from "../status/index.js";
 import { colorize } from "../utils/colors.js";
 import { toErrorMessage } from "../utils/errors.js";
 import { normalizePathForDisplay, relativeToRoot, resolvePath, } from "../utils/path.js";
-import { parsePositiveInteger } from "../utils/validators.js";
-import { resolveWorkspacePath, VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VORATIQ_VERIFICATION_FILE, VORATIQ_VERIFICATION_SESSIONS_DIR, } from "../workspace/structure.js";
+import { VORATIQ_MESSAGE_FILE, VORATIQ_REDUCTION_FILE, VORATIQ_VERIFICATION_FILE, VORATIQ_VERIFICATION_SESSIONS_DIR, } from "../workspace/constants.js";
+import { resolveWorkspacePath } from "../workspace/path-resolvers.js";
 import { parseVerifyExecutionCommandOptions } from "./contract.js";
 import { buildVerifyOperatorEnvelope, createSilentCliWriter, writeOperatorResultEnvelope, } from "./operator-envelope.js";
+import { collectRepeatedStringOption, parseMaxParallelOption, } from "./option-parsers.js";
 import { writeCommandOutput } from "./output.js";
+const UNRESOLVED_VERIFICATION_MESSAGE = "Verification did not produce a resolvable candidate; manual review required.";
+function resolveVerifyManualActionMessage(options) {
+    const { targetKind, status, selection, selectedSpecPath } = options;
+    if (status !== "succeeded") {
+        return undefined;
+    }
+    if (targetKind === "spec" && !selectedSpecPath) {
+        return UNRESOLVED_VERIFICATION_MESSAGE;
+    }
+    if (selection?.decision.state !== "unresolved") {
+        return undefined;
+    }
+    return UNRESOLVED_VERIFICATION_MESSAGE;
+}
 export async function runVerifyCommand(options) {
     const { target, agentIds, agentOverrideFlag, profile, maxParallel, extraContext, json = false, suppressHint, stdout, stderr, writeOutput, } = options;
     const effectiveWriteOutput = json
@@ -97,10 +112,30 @@ export async function runVerifyCommand(options) {
         return undefined;
     });
     const selectionWarnings = (selection?.warnings ?? []).map((warning) => `Warning: ${warning}`);
+    const selectedSpecPath = execution.record.target.kind === "spec" &&
+        typeof execution.record.target.specPath === "string"
+        ? execution.record.target.specPath
+        : undefined;
+    const manualActionMessage = resolveVerifyManualActionMessage({
+        targetKind: execution.record.target.kind,
+        status: execution.record.status,
+        selection,
+        selectedSpecPath,
+    });
     const warningMessage = [
         ...selectionWarnings,
         ...(selectionPolicyWarning ? [selectionPolicyWarning] : []),
+        ...(manualActionMessage ? [manualActionMessage] : []),
     ].join("\n");
+    const displayStatus = selection?.decision.state === "unresolved"
+        ? "unresolved"
+        : execution.record.status;
+    if (displayStatus === "unresolved" && !json) {
+        renderer.complete("unresolved", {
+            startedAt: execution.record.startedAt,
+            completedAt: execution.record.completedAt,
+        });
+    }
     const recommendedRunAgent = execution.record.target.kind === "run" &&
         selection !== undefined &&
         selection.decision.state === "resolvable"
@@ -109,9 +144,10 @@ export async function runVerifyCommand(options) {
     const hintMessage = suppressHint ||
         selectionPolicyWarning ||
         execution.record.target.kind !== "run" ||
-        execution.record.status !== "succeeded"
+        execution.record.status !== "succeeded" ||
+        selection?.decision.state !== "resolvable"
         ? undefined
-        : `To apply a solution:\n  voratiq apply --run ${execution.record.target.sessionId} --agent ${recommendedRunAgent ?? "<agent-id>"}`;
+        : `To apply a solution:\n  voratiq apply --run ${execution.record.target.sessionId} --agent ${recommendedRunAgent}`;
     const outputPath = normalizePathForDisplay(relativeToRoot(root, resolveWorkspacePath(root, VORATIQ_VERIFICATION_SESSIONS_DIR, execution.verificationId)));
     const body = renderVerifyTranscript({
         verificationId: execution.verificationId,
@@ -123,7 +159,7 @@ export async function runVerifyCommand(options) {
         }) ?? "—",
         workspacePath: normalizePathForDisplay(relativeToRoot(root, resolveWorkspacePath(root, VORATIQ_VERIFICATION_SESSIONS_DIR, execution.verificationId))),
         target: execution.record.target,
-        status: execution.record.status,
+        status: displayStatus,
         methods: methodBlocks,
         suppressHint,
         ...(warningMessage ? { warningMessage } : {}),
@@ -133,28 +169,21 @@ export async function runVerifyCommand(options) {
     });
     return {
         verificationId: execution.verificationId,
-        status: execution.record.status,
+        status: displayStatus,
         target: execution.record.target,
         body,
-        exitCode: execution.record.status === "succeeded" ? 0 : 1,
+        exitCode: execution.record.status === "succeeded" &&
+            selection?.decision.state !== "unresolved" &&
+            !(execution.record.target.kind === "spec" &&
+                typeof selectedSpecPath !== "string")
+            ? 0
+            : 1,
         outputPath,
-        ...(execution.record.target.kind === "spec" &&
-            typeof execution.record.target.specPath === "string"
-            ? { selectedSpecPath: execution.record.target.specPath }
-            : {}),
+        ...(selectedSpecPath ? { selectedSpecPath } : {}),
         selection,
         ...(warningMessage ? { warningMessage } : {}),
     };
 }
-function collectAgentOption(value, previous) {
-    return [...previous, value];
-}
-function collectExtraContextOption(value, previous) {
-    return [...previous, value];
-}
-function parseMaxParallelOption(value) {
-    return parsePositiveInteger(value, "Expected positive integer after --max-parallel", "--max-parallel must be greater than 0");
-}
 export function createVerifyCommand() {
     return new Command("verify")
         .description("Verify a recorded spec, run, reduction, or message session")
@@ -164,12 +193,12 @@ export function createVerifyCommand() {
         .addOption(new Option("--message <message-id>", "Message session to verify"))
         .addOption(new Option("--agent <agent-id>", "Set verifiers directly (repeatable; order preserved)")
         .default([], "")
-        .argParser(collectAgentOption))
+        .argParser(collectRepeatedStringOption))
         .option("--profile <name>", 'Orchestration profile (default: "default")')
         .option("--max-parallel <count>", "Max concurrent verifiers (default: all)", parseMaxParallelOption)
         .addOption(new Option("--extra-context <path>", "Stage an extra context file into each verifier workspace (repeatable)")
         .default([], "")
-        .argParser(collectExtraContextOption))
+        .argParser(collectRepeatedStringOption))
         .option("--json", "Emit a machine-readable result envelope")
         .allowExcessArguments(false)
         .action(async (options, command) => {