@sentropic/h2a-runtime 0.98.6 → 0.98.7-rc.2

package/dist/index.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 import { randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command, Help } from "commander";
+import { agyClaudeQuotaError, assertAgyClaudeBuildAllowed, detectAgyClaudeQuotaExhaustion, isAgyClaudeModel, normalizeAgyEffort, readAgyClaudeQuotaStatus, resolveAgyModel, writeAgyClaudeQuotaStatus } from "./agy-claude.js";
 import { applyRuntimeHelpGroups, groupRuntimeHelpItems, } from "./cli-help-groups.js";
 import { attach, createRemoteSession, getRemoteSession, listRemoteSessions, refreshRemoteSession, renameRemoteSession, sessionTerminalHealth, stopRemoteSession, } from "./attach.js";
 import { authHeaders, clearDefaultRemote, getDefaultRemote, getDefaultTarget, getDefaultTools, getH2aConfig, getJobMaxAgeHours, getMaxConcurrent, getLlmMeshRuntimeConfig, getTmuxProfileConfig, getTunnel, resolveConfigPath, setDefaultRemote, setDefaultTarget, migrateConfigHomeIfNeeded, setDefaultTools, setLlmMeshRuntimeConfig, setTmuxProfileConfig, setToken, setTunnel, } from "./config.js";
-import { prepareCentralMcpForLaunch, prepareCentralMcpForRestore, } from "./central-mcp.js";
+import { prepareCentralMcpForLaunch, prepareCentralMcpForRestore, resolveCentralMcpLogPath, } from "./central-mcp.js";
+import { CRASH_LOG_COMPONENTS, formatCrashLogHumanRow, installCliWitnessOnce, installCrashHandlers, readFileTailLines, redactCrashText, readRecentCrashLogs, resolveCrashLogDir, } from "./crash-log.js";
+import { readHostJournal, resolveHostJournalPath } from "./native-terminal/journal.js";
 import { ensureConnected, stopTunnel } from "./tunnel.js";
 import { detectToolAuth, KNOWN_TOOLS, partitionTools } from "./auth-tools.js";
 import { transmittedSecrets, secretsSummary } from "./secrets.js";
@@ -1434,7 +1437,7 @@ async function injectLlmMeshGatewayEnv(mode = "auto", allowDirectFallback = true
         delete process.env.ANTHROPIC_BASE_URL;
         delete process.env.ANTHROPIC_AUTH_TOKEN;
         if (mode === "gateway") {
-            throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse` first");
+            throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse|claude-code` first");
         }
         if (allowDirectFallback) {
             process.stderr.write("[h2a] llm-mesh: gateway unavailable; continuing with native authentication.\n");
@@ -1516,7 +1519,7 @@ function renderNativeRestartResult(result, json) {
 export async function prepareStructuredGateway(mode, inject = (selectedMode) => injectLlmMeshGatewayEnv(selectedMode, selectedMode !== "gateway")) {
     const gateway = await inject(mode);
     if (mode === "gateway" && !gateway) {
-        throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse` first");
+        throw new Error("llm-mesh gateway is required but unavailable; no agent was started. Run `h2a llm-mesh start` or `h2a llm-mesh account enroll codex|cloud-code|muse|claude-code` first");
     }
     return gateway;
 }
@@ -1718,7 +1721,45 @@ function setAndReportDefaultRemote(url) {
     ensureManagedTmuxProfile(getTmuxProfileConfig().profile);
     process.stderr.write(`[h2a] default remote set to ${configured}\n`);
 }
+// Root commander error boundary (DEC-119): commander never prints its own
+// error text. `outputError` is a no-op so the commander-built message (which
+// echoes argv, possibly multi-line) is dropped; `exitOverride` writes a
+// static message chosen ONLY from `err.code` — never `err.message`, never
+// user-typed text. Registered on the ROOT program before any `.command()`
+// so the whole tree inherits it via `copyInheritedSettings`.
+function staticCommanderErrorForCode(code) {
+    switch (code) {
+        case "commander.unknownOption":
+            return "error: unknown option\n";
+        case "commander.unknownCommand":
+            return "error: unknown command\n";
+        case "commander.excessArguments":
+            return "error: too many arguments\n";
+        case "commander.missingArgument":
+            return "error: missing required argument\n";
+        case "commander.optionMissingArgument":
+            return "error: option argument missing\n";
+        case "commander.missingMandatoryOptionValue":
+            return "error: required option not specified\n";
+        case "commander.conflictingOption":
+            return "error: conflicting option\n";
+        case "commander.invalidArgument":
+            return "error: invalid argument\n";
+        default:
+            return "error: command error\n";
+    }
+}
+function isCommanderNonErrorCode(code) {
+    return (code === "commander.help" ||
+        code === "commander.helpDisplayed" ||
+        code === "commander.version" ||
+        code === "commander.executeSubCommandAsync");
+}
 export async function main(argv) {
+    // Passive fatal-path witness on the real entry path (see
+    // installCliWitnessOnce): observes via uncaughtExceptionMonitor, so the
+    // default crash/exit behavior is unchanged.
+    installCliWitnessOnce();
     // ②b — auto-migrate the config home remote-cli/ -> h2a/ on first run (backup +
     // compat symlink). Best-effort: never let it break a command. Runs once
     // (idempotent) before any config/registry read.
@@ -1767,6 +1808,25 @@ export async function main(argv) {
         "the separate remote and track CLIs. The heavy session runtime loads on " +
         "demand. h2a runs and coordinates agents; it is not itself an agent.")
         .version("0.0.0");
+    // Root error boundary (DEC-119): commander never prints its own error
+    // text. `outputError` is a no-op (commander message dropped);
+    // `exitOverride` writes the static per-code message. Registered here —
+    // before any `.command()` — so the whole tree inherits it through
+    // `copyInheritedSettings`.
+    program.configureOutput({
+        writeErr: (str) => {
+            process.stderr.write(str);
+        },
+        outputError: () => { },
+    });
+    program.showHelpAfterError(false);
+    program.showSuggestionAfterError(false);
+    program.exitOverride((err) => {
+        if (isCommanderNonErrorCode(err.code))
+            throw err;
+        process.stderr.write(staticCommanderErrorForCode(err.code));
+        throw err;
+    });
     const identityCommand = program
         .command("identity")
         .description("Inspect identity bindings or unlock a token-fenced identity lock");
@@ -3991,8 +4051,11 @@ export async function main(argv) {
         .option("--prompt-stdin", "read the initial Claude/Codex/AGY prompt from stdin (keeps it out of process argv)")
         .option("--agent <agent>", "AGY agent override (for example: stp)")
         .option("--model <model>", "Claude/Codex/AGY model override")
-        .option("--effort <level>", "reasoning effort: low|medium|high|xhigh (AGY supports low|medium|high)")
-        .option("--headless", "run once and exit (Claude -p / Codex exec / AGY --print), recording output under .h2a/runs/<name>")
+        .option("--role <role>", "launch purpose: review|challenge|build; AGY Claude builds require explicit opt-in")
+        .option("--allow-claude-build", "explicitly spend the reserved AGY Claude pool on a build")
+        .option("--output-file <path>", "expected AGY Claude headless artifact; report missing or unchanged output at exit")
+        .option("--effort <level>", "reasoning effort: low|medium|high|xhigh (AGY: low|medium|high, max maps to high)")
+        .option("--headless", "run once and exit (Claude -p / Codex exec / AGY stream-json), recording output under .h2a/runs/<name>")
         .option("--background", "classify this detached session as a background worker excluded from human restore")
         .option("--json", "emit one machine-readable h2a.run.result object")
         .option("--llm-gateway", "launch the CLI through the local llm-mesh gateway")
@@ -4014,13 +4077,30 @@ export async function main(argv) {
             process.exitCode = 2;
             return;
         }
-        if (opts.effort !== undefined && !isAgentLaunchEffort(opts.effort)) {
-            process.stderr.write(`[h2a] --effort must be low|medium|high|xhigh\n`);
+        try {
+            if (profile === "agy") {
+                const effort = normalizeAgyEffort(opts.effort);
+                if (effort !== undefined)
+                    opts.effort = effort;
+                const model = resolveAgyModel(opts.model, effort);
+                if (model !== undefined)
+                    opts.model = model;
+            }
+            assertAgyClaudeBuildAllowed({ profile, model: opts.model, role: opts.role, allowClaudeBuild: opts.allowClaudeBuild });
+            if (opts.outputFile && !(profile === "agy" && isAgyClaudeModel(opts.model) && opts.headless)) {
+                throw new Error("--output-file requires an AGY Claude headless run");
+            }
+        }
+        catch (error) {
+            process.stderr.write(`[h2a] ${error.message}\n`);
+            if (opts.json)
+                process.stdout.write(`${JSON.stringify({ kind: "h2a.run.failure", version: 1, state: "not-started",
+                    code: error.code ?? "invalid-agy-launch", error: error.message, retrySafe: false })}\n`);
             process.exitCode = 2;
             return;
         }
-        if (profile === "agy" && opts.effort === "xhigh") {
-            process.stderr.write("[h2a] AGY --effort must be low|medium|high\n");
+        if (opts.effort !== undefined && !isAgentLaunchEffort(opts.effort)) {
+            process.stderr.write(`[h2a] --effort must be low|medium|high|xhigh\n`);
             process.exitCode = 2;
             return;
         }
@@ -4383,6 +4463,10 @@ export async function main(argv) {
                     mkdirSync(runDir, { recursive: true });
                     outputLog = join(runDir, "output.log");
                     resultJson = join(runDir, "result.json");
+                    // Name admission above has completed. Retire the previous result
+                    // before returning a path or starting the new run-once supervisor.
+                    if (profile === "agy" && isAgyClaudeModel(opts.model))
+                        rmSync(resultJson, { force: true });
                     const headlessPromptInput = structuredLaunch && isAgentLaunchProfile(profile)
                         ? buildAgentLaunchStdin({
                             profile,
@@ -4396,10 +4480,10 @@ export async function main(argv) {
                         ({ name, slug, promptFile } = startNativeHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, headlessPromptInput, structuredLaunch, sessionClass, onCreateAttempt, structuredLaunch ? (owned) => {
                             launchOwnership = { host: "native", sessions: [owned] };
                             launchGuard = startLaunchGuard(runDir, launchOwnership);
-                        } : undefined));
+                        } : undefined, opts.outputFile ? resolve(cwd, opts.outputFile) : undefined));
                     }
                     else {
-                        ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, headlessPromptInput, structuredLaunch, sessionClass, onCreateAttempt));
+                        ({ name, slug, agentPane, promptFile } = startHeadlessSession(profile, command, cwd, args, resultJson, outputLog, label, getTmuxProfileConfig().profile, headlessPromptInput, structuredLaunch, sessionClass, onCreateAttempt, opts.outputFile ? resolve(cwd, opts.outputFile) : undefined));
                     }
                 }
                 else if (sessionHost === "native") {
@@ -4532,6 +4616,18 @@ export async function main(argv) {
                             now: () => Date.now(),
                         }, { profile });
                     if (promptDelivery.state !== "working") {
+                        const quotaDiagnostic = promptDelivery.state === "submitted-idle" ? "" : `${promptDelivery.reason}\n${promptDelivery.capture ?? ""}`;
+                        const quotaVerdict = profile === "agy" && isAgyClaudeModel(opts.model)
+                            ? detectAgyClaudeQuotaExhaustion(quotaDiagnostic) : { exhausted: false };
+                        const quotaFailure = profile === "agy" && isAgyClaudeModel(opts.model) &&
+                            promptDelivery.state === "provider-blocked" && promptDelivery.providerError
+                            ? promptDelivery.providerError : quotaVerdict.exhausted
+                            ? agyClaudeQuotaError(quotaVerdict.signature, quotaDiagnostic) : undefined;
+                        if (quotaFailure)
+                            try {
+                                writeAgyClaudeQuotaStatus(quotaFailure.quota);
+                            }
+                            catch { /* Response still carries the observation. */ }
                         cleanupHeadlessPromptFile(promptFile);
                         // Only claim the session is gone when the kill actually reported
                         // success. "nothing is left running" over an unchecked call is the
@@ -4561,15 +4657,47 @@ export async function main(argv) {
                                 ? `[h2a] last screen:\n${promptDelivery.capture}\n`
                                 : ""));
                         process.exitCode = 1;
-                        if (opts.json && promptDelivery.state === "provider-blocked") {
+                        if (opts.json && (promptDelivery.state === "provider-blocked" || quotaFailure)) {
                             process.stdout.write(`${JSON.stringify({ kind: "h2a.run.failure", version: 1,
-                                state: "provider-blocked", launchId: slug, error: promptDelivery.reason,
-                                stopped, retrySafe: false, prompt: { delivered: true, waitedMs: promptDelivery.waitedMs },
+                                state: "provider-blocked", launchId: slug, error: quotaFailure?.message ?? (promptDelivery.state === "submitted-idle" ? "agent idle after submission" : promptDelivery.reason),
+                                stopped, retrySafe: false, prompt: { delivered: promptDelivery.state === "provider-blocked", ...("waitedMs" in promptDelivery ? { waitedMs: promptDelivery.waitedMs } : {}) },
+                                ...(quotaFailure ? { code: quotaFailure.code, error: quotaFailure.message, quota: quotaFailure.quota,
+                                    resetsAt: quotaFailure.resetsAt, retryable: false, model: opts.model } : {}),
                             })}\n`);
                         }
                         return;
                     }
                 }
+                const reportAgyCompletion = () => {
+                    if (!(profile === "agy" && isAgyClaudeModel(opts.model) && opts.headless && resultJson))
+                        return false;
+                    try {
+                        const completed = JSON.parse(readFileSync(resultJson, "utf8"));
+                        // The previous result was removed before this supervisor started.
+                        // Filesystem and wall-clock timestamps cannot prove generation.
+                        if (!["h2a.run.failure", "h2a.run.completion"].includes(completed.kind))
+                            return false;
+                        launchGuard?.complete();
+                        if (opts.json)
+                            process.stdout.write(`${JSON.stringify({ ...completed, launchId: slug, result: { path: resultJson }, logs: { path: outputLog } })}\n`);
+                        else
+                            process.stderr.write(`[h2a] ${completed.error ?? "AGY run completed"}\n`);
+                        process.exitCode = completed.state === "done" ? 0 : 1;
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    } // Still running; the durable result may appear later.
+                };
+                if (profile === "agy" && isAgyClaudeModel(opts.model) && opts.headless && resultJson) {
+                    // A fast provider refusal may finish before the host PID probe.
+                    // Return that typed completion rather than a misleading PID error.
+                    for (let attempt = 0; attempt < 5; attempt++) {
+                        if (reportAgyCompletion())
+                            return;
+                        sleepSync(50);
+                    }
+                }
                 const pid = sessionHost === "native"
                     ? nativeSessionPid(name)
                     : agentPane
@@ -4581,6 +4709,9 @@ export async function main(argv) {
                         ? paneWorkerPid(agentPane)
                         : undefined;
                 if (structuredLaunch && pid === undefined) {
+                    // The supervisor can publish and exit DURING the PID probe.
+                    if (reportAgyCompletion())
+                        return;
                     cleanupHeadlessPromptFile(promptFile);
                     // OWN-CLEANUP, deliberately NOT resolver-derived (F1 sorting):
                     // `name`/`sessionHost` are the session and host THIS command
@@ -4650,6 +4781,8 @@ export async function main(argv) {
                         tmuxSession: only.name,
                         host: sessionHost === "native" ? "native" : "tmux",
                         profile,
+                        ...(opts.model ? { model: opts.model, modelSource: "launch-argument", effectiveModel: "unknown" } : {}),
+                        ...(profile === "agy" && isAgyClaudeModel(opts.model) ? { quota: readAgyClaudeQuotaStatus() } : {}),
                         workspace: cwd,
                         mode: opts.headless ? "headless" : "interactive",
                         background: opts.background === true,
@@ -7525,11 +7658,26 @@ export async function main(argv) {
     llmMeshAccountCommand
         .command("enroll <provider>")
         .description("Enroll through the sentropic-owned OAuth state machine " +
-        "(cloud-code, codex, muse OAuth device flow, or mistral-vibe browser sign-in — alias: vibe). " +
-        "--cli imports credentials from the provider's local CLI store instead (muse only)")
+        "(cloud-code, codex, muse OAuth device flow, mistral-vibe browser sign-in — alias: vibe, or claude-code). " +
+        "--from oauth|cli|token selects the source (default oauth): cli imports from the provider's official CLI store (muse, claude-code), " +
+        "token imports a serialized credential from a secret manager via stdin pipe or masked prompt (claude-code only). " +
+        "--cli / --token are the same modes as booleans")
         .option("--config-ref <ref>", "sentropic configuration reference for OAuth")
-        .option("--cli", "import credentials from the provider's local CLI store (muse only) instead of the OAuth flow")
-        .action(async (provider, opts) => {
+        .option("--from <mode>", "enrollment source: oauth (default), cli (provider official CLI store) or token (secret-manager credential)")
+        .option("--cli", "import credentials from the provider's local CLI store (muse, claude-code) instead of the OAuth flow. Takes no value")
+        .option("--token", "import a serialized credential from a secret manager into llm-mesh (claude-code only): pipe it on stdin, or enter it at the masked prompt. Takes no value; never argv, never logged")
+        .allowExcessArguments(true)
+        .action(async (provider, opts, command) => {
+        // Static excess-argument refusal (m1): commander would otherwise echo
+        // every positional value (including a secret) on stderr before the
+        // action runs. Excess positionals are refused here without echoing
+        // any value. Token material travels on stdin only, never argv.
+        const positionalCount = Array.isArray(command?.args) ? command.args.length : 1;
+        if (positionalCount > 1) {
+            process.stderr.write("[h2a] llm-mesh account: too many arguments (expected provider only; never pass secrets in argv)\n");
+            process.exitCode = 1;
+            return;
+        }
         // "vibe" is the CLI-friendly alias of the mistral-vibe transport.
         const normalized = provider === "vibe" ? "mistral-vibe" : provider;
         if (normalized === "muse-code") {
@@ -7541,19 +7689,48 @@ export async function main(argv) {
             process.exitCode = 1;
             return;
         }
+        if (opts.from !== undefined && opts.from !== "oauth" && opts.from !== "cli" && opts.from !== "token") {
+            process.stderr.write("[h2a] llm-mesh account: --from must be one of oauth, cli, token\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.from !== undefined && (opts.cli || opts.token)) {
+            process.stderr.write("[h2a] llm-mesh account: --from cannot be combined with --cli or --token\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.cli && opts.token) {
+            process.stderr.write("[h2a] llm-mesh account: --cli and --token cannot be combined\n");
+            process.exitCode = 1;
+            return;
+        }
+        if ((opts.cli || opts.from === "cli") && normalized !== "muse" && normalized !== "claude-code") {
+            process.stderr.write("[h2a] llm-mesh account: provider has no CLI-store import; " +
+                "--cli/--from cli is only valid for providers with a local CLI import (muse, claude-code)\n");
+            process.exitCode = 1;
+            return;
+        }
+        if ((opts.token || opts.from === "token") && normalized !== "claude-code") {
+            process.stderr.write(`[h2a] llm-mesh account: --token/--from token is only valid for claude-code\n`);
+            process.exitCode = 1;
+            return;
+        }
         if (normalized !== "cloud-code" &&
             normalized !== "codex" &&
             normalized !== "muse" &&
-            normalized !== "mistral-vibe") {
-            process.stderr.write(`[h2a] llm-mesh account: unsupported provider "${provider}". ` +
-                "Supported: cloud-code, codex, muse (OAuth; --cli imports the CLI store), mistral-vibe (alias: vibe)\n");
+            normalized !== "mistral-vibe" &&
+            normalized !== "claude-code") {
+            process.stderr.write("[h2a] llm-mesh account: unsupported provider. " +
+                "Supported: cloud-code, codex, muse (OAuth; --cli imports the CLI store), mistral-vibe (alias: vibe), claude-code (OAuth; --cli imports the CLI store; --token imports a secret-manager credential)\n");
             process.exitCode = 1;
             return;
         }
         try {
             const account = await enrollViaFacade(normalized, {
                 ...(opts.configRef ? { configRef: opts.configRef } : {}),
+                ...(opts.from ? { from: opts.from } : {}),
                 ...(opts.cli ? { cliImport: true } : {}),
+                ...(opts.token ? { tokenImport: true } : {}),
             });
             process.stdout.write(`[h2a] llm-mesh account: enrolled ${account.provider}; ` +
                 "account inventory remains in Sentropic\n");
@@ -7771,6 +7948,75 @@ export async function main(argv) {
             ? `[h2a] lineage ${id} resumed\n`
             : `[h2a] lineage ${id} was not suspended (no-op)\n`);
     });
+    // ---------------------------------------------------------------------------
+    // logs — last crash-log incidents (native host journal + per-component logs)
+    // ---------------------------------------------------------------------------
+    program
+        .command("logs")
+        .description("Show the last crash-log incidents: native host journal plus cli/attach/mcp-server logs.")
+        .option("--component <name>", "only this component (native-host|cli|attach|mcp-server)")
+        .option("-n, --lines <n>", "number of rows to show", "50")
+        .option("--json", "emit JSON rows instead of human lines")
+        .action((opts) => {
+        const dir = resolveCrashLogDir();
+        const lines = Math.max(1, parseInt(opts.lines ?? "50", 10) || 50);
+        const only = (opts.component ?? "").trim();
+        const wantHost = only === "" || only === "native-host";
+        const wanted = CRASH_LOG_COMPONENTS.filter((c) => only === "" || only === c);
+        if (!wantHost && wanted.length === 0) {
+            process.stderr.write("h2a logs: --component must be native-host|cli|attach|mcp-server\n");
+            process.exitCode = 1;
+            return;
+        }
+        const rows = readRecentCrashLogs(wanted, lines).map((row) => ({
+            timestamp: row.timestamp,
+            component: row.component,
+            version: row.version,
+            pid: row.pid,
+            event: row.event,
+            ...(row.sessionId ? { sessionId: row.sessionId } : {}),
+            ...(row.instanceId ? { instanceId: row.instanceId } : {}),
+            ...(row.reason ? { reason: row.reason } : {}),
+            ...(row.exitCode !== undefined ? { exitCode: row.exitCode } : {}),
+            ...(row.signal ? { signal: row.signal } : {}),
+            ...(row.detail ? { detail: row.detail } : {}),
+        }));
+        const hostRows = wantHost
+            ? readHostJournal(resolveHostJournalPath())
+                .slice(-lines)
+                .map((entry) => ({
+                timestamp: entry.timestamp ?? "unknown",
+                component: "native-host",
+                ...entry,
+            }))
+            : [];
+        const merged = [...hostRows, ...rows]
+            .sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0))
+            .slice(-lines);
+        // The raw server output is verbatim child stderr (unredacted at rest):
+        // read it before the empty check so a raw-only crash is shown, and
+        // redact it on display like every structured row.
+        const rawPath = resolveCentralMcpLogPath();
+        const rawTail = (only === "" || only === "mcp-server") ? readFileTailLines(rawPath, 20) : [];
+        if (merged.length === 0 && rawTail.length === 0) {
+            process.stdout.write(`[h2a] no crash-log incidents in ${dir}\n`);
+            return;
+        }
+        if (opts.json && merged.length > 0) {
+            process.stdout.write(`${merged.map((row) => JSON.stringify(row)).join("\n")}\n`);
+            return;
+        }
+        for (const row of merged) {
+            process.stdout.write(`${formatCrashLogHumanRow(row)}\n`);
+        }
+        if (rawTail.length > 0) {
+            // The server process itself leaves no structured rows (it dies with
+            // its witness); its raw stderr tail is the only "why" for its crash.
+            process.stdout.write(`[h2a] --- mcp-central.log raw tail (${rawPath}) ---\n`);
+            for (const line of rawTail)
+                process.stdout.write(`${redactCrashText(line)}\n`);
+        }
+    });
     // Help layout only — assign every top-level command an intention group and
     // render the groups in the declared order instead of registration order.
     // Presentational for every PRE-EXISTING RECOGNIZED COMMAND: `helpGroup()` and
@@ -7822,7 +8068,25 @@ export async function main(argv) {
     applyRuntimeHelpGroups(program.createHelp().visibleCommands(program));
     program.configureHelp({ groupItems: groupRuntimeHelpItems });
     program.addHelpText("after", "\nGrouped map of every h2a command (core + runtime): h2a explain\n");
-    await program.parseAsync([...argv]);
+    try {
+        await program.parseAsync([...argv]);
+    }
+    catch (err) {
+        // Commander errors already wrote their static per-code message in
+        // `exitOverride`; only set the exit code here, never `err.message`.
+        if (err !== null &&
+            typeof err === "object" &&
+            "code" in err &&
+            typeof err.code === "string") {
+            const code = err.code;
+            if (code.startsWith("commander.")) {
+                const exitCode = err.exitCode;
+                process.exitCode = typeof exitCode === "number" ? exitCode : 1;
+                return process.exitCode;
+            }
+        }
+        throw err;
+    }
     const code = process.exitCode;
     return typeof code === "number" ? code : 0;
 }
@@ -7838,6 +8102,9 @@ function isEntryPoint() {
     }
 }
 if (isEntryPoint()) {
+    // Passive witness for fatal paths outside runOp: installed once inside
+    // main() so the lazy core-binary dispatch path is covered too.
+    installCliWitnessOnce();
     main(process.argv).catch((error) => {
         if (error instanceof AuthRefreshError ||
             error instanceof AuthBundleMissingError) {