@claudexor/cli 2.1.2 → 3.0.0

package/dist/cli.js

@@ -5,11 +5,11 @@ import { createHash } from "node:crypto";
 import { Readable, Transform } from "node:stream";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { ArtifactStore } from "@claudexor/artifact-store";
-import { CLAUDEXOR_VERSION, containsSecretLikeToken, noProjectRepoRoot, readTextSafe, userConfigDir, } from "@claudexor/util";
-import { checkName } from "./release.js";
-import { serveAcpBridge, serveMcpBridge } from "./bridge-serve.js";
+import { CLAUDEXOR_VERSION, noProjectRepoRoot, readTextSafe, userConfigDir } from "@claudexor/util";
+import { releaseCommand } from "./release-command.js";
+import { serveAcpBridge, serveBeltBridge, serveMcpBridge } from "./bridge-serve.js";
 import { initProjectConfig } from "@claudexor/config";
-import { DecisionRecord, ControlSpecSession, EffortHint, ExternalContextPolicy, ModeKind as ModeKindSchema, RoutingGoal, ControlThreadListResponse, RunTelemetry, StructuredOutputConformance, TaskContract, } from "@claudexor/schema";
+import { DecisionRecord, EffortHint, ExternalContextPolicy, ModeKind as ModeKindSchema, RoutingGoal, ControlThreadListResponse, RunTelemetry, StructuredOutputConformance, TaskContract, runOutcomeLabel, } from "@claudexor/schema";
 import { flagBool, flagStr, flagStringList, flagValues, parseArgs, requiredStringFlagError, } from "./args.js";
 import { print, printJson, printJsonLine, printUsageError, statusGlyph } from "./cli-io.js";
 import { pickResumableThread } from "./thread-select.js";
@@ -21,7 +21,8 @@ import { controlApiFetch, followRun } from "./live.js";
 import { retryCommand, runAgainCommand } from "./retry-command.js";
 import { assertCliRunParamsHaveNoInlineSecrets } from "./run-secret-scan.js";
 import { openLocalAttachment, resolveLocalAttachment, } from "./local-attachment.js";
-import { connectDaemonIfRunning, daemonOutcomeSummary, ensureDaemon, enqueueAndAwait, exitCodeForState, fetchApplyEligibility, runStatusForCli, } from "./daemon-run.js";
+import { connectDaemonIfRunning, daemonOutcomeSummary, ensureDaemon, enqueueAndAwait, exitCodeForState, fetchApplyEligibility, fetchCouncil, fetchOutcomeBanner, } from "./daemon-run.js";
+import { runPlanQuestionLoop } from "./plan-question-loop.js";
 import { resolveDecisionBody } from "./decision.js";
 import { primaryOutputForCli } from "./primary-output.js";
 import { PLUGIN_TARGETS, PLUGIN_VERBS, formatPluginResult, pluginCommandErrorResult, runPluginCommand, } from "./plugins.js";
@@ -30,13 +31,11 @@ import { settingsCommand } from "./settings-command.js";
 import { quotaCommand } from "./quota-command.js";
 import { trustCommand } from "./trust-command.js";
 import { projectCommand } from "./project-command.js";
-import { loadFrozenSpec, readAnswers, resolveRunTestCommands } from "./spec.js";
-import { parseAutonomy } from "./orchestrate-options.js";
 import { runRepl } from "./repl.js";
 import { parseProtectedPathApprovalFlags, parseTestCommandFlags, parseReviewerEffortFlags, parseReviewerModelFlags, parseReviewerPanelFlags, } from "./run-options.js";
 const CLI_VERSION = CLAUDEXOR_VERSION;
 const HELP = renderHelp(CLI_VERSION);
-const MODES = new Set(["ask", "plan", "audit", "agent", "orchestrate"]);
+const MODES = new Set(["ask", "plan", "agent"]);
 function normalizeMode(s) {
     const trimmed = s.trim();
     const parsed = ModeKindSchema.safeParse(trimmed);
@@ -240,44 +239,8 @@ async function orchestrate(args, mode, json, forced = {}) {
             return printUsageError(json, "claudexor: stdin prompt (`-`) was empty");
         }
     }
-    const specPath = flagStr(args, "spec");
-    let loadedSpec = null;
-    try {
-        loadedSpec = specPath ? loadFrozenSpec(specPath) : null;
-    }
-    catch (err) {
-        return printUsageError(json, `claudexor: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    const prompt = loadedSpec
-        ? [
-            rawPrompt || loadedSpec.spec.intent.raw,
-            "",
-            "Use this frozen Claudexor SpecPack as the contract. Do not re-litigate settled choices; implement against the acceptance criteria and tests.",
-            "",
-            `Spec id: ${loadedSpec.spec.id} v${loadedSpec.spec.version}`,
-            `Spec hash: ${loadedSpec.specHash}`,
-            "",
-            "## Summary",
-            loadedSpec.spec.summary || "(none)",
-            "",
-            "## Acceptance Criteria",
-            ...(loadedSpec.spec.success_criteria.length
-                ? loadedSpec.spec.success_criteria.map((c) => `- [${c.id}] ${c.behavior}`)
-                : ["- (none)"]),
-            "",
-            "## Non-goals",
-            ...(loadedSpec.spec.non_goals.length
-                ? loadedSpec.spec.non_goals.map((x) => `- ${x}`)
-                : ["- (none)"]),
-            "",
-            "## Forbidden approaches",
-            ...(loadedSpec.spec.forbidden_approaches.length
-                ? loadedSpec.spec.forbidden_approaches.map((x) => `- ${x}`)
-                : ["- (none)"]),
-        ].join("\n")
-        : rawPrompt;
-    const spec = loadedSpec?.spec ?? null;
-    if (!prompt && mode !== "audit") {
+    const prompt = rawPrompt;
+    if (!prompt) {
         return printUsageError(json, "claudexor: missing prompt");
     }
     const portfolioRaw = flagStr(args, "portfolio");
@@ -297,10 +260,10 @@ async function orchestrate(args, mode, json, forced = {}) {
     let resolvedAccess = undefined;
     let resolvedEffort;
     let paidBudget;
-    let maxToolCalls;
     let nFlag;
     let attemptsFlag;
-    let autonomy;
+    let delegate;
+    let council;
     let resolvedSynthesis = undefined;
     let resolvedHarnesses;
     let resolvedPrimaryHarness;
@@ -324,10 +287,10 @@ async function orchestrate(args, mode, json, forced = {}) {
         resolvedModel = flagStr(args, "model");
         const maxUsd = floatFlag(args, "max-usd");
         paidBudget = maxUsd === undefined ? undefined : { kind: "finite", maxUsd };
-        maxToolCalls = intFlag(args, "max-tool-calls");
         nFlag = intFlag(args, "n");
         attemptsFlag = intFlag(args, "attempts");
-        autonomy = parseAutonomy(flagStr(args, "autonomy"));
+        delegate = flagBool(args, "delegate") ? true : undefined;
+        council = flagBool(args, "council") ? true : undefined;
         resolvedSynthesis = synthesisMode(args);
         attachmentRequest = attachmentInputs(args);
         resolvedProtectedPathApprovals = protectedPathApprovals(args);
@@ -364,7 +327,7 @@ async function orchestrate(args, mode, json, forced = {}) {
     let tests;
     try {
         const cliTests = testCommands(args) ?? [];
-        tests = resolveRunTestCommands(cliTests, spec);
+        tests = cliTests.length > 0 ? cliTests : undefined;
         assertCliRunParamsHaveNoInlineSecrets({
             prompt,
             instructions: resolvedInstructions,
@@ -384,24 +347,21 @@ async function orchestrate(args, mode, json, forced = {}) {
             web: resolvedWebPolicy,
             externalContextPolicy: resolvedWebPolicy,
             synthesis: resolvedSynthesis,
-            autonomy,
-            specId: spec?.id,
-            specHash: loadedSpec?.specHash,
-            specPath: loadedSpec?.specPath,
         });
     }
     catch (err) {
         return printUsageError(json, `claudexor: ${err instanceof Error ? err.message : String(err)}`);
     }
-    if (autonomy !== undefined && mode !== "orchestrate") {
-        return printUsageError(json, `claudexor: --autonomy only applies to 'orchestrate' (got mode '${mode}')`);
+    if (delegate && mode !== "agent") {
+        return printUsageError(json, `claudexor: --delegate is an agent strategy (got mode '${mode}')`);
     }
-    if (maxToolCalls !== undefined && mode !== "orchestrate") {
-        return printUsageError(json, "claudexor: --max-tool-calls only applies to orchestrate runs");
+    if (council && mode !== "plan") {
+        return printUsageError(json, `claudexor: --council is a plan strategy (got mode '${mode}')`);
     }
     return daemonRun(args, json, {
         mode,
-        autonomy,
+        delegate,
+        council,
         prompt: prompt || "audit this repository",
         instructions: resolvedInstructions,
         maxSeconds: resolvedMaxSeconds,
@@ -412,7 +372,6 @@ async function orchestrate(args, mode, json, forced = {}) {
         paidBudget,
         routingGoal: routingGoal?.success ? routingGoal.data : undefined,
         credentialProfileId,
-        maxToolCalls,
         reviewerPanel: resolvedReviewerPanel,
         reviewerModels: resolvedReviewerModels,
         reviewerEfforts: reviewerEffortOverrides,
@@ -426,9 +385,6 @@ async function orchestrate(args, mode, json, forced = {}) {
         resolvedModel,
         nFlag,
         attemptsFlag,
-        specId: spec?.id,
-        specHash: loadedSpec?.specHash,
-        specPath: loadedSpec?.specPath,
         attachmentRequest,
         forced,
     });
@@ -459,10 +415,11 @@ async function daemonRun(args, json, p) {
             process.stderr.write(`claudexor: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }
-    // Thread continuation (W13): --thread <id> targets a thread explicitly;
-    // --resume picks the most recently updated one. POST /runs already funnels a
-    // threadId through the SINGLE createThreadTurn point server-side — this is
-    // parameter plumbing, never a second turn-creation path.
+    // Thread continuation (W13/D10): --thread <id> targets a thread explicitly;
+    // --resume picks the most recently updated one. When a threadId is present
+    // the run is enqueued through POST /threads/:id/turns (enqueueAndAwait routes
+    // it there) — the ONE turn-creation path that owns scope, lineage, and the
+    // continuation packet. POST /runs itself now refuses threadId.
     let threadId = flagStr(args, "thread");
     if (threadId === undefined && flagBool(args, "resume")) {
         try {
@@ -474,11 +431,13 @@ async function daemonRun(args, json, p) {
             // Parse through the typed DTO — the field is camelCase `updatedAt`, and a
             // hand-rolled `updated_at` read silently sorts undefined and throws.
             const list = ControlThreadListResponse.parse(await res.json());
-            const newest = pickResumableThread(list.threads);
+            // Scope to the current project (D28): --resume must never cross into
+            // another project's threads.
+            const newest = pickResumableThread(list.threads, process.cwd());
             if (!newest) {
                 // Stay valid on the active output surface: NDJSON stream keeps compact
                 // lines; --json prints its one object; text goes to stderr.
-                const message = "claudexor: --resume found no threads to continue";
+                const message = "claudexor: --resume found no threads to continue in this project";
                 if (jsonStream)
                     printJsonLine({ ok: false, exitCode: 1, error: message });
                 else if (json)
@@ -527,7 +486,8 @@ async function daemonRun(args, json, p) {
         ...(attachmentRefs ? { attachments: attachmentRefs } : {}),
         mode: p.mode,
         ...(threadId ? { threadId } : {}),
-        ...(p.mode === "orchestrate" && p.autonomy ? { autonomy: p.autonomy } : {}),
+        ...(p.delegate ? { delegate: true } : {}),
+        ...(p.council ? { council: true } : {}),
         scope: { kind: "project", root: process.cwd() },
         execution: { isolation: inPlace ? "live" : "envelope" },
         ...(p.resolvedHarnesses ? { harnesses: p.resolvedHarnesses } : {}),
@@ -537,15 +497,12 @@ async function daemonRun(args, json, p) {
         ...(p.forced.race === true ? { n: p.nFlag ?? 2 } : p.nFlag !== undefined ? { n: p.nFlag } : {}),
         ...(p.attemptsFlag !== undefined ? { attempts: p.attemptsFlag } : {}),
         ...(flagBool(args, "until-clean") ? { untilClean: true } : {}),
-        ...(p.forced.swarm === true || flagBool(args, "swarm") ? { swarm: true } : {}),
+        ...(p.forced.deepScan === true || flagBool(args, "deep-scan") ? { deepScan: true } : {}),
         ...(p.forced.create === true || flagBool(args, "create") ? { create: true } : {}),
         ...(p.resolvedSynthesis ? { synthesis: p.resolvedSynthesis } : {}),
         ...(p.tests ? { tests: p.tests } : {}),
         ...(p.protectedPathApprovals ? { protectedPathApprovals: p.protectedPathApprovals } : {}),
         ...(p.paidBudget !== undefined ? { paidBudget: p.paidBudget } : {}),
-        ...(p.mode === "orchestrate" && p.maxToolCalls !== undefined
-            ? { maxToolCalls: p.maxToolCalls }
-            : {}),
         ...(p.resolvedAccess ? { access: p.resolvedAccess } : {}),
         ...(p.resolvedWebPolicy ? { web: p.resolvedWebPolicy } : {}),
         ...(p.resolvedModel ? { model: p.resolvedModel } : {}),
@@ -553,9 +510,6 @@ async function daemonRun(args, json, p) {
         ...(p.reviewerPanel ? { reviewerPanel: p.reviewerPanel } : {}),
         ...(p.reviewerModels ? { reviewerModels: p.reviewerModels } : {}),
         ...(p.reviewerEfforts ? { reviewerEfforts: p.reviewerEfforts } : {}),
-        ...(p.specId ? { specId: p.specId } : {}),
-        ...(p.specHash ? { specHash: p.specHash } : {}),
-        ...(p.specPath ? { specPath: p.specPath } : {}),
     };
     try {
         if (jsonStream) {
@@ -570,7 +524,7 @@ async function daemonRun(args, json, p) {
                     frame: "run.terminal",
                     runId: "",
                     runDir: started.runDir,
-                    status: runStatusForCli(started.status),
+                    status: started.status,
                     jobId: started.jobId,
                     mode: p.mode,
                     ...(started.error ? { error: started.error } : {}),
@@ -592,12 +546,13 @@ async function daemonRun(args, json, p) {
             const out = {
                 runId: started.runId,
                 runDir: final?.runDir ?? started.runDir,
-                status: runStatusForCli(status),
+                status: status,
                 jobId: started.jobId,
                 error: final?.error ?? started.error,
             };
             const reason = daemonOutcomeSummary({ ...started, status, error: out.error });
             const applyEligibility = await fetchApplyEligibility(addr, started.runId);
+            const outcomeBanner = await fetchOutcomeBanner(addr, started.runId);
             printJsonLine({
                 frame: "run.terminal",
                 runId: out.runId,
@@ -607,6 +562,7 @@ async function daemonRun(args, json, p) {
                 mode: p.mode,
                 ...(out.error ? { error: out.error } : {}),
                 ...(reason ? { summary: reason } : {}),
+                ...(outcomeBanner ? { outcomeBanner } : {}),
                 ...(applyEligibility ? { applyEligibility } : {}),
             });
             return exitCodeForState(status);
@@ -620,14 +576,16 @@ async function daemonRun(args, json, p) {
             // apply-gate verdict, so machine callers act on truth instead of
             // re-implying eligibility from status.
             const applyEligibility = await fetchApplyEligibility(addr, out.runId);
+            const outcomeBanner = await fetchOutcomeBanner(addr, out.runId);
             printJson({
                 runId: out.runId,
                 runDir: out.runDir,
-                status: runStatusForCli(out.status),
+                status: out.status,
                 jobId: out.jobId,
                 mode: p.mode,
                 ...(out.error ? { error: out.error } : {}),
                 ...(reason ? { summary: reason } : {}),
+                ...(outcomeBanner ? { outcomeBanner } : {}),
                 ...(applyEligibility ? { applyEligibility } : {}),
             });
             return exitCodeForState(out.status);
@@ -643,24 +601,55 @@ async function daemonRun(args, json, p) {
         await followRun(started.runId, false);
         const final = started.jobId ? await client.status(started.jobId) : null;
         const status = final?.state ?? started.status;
-        const publicStatus = runStatusForCli(status);
+        const publicStatus = status;
         print("");
         print(`run ${started.runId} [${publicStatus}]`);
+        // Server-owned outcome headline (D18), printed verbatim above any output.
+        const terminalBanner = await fetchOutcomeBanner(addr, started.runId);
+        if (terminalBanner)
+            print(`  ${terminalBanner}`);
         print(`  artifacts: ${final?.runDir ?? started.runDir}`);
-        if (status === "blocked") {
-            print(`  blocked (needs human): unblock with \`claudexor decision ${started.runId} --accept-risk\` or rerun with \`claudexor decision ${started.runId} --rerun --feedback "..."\``);
-        }
-        else if (exitCodeForState(status) === 0) {
+        // A succeeded lifecycle exits 0 — INCLUDING a "Done · needs review" run
+        // (review blocked / checks failed). The apply-eligibility verdict (state
+        // needs_review) is the ONE source for the unblock guidance (D8).
+        // The plan question loop advances this past each answered follow-up turn.
+        let effectiveRunId = started.runId;
+        if (exitCodeForState(status) === 0) {
+            // Plan runs: server-derived readiness (D17) + interactive answer loop.
+            if (p.mode === "plan") {
+                // Council disclosure (INV-031): membership + merge, projected by the
+                // server (never a client re-derivation).
+                if (p.council) {
+                    const council = await fetchCouncil(addr, started.runId);
+                    if (council) {
+                        print(`  council: merged by ${council.mergedBy ?? "(none)"} from ${council.drafted} of ${council.requested} member(s)${council.degraded ? " (degraded)" : ""}`);
+                        const failed = council.members.filter((m) => m.status === "failed");
+                        if (failed.length > 0) {
+                            print(`  council failures: ${failed.map((m) => m.harnessId).join(", ")}`);
+                        }
+                    }
+                }
+                effectiveRunId = await runPlanQuestionLoop({
+                    client,
+                    addr,
+                    threadId,
+                    runId: started.runId,
+                    interactive: !json && !jsonStream, // TTY plan turns answer inline
+                });
+            }
             // Offer apply only after a positive gate; otherwise print inspect/unblock guidance.
-            const eligibility = await fetchApplyEligibility(addr, started.runId);
+            const eligibility = await fetchApplyEligibility(addr, effectiveRunId);
             if (eligibility?.eligible) {
-                print(`  apply with: claudexor apply ${started.runId}`);
+                print(`  apply with: claudexor apply ${effectiveRunId}`);
+            }
+            else if (eligibility?.state === "needs_review") {
+                print(`  needs review: unblock with \`claudexor decision ${effectiveRunId} --accept-risk\` or rerun with \`claudexor decision ${effectiveRunId} --rerun --feedback "..."\``);
             }
             else if (eligibility?.requiredAction) {
                 print(`  not applyable yet: ${eligibility.requiredAction}`);
             }
             else {
-                print(`  inspect with: claudexor inspect ${started.runId}`);
+                print(`  inspect with: claudexor inspect ${effectiveRunId}`);
             }
         }
         return exitCodeForState(status);
@@ -739,7 +728,7 @@ async function decisionCommand(args, json) {
  * Resolve the ArtifactStore that owns a given run, regardless of the cwd the
  * CLI is invoked from. Order:
  *   1. the project store rooted at the current cwd (the common case);
- *   2. the v2 user store (~/.claudexor/v2/runs) used by no-project Ask runs;
+ *   2. the user store (~/.claudexor/v3/runs) used by no-project Ask runs;
  *   3. a daemon-tracked run that started in ANOTHER project — agent/race/create
  *      runs live under that project's external runtime namespace, so we ask
  *      the daemon for the run's absolute runDir (GET /runs/:id ->
@@ -793,131 +782,6 @@ async function resolveRunStore(runId) {
     }
     return null;
 }
-async function specCommand(args, json) {
-    const prompt = args._.slice(1).join(" ").trim();
-    if (!prompt) {
-        return printUsageError(json, "claudexor: missing spec prompt");
-    }
-    if (containsSecretLikeToken(prompt)) {
-        return printUsageError(json, "claudexor spec: prompt contains a secret-like token; specs are durable artifacts, so store secrets by ref and retry with a sanitized prompt");
-    }
-    const answersPath = flagStr(args, "answers");
-    // The grounding step is a real (multi-)harness plan run, so the same
-    // routing/cost/review controls as the plan verb apply — but ONLY that step
-    // spawns a run. Parse them up-front so malformed values fail loudly on
-    // every path, and refuse ALL grounding-only flags on the --answers path,
-    // where no grounding run exists for them to control.
-    let groundingEffort;
-    let groundingMaxUsd;
-    let groundingHarnesses;
-    let groundingN;
-    let groundingWeb;
-    let groundingReviewerPanel;
-    let groundingReviewerModels;
-    let groundingReviewerEfforts;
-    try {
-        groundingEffort = effortHint(args);
-        groundingMaxUsd = floatFlag(args, "max-usd");
-        groundingHarnesses = harnessList(args);
-        groundingN = intFlag(args, "n");
-        groundingWeb = webPolicy(args);
-        groundingReviewerPanel = reviewerPanel(args);
-        groundingReviewerModels = reviewerModels(args);
-        groundingReviewerEfforts = reviewerEfforts(args);
-    }
-    catch (err) {
-        return printUsageError(json, `claudexor: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (answersPath &&
-        (groundingEffort !== undefined ||
-            groundingMaxUsd !== undefined ||
-            groundingHarnesses !== undefined ||
-            groundingN !== undefined ||
-            groundingWeb !== undefined ||
-            groundingReviewerPanel !== undefined ||
-            groundingReviewerModels !== undefined ||
-            groundingReviewerEfforts !== undefined)) {
-        return printUsageError(json, "claudexor spec: --harness/--n/--web/--effort/--max-usd/--reviewer-panel/--reviewer-model/--reviewer-effort control the grounding plan run and only apply when generating questions; drop them when re-running with --answers");
-    }
-    try {
-        const { addr } = await ensureDaemon();
-        await controlJson(addr, "/projects", {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ root: process.cwd() }),
-        });
-        if (!answersPath) {
-            const session = ControlSpecSession.parse(await controlJson(addr, "/spec/sessions", {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify({
-                    prompt,
-                    scope: { kind: "project", root: process.cwd(), context: "auto" },
-                    harnesses: groundingHarnesses,
-                    n: groundingN,
-                    effort: groundingEffort,
-                    paidBudget: groundingMaxUsd === undefined
-                        ? undefined
-                        : { kind: "finite", maxUsd: groundingMaxUsd },
-                    web: groundingWeb,
-                    reviewerPanel: groundingReviewerPanel,
-                    reviewerModels: groundingReviewerModels,
-                    reviewerEfforts: groundingReviewerEfforts,
-                }),
-            }));
-            if (json)
-                printJson(session);
-            else {
-                print(`durable spec session: ${session.sessionId}`);
-                print(`grounding run: ${session.planRunId ?? "pending"}`);
-                for (const question of session.questions)
-                    print(`- [${question.id}] ${question.prompt}`);
-                print("save `claudexor spec ... --json` output, fill its answers array, then pass it with --answers");
-            }
-            return session.state === "failed" || session.state === "interrupted_unknown" ? 1 : 0;
-        }
-        const answers = readAnswers(answersPath);
-        if (!answers.sessionId) {
-            throw new Error("answers file must contain sessionId from the durable spec session");
-        }
-        const encodedId = encodeURIComponent(answers.sessionId);
-        await controlJson(addr, `/spec/sessions/${encodedId}/answers`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({
-                answers: answers.answers,
-                priorDecisions: answers.priorDecisions,
-            }),
-        });
-        const session = ControlSpecSession.parse(await controlJson(addr, `/spec/sessions/${encodedId}/freeze`, { method: "POST" }));
-        if (session.state !== "frozen" || !session.specPath || !session.specId || !session.specHash) {
-            throw new Error(`spec session ended as ${session.state}`);
-        }
-        const runHint = `claudexor best-of --spec ${JSON.stringify(session.specPath)}`;
-        if (json)
-            printJson({ ...session, status: "frozen", runHint });
-        else {
-            print(`frozen SpecPack: ${session.specId}`);
-            print(`  path: ${session.specPath}`);
-            print(`  hash: ${session.specHash}`);
-            print(`run: ${runHint}`);
-        }
-        return 0;
-    }
-    catch (err) {
-        // Same runtime-error envelope contract as the run/race commands: --json
-        // callers get a machine-readable {ok:false} on stdout, never bare stderr.
-        if (json)
-            printJson({
-                ok: false,
-                exitCode: 1,
-                error: `claudexor spec: ${err instanceof Error ? err.message : String(err)}`,
-            });
-        else
-            process.stderr.write(`claudexor spec: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 1;
-    }
-}
 async function controlJson(addr, path, init = {}) {
     const response = await controlApiFetch(addr, path, init);
     const text = await response.text();
@@ -976,7 +840,7 @@ async function main() {
     if (valueFlagError)
         return printPreflightError(args, json, valueFlagError);
     // Registry-enforced per-command flag scope: a KNOWN flag outside the
-    // command's declared set (e.g. `spec --model`, `ask --force`) fails loudly
+    // command's declared set (e.g. `plan --create`, `ask --force`) fails loudly
     // instead of being silently ignored. Data-driven from CLI_COMMANDS for
     // every verb (this replaced the old hand-listed plugin/--force special cases).
     const scopeError = commandFlagScopeError(cmd, Object.keys(args.flags));
@@ -1003,65 +867,44 @@ async function main() {
         case "project":
             return projectCommand(args, json);
         case "agent": {
-            const specStrategyError = "claudexor: --spec requires a gated strategy; use 'claudexor best-of --spec <file>' or 'claudexor agent --attempts N --spec <file>'";
-            // ONE gate for both spellings: `agent --spec` and `agent --mode agent --spec`
-            // must enforce the same gated-strategy requirement (a flag spelling must
-            // never bypass a policy the bare verb enforces).
-            const agentSpecGateError = () => {
-                if (!flagStr(args, "spec") || flagBool(args, "until-clean"))
-                    return null;
-                try {
-                    const hasGatedStrategy = intFlag(args, "attempts") !== undefined || intFlag(args, "n") !== undefined;
-                    return hasGatedStrategy ? null : specStrategyError;
-                }
-                catch (err) {
-                    return `claudexor: ${err instanceof Error ? err.message : String(err)}`;
-                }
-            };
             const modeStr = flagStr(args, "mode");
             if (modeStr !== undefined) {
                 const mode = normalizeMode(modeStr);
                 if (!MODES.has(mode)) {
                     return printUsageError(json, `claudexor: unknown --mode '${modeStr}'. valid: ${[...MODES].join(", ")}`);
                 }
-                if ((mode === "ask" || mode === "audit") && flagStr(args, "spec")) {
-                    return printUsageError(json, specStrategyError);
-                }
-                if (mode === "agent") {
-                    const gateError = agentSpecGateError();
-                    if (gateError)
-                        return printUsageError(json, gateError);
-                }
                 return orchestrate(args, mode, json);
             }
-            const gateError = agentSpecGateError();
-            if (gateError)
-                return printUsageError(json, gateError);
             return orchestrate(args, "agent", json);
         }
         case "ask":
             return orchestrate(args, "ask", json);
-        case "explore":
-            return orchestrate(args, "audit", json, { swarm: true });
         case "best-of":
             return orchestrate(args, "agent", json, { race: true });
-        // RENAMED verbs hard-error with the new name — no silent aliases (the
-        // same doctrine as retired mode ids: a stale script must fail loudly).
+        // RETIRED verb spellings hard-error with the new spelling — no silent
+        // aliases (same doctrine as retired mode ids: stale scripts fail loudly).
         case "run":
-            return printPreflightError(args, json, "claudexor: the 'run' verb was renamed; use 'claudexor agent' (same flags)");
         case "race":
-            return printPreflightError(args, json, "claudexor: the 'race' verb was renamed; use 'claudexor best-of' (same flags)");
+        case "audit":
+        case "map":
+        case "explore":
         case "orchestrate":
-            return orchestrate(args, "orchestrate", json);
+        case "spec": {
+            const replacement = cmd === "run"
+                ? "claudexor agent (same flags)"
+                : cmd === "race"
+                    ? "claudexor best-of (same flags)"
+                    : cmd === "orchestrate"
+                        ? "claudexor agent --delegate <prompt> (the harness spawns bounded isolated sub-runs; suggest-only planning is ordinary claudexor plan)"
+                        : cmd === "spec"
+                            ? "claudexor plan <prompt> then Implement (the plan lifecycle surfaces open questions and freezes the plan on implement)"
+                            : "claudexor ask --deep-scan <prompt>";
+            return printPreflightError(args, json, `claudexor: the '${cmd}' verb was retired; use ${replacement}`);
+        }
         case "plan":
             return orchestrate(args, "plan", json);
-        case "spec":
-            return specCommand(args, json);
         case "create":
             return orchestrate(args, "agent", json, { create: true });
-        case "audit":
-        case "map":
-            return orchestrate(args, "audit", json);
         case "settings":
             return settingsCommand(args, json);
         case "quota":
@@ -1071,6 +914,10 @@ async function main() {
         case "mcp": {
             if (args._[1] === "serve")
                 return serveMcpBridge();
+            // Internal: the scoped delegation belt injected into a delegate agent
+            // run's sandbox (D32). Not a user-facing verb.
+            if (args._[1] === "serve-belt")
+                return serveBeltBridge();
             return printUsageError(json, "usage: claudexor mcp serve");
         }
         case "acp": {
@@ -1189,7 +1036,8 @@ async function main() {
             }
             if (parsedDecision.success) {
                 const vb = parsedDecision.data.verification_basis;
-                print(`decision: ${parsedDecision.data.status} outcome=${parsedDecision.data.outcome} apply=${parsedDecision.data.apply_recommendation}${vb !== "none" ? ` verified_by=${vb}` : ""}`);
+                const f = parsedDecision.data.facts;
+                print(`decision: ${runOutcomeLabel(f)} (lifecycle=${f.lifecycle} checks=${f.checks} review=${f.review}${f.reason ? ` reason=${f.reason}` : ""}) apply=${parsedDecision.data.apply_recommendation}${vb !== "none" ? ` verified_by=${vb}` : ""}`);
                 const budget = parsedDecision.data.budget_summary;
                 print(`budget: spend=${budget.spend_usd ?? "unknown"}${budget.estimated ? " estimated" : ""}`);
             }
@@ -1280,27 +1128,8 @@ async function main() {
         }
         case "decision":
             return decisionCommand(args, json);
-        case "release": {
-            if (args._[1] === "check-name") {
-                const name = args._[2] ?? "claudexor";
-                const checks = await checkName(name);
-                if (json)
-                    printJson({ name, checks });
-                else {
-                    print(`naming gate for "${name}":`);
-                    for (const c of checks) {
-                        const tag = c.availability === "free"
-                            ? "[free]   "
-                            : c.availability === "taken"
-                                ? "[taken]  "
-                                : "[unknown]";
-                        print(`  ${tag} ${c.registry}: ${c.detail}`);
-                    }
-                }
-                return 0;
-            }
-            return printUsageError(json, "usage: claudexor release check-name <name>");
-        }
+        case "release":
+            return releaseCommand(args, json);
         case "plugin": {
             const sub = args._[1];
             const target = args._[2];