@claudexor/cli 3.1.2 → 3.3.7-rc.0

package/dist/cli.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import process from "node:process";
-import { createReadStream, existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { Readable, Transform } from "node:stream";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { ArtifactStore } from "@claudexor/artifact-store";
 import { CLAUDEXOR_VERSION, noProjectRepoRoot, readTextSafe, userConfigDir } from "@claudexor/util";
@@ -10,13 +8,15 @@ import { releaseCommand } from "./release-command.js";
 import { serveBeltBridge, serveMcpBridge } from "./bridge-serve.js";
 import { dispatchAcpCommand } from "./acp-auth-command.js";
 import { initProjectConfig } from "@claudexor/config";
-import { DecisionRecord, EFFORT_HINT_HELP, EffortHint, ExternalContextPolicy, ModeKind as ModeKindSchema, RoutingGoal, ControlThreadListResponse, RunTelemetry, StructuredOutputConformance, TaskContract, runOutcomeLabel, } from "@claudexor/schema";
+import { DecisionRecord, EFFORT_HINT_HELP, EffortHint, ExternalContextPolicy, ModeKind as ModeKindSchema, RoutingGoal, ControlThreadListResponse, RunFailure, 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 { controlProblemError, minIntError, renderCliFailure, usageError } from "./cli-error.js";
+import { cliOutputMode, outputModeIsMachine, outputModeIsStream, renderOutputFailure, renderOutputUsageFailure, } from "./output-mode.js";
 import { handleHelpRequest } from "./command-help.js";
 import { pickResumableThread } from "./thread-select.js";
-import { KNOWN_FLAGS, VALUE_FLAGS, commandFlagScopeError, helpJson, renderHelp, } from "./command-registry.js";
+import { KNOWN_FLAGS, VALUE_FLAGS, helpJson, renderHelp } from "./command-registry.js";
+import { commandFlagScopeError, commandPositionalError, runModeFlagScopeError, } from "./command-scope.js";
 import { buildAgentCapabilityCatalog } from "./capabilities.js";
 import { aboutJson, renderAbout } from "./about-command.js";
 import { dispatchOpsCommand } from "./ops-commands.js";
@@ -24,18 +24,22 @@ import { reviewCommand } from "./review-command.js";
 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, daemonOutcomeProblemFields, daemonOutcomeSummary, ensureDaemon, enqueueAndAwait, exitCodeForState, fetchApplyEligibility, fetchCouncil, fetchRunDetail, fetchRunOutcomeFacts, projectOutcomeBanner, projectRunOutcomeFacts, mergeDaemonRunOutcome, } from "./daemon-run.js";
-import { inspectDelegationLines, projectDelegation, terminalDelegationLines, terminalDetailFields, } from "./delegation-output.js";
+import { resolveLocalAttachment } from "./local-attachment.js";
+import { uploadLocalAttachment } from "./attachment-upload.js";
+import { connectDaemonIfRunning, daemonOutcomeSummary, ensureDaemon, enqueueAndAwait, exitCodeForState, fetchApplyEligibility, fetchCouncil, fetchRunDetail, fetchRunOutcomeFacts, projectOutcomeBanner, projectRunOutcomeFacts, mergeDaemonRunOutcome, } from "./daemon-run.js";
+import { inspectDelegationLines, projectDelegation, terminalDelegationLines, } from "./delegation-output.js";
+import { readRunFactsArtifact } from "./run-facts-projection.js";
+import { projectTerminalRunOutput, terminalRunRequiredActionLines } from "./terminal-run-output.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";
-import { buildRegistry } from "./registry.js";
 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 { remoteCommand, setupCommand } from "./remote-command.js";
+import { harnessCommand } from "./harness-command.js";
 import { runRepl } from "./repl.js";
 import { parseProtectedPathApprovalFlags, parseTestCommandFlags, parseReviewerEffortFlags, parseReviewerModelFlags, parseReviewerPanelFlags, } from "./run-options.js";
 const CLI_VERSION = CLAUDEXOR_VERSION;
@@ -160,55 +164,6 @@ function attachmentInputs(args) {
     const out = attachmentPaths(args).map(({ path, forceImage }) => resolveLocalAttachment(path, forceImage));
     return out.length > 0 ? out : undefined;
 }
-async function uploadLocalAttachment(addr, attachment) {
-    const created = (await controlJson(addr, "/uploads", {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-            kind: attachment.kind,
-            mime: attachment.mime,
-            name: attachment.name,
-            sizeBytes: attachment.sizeBytes,
-        }),
-    }));
-    try {
-        const source = createReadStream(attachment.path, {
-            fd: openLocalAttachment(attachment),
-            autoClose: true,
-        });
-        const hash = createHash("sha256");
-        const hashingStream = new Transform({
-            transform(chunk, _encoding, callback) {
-                hash.update(chunk);
-                callback(null, chunk);
-            },
-        });
-        source.pipe(hashingStream);
-        const response = await controlApiFetch(addr, `/uploads/${encodeURIComponent(created.uploadId)}/bytes`, {
-            method: "PUT",
-            headers: { "content-type": "application/octet-stream" },
-            body: Readable.toWeb(hashingStream),
-            duplex: "half",
-        });
-        if (!response.ok) {
-            const detail = (await response.json().catch(() => ({})));
-            throw new Error(String(detail["message"] ?? detail["error"] ?? `HTTP ${response.status}`));
-        }
-        const expectedSha256 = `sha256:${hash.digest("hex")}`;
-        const resource = (await controlJson(addr, `/uploads/${encodeURIComponent(created.uploadId)}/finalize`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ expectedSha256 }),
-        }));
-        return { resourceId: resource.resourceId };
-    }
-    catch (error) {
-        await controlApiFetch(addr, `/uploads/${encodeURIComponent(created.uploadId)}`, {
-            method: "DELETE",
-        }).catch(() => undefined);
-        throw error;
-    }
-}
 /** Per-family reviewer model map from `--reviewer-model "openai=gpt-4o-mini,anthropic=claude-haiku"`. Fails loudly on malformed input. */
 function reviewerModels(args) {
     return parseReviewerModelFlags(flagValues(args, "reviewer-model"));
@@ -221,7 +176,7 @@ function reviewerEfforts(args) {
 function reviewerPanel(args) {
     return parseReviewerPanelFlags(flagValues(args, "reviewer-panel"));
 }
-async function orchestrate(args, mode, json, forced = {}) {
+async function orchestrate(args, mode, outputMode, forced = {}) {
     let rawPrompt = args._.slice(1).join(" ").trim();
     // Headless prompt sources (W13): `-` reads the prompt from stdin; a file
     // beats retyping. Exactly ONE source — ambiguity is a usage error, never a
@@ -229,34 +184,34 @@ async function orchestrate(args, mode, json, forced = {}) {
     const promptFile = flagStr(args, "prompt-file");
     if (promptFile !== undefined) {
         if (rawPrompt && rawPrompt !== "-") {
-            return printUsageError(json, "claudexor: pass either an inline prompt or --prompt-file, not both");
+            return renderOutputUsageFailure(outputMode, "claudexor: pass either an inline prompt or --prompt-file, not both");
         }
         try {
             rawPrompt = readFileSync(promptFile, "utf8").trim();
         }
         catch (err) {
-            return printUsageError(json, `claudexor: --prompt-file: cannot read ${promptFile}: ${err instanceof Error ? err.message : String(err)}`);
+            return renderOutputUsageFailure(outputMode, `claudexor: --prompt-file: cannot read ${promptFile}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     else if (rawPrompt === "-") {
         rawPrompt = readFileSync(0, "utf8").trim();
         if (!rawPrompt) {
-            return printUsageError(json, "claudexor: stdin prompt (`-`) was empty");
+            return renderOutputUsageFailure(outputMode, "claudexor: stdin prompt (`-`) was empty");
         }
     }
     const prompt = rawPrompt;
     if (!prompt) {
-        return printUsageError(json, "claudexor: missing prompt");
+        return renderOutputUsageFailure(outputMode, "claudexor: missing prompt");
     }
     const portfolioRaw = flagStr(args, "portfolio");
     if (portfolioRaw !== undefined) {
-        return printUsageError(json, "claudexor: --portfolio was removed in v2; use --routing-goal auto|quality|economy");
+        return renderOutputUsageFailure(outputMode, "claudexor: --portfolio was removed in v2; use --routing-goal auto|quality|economy");
     }
     const credentialProfileId = flagStr(args, "profile");
     const routingGoalRaw = flagStr(args, "routing-goal");
     const routingGoal = routingGoalRaw !== undefined ? RoutingGoal.safeParse(routingGoalRaw) : null;
     if (routingGoalRaw !== undefined && !routingGoal?.success) {
-        return printUsageError(json, `claudexor: unknown --routing-goal '${routingGoalRaw}'`);
+        return renderOutputUsageFailure(outputMode, `claudexor: unknown --routing-goal '${routingGoalRaw}'`);
     }
     let reviewerEffortOverrides;
     let resolvedReviewerModels;
@@ -333,7 +288,10 @@ async function orchestrate(args, mode, json, forced = {}) {
     }
     catch (err) {
         // Projector: typed field errors / domain codes survive; a plain flag-parse Error is usage (exit 2).
-        return renderCliFailure(json, err, { defaultCategory: "usage", messagePrefix: "claudexor:" });
+        return renderOutputFailure(outputMode, err, {
+            defaultCategory: "usage",
+            messagePrefix: "claudexor:",
+        });
     }
     let tests;
     try {
@@ -362,15 +320,18 @@ async function orchestrate(args, mode, json, forced = {}) {
     }
     catch (err) {
         // Preserves the typed `inline_secret_rejected` code (never echoing the token).
-        return renderCliFailure(json, err, { defaultCategory: "usage", messagePrefix: "claudexor:" });
+        return renderOutputFailure(outputMode, err, {
+            defaultCategory: "usage",
+            messagePrefix: "claudexor:",
+        });
     }
     if (delegate && mode !== "agent") {
-        return printUsageError(json, `claudexor: --delegate is an agent strategy (got mode '${mode}')`);
+        return renderOutputUsageFailure(outputMode, `claudexor: --delegate is an agent strategy (got mode '${mode}')`);
     }
     if (council && mode !== "plan") {
-        return printUsageError(json, `claudexor: --council is a plan strategy (got mode '${mode}')`);
+        return renderOutputUsageFailure(outputMode, `claudexor: --council is a plan strategy (got mode '${mode}')`);
     }
-    return daemonRun(args, json, {
+    return daemonRun(args, outputMode, {
         mode,
         delegate,
         council,
@@ -405,12 +366,10 @@ async function orchestrate(args, mode, json, forced = {}) {
  * All five product modes enter through the managed daemon and control API.
  * `--json` prints one stable `{ runId, runDir, status }` machine envelope.
  */
-async function daemonRun(args, json, p) {
+async function daemonRun(args, outputMode, p) {
     const inPlace = flagBool(args, "in-place");
-    const jsonStream = flagBool(args, "json-stream");
-    if (json && jsonStream) {
-        return printUsageError(json, "claudexor: --json prints exactly one object and --json-stream prints NDJSON; pass one, not both");
-    }
+    const json = outputModeIsMachine(outputMode);
+    const jsonStream = outputModeIsStream(outputMode);
     let client;
     let addr;
     try {
@@ -504,6 +463,10 @@ async function daemonRun(args, json, p) {
         ...(p.reviewerModels ? { reviewerModels: p.reviewerModels } : {}),
         ...(p.reviewerEfforts ? { reviewerEfforts: p.reviewerEfforts } : {}),
     };
+    // The last run id this command bound, threaded into the failure envelope as
+    // a per-command extra: a run that DID start (or finish) must keep its handle
+    // even when a post-terminal read raises (e.g. 500 run_facts_invalid).
+    let terminalRunId = "";
     try {
         if (jsonStream) {
             // NDJSON machine surface (W13): an EARLY runId frame first, every run
@@ -513,18 +476,10 @@ async function daemonRun(args, json, p) {
             const started = await enqueueAndAwait(client, addr, body, { waitForTerminal: false });
             if (!started.runId) {
                 // Even the early-failure path stays valid NDJSON (compact, one line).
-                printJsonLine({
-                    frame: "run.terminal",
-                    runId: "",
-                    runDir: started.runDir,
-                    status: started.status,
-                    jobId: started.jobId,
-                    mode: p.mode,
-                    ...(started.error ? { error: started.error } : {}),
-                    ...daemonOutcomeProblemFields(started),
-                });
+                printJsonLine(projectTerminalRunOutput(started, p.mode, null, { frame: "run.terminal" }));
                 return exitCodeForState(started.status);
             }
+            terminalRunId = started.runId;
             printJsonLine({
                 frame: "run.started",
                 runId: started.runId,
@@ -538,43 +493,31 @@ async function daemonRun(args, json, p) {
             const final = started.jobId ? await client.status(started.jobId) : null;
             const out = mergeDaemonRunOutcome(started, final);
             const status = out.status;
-            const reason = daemonOutcomeSummary({ ...started, status, error: out.error });
             const detail = await fetchRunDetail(addr, out.runId);
-            printJsonLine({
+            const facts = projectRunOutcomeFacts(detail);
+            const reason = daemonOutcomeSummary({ ...out, outcomeFacts: facts ?? undefined });
+            printJsonLine(projectTerminalRunOutput(out, p.mode, detail, {
                 frame: "run.terminal",
-                runId: out.runId,
-                runDir: out.runDir,
-                status: out.status,
-                jobId: out.jobId,
-                mode: p.mode,
-                ...(out.error ? { error: out.error } : {}),
-                ...daemonOutcomeProblemFields(out),
-                ...(reason ? { summary: reason } : {}),
-                ...terminalDetailFields(detail),
-            });
+                summary: reason,
+            }));
             return exitCodeForState(status, projectRunOutcomeFacts(detail));
         }
         if (json) {
             // Pure machine surface: await the terminal outcome and print one JSON object.
             const out = await enqueueAndAwait(client, addr, body, { waitForTerminal: true });
-            // Preserve bench keys while adding mode and honest non-success detail.
-            const reason = daemonOutcomeSummary(out);
+            terminalRunId = out.runId;
             // ADD-ONLY key (bench contract keeps {runId,runDir,status}): the derived
             // apply-gate verdict, so machine callers act on truth instead of
             // re-implying eligibility from status. ONE GET /runs/:id feeds all three
             // terminal projections (INV-120/122).
             const detail = await fetchRunDetail(addr, out.runId);
-            printJson({
-                runId: out.runId,
-                runDir: out.runDir,
-                status: out.status,
-                jobId: out.jobId,
-                mode: p.mode,
-                ...(out.error ? { error: out.error } : {}),
-                ...daemonOutcomeProblemFields(out),
-                ...(reason ? { summary: reason } : {}),
-                ...terminalDetailFields(detail),
+            // Preserve bench keys while deriving the human summary from the same
+            // canonical receipt that feeds the machine terminal fields.
+            const reason = daemonOutcomeSummary({
+                ...out,
+                outcomeFacts: projectRunOutcomeFacts(detail) ?? undefined,
             });
+            printJson(projectTerminalRunOutput(out, p.mode, detail, { summary: reason }));
             return exitCodeForState(out.status, projectRunOutcomeFacts(detail));
         }
         // Text mode: enqueue, then live-stream the run through the shared follow
@@ -583,11 +526,15 @@ async function daemonRun(args, json, p) {
         const started = await enqueueAndAwait(client, addr, body, { waitForTerminal: false });
         if (!started.runId) {
             print(`run did not start: ${started.status}${started.error ? ` — ${started.error}` : ""}`);
+            for (const line of terminalRunRequiredActionLines(started))
+                print(line);
             return exitCodeForState(started.status);
         }
+        terminalRunId = started.runId;
         await followRun(started.runId, false);
         const final = started.jobId ? await client.status(started.jobId) : null;
-        const status = final?.state ?? started.status;
+        const out = mergeDaemonRunOutcome(started, final);
+        const status = out.status;
         const publicStatus = status;
         print("");
         print(`run ${started.runId} [${publicStatus}]`);
@@ -598,7 +545,11 @@ async function daemonRun(args, json, p) {
             print(`  ${terminalBanner}`);
         for (const line of terminalDelegationLines(projectDelegation(terminalDetail)))
             print(line);
-        print(`  artifacts: ${final?.runDir ?? started.runDir}`);
+        print(`  artifacts: ${out.runDir}`);
+        if (out.error)
+            print(`  error: ${out.error}`);
+        for (const line of terminalRunRequiredActionLines(out))
+            print(line);
         // 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).
@@ -626,6 +577,7 @@ async function daemonRun(args, json, p) {
                     runId: started.runId,
                     interactive: !json && !jsonStream, // TTY plan turns answer inline
                 });
+                terminalRunId = effectiveRunId;
             }
             // Offer apply only after a positive gate; otherwise print inspect/unblock guidance.
             const eligibility = await fetchApplyEligibility(addr, effectiveRunId);
@@ -647,9 +599,11 @@ async function daemonRun(args, json, p) {
     catch (err) {
         // D-7 projector: a typed control problem (code/retryable/context) survives
         // intact; --json-stream stays valid NDJSON via the compact-line stream option.
+        // A run that already started keeps its handle in the envelope (extras).
         return renderCliFailure(json || jsonStream, err, {
             messagePrefix: "claudexor:",
             stream: jsonStream,
+            ...(terminalRunId ? { extras: { runId: terminalRunId } } : {}),
         });
     }
 }
@@ -758,21 +712,12 @@ async function resolveRunStore(runId) {
     }
     return null;
 }
-async function controlJson(addr, path, init = {}) {
-    const response = await controlApiFetch(addr, path, init);
-    const text = await response.text();
-    const body = text ? JSON.parse(text) : {};
-    if (response.ok)
-        return body;
-    const detail = body && typeof body === "object" ? body : {};
-    throw new Error(String(detail["message"] ?? detail["error"] ?? `HTTP ${response.status}`));
-}
-function printPreflightError(args, json, error) {
-    if (json && (args._[0] ?? "help") === "plugin") {
+function printPreflightError(args, outputMode, error) {
+    if (outputMode === "json" && (args._[0] ?? "help") === "plugin") {
         printJson(pluginCommandErrorResult(args._[1], args._[2], flagBool(args, "dry-run"), 2, error));
         return 2;
     }
-    return printUsageError(json, error);
+    return renderOutputUsageFailure(outputMode, error);
 }
 function listCliArtifacts(root) {
     if (!existsSync(root))
@@ -794,8 +739,12 @@ function listCliArtifacts(root) {
 // KNOWN_FLAGS / VALUE_FLAGS (imported above) and the per-command scope check
 // are projections of the command registry. Unknown flags FAIL LOUDLY: `--harnes
 // codex` must never silently run all harnesses.
-async function dispatch(args, json) {
+async function dispatch(args, outputMode) {
     const cmd = args._[0] ?? "help";
+    if (outputMode === "conflict") {
+        return renderOutputUsageFailure(outputMode, "claudexor: --json prints exactly one object and --json-stream prints NDJSON; pass one, not both");
+    }
+    const json = outputModeIsMachine(outputMode);
     // `--help` resolves the COMMAND first (QA-057): scoped usage for a known verb,
     // global help for a bare/`help` verb, a usage error (exit 2) for a typo.
     if (flagBool(args, "help"))
@@ -803,18 +752,21 @@ async function dispatch(args, json) {
     const unknownFlags = Object.keys(args.flags).filter((f) => !KNOWN_FLAGS.has(f));
     if (unknownFlags.length > 0) {
         const error = `claudexor: unknown flag(s): ${unknownFlags.map((f) => `--${f}`).join(", ")} (see \`claudexor help\`)`;
-        return printPreflightError(args, json, error);
+        return printPreflightError(args, outputMode, error);
     }
     const valueFlagError = requiredStringFlagError(args, VALUE_FLAGS);
     if (valueFlagError)
-        return printPreflightError(args, json, valueFlagError);
+        return printPreflightError(args, outputMode, valueFlagError);
     // Registry-enforced per-command flag scope: a KNOWN flag outside the
     // 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));
     if (scopeError)
-        return printPreflightError(args, json, scopeError);
+        return printPreflightError(args, outputMode, scopeError);
+    const positionalError = commandPositionalError(cmd, args._.slice(1));
+    if (positionalError)
+        return printPreflightError(args, outputMode, positionalError);
     // No arguments at all = the interactive REPL: a thread of turns over the
     // current project with native session continuity (chat is the normal loop).
     if (args._.length === 0 && process.stdin.isTTY) {
@@ -835,21 +787,28 @@ async function dispatch(args, json) {
         }
         case "project":
             return projectCommand(args, json);
+        case "remote":
+            return remoteCommand(args, json);
+        case "setup":
+            return setupCommand(args, json);
         case "agent": {
             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(", ")}`);
+                    return renderOutputUsageFailure(outputMode, `claudexor: unknown --mode '${modeStr}'. valid: ${[...MODES].join(", ")}`);
                 }
-                return orchestrate(args, mode, json);
+                const modeScopeError = runModeFlagScopeError(mode, Object.keys(args.flags));
+                if (modeScopeError)
+                    return printPreflightError(args, outputMode, modeScopeError);
+                return orchestrate(args, mode, outputMode);
             }
-            return orchestrate(args, "agent", json);
+            return orchestrate(args, "agent", outputMode);
         }
         case "ask":
-            return orchestrate(args, "ask", json);
+            return orchestrate(args, "ask", outputMode);
         case "best-of":
-            return orchestrate(args, "agent", json, { race: true });
+            return orchestrate(args, "agent", outputMode, { race: true });
         // RETIRED verb spellings hard-error with the new spelling — no silent
         // aliases (same doctrine as retired mode ids: stale scripts fail loudly).
         case "run":
@@ -868,12 +827,12 @@ async function dispatch(args, json) {
                         : 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}`);
+            return printPreflightError(args, outputMode, `claudexor: the '${cmd}' verb was retired; use ${replacement}`);
         }
         case "plan":
-            return orchestrate(args, "plan", json);
+            return orchestrate(args, "plan", outputMode);
         case "create":
-            return orchestrate(args, "agent", json, { create: true });
+            return orchestrate(args, "agent", outputMode, { create: true });
         case "settings":
             return settingsCommand(args, json);
         case "quota":
@@ -922,12 +881,23 @@ async function dispatch(args, json) {
             const decision = store.readYaml(join(paths.arbitrationDir, "decision.yaml"));
             const workProduct = store.readYaml(join(paths.finalDir, "work_product.yaml"));
             const contract = TaskContract.safeParse(store.readYaml(join(paths.contextDir, "task.yaml")));
-            const primary = primaryOutputForCli(paths.root, contract.success ? contract.data.mode.kind : undefined);
+            const parsedFailure = RunFailure.safeParse(store.readYaml(join(paths.finalDir, "failure.yaml")));
+            const failure = parsedFailure.success ? parsedFailure.data : null;
             // The CLI projects the orchestrator-owned telemetry artifact and NEVER
             // recomputes evidence from raw events (single-owner rule); a missing
             // artifact (legacy run) renders "telemetry unavailable".
             const parsedTelemetry = RunTelemetry.safeParse(store.readYaml(join(paths.finalDir, "telemetry.yaml")));
             const telemetry = parsedTelemetry.success ? parsedTelemetry.data : null;
+            // GH #29: inspect reads the same immutable receipt as GET and terminal JSON.
+            const runFacts = readRunFactsArtifact(store, paths.finalDir, {
+                runId,
+                ...(contract.success ? { taskId: contract.data.task_id } : {}),
+            });
+            const primary = primaryOutputForCli(paths.root, contract.success ? contract.data.mode.kind : undefined, {
+                failure,
+                lifecycle: runFacts?.outcome.lifecycle,
+                ...(runFacts?.presentation ? { presentation: runFacts.presentation } : {}),
+            });
             const toolErrors = telemetry
                 ? telemetry.attempts.flatMap((a) => a.tool_errors
                     .filter((e) => !e.recovered && e.kind === "web")
@@ -949,22 +919,26 @@ async function dispatch(args, json) {
                 })))
                 : [];
             const artifacts = listCliArtifacts(paths.root).filter((p) => !p.endsWith("/"));
-            const outputReadyState = primary?.kind === "diagnostic"
-                ? "diagnostic"
-                : primary?.text.trim()
-                    ? "ready"
-                    : readTextSafe(join(paths.finalDir, "failure.yaml"))
-                        ? "diagnostic"
-                        : "finalizing";
+            const outputReadyState = runFacts?.presentation?.state ??
+                (primary?.kind === "diagnostic"
+                    ? "diagnostic"
+                    : primary?.text.trim()
+                        ? "ready"
+                        : (failure ?? readTextSafe(join(paths.finalDir, "failure.yaml")))
+                            ? "diagnostic"
+                            : "finalizing");
             const parsedDecision = DecisionRecord.safeParse(decision);
             const summary = readTextSafe(join(paths.finalDir, "summary.md"));
             if (json) {
                 printJson({
                     runId,
                     runDir: paths.root,
+                    lifecycle: runFacts?.outcome.lifecycle ?? null,
                     outputReadyState,
                     contract: contract.success ? contract.data : null,
                     telemetry,
+                    runFacts,
+                    failure,
                     toolErrors,
                     toolWarnings,
                     primaryOutput: primary,
@@ -976,6 +950,8 @@ async function dispatch(args, json) {
                 return summary || primary ? 0 : 1;
             }
             print(`run ${runId} @ ${paths.root}`);
+            if (runFacts)
+                print(`lifecycle: ${runFacts.outcome.lifecycle}`);
             if (contract.success) {
                 print(`mode: ${contract.data.mode.kind}`);
                 print(`access: requested=${contract.data.access.requested_profile} effective=${contract.data.access.effective_profile}`);
@@ -992,6 +968,12 @@ async function dispatch(args, json) {
                 print(`web: policy=${contract.data.external_context.policy} required=${contract.data.external_context.web_required} evidence=unavailable (no telemetry.yaml)`);
             }
             print(`output: ${outputReadyState}${primary ? ` ${primary.path}` : ""}`);
+            if (failure) {
+                print(`failure: ${failure.category}${failure.code ? `/${failure.code}` : ""} phase=${failure.phase}${failure.harnessId ? ` harness=${failure.harnessId}` : ""}`);
+                print(`failure message: ${failure.safeMessage}`);
+                for (const action of failure.nextActions)
+                    print(`next action: ${action}`);
+            }
             {
                 // Structured-output contract receipt (only present when the run was
                 // started with --output-schema); projected, never re-validated here.
@@ -1148,20 +1130,8 @@ async function dispatch(args, json) {
                 throw err;
             }
         }
-        case "harness": {
-            const sub = args._[1];
-            if (sub === "list") {
-                // Fakes are test fixtures, not real harnesses; `--all` reveals them.
-                const includeFakes = flagBool(args, "all");
-                const ids = [...buildRegistry({ includeFakes }).keys()];
-                if (json)
-                    printJson({ harnesses: ids });
-                else
-                    ids.forEach((id) => print(id));
-                return 0;
-            }
-            return printUsageError(json, "usage: claudexor harness list [--all]");
-        }
+        case "harness":
+            return harnessCommand(args, json);
         case "capabilities": {
             // The derived AgentCapabilityCatalog — same composer as the daemon's
             // GET /agent-capabilities and the MCP claudexor_capabilities tool.
@@ -1171,6 +1141,7 @@ async function dispatch(args, json) {
             else {
                 print(`claudexor ${catalog.version} — capability catalog`);
                 print(`modes: ${catalog.modes.join(", ")}`);
+                print(`git: ${catalog.git.status}${catalog.git.version ? ` (${catalog.git.version})` : ""}${catalog.git.remediation ? ` — ${catalog.git.remediation}` : ""}`);
                 print(`available harnesses: ${catalog.availableHarnesses.join(", ") || "(none)"}`);
                 for (const h of catalog.harnesses) {
                     const model = h.configuredModel
@@ -1207,7 +1178,7 @@ async function dispatch(args, json) {
             // callers get the ONE projector envelope (with message/code shape, no
             // longer a partial {ok,exitCode,error}); text mode prints the full help.
             if (json) {
-                return renderCliFailure(true, usageError(`claudexor: unknown command '${cmd}' (see \`claudexor help --json\`)`), {});
+                return renderOutputFailure(outputMode, usageError(`claudexor: unknown command '${cmd}' (see \`claudexor help --json\`)`), {});
             }
             process.stderr.write(`claudexor: unknown command '${cmd}'\n\n${HELP}\n`);
             return 2;
@@ -1223,18 +1194,27 @@ async function main() {
         process.stdout.write(`${CLI_VERSION}\n`);
         return 0;
     }
-    const json = flagBool(args, "json");
+    const outputMode = cliOutputMode(args);
     try {
-        return await dispatch(args, json);
+        return await dispatch(args, outputMode);
     }
     catch (err) {
-        return renderCliFailure(json, err);
+        return renderOutputFailure(outputMode, err);
     }
 }
 main()
     .then((code) => process.exit(code))
     .catch((err) => {
-    // Last-resort projector: still emit ONE envelope if the parse threw before json was known.
-    process.exit(renderCliFailure(process.argv.includes("--json"), err));
+    // Last-resort projector: infer the complete mode even if parsing itself threw.
+    const json = process.argv.includes("--json");
+    const stream = process.argv.includes("--json-stream");
+    const outputMode = json
+        ? stream
+            ? "conflict"
+            : "json"
+        : stream
+            ? "json-stream"
+            : "human";
+    process.exit(renderOutputFailure(outputMode, err));
 });
 //# sourceMappingURL=cli.js.map