@vibesdotdev/cli 0.0.2 → 1.0.0-rc.3

package/dist/surface/CLISurface.js

@@ -1,95 +1,405 @@
+import { argvWantsJson, buildJsonFailureEnvelope, writeScrubbedEnvelope } from "./failure-output.js";
+export { argvWantsJson } from "./failure-output.js";
+import { getCLIInvocationClient } from "../invocation/state.js";
 import { Command, CommanderError } from 'commander';
-import { writeSync } from 'node:fs';
-import { CLIExitSignal, registerCLIProviders, resetKeepAlive, shouldKeepAlive } from '../providers';
-import { createPatternResolver } from '../patterns';
-import { buildCommandContext } from './build-context';
-import { registerGroups } from './register-groups';
-import { registerCommands } from './register-commands';
-import { getLogger } from '../logging';
-const logger = getLogger('surface');
-/**
- * Strip frames pointing into the `bun build --compile` virtual filesystem
- * (`/$bunfs/root/vibes.js:...`) and other bundle-only paths. These leak
- * implementation details that aren't actionable for users.
- */
-function stripBundlePaths(text) {
-    return text
-        .split('\n')
-        .filter((line) => {
-        if (line.includes('/$bunfs/'))
-            return false;
-        if (line.includes('B:/~BUN/'))
-            return false;
-        return true;
-    })
-        .join('\n')
-        .trim();
+import * as z from 'zod/v4';
+import { CapabilityError, CaughtFailureSchema, getRuntimeStdio, getRuntimeStdioOutputPlane, hasRuntimeStdioOutputPlane, isCapabilityError, valueFreeFailure } from '@vibesdotdev/kernel';
+import { isCLIExitSignal, readCLIExitCode, registerCLIProviders, resolveOutputStripSgr, shouldKeepAlive } from "../boot/providers.js";
+import { createPatternResolver } from "../patterns/resolver.js";
+import { CLICommandRecommendationsSchema } from "../schemas/command-recommendations.js";
+import { buildCommandContext } from "./build-context.js";
+import { configureInheritedGlobalOptions, resolveScopedCommandOptions } from "./inherited-options.js";
+import { resolveCLIInvocationEffects } from "./invocation-effects.js";
+import { CLIInvocationController } from "./invocation-lifecycle.js";
+import { failureOf } from "./failure-of.js";
+import { resolveCliInvocationActor, routeActionsThrough } from "./invocation-actions.js";
+import { registerGroups } from "./register-groups.js";
+import { registerCommands } from "./register-commands.js";
+import { hasWrittenJsonPayload } from "../commands/output.js";
+import { getLogger } from "../support/logging/logging.js";
+import { renderCliFailure, scrubCliText, stripBundlePaths } from "./failure-report.js";
+const HELP_FLAGS = new Set(['-h', '--help']);
+function resolveMaterializedCommand(program, destination) {
+    let command = program;
+    const segments = destination.trim().split(/\s+/);
+    for (let index = 0; index < segments.length; index++) {
+        const segment = segments[index];
+        const next = command.commands.find((candidate) => candidate.name() === segment || candidate.aliases().includes(segment));
+        if (!next) {
+            const arguments_ = segments.slice(index);
+            if (command.commands.length === 0 && command.registeredArguments.length > 0 && arguments_.length <= positionalCapacity(command)) {
+                return { command, arguments: arguments_ };
+            }
+            return undefined;
+        }
+        command = next;
+    }
+    return { command, arguments: [] };
 }
 /**
- * Map common runtime errors to actionable, user-facing guidance.
- * Falls back to the original message when no mapping applies.
- *
- * Returns `null` when no friendly mapping is known (caller falls back to
- * the raw error message).
+ * Find the next command operand without mistaking an option value for command
+ * intent. Unknown options are returned explicitly so help cannot hide one by
+ * short-circuiting before Commander's validation.
  */
-function mapKnownError(rawMessage) {
-    // "No matching implementation found for query (filtered to: foo.bar)"
-    const noMatchingImpl = /No matching implementation found for query \(filtered to:\s*([^)]+)\)/i.exec(rawMessage);
-    if (noMatchingImpl) {
-        const target = noMatchingImpl[1].trim();
-        return (`No provider for "${target}". The plugin owning this query did not register, ` +
-            `or its dependencies are missing. Run with -v for plugin-load details.`);
-    }
-    // "No available adapter for record 'session.sessions'. Checked: storage.localdb"
-    const noAdapter = /No available adapter for record\s*'?([^'"\s]+)'?\.?\s*Checked:\s*([^\n]+)/i.exec(rawMessage);
-    if (noAdapter) {
-        const record = noAdapter[1].trim();
-        const checked = noAdapter[2].trim();
-        return (`No storage adapter is initialized for "${record}" (checked: ${checked}).\n` +
-            `Run \`vibes os init\` to set up local storage, or run with -v for details.`);
-    }
-    if (rawMessage.includes('getRuntimePathSync() called before the runtime path service was resolved')) {
-        return ('The runtime path service has not been initialized yet. ' +
-            'This is a bug — please report it. Run with -v for the full stack.');
+function commandOperand(command, args) {
+    let optionsEnded = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!optionsEnded && token === '--') {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && token.startsWith('-') && token !== '-') {
+            if (HELP_FLAGS.has(token))
+                continue;
+            const option = commandOptionForToken(command, token);
+            if (!option)
+                return { kind: 'unknown-option', token, index };
+            if (option.required && !hasAttachedOptionValue(option, token)) {
+                index += 1;
+            }
+            else if (option.optional &&
+                !hasAttachedOptionValue(option, token) &&
+                args[index + 1] !== undefined &&
+                !args[index + 1].startsWith('-')) {
+                index += 1;
+            }
+            continue;
+        }
+        return { kind: 'operand', token, index };
+    }
+    return null;
+}
+function commandOptionForToken(command, token) {
+    return command.options.find((option) => token === option.short ||
+        token === option.long ||
+        (option.long !== undefined && token.startsWith(`${option.long}=`)) ||
+        (option.short !== undefined &&
+            (option.required || option.optional) &&
+            token.startsWith(option.short) &&
+            token.length > option.short.length));
+}
+function hasAttachedOptionValue(option, token) {
+    return ((option.long !== undefined && token.startsWith(`${option.long}=`)) ||
+        (option.short !== undefined && token.startsWith(option.short) && token !== option.short));
+}
+function findSubcommand(command, operand) {
+    const commands = [...command.commands, ...command.createHelp().visibleCommands(command)];
+    return commands.find((candidate) => candidate.name() === operand ||
+        candidate.aliases().includes(operand) ||
+        candidate.name() === '*');
+}
+/** Every operand in `args` for `command`, in order (option values and help flags skipped). */
+function commandOperands(command, args) {
+    const operands = [];
+    let rest = args;
+    for (let found = commandOperand(command, rest); found?.kind === 'operand'; found = commandOperand(command, rest)) {
+        operands.push(found.token);
+        rest = rest.slice(found.index + 1);
+    }
+    return operands;
+}
+/** How many operands `command` accepts: its declared positionals, unbounded when one is variadic. */
+function positionalCapacity(command) {
+    return command.registeredArguments.some((argument) => argument.variadic)
+        ? Number.POSITIVE_INFINITY
+        : command.registeredArguments.length;
+}
+function isImplicitHelpCommand(command, operand) {
+    const explicitlyRegistered = command.commands.some((candidate) => candidate.name() === operand || candidate.aliases().includes(operand));
+    if (explicitlyRegistered)
+        return false;
+    return command
+        .createHelp()
+        .visibleCommands(command)
+        .some((candidate) => candidate.name() === operand);
+}
+function findUnknownCommandOption(command, args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === '--')
+            return null;
+        if (!token.startsWith('-') || token === '-' || HELP_FLAGS.has(token))
+            continue;
+        const option = commandOptionForToken(command, token);
+        if (!option)
+            return { kind: 'unknown-option', token, index };
+        if (option.required && !hasAttachedOptionValue(option, token)) {
+            index += 1;
+        }
+        else if (option.optional &&
+            !hasAttachedOptionValue(option, token) &&
+            args[index + 1] !== undefined &&
+            !args[index + 1].startsWith('-')) {
+            index += 1;
+        }
     }
     return null;
 }
-function formatCliError(error, verbose) {
-    if (verbose) {
-        const text = error instanceof Error ? error.stack?.trim() || error.message.trim() : String(error);
-        return text;
+function normalizedHelpArgv(argv, implicitHelpIndexes) {
+    if (implicitHelpIndexes.length === 0)
+        return argv;
+    const indexes = new Set(implicitHelpIndexes);
+    const args = argv.slice(2).filter((_, index) => !indexes.has(index));
+    if (!args.some((token) => HELP_FLAGS.has(token)))
+        args.push('--help');
+    return [argv[0] ?? 'node', argv[1] ?? 'vibes', ...args];
+}
+/**
+ * Resolve help intent against the materialized Commander tree. Commander's
+ * implicit `help <path>` command is syntax for the same lookup as
+ * `<path> --help`, not a positional leaf that may silently fall back to parent
+ * help.
+ */
+function commandHelpIntent(program, argv) {
+    let command = program;
+    let remaining = argv.slice(2);
+    let remainingOffset = 0;
+    const commandPath = [program.name()];
+    let helpRequested = remaining.some((token) => HELP_FLAGS.has(token));
+    const implicitHelpIndexes = [];
+    while (true) {
+        const operand = commandOperand(command, remaining);
+        const effectiveArgv = () => normalizedHelpArgv(argv, implicitHelpIndexes);
+        if (operand === null) {
+            return helpRequested ? { kind: 'resolved-help', argv: effectiveArgv() } : null;
+        }
+        if (operand.kind === 'unknown-option') {
+            return helpRequested
+                ? {
+                    kind: 'unknown-option',
+                    argv: effectiveArgv(),
+                    commandPath,
+                    option: operand.token
+                }
+                : null;
+        }
+        if (isImplicitHelpCommand(command, operand.token)) {
+            helpRequested = true;
+            implicitHelpIndexes.push(remainingOffset + operand.index);
+            remainingOffset += operand.index + 1;
+            remaining = remaining.slice(operand.index + 1);
+            continue;
+        }
+        const subcommand = findSubcommand(command, operand.token);
+        if (subcommand) {
+            commandPath.push(operand.token);
+            command = subcommand;
+            remainingOffset += operand.index + 1;
+            remaining = remaining.slice(operand.index + 1);
+            continue;
+        }
+        if (command.registeredArguments.length > 0) {
+            const unknownOption = findUnknownCommandOption(command, remaining);
+            if (!helpRequested)
+                return null;
+            // More operands than the selected command accepts are a path, not its
+            // arguments: `vibes code deps analyze --help` names no command under
+            // the editor's `code` alias (whose one positional is a workspace), so
+            // it must not answer the editor's help.
+            const operands = commandOperands(command, remaining);
+            if (operands.length > positionalCapacity(command)) {
+                return { kind: 'unresolved-path', argv: effectiveArgv(), commandPath: [...commandPath, ...operands] };
+            }
+            return unknownOption
+                ? {
+                    kind: 'unknown-option',
+                    argv: effectiveArgv(),
+                    commandPath,
+                    option: unknownOption.token
+                }
+                : { kind: 'resolved-help', argv: effectiveArgv() };
+        }
+        return helpRequested
+            ? {
+                kind: 'unresolved-path',
+                argv: effectiveArgv(),
+                commandPath: [...commandPath, operand.token]
+            }
+            : null;
     }
-    const rawMessage = error instanceof Error ? error.message.trim() : String(error).trim();
-    const friendly = mapKnownError(rawMessage);
-    const body = friendly ?? rawMessage;
-    const cleaned = stripBundlePaths(body);
-    return cleaned || 'CLI command failed (run with -v for details).';
 }
+function rejectUnknownCommandHelp(program, commandPath) {
+    const attempted = commandPath.join(' ');
+    const codePoints = Array.from(attempted);
+    const boundedOperand = codePoints.length <= 256 ? attempted : `${codePoints.slice(0, 256).join('')}…`;
+    const path = JSON.stringify(boundedOperand);
+    program.error(`error: unknown command path ${path}\n` +
+        `Run "${program.name()} --help" to see available commands.`, { exitCode: 1, code: 'commander.unknownCommand' });
+}
+function rejectUnknownCommandHelpOption(program, commandPath, option) {
+    const codePoints = Array.from(option);
+    const boundedOption = codePoints.length <= 256 ? option : `${codePoints.slice(0, 256).join('')}…`;
+    program.error(`error: unknown option ${JSON.stringify(boundedOption)} while resolving ` +
+        `${JSON.stringify(commandPath.join(' '))} help`, { exitCode: 1, code: 'commander.unknownOption' });
+}
+/** Anything that carries both `code` and `exitCode`: a CommanderError, or a value shaped like one. */
+const CommanderFailureSchema = z.custom((value) => typeof value === 'object' && value !== null && 'exitCode' in value && 'code' in value);
+/** A Commander-shaped failure's fields, each read independently. */
+const CommanderFieldsSchema = z.object({
+    code: z.union([z.string(), z.unknown().transform((code) => String(code ?? 'unknown'))]),
+    exitCode: z.number().optional().catch(undefined),
+    message: z.string().optional().catch(undefined)
+});
+/** The caught failure as a Commander outcome, when it is Commander-shaped. */
+function commanderOutcome(failure) {
+    const candidate = failure instanceof Error ? failure : failure.value;
+    if (!(candidate instanceof CommanderError) && !CommanderFailureSchema.safeParse(candidate).success)
+        return undefined;
+    const fields = CommanderFieldsSchema.parse(candidate);
+    return {
+        code: fields.code,
+        exitCode: fields.exitCode,
+        message: fields.message,
+        commanderOwn: fields.code.startsWith('commander.')
+    };
+}
+export { buildJsonFailureEnvelope, writeJsonEnvelope, reportBootstrapFailure } from "./failure-output.js";
+export { mapKnownError, renderCliFailure } from "./failure-report.js";
 export class CLISurface {
     runtime;
     program;
     options;
     groups = new Map();
     groupDescriptors = new Map();
+    commandRecommendations;
     patternResolver = null;
     initialized = false;
+    runtimeWriter;
+    invocationController;
+    invocationDescriptors = new WeakMap();
+    invocationPreparers = [];
+    /** The overlay the dispatched action runs with; set once its preparation completes. */
+    actionInvocation;
+    /** The host env snapshot failure text is scrubbed against; read before any runtime this surface holds is disposed. */
+    capturedHostEnv;
+    /** The host output plane this surface installed, and the runtime it was resolved on (its methods refuse once that runtime is disposed). */
+    outputPlane;
     constructor(runtime, program, options = {}) {
         this.runtime = runtime;
         this.program = program;
         this.options = options;
+        this.commandRecommendations = CLICommandRecommendationsSchema.parse(options.commandRecommendations ?? {});
+        // Observer failures never change the outcome; under -v the report also
+        // carries the failure rendered by the one renderer (cause chain, redacted).
+        this.invocationController = new CLIInvocationController(() => this.runtime, (failure) => (this.options.verbose ? renderCliFailure(failure, { verbose: true, env: this.hostEnv() }) : undefined));
+        // Every action runs as one invocation of this runtime, acting for the
+        // actor its preparation resolved (rc01 §2.1, interactiveSession).
+        routeActionsThrough(this.program, (action) => this.runtime.runInvocation(action, this.actionInvocation));
+        this.program.hook('preAction', async (_command, actionCommand) => {
+            const descriptor = this.invocationDescriptors.get(actionCommand);
+            const baseInfo = {
+                commandPath: resolveCommandPath(actionCommand),
+                effects: resolveCLIInvocationEffects(actionCommand, descriptor?.effects)
+            };
+            if (resolveScopedCommandOptions(actionCommand).finite === true)
+                baseInfo.lifecycle = 'finite';
+            // The host declared purpose and lifecycle once, before boot
+            // (`--finite ? finite : persistent`); nothing patches them here. A
+            // serve command becomes its own host instead (rc02-rc03 §2.3): the
+            // un-activated CLI runtime is disposed and the serve host, booted
+            // through the one entry, runs the action and every preparation.
+            if (baseInfo.effects.serve && descriptor) {
+                // The transition disposes this runtime: read the host env first.
+                this.hostEnv();
+                if (!this.options.serveTransition) {
+                    throw new CapabilityError(`'${descriptor.id}' is a serve command, but this CLI host supplied no serve transition.`, 'INTERNAL', { reason: 'dependency-absent', details: { command: descriptor.id } });
+                }
+                this.runtime = await this.options.serveTransition({
+                    descriptorId: descriptor.id,
+                    serve: baseInfo.effects.serve
+                });
+                registerCLIProviders(this.runtime, this.options);
+                (await getCLIInvocationClient(this.runtime)).begin();
+                await this.resolveWriter();
+            }
+            // Admission happens here, in the action envelope, before any
+            // preparer or observer runs — never inside a handler after the
+            // outer lifecycle hooks have already fired unvetted (RC08/D-RC04
+            // U7). `resolveCliInvocationActor` reads only the host's own
+            // captured launch identity and (when the action writes home) the
+            // verified stored session; it never trusts a caller-declared
+            // value at this point.
+            const actor = await resolveCliInvocationActor(this.runtime, baseInfo);
+            const info = actor ? { ...baseInfo, actor } : baseInfo;
+            this.actionInvocation = actor ? { actor } : undefined;
+            for (const preparer of this.invocationPreparers) {
+                await preparer.prepare(info);
+            }
+            await this.invocationController.start(info);
+        });
+    }
+    /** The host env snapshot, read once while the held runtime is live. */
+    hostEnv() {
+        this.capturedHostEnv ??= this.runtime.getEnvSnapshot();
+        return this.capturedHostEnv;
+    }
+    /**
+     * The runtime the selected action runs on: the host's CLI runtime, or the
+     * serve host a serve command's transition booted (rc02-rc03 §2.3).
+     */
+    get activeRuntime() {
+        return this.runtime;
+    }
+    setInvocationObserver(observer) {
+        this.invocationController.setObserver(observer);
+    }
+    /**
+     * Observer failures this surface could not log because the action's runtime
+     * had no logging to take them: typed `UNAVAILABLE`
+     * `observer-failure-unlogged` diagnostics (value-free observer facts in
+     * `details`, the logging refusal as `cause`). They never change an outcome.
+     */
+    get invocationDiagnostics() {
+        return this.invocationController.undeliveredDiagnostics;
+    }
+    setInvocationPreparer(preparer) {
+        this.invocationPreparers.length = 0;
+        if (preparer)
+            this.invocationPreparers.push(preparer);
+    }
+    addInvocationPreparer(preparer) {
+        this.invocationPreparers.push(preparer);
+    }
+    prependInvocationPreparer(preparer) {
+        this.invocationPreparers.unshift(preparer);
     }
     async initialize() {
         if (this.initialized)
             throw new Error('CLISurface already initialized');
-        const { verbose, enablePatterns } = this.options;
+        const { enablePatterns } = this.options;
+        const logger = getLogger(this.runtime, 'surface');
+        let verbose = !!this.options.verbose;
+        if (verbose) {
+            const failure = await failureOf(() => logger.debug('Initializing CLI surface'));
+            if (failure) {
+                if (!isCapabilityError(failure) || failure.code !== 'UNAVAILABLE' || failure.reason !== 'logger-not-initialized')
+                    throw failure;
+                // Setup diagnostics need Logging; failure rendering and observer
+                // diagnostics still honor the host's verbose option without it.
+                verbose = false;
+            }
+        }
+        const registrationOptions = { ...this.options, verbose };
         this.program.exitOverride();
+        // The output plane owns two flags impls do not implement themselves:
+        // every write is tracked so the surface can join them before the host
+        // exits, and `--no-color` / `NO_COLOR` / JSON output strip SGR at the
+        // stream boundary (impls carry raw `\x1b[`). It is the host's
+        // (`runtime/stdio` `trackOutput`); a host without one tracks nothing.
+        if (await hasRuntimeStdioOutputPlane(this.runtime)) {
+            const plane = await getRuntimeStdioOutputPlane(this.runtime);
+            plane.trackOutput({ stripSgr: resolveOutputStripSgr(this.runtime, this.options) });
+            this.outputPlane = { plane, runtime: this.runtime };
+        }
         registerCLIProviders(this.runtime, this.options);
+        await getCLIInvocationClient(this.runtime);
         if (verbose)
             logger.debug('Registered context providers');
         if (enablePatterns) {
             this.patternResolver = await createPatternResolver(this.runtime);
             if (verbose) {
-                logger.debug(`Pattern resolver: ${this.patternResolver.getPatternTypes().join(', ')}`);
+                logger.debug(`Runtime cli/pattern: ${this.patternResolver.getPatternTypes().join(', ')}`);
             }
         }
         const buildContext = async () => buildCommandContext(this.runtime);
@@ -102,7 +412,7 @@ export class CLISurface {
             program: this.program,
             groups: this.groups,
             groupDescriptors: this.groupDescriptors,
-            options: this.options,
+            options: registrationOptions,
             patternResolver: this.patternResolver,
             buildContext
         });
@@ -110,64 +420,298 @@ export class CLISurface {
             logger.debug(`Registered ${this.groups.size} groups`);
         await registerCommands({
             runtime: this.runtime,
+            currentRuntime: () => this.runtime,
             program: this.program,
             groups: this.groups,
             groupDescriptors: this.groupDescriptors,
-            options: this.options,
+            options: registrationOptions,
             patternResolver: this.patternResolver,
-            buildContext
+            buildContext,
+            registerInvocationDescriptor: (command, descriptor) => {
+                this.invocationDescriptors.set(command, descriptor);
+            }
         });
+        configureInheritedGlobalOptions(this.program);
         this.initialized = true;
         if (verbose)
             logger.debug('Surface initialized');
     }
-    async run(argv = process.argv) {
+    async run(argv) {
         if (!this.initialized)
             await this.initialize();
-        // Ensure stale keepAlive state from eager module side effects never leaks into a new invocation.
-        resetKeepAlive();
-        let exitCode;
-        try {
-            if (argv.slice(2).length === 0) {
-                this.program.outputHelp();
-                exitCode = 0;
-            }
-            else {
-                await this.program.parseAsync(argv);
+        await this.resolveWriter();
+        // Reset only the executing runtime's lifetime and output accounting.
+        (await getCLIInvocationClient(this.runtime)).begin();
+        // The host env, read once while a runtime is live (see `hostEnv`): every
+        // failure this run prints (the exit-boundary disposal's included) has its
+        // credential values scrubbed against it.
+        const render = () => ({ verbose: !!this.options.verbose, env: this.hostEnv() });
+        // One dispatch. A failure is parsed at its catch (`failureOf`), then
+        // rendered once and projected to the exit code by `reportRunFailure`.
+        const dispatched = {};
+        const undeliveredBefore = this.invocationController.undeliveredDiagnostics.length;
+        const failure = await failureOf(async () => {
+            dispatched.exitCode = await this.dispatch(argv);
+            await this.invocationController.finish('success');
+        });
+        let exitCode = failure
+            ? await this.reportRunFailure(failure, argv, render)
+            : dispatched.exitCode ?? readCLIExitCode(this.runtime) ?? 0;
+        // An observer failure logging could not take is carried, never the
+        // outcome; under -v it is printed to stderr (stdout stays the output).
+        if (this.options.verbose) {
+            for (const diagnostic of this.invocationController.undeliveredDiagnostics.slice(undeliveredBefore)) {
+                this.writer.write('stderr', `${renderCliFailure(diagnostic, render())}\n`);
             }
         }
-        catch (error) {
-            if (error instanceof CLIExitSignal) {
-                exitCode = error.code;
+        // Join the command's writes while the runtime is live, then once more
+        // after the exit-boundary disposal (through the host's own output).
+        await this.flushOutput();
+        if (!shouldKeepAlive(this.runtime)) {
+            exitCode = await this.finishBeforeAutoExit(argv, render, exitCode);
+            await this.flushOutput();
+        }
+        return exitCode;
+    }
+    /**
+     * Whether this invocation already put its JSON document on stdout, through
+     * the runtime its command was handed (`context.runtime`: the serve host
+     * after a serve transition), including the canonically bound free form.
+     */
+    jsonDocumentWritten() {
+        return hasWrittenJsonPayload(this.runtime);
+    }
+    /**
+     * Where the surface writes: the executable host's output, else the text
+     * output of the runtime it holds (resolved by `resolveWriter` as a run
+     * starts, and again when a serve transition swaps the runtime).
+     */
+    get writer() {
+        if (this.options.hostOutput)
+            return this.options.hostOutput;
+        if (this.runtimeWriter)
+            return this.runtimeWriter.writer;
+        throw new CapabilityError('The CLI surface has no host output and has not resolved its runtime\'s text output.', 'UNAVAILABLE', {
+            reason: 'stdio-unavailable',
+            retryable: false
+        });
+    }
+    /** Resolve the held runtime's text output as the surface's writer when no host output was handed. */
+    async resolveWriter() {
+        if (this.options.hostOutput || this.runtimeWriter?.runtime === this.runtime)
+            return;
+        const stdio = await getRuntimeStdio(this.runtime);
+        this.runtimeWriter = { runtime: this.runtime, writer: { write: (channel, text) => stdio.write(channel, text) } };
+    }
+    /**
+     * Join every tracked write: through the host's own output when it handed
+     * one (usable after any disposal), else through the installed plane while
+     * the runtime it was resolved on is live.
+     */
+    async flushOutput() {
+        if (this.options.hostOutput) {
+            await this.options.hostOutput.flush();
+            return;
+        }
+        if (this.outputPlane && !this.outputPlane.runtime.disposed)
+            await this.outputPlane.plane.flush();
+    }
+    /**
+     * Answer help or dispatch the selected action. Answers the exit code a help
+     * path chose (`undefined` when the action ran and chose none); throws what
+     * Commander or the action threw.
+     */
+    async dispatch(argv) {
+        if (argv.slice(2).length === 0) {
+            this.program.outputHelp();
+            return 0;
+        }
+        const helpIntent = commandHelpIntent(this.program, argv);
+        if (helpIntent?.kind === 'unresolved-path') {
+            const canonicalExitCode = await this.options.canonicalCommandHelp?.(helpIntent.argv);
+            if (canonicalExitCode === undefined) {
+                rejectUnknownCommandHelp(this.program, helpIntent.commandPath);
             }
-            else if (error instanceof CommanderError || ('exitCode' in error && 'code' in error)) {
-                // `commander.help` / `commander.helpDisplayed` / `commander.version`
-                // are not failures — they're successful help/version output. Map them
-                // to exit 0 so non-TTY callers (CI, subprocesses) treat them the
-                // same way TTY users see them.
-                const helpCodes = new Set([
-                    'commander.help',
-                    'commander.helpDisplayed',
-                    'commander.version'
-                ]);
-                exitCode = helpCodes.has(error.code) ? 0 : error.exitCode;
+            return canonicalExitCode;
+        }
+        if (helpIntent?.kind === 'unknown-option') {
+            rejectUnknownCommandHelpOption(this.program, helpIntent.commandPath, helpIntent.option);
+        }
+        await this.program.parseAsync(helpIntent?.argv ?? argv);
+        return undefined;
+    }
+    /**
+     * Close the invocation with the failure's outcome, render the failure once
+     * (a JSON envelope under --json, otherwise the one renderer's text), and
+     * answer the exit code it projects to.
+     */
+    async reportRunFailure(failure, argv, render) {
+        // Every field the projection needs is read once, inside one guard.
+        const classified = classifyRunFailure(failure);
+        const successfulExit = classified.kind === 'exit' && classified.code === 0;
+        const failureCause = successfulExit
+            ? undefined
+            : classified.kind === 'exit' && classified.cause !== undefined
+                ? valueFreeFailure(classified.cause)
+                : classified.kind === 'capability'
+                    ? valueFreeFailure(classified.error)
+                    : undefined;
+        await this.invocationController.finish(successfulExit ? 'success' : 'failure', successfulExit ? undefined : invocationFailureCode(classified), failureCause);
+        if (classified.kind === 'exit')
+            return classified.code;
+        if (classified.kind === 'capability') {
+            // The cross-surface outcome contract: the impl chose a stable code;
+            // the surface projects it. Exit code comes from the code (never 0 for
+            // a real failure); the failure renders as a JSON envelope under --json,
+            // a stack under -v, otherwise a friendly message + recovery hint.
+            if (argvWantsJson(argv)) {
+                writeScrubbedEnvelope(classified.envelope, render().env, this.writer, this.jsonDocumentWritten());
             }
             else {
-                exitCode = 1;
-                const formatted = formatCliError(error, !!this.options.verbose);
-                if (formatted) {
-                    writeSync(2, `${formatted}\n`);
+                this.writer.write('stderr', `${renderCliFailure(classified.error, render())}\n`);
+            }
+            return classified.exitCode;
+        }
+        if (classified.kind === 'commander') {
+            const commander = classified.outcome;
+            if (commander.code === 'commander.unknownCommand') {
+                const attempted = argv.slice(2).find((a) => !a.startsWith('-'));
+                const recommendation = attempted && Object.hasOwn(this.commandRecommendations, attempted)
+                    ? this.commandRecommendations[attempted]
+                    : undefined;
+                const destination = recommendation
+                    ? resolveMaterializedCommand(this.program, recommendation)
+                    : undefined;
+                if (destination && !argvWantsJson(argv)) {
+                    this.writer.write('stderr', `Try: ${[...resolveCommandPath(destination.command), ...destination.arguments].join(' ')}\n`);
                 }
             }
+            // `commander.help` / `commander.helpDisplayed` / `commander.version`
+            // are not failures — they're successful help/version output. Map them
+            // to exit 0 so non-TTY callers (CI, subprocesses) treat them the
+            // same way TTY users see them.
+            const helpCodes = new Set([
+                'commander.help',
+                'commander.helpDisplayed',
+                'commander.version'
+            ]);
+            const code = commander.code;
+            const exitCode = helpCodes.has(code) ? 0 : (commander.exitCode ?? 1);
+            // Machine callers: never leave bare commander text as the only signal.
+            const message = () => commander.message?.trim()
+                ? scrubCliText(stripBundlePaths(commander.message.trim()), render().env)
+                : `CLI error (${code})`;
+            if (exitCode !== 0 && argvWantsJson(argv)) {
+                writeScrubbedEnvelope(buildJsonFailureEnvelope(message(), 'INVALID_INPUT'), render().env, this.writer, this.jsonDocumentWritten());
+            }
+            else if (exitCode !== 0 && !commander.commanderOwn) {
+                // Commander's own errors have already printed themselves; anything
+                // ELSE that merely looks like one (any object carrying `code` and
+                // `exitCode` — which every CapabilityError does) has not. Staying
+                // silent here is how a non-zero exit ended up with no explanation
+                // whenever the CapabilityError branch above was missed.
+                this.writer.write('stderr', `${message()}\n`);
+            }
+            return exitCode;
         }
-        if (exitCode !== undefined) {
-            process.exitCode = exitCode;
+        // Any other failure, or one whose own fields could not be read: the one
+        // renderer (total) describes it; under -v an unreadable one also prints
+        // why it could not be classified.
+        const formatted = renderCliFailure(failure, render()) || 'CLI command failed (run with -v for details).';
+        if (argvWantsJson(argv)) {
+            // Scripts must get a parseable envelope, not prose on stderr
+            // (work 6f1aa9e5 / cli-audit: --json bare "disk I/O error").
+            writeScrubbedEnvelope(buildJsonFailureEnvelope(formatted), render().env, this.writer, this.jsonDocumentWritten());
         }
-        if (!shouldKeepAlive()) {
-            if (this.options.onBeforeAutoExit)
-                await this.options.onBeforeAutoExit();
-            process.exit(exitCode ?? process.exitCode ?? 0);
+        else {
+            this.writer.write('stderr', `${formatted}\n`);
         }
+        if (classified.kind === 'unreadable' && render().verbose) {
+            this.writer.write('stderr', `${renderCliFailure(classified.refusal, render())}\n`);
+        }
+        return 1;
     }
+    /**
+     * The host's exit-boundary work (disposal of the active runtime). Its
+     * failure is a failure of the invocation: reported once through the one
+     * renderer — an `AggregateError` lists each plugin and its typed reason —
+     * and the exit code becomes non-zero. It never escapes as an unhandled
+     * rejection with only the aggregate's message.
+     */
+    async finishBeforeAutoExit(argv, renderOptions, exitCode) {
+        const beforeAutoExit = this.options.onBeforeAutoExit;
+        if (!beforeAutoExit)
+            return exitCode;
+        // Read before disposal: a disposed runtime no longer answers its env.
+        const render = renderOptions();
+        const documentWritten = this.jsonDocumentWritten();
+        const failure = await failureOf(beforeAutoExit);
+        if (!failure)
+            return exitCode;
+        const formatted = renderCliFailure(failure, render) || 'CLI shutdown failed (run with -v for details).';
+        if (argvWantsJson(argv)) {
+            const classified = classifyRunFailure(failure);
+            writeScrubbedEnvelope(classified.kind === 'capability' ? classified.envelope : buildJsonFailureEnvelope(formatted), render.env, this.writer, documentWritten);
+        }
+        else {
+            this.writer.write('stderr', `${formatted}\n`);
+        }
+        // A disposal failure after a successful action still fails the invocation.
+        return exitCode === 0 ? 1 : exitCode;
+    }
+}
+function resolveCommandPath(command) {
+    const path = [];
+    let cursor = command;
+    while (cursor) {
+        path.unshift(cursor.name());
+        cursor = cursor.parent;
+    }
+    return path;
+}
+/** The classification itself; reading a hostile failure's fields may throw, so callers use {@link classifyRunFailure}. */
+function readRunFailureClass(failure) {
+    if (isCLIExitSignal(failure)) {
+        const code = failure.outcome.ok ? 0 : failure.code;
+        return failure.cause === undefined ? { kind: 'exit', code } : { kind: 'exit', code, cause: failure.cause };
+    }
+    // Structural, not `instanceof`: a second copy of the runtime module makes a
+    // genuine CapabilityError fail the identity test, and this would then log
+    // every one of them as UNHANDLED_ERROR instead of its real code.
+    if (failure instanceof Error && isCapabilityError(failure)) {
+        return { kind: 'capability', error: failure, exitCode: failure.exitCode, envelope: failure.toEnvelope() };
+    }
+    const outcome = commanderOutcome(failure);
+    return outcome ? { kind: 'commander', outcome } : { kind: 'other' };
+}
+/**
+ * The one guard over a caught failure's fields: never throws. A failure whose
+ * own fields throw when read is `unreadable`, carrying that read failure's
+ * value-free facts as the cause of a typed `INTERNAL` `cli-failure-unreadable`
+ * refusal.
+ */
+function classifyRunFailure(failure) {
+    try {
+        return readRunFailureClass(failure);
+    }
+    catch (error) {
+        return {
+            kind: 'unreadable',
+            refusal: new CapabilityError('The thrown value could not be classified; it is reported as an unhandled failure.', 'INTERNAL', {
+                reason: 'cli-failure-unreadable',
+                retryable: false,
+                // The read failure came from the hostile value itself (a trap's own
+                // throw), so its text may carry that value: only its value-free facts.
+                cause: valueFreeFailure(CaughtFailureSchema.parse(error))
+            })
+        };
+    }
+}
+function invocationFailureCode(classified) {
+    if (classified.kind === 'capability')
+        return classified.error.code;
+    if (classified.kind === 'exit')
+        return 'CLI_EXIT_NONZERO';
+    return 'UNHANDLED_ERROR';
 }
 //# sourceMappingURL=CLISurface.js.map