@namzu/cli 35.0.0 → 36.0.0

package/dist/commands/exec.js

@@ -1,688 +0,0 @@
-/**
- * `namzu exec "<prompt>"` — the headless one-shot. Runs a single prompt
- * through the same agent the TUI uses, for scripts, CI and host UIs.
- *
- * By default it prints the reply to stdout. The prompt comes from the
- * arguments, or from stdin when piped. Status lines go to stderr (info,
- * suppressed by `--quiet`); only the answer hits stdout. With `--json` it
- * streams one JSON event per line instead (`./exec-json.ts`). With
- * `--output-schema <file>` the final answer is bound to that JSON Schema.
- *
- * Non-interactive, so there's no approval prompt — tools auto-run, but the
- * safety gate still hard-denies catastrophic commands. A one-shot is a
- * conversation like any other: its session log is kept under the project in
- * `NAMZU_HOME`, so `--continue` picks it up and `namzu drain` can finish a
- * turn it parked.
- *
- * Options are parsed, not spoken: both modes share one parser
- * (`./exec-flags.js`), because they are the same one-shot differing only in
- * how they print.
- */
-import { relative, resolve } from 'node:path';
-import { BOOT_EVENT_NAMES, EVENT_NAME_ATTRIBUTE, TurnCancelled, asSessionId } from '@namzu/sdk';
-import { resolveTrustedProjectContext } from '../config/trusted-project-context.js';
-import { EXIT_UNTRUSTED, EXIT_USAGE } from '../exit-codes.js';
-import { closeSessions, openSessions, startConversation } from '../integrations/sessions/store.js';
-import { attachSessionExport, } from '../integrations/telemetry/session-export.js';
-import { cliLogger, contextLogging, createStderrSink, installCliLogging } from '../logging.js';
-import { loadOutputSchema } from '../output-schema.js';
-import { decideHeadlessTrust } from '../permissions/headless-trust.js';
-import { resolvePermissionMode } from '../permissions/mode.js';
-import { compilePermissions, warnLegacyMcpPermissionNames } from '../permissions/rules.js';
-import { withTerminationHandling, } from '../termination.js';
-import { hostCommandNames } from '../tui/slashCommands.js';
-import { describeTurnInterruption, retryAfterMs } from '../tui/turn-interruption.js';
-import { expandHeadlessCommand } from '../user-commands/store.js';
-import { applyProviderFlags, buildGate, loadSkillsContext, parseExecFlags, resolveWorkingDirectory, unknownOptionMessage, } from './exec-flags.js';
-import { execJson } from './exec-json.js';
-import { duration, pauseWait } from './provider-wait.js';
-import { resolveResume } from './resume.js';
-import { readStdin } from './stdin.js';
-/**
- * The prompt, from the arguments and the pipe together.
- *
- * Piped input used to be read only when there was no argument prompt, so
- *
- *     cat notes.txt | namzu exec "summarise this"
- *
- * sent the model three words and silently dropped the file. Nothing reported
- * it: the turn succeeded, and the answer was about nothing. A pipe and a
- * question are the ordinary way to ask about a document, and taking only one
- * of the two is the worst reading of that command.
- *
- * The piped text is fenced in a tag so the model can tell the instruction from
- * the material it is about — without a boundary, a long paste runs into the
- * question and the last line of a file reads as part of the request.
- *
- * Pure so it can be tested without a pipe; the reading happens in the handler.
- */
-export function composePrompt(fromArgs, piped) {
-    const question = fromArgs.trim();
-    const material = piped.trim();
-    if (!question)
-        return material;
-    if (!material)
-        return question;
-    return `${question}\n\n<stdin>\n${material}\n</stdin>`;
-}
-function defaultPrefs(detected) {
-    const first = detected[0];
-    return first
-        ? {
-            version: 3,
-            providers: [{ id: first.entry.id }],
-            subagents: { active: [] },
-        }
-        : null;
-}
-/**
- * What `exec` prints on stderr when a termination signal stops it, worded from
- * where the signal found the turn (`termination.ts` has already given the
- * conversation's lease back).
- */
-function stoppedBy(signal, sessionId, phase, paused) {
-    switch (phase) {
-        case 'running':
-            return `stopped by ${signal}: the turn in conversation ${sessionId} was left interrupted — close it with /abandon in the TUI, or continue it with /resume or \`namzu drain\``;
-        case 'paused':
-            return `stopped by ${signal} while the turn was paused: it keeps checkpoint ${paused?.checkpointId ?? '(unknown)'} in conversation ${sessionId} — continue it with /resume or \`namzu drain\`, or close it with /abandon in the TUI`;
-        case 'ended':
-            return `stopped by ${signal} after the turn ended; it is recorded in conversation ${sessionId}, and nothing is left to close`;
-        case 'not-started':
-            return `stopped by ${signal}; no turn was started in conversation ${sessionId}`;
-    }
-}
-/**
- * `--output-schema <file>`, loaded, or the reason it could not be. Resolved
- * against the process's directory, like every other path on the command line.
- */
-function loadExecOutputSchema(path) {
-    if (path === null)
-        return undefined;
-    const absolute = resolve(process.cwd(), path);
-    try {
-        return loadOutputSchema(absolute);
-    }
-    catch (error) {
-        return {
-            error: `--output-schema ${absolute}: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-}
-/** The default mode: print the reply. */
-async function execPrint({ ctx: bootstrapCtx }, termination, flags, structuredOutput) {
-    let ctx = bootstrapCtx;
-    // The turn's leash: the config file's limits, with a flag overriding each.
-    const limitsFromFlags = {
-        ...(flags.maxIterations !== null ? { maxIterations: flags.maxIterations } : {}),
-        ...(flags.tokenBudget !== null ? { tokenBudget: flags.tokenBudget } : {}),
-    };
-    if (flags.unknown.length > 0) {
-        // A shell caller learns about a bad argument from `$?`, so this is 64
-        // rather than the in-band error event the streaming sibling emits.
-        ctx.formatter.error({ message: unknownOptionMessage(flags.unknown) });
-        return EXIT_USAGE;
-    }
-    if (structuredOutput && 'error' in structuredOutput) {
-        ctx.formatter.error({ message: structuredOutput.error });
-        return EXIT_USAGE;
-    }
-    // `--session` keys a host's conversation for `--json`. This mode resumes
-    // with --continue or --resume; accepting the key and ignoring it would
-    // answer against no history while looking like it answered against one.
-    if (flags.session !== null) {
-        ctx.formatter.error({
-            message: '--session binds a host conversation for `exec --json`; this mode resumes with --continue or --resume <id>',
-        });
-        return EXIT_USAGE;
-    }
-    // `-` on its own means "the prompt is on stdin", the usual spelling for
-    // it. Before, it was sent to the model as a one-character question.
-    const fromArgs = flags.rest.join(' ').trim() === '-' ? '' : flags.rest.join(' ').trim();
-    // With no prompt argument, piped input IS the prompt and is waited for
-    // as long as it takes — that is the existing contract for `echo … |
-    // namzu exec` and for the `-` sentinel. Alongside a prompt it is extra
-    // material, so it gets the first-byte deadline instead: a caller who
-    // asked a complete question should never be left waiting on a pipe
-    // they did not mean to open.
-    const piped = await readStdin({ deadline: Boolean(fromArgs) });
-    const prompt = composePrompt(fromArgs, piped);
-    if (!prompt) {
-        ctx.formatter.error({
-            message: 'no prompt — pass it as an argument or pipe it via stdin',
-        });
-        return 2;
-    }
-    const resolved = resolveWorkingDirectory(flags.cwd);
-    if ('error' in resolved) {
-        ctx.formatter.error({ message: resolved.error });
-        return EXIT_USAGE;
-    }
-    // Before anything is read, run or constructed in that directory. The
-    // order is the gate: a check that happens after the session is built has
-    // already opened stores and walked the tree it was meant to protect.
-    const trust = decideHeadlessTrust({
-        cwd: resolved.cwd,
-        trustFlag: flags.trust,
-    });
-    if (!trust.allowed) {
-        ctx.formatter.error({ message: trust.message ?? 'folder not trusted' });
-        return EXIT_UNTRUSTED;
-    }
-    const cwd = trust.cwd;
-    ctx = resolveTrustedProjectContext(bootstrapCtx, cwd);
-    // Project commands are code-like launch authority: discover and expand
-    // them only after the target folder has crossed the same trust boundary
-    // as its config and instructions.
-    const expansion = expandHeadlessCommand(prompt, {
-        cwd,
-        builtins: hostCommandNames(),
-    });
-    if (expansion.kind === 'refused') {
-        ctx.formatter.error({ message: expansion.reason });
-        return EXIT_USAGE;
-    }
-    const finalPrompt = expansion.kind === 'expanded' ? expansion.prompt : prompt;
-    // The CLI owns stderr, not the kernel it drives (LOG-05) — a live sink
-    // at the level --verbose/--quiet/NAMZU_LOG_LEVEL named, instead of
-    // forcing the level to `silent` via `configureLogger`, which threw
-    // every diagnostic away regardless of what anyone asked for.
-    // `{ replace: true }`: a real invocation calls this once, but this
-    // package's own test suite calls a command's handler more than once
-    // per process, which a refusing second install would break for
-    // reasons that have nothing to do with what those tests are about.
-    const logging = contextLogging(ctx);
-    installCliLogging(createStderrSink(logging.format), logging.level);
-    const { probeAgentSession, createAgentSession } = await import('../tui/agent.js');
-    const probe = await probeAgentSession();
-    let prefs = probe.preferences ?? defaultPrefs(probe.detected);
-    if (!prefs) {
-        ctx.formatter.error({
-            message: 'no LLM provider available — set a credential (e.g. ANTHROPIC_API_KEY) or run `namzu` to pick one',
-        });
-        return 1;
-    }
-    prefs = applyProviderFlags(prefs, flags);
-    // A permission the operator wrote and which was silently dropped is the
-    // worst outcome available here: they believe a control is in force and it
-    // is not. So a bad line is reported and the rest still load.
-    const modeResult = resolvePermissionMode({
-        flag: flags.permissionMode,
-        skipPermissions: flags.skipPermissions,
-        // A headless turn has nobody to ask, so `prompt` here would silently
-        // become `auto`. Resolving it as `auto` says so instead.
-        interactive: false,
-    });
-    if ('error' in modeResult) {
-        ctx.formatter.error({ message: modeResult.error });
-        return EXIT_USAGE;
-    }
-    warnLegacyMcpPermissionNames(ctx.config.permissions);
-    const permissions = compilePermissions(ctx.config.permissions, ctx.config.permissionChecks);
-    for (const d of permissions.diagnostics) {
-        const where = d.pattern ? `permissions.${d.tool}."${d.pattern}"` : `permissions.${d.tool}`;
-        ctx.formatter.error({ message: `${where}: ${d.message}` });
-    }
-    const gate = buildGate(flags, cwd);
-    // Attached BEFORE the session, and its failure is fatal. An operator who
-    // configured `telemetry.sessionExport` asked for this turn to be
-    // recorded; continuing without it means the turn happens and the record
-    // they were counting on does not exist, which is a failure they only
-    // discover when they go looking for a session that was never written.
-    let sessionExport;
-    if (ctx.config.telemetry?.sessionExport) {
-        try {
-            sessionExport = await attachSessionExport({
-                config: ctx.config.telemetry.sessionExport,
-            });
-            // Under the same event name the boot narrative used for the
-            // boolean. This is the half that names the destination and the
-            // redactors, and it is emitted HERE because it describes what
-            // actually resolved rather than what was configured.
-            cliLogger().info(sessionExport.disclosure, {
-                [EVENT_NAME_ATTRIBUTE]: BOOT_EVENT_NAMES.TELEMETRY_STATUS,
-                'namzu.telemetry.session_export': true,
-            });
-        }
-        catch (err) {
-            ctx.formatter.error({
-                message: err instanceof Error ? err.message : String(err),
-            });
-            return 1;
-        }
-    }
-    let sessions;
-    try {
-        sessions = await openSessions(cwd);
-    }
-    catch (error) {
-        await sessionExport?.shutdown();
-        ctx.formatter.error({
-            message: `workspace state is unavailable: ${error instanceof Error ? error.message : String(error)}`,
-        });
-        return 1;
-    }
-    const resume = await resolveResume(sessions, { continueLast: flags.continueLast, sessionId: flags.resume }, cwd);
-    if (resume.kind === 'error') {
-        ctx.formatter.error({ message: resume.message });
-        await sessionExport?.shutdown();
-        return EXIT_USAGE;
-    }
-    const prior = resume.kind === 'resumed' ? resume.messages : [];
-    // A new one-shot is a new conversation: its log starts here, so the turn
-    // the kernel records has somewhere to go and `--continue` can find it.
-    let sessionId;
-    try {
-        sessionId =
-            resume.kind === 'resumed' ? asSessionId(resume.sessionId) : await startConversation(sessions);
-    }
-    catch (error) {
-        closeSessions(sessions);
-        await sessionExport?.shutdown();
-        ctx.formatter.error({
-            message: `could not start a conversation: ${error instanceof Error ? error.message : String(error)}`,
-        });
-        return 1;
-    }
-    const session = await createAgentSession(prefs, probe.detected, {
-        cwd,
-        ...(structuredOutput ? { structuredOutput } : {}),
-        scope: {
-            sessionId,
-            topicId: sessions.topicId,
-            projectId: sessions.projectId,
-            tenantId: sessions.tenantId,
-        },
-        stateRoot: sessions.root,
-        conversationSessions: sessions,
-        rules: permissions.rules,
-        ...(sessionExport ? { onSessionEvent: sessionExport.listener } : {}),
-        // The operator's --gate commands, as a standing condition on the
-        // answer. Spread rather than passed as undefined so a turn without
-        // gates is byte-identical to the one that shipped before them.
-        ...(gate ?? {}),
-        permissionMode: modeResult.mode,
-        // Run from the user's own terminal, so a page can be opened on their
-        // desktop. Never `exec --json`, `drain` or a scheduled run.
-        openUrl: true,
-        ...(ctx.config.mcpServers ? { mcpServers: ctx.config.mcpServers } : {}),
-        ...(ctx.config.plugins ? { plugins: ctx.config.plugins } : {}),
-        ...(ctx.config.skills ? { skills: ctx.config.skills } : {}),
-        ...(ctx.config.web ? { web: ctx.config.web } : {}),
-        ...(ctx.config.hooks ? { hooks: ctx.config.hooks } : {}),
-        ...(ctx.config.compaction ? { compaction: ctx.config.compaction } : {}),
-        ...(ctx.config.memory ? { memory: ctx.config.memory } : {}),
-        ...(Object.keys({ ...ctx.config.limits, ...limitsFromFlags }).length > 0
-            ? { limits: { ...ctx.config.limits, ...limitsFromFlags } }
-            : {}),
-        ...(ctx.config.sandbox ? { sandbox: ctx.config.sandbox } : {}),
-        // `!== undefined`, not truthiness: an empty list is the operator
-        // turning the default screen OFF, and a falsy check would drop it.
-        ...(ctx.config.toolResultScreens !== undefined
-            ? { toolResultScreens: ctx.config.toolResultScreens }
-            : {}),
-    });
-    if (!session.hasProvider) {
-        await session.close();
-        closeSessions(sessions);
-        await sessionExport?.shutdown();
-        ctx.formatter.error({
-            message: session.errorHint ?? 'agent is not ready',
-        });
-        return 1;
-    }
-    // A configured tool server that is not here means the turn cannot do what
-    // the operator set it up to do, and there is nobody watching to notice.
-    // The TUI reports and carries on, because a person can read the line and
-    // decide; a script has no such reader, so it refuses. Same principle as
-    // the permission mode resolving differently when `interactive` is false.
-    if (session.mcpFailed.length > 0) {
-        for (const f of session.mcpFailed) {
-            ctx.formatter.error({
-                message: `tool server "${f.name}" is not available: ${f.reason}`,
-            });
-        }
-        await session.close();
-        closeSessions(sessions);
-        await sessionExport?.shutdown();
-        return 1;
-    }
-    // "Printed on every launch" has to mean every launch, not every launch of
-    // the TUI. A scripted turn under an accepted capability limitation is
-    // exactly the case where nobody is watching, so the line has to be in the
-    // output the script keeps.
-    for (const notice of session.configNotices) {
-        ctx.formatter.info(notice);
-    }
-    for (const s of session.mcpConnected) {
-        ctx.formatter.info(`tool server ${s.name} · ${s.toolCount} tools`);
-    }
-    ctx.formatter.info(`namzu · ${session.providerSummary}${session.modelSummary ? ` · ${session.modelSummary}` : ''}`);
-    // stderr like every other status line, so a caller piping the answer is
-    // unaffected and a person watching can still tell which instructions the
-    // turn is bound by. A script that reads AGENTS.md aloud is not a script
-    // whose output changed.
-    if (session.instructionFiles.length > 0) {
-        ctx.formatter.info(`project instructions: ${session.instructionFiles
-            .map((p) => relative(cwd, p) || p)
-            .join(', ')}`);
-    }
-    // A refusal that says nothing is indistinguishable from a project that
-    // declared nothing, and the two want opposite responses from the reader.
-    for (const skip of session.skippedInstructionFiles) {
-        ctx.formatter.error({
-            message: `skipped ${relative(cwd, skip.path) || skip.path}: ${skip.reason}`,
-        });
-    }
-    const extraSystem = await loadSkillsContext(cwd, flags.skills, ctx.config.skills);
-    if (resume.kind === 'resumed') {
-        ctx.formatter.info(`resuming ${resume.sessionId} · ${prior.length} messages`);
-    }
-    let text = '';
-    const measured = {};
-    const jsonResult = (value) => ({
-        text: value,
-        ...(measured.usage
-            ? {
-                usage: {
-                    totalTokens: measured.usage.totalTokens,
-                    cost: measured.usage.cost,
-                },
-            }
-            : {}),
-        ...(measured.budget ? { budget: measured.budget } : {}),
-    });
-    let stopReason;
-    // Written from inside `consume`, so held on an object: a `let` assigned
-    // only in a closure is `null` as far as the type checker can see, and
-    // every read after the loop would narrow it to `never`.
-    const stop = {
-        failed: null,
-        paused: null,
-        busy: false,
-    };
-    // Stopped from outside (SIGTERM, SIGHUP, Ctrl+C): the conversation's
-    // lease is already given back when this runs (`termination.ts`). Stop the
-    // turn, so its tools' processes go with it, and release what the session
-    // holds. What the operator is told depends on where the signal found the
-    // turn: mid-flight it is left interrupted; waiting out a provider pause it
-    // keeps its checkpoint; after it settled (the session still closing, a
-    // slow `session_end` hook) it is recorded, and there is nothing to close.
-    const turnAbort = new AbortController();
-    let stopped = false;
-    let phase = 'running';
-    const afterPhase = () => {
-        phase = stop.busy ? 'not-started' : stop.paused ? 'paused' : 'ended';
-    };
-    termination.onTerminate(async (signal) => {
-        stopped = true;
-        ctx.formatter.error({ message: stoppedBy(signal, sessionId, phase, stop.paused) });
-        turnAbort.abort(new TurnCancelled('user'));
-        await session.close();
-        closeSessions(sessions);
-        await sessionExport?.shutdown();
-    });
-    const consume = async (stream) => {
-        stop.failed = null;
-        stop.paused = null;
-        for await (const event of stream) {
-            if (event.kind === 'delta')
-                text += event.text;
-            else if (event.kind === 'tool-start')
-                ctx.formatter.info(`Tool: ${event.toolName} ${event.summary}`);
-            // stderr, like every other status line, so it reaches a person
-            // watching without contaminating the answer a caller piped.
-            else if (event.kind === 'context')
-                ctx.formatter.info(event.text);
-            else if (event.kind === 'error' || event.kind === 'paused') {
-                if (event.budget)
-                    measured.budget = event.budget;
-                stop.failed = describeTurnInterruption(event);
-                if (event.kind === 'error' && event.turnInProgress) {
-                    stop.busy = true;
-                    stop.failed = `conversation ${event.turnInProgress.sessionId} already has a ${event.turnInProgress.state} turn ${event.turnInProgress.activeTurnId}; nothing was started. Finish it with \`namzu drain\`, or abandon it with /abandon in the TUI.`;
-                }
-                if (event.kind === 'paused')
-                    stop.paused = event;
-            }
-            else if (event.kind === 'usage') {
-                measured.usage = event;
-                if (event.budget)
-                    measured.budget = event.budget;
-            }
-            else if (event.kind === 'done') {
-                // Deltas include preliminary and rejected answers. Settlement
-                // supplies the final result after review and output guardrails;
-                // an explicit empty result must also replace earlier text.
-                if (event.text !== undefined)
-                    text = event.text;
-                stopReason = event.stopReason;
-                if (event.budget)
-                    measured.budget = event.budget;
-            }
-        }
-    };
-    await consume(session.send([...prior, { role: 'user', content: finalPrompt, timestamp: Date.now() }], {
-        signal: turnAbort.signal,
-        ...(extraSystem ? { extraSystem } : {}),
-        ...(flags.effort !== null ? { effort: flags.effort } : {}),
-    }));
-    afterPhase();
-    // A provider pause is answered by waiting, when the caller gave time to
-    // wait with. The kernel kept a checkpoint; the turn resumes from it in
-    // this process, with its own context, rather than being re-prompted from
-    // notes by a wrapper that saw exit 75. A pause with no provider behind
-    // it is not waited on: that is a turn parked on something else.
-    const waitBudgetMs = flags.waitForProviderMs ?? ctx.config.limits?.waitForProviderMs ?? 0;
-    let waits = 0;
-    let waitedMs = 0;
-    while (!stopped &&
-        stop.paused &&
-        waitBudgetMs > 0 &&
-        (stop.paused.providerError || stop.paused.failure)) {
-        const paused = stop.paused;
-        const asked = retryAfterMs(paused);
-        const decision = pauseWait({
-            waited: waits,
-            ...(asked !== undefined ? { retryAfterMs: asked } : {}),
-            waitedMs,
-            budgetMs: waitBudgetMs,
-        });
-        if (decision.kind === 'stop') {
-            stop.failed = `${stop.failed}\nNot resumed: ${decision.reason}.`;
-            break;
-        }
-        waits += 1;
-        ctx.formatter.info(`provider paused the turn: waiting ${duration(decision.delayMs)}, then resuming from ${paused.checkpointId} (wait ${waits}, ${duration(waitedMs)} of ${duration(waitBudgetMs)} spent)`);
-        await new Promise((resolve) => setTimeout(resolve, decision.delayMs));
-        // A signal during the wait: the process is on its way out, and the
-        // turn keeps its checkpoint for whoever resumes it next.
-        if (stopped)
-            break;
-        waitedMs += decision.delayMs;
-        phase = 'running';
-        await consume(session.resumePaused({
-            turnId: paused.turnId,
-            checkpointId: paused.checkpointId,
-            signal: turnAbort.signal,
-        }));
-        afterPhase();
-    }
-    // The signal handler closes the session and ends the process.
-    if (stopped)
-        return 1;
-    const failed = stop.failed;
-    // 75 (EX_TEMPFAIL) for both: a provider pause kept a checkpoint, and a
-    // conversation busy with another turn refused to start one. Either way
-    // running again later is the remedy, not a different invocation.
-    const paused = stop.paused !== null || stop.busy;
-    // Every exit below this point releases the session first. A stdio tool
-    // server is a child process, and an `exec` that returns without closing
-    // leaves it behind.
-    await session.close();
-    closeSessions(sessions);
-    // Drained with the session, not at process exit: a buffering sink that
-    // only flushed on `beforeExit` loses its tail whenever the CLI is
-    // interrupted, which is exactly the turn somebody wanted the record of.
-    await sessionExport?.shutdown();
-    if (measured.budget) {
-        ctx.formatter.info(`Tokens: ${measured.budget.ownTokens} own · ${measured.budget.treeTokens} including descendants`);
-    }
-    if (failed) {
-        // A provider can pause or fail after producing useful text. The TUI
-        // keeps that partial answer and a shell caller deserves the same bytes;
-        // the non-zero verdict is what prevents it being mistaken for complete.
-        const partial = text.trim();
-        if (partial) {
-            ctx.formatter.print(ctx.formatter.name === 'json' ? jsonResult(partial) : partial);
-        }
-        ctx.formatter.error({
-            message: `${failed}${partial ? ' — the output above is partial' : ''}`,
-        });
-        // A pause is not a failure: the provider said "not now" (a rate
-        // limit, an outage) and the kernel kept a checkpoint. A wrapper that
-        // re-runs on 1 would hammer a limited provider and give up on a
-        // finished-looking failure alike; 75 (EX_TEMPFAIL, the sysexits
-        // convention for "try again later") lets it back off instead.
-        return paused ? 75 : 1;
-    }
-    // The text prints either way. Partial output is real output, and a
-    // caller who piped it wants what there is — but `$?` has to be able to
-    // tell them it is partial, which it could not: `turn_failed` is emitted
-    // only from the throw path, so a turn stopped by its token budget, its
-    // timeout, its iteration cap, a cancellation, or a blocking output
-    // guardrail all arrived as `turn_completed` and exited 0. Measured: a
-    // `max_iterations` stop reports `status: 'completed'`. The sharp case is
-    // the guardrail — a REFUSED answer exited 0 with empty text, so
-    // `namzu exec … > out.txt && deploy` proceeded on the empty file.
-    ctx.formatter.print(ctx.formatter.name === 'json' ? jsonResult(text.trim()) : text.trim());
-    if (stopReason && stopReason !== 'end_turn') {
-        ctx.formatter.error({
-            message: `turn did not finish normally: ${stopReason}${text.trim() ? ' — the output above is partial' : ''}`,
-        });
-        return 1;
-    }
-    return 0;
-}
-export const execCommand = {
-    name: 'exec',
-    aliases: ['e'],
-    description: 'Run a single prompt headlessly: print the reply, or stream events with --json',
-    passThrough: true,
-    help: [
-        'Usage: namzu exec [options] <prompt...>',
-        '       echo "<prompt>" | namzu exec',
-        '       cat file.txt | namzu exec "summarise this"',
-        '       namzu exec --json [--session <id>] <prompt...>',
-        '',
-        'Run a single prompt headlessly. Everything that is not an option is the',
-        'prompt. `namzu e` is the same command.',
-        '',
-        'By default the reply is printed on stdout and status lines go to stderr.',
-        'Piped input is used too, not discarded: with no prompt argument it IS',
-        'the prompt, and alongside one it is appended as material the question',
-        'is about. `namzu exec -` reads the prompt from stdin explicitly.',
-        '',
-        'Options:',
-        '  --json                Stream one JSON event per line instead of the reply',
-        '  --output-schema <f>   Bind the final answer to the JSON Schema in file f,',
-        "                        using the provider's native structured output",
-        '  --cwd <path>          Directory the agent works in (default: this one)',
-        '  --provider <id>       Provider to answer with',
-        '  --model <id>          Model to answer with',
-        '  --skills <a,b,c>      Load these skills as context for the turn',
-        '  --continue, -c        Resume the most recent conversation here',
-        '  --resume <id>         Resume that conversation, and no other',
-        '  --session <id>        With --json: bind the turn to the host conversation',
-        '                        keyed by this id',
-        '  --gate <command>      Verify proposed answers with this command; repeatable',
-        '  --gate-retries <n>    Fix attempts a failing gate allows (default 3)',
-        '  --max-iterations <n>  Main-loop iteration limit (default 50; 0 unlimited)',
-        '  --token-budget <n>    Tree token limit (default unlimited; 0 removes a configured cap)',
-        '  --effort <level>      Explicit reasoning effort (supported levels depend on the model)',
-        '  --wait-for-provider <d>  Wait out provider pauses (a rate limit, an outage)',
-        '                        for up to this long in total — 90s, 30m, 2h — resuming',
-        '                        from the checkpoint each time (default: none; exit 75)',
-        '  --permission-mode <m> prompt | accept-edits | auto | strict | plan —',
-        '                        what happens to a call no [permissions] rule',
-        '                        decided (default: auto)',
-        '  --trust               Accept this folder for THIS turn',
-        '  --                    End of options; the rest is the prompt verbatim',
-        '',
-        'A folder has to be trusted before namzu will work in it, because namzu',
-        'reads its files, runs commands in it and executes its code. Run `namzu`',
-        'here once and accept the prompt to trust it permanently, or pass --trust',
-        'to accept it for one turn. --trust does not remember; that is the point.',
-        '',
-        '--yolo does NOT imply --trust: one is about which tools may run inside a',
-        'folder, the other about the folder.',
-        '',
-        'By default tools run without asking, because there is nobody to ask, and',
-        'the safety gate still refuses catastrophic commands. Use --permission-mode',
-        'strict for an unattended turn that must refuse anything no rule allowed.',
-        '',
-        'A mode only decides calls no rule decided: it can never reopen a deny.',
-        '',
-        '--gate checks proposed answers with operator-supplied commands. Every',
-        'command must complete successfully; a failure returns diagnostics to the',
-        'model for correction. Repeat the flag to check several commands in order.',
-        'Budget exhaustion or cancellation may stop a turn before verification.',
-        '',
-        'A failed gate may skip a retry when its Git change detector is unchanged.',
-        'The attempt still counts. Exhausted review attempts stop the turn with',
-        'answer_rejected and a non-zero exit.',
-        '',
-        "The working directory's AGENTS.md files — that directory and every one up",
-        'to the repository root — are loaded as standing instructions for the turn,',
-        'and the ones that were loaded are named on stderr.',
-        '',
-        '--continue and --resume refuse when the conversation cannot be reopened,',
-        'and say why. Neither ever falls back to starting a new one: leave both',
-        'out if that is what you want.',
-        '',
-        'Needs a provider. Set a credential in the environment, or run namzu',
-        'once to pick one interactively.',
-        '',
-        'A turn the provider pauses keeps a checkpoint. Without --wait-for-provider',
-        'it exits 75 at once and a wrapper decides when to try again; with it, the',
-        "turn waits the provider's own delay when it named one (otherwise a minute,",
-        'doubling, at most fifteen) and resumes from the checkpoint in this process,',
-        'until the budget is spent. The `limits.waitForProviderMs` config key sets',
-        'the same budget for every turn in the folder.',
-        '',
-        'Exit codes: 0 on a reply, 1 on a failed or unfinished turn, 2 when no',
-        'prompt was supplied, 64 when an argument is wrong, 75 when the provider',
-        'paused the turn (a rate limit or an outage) and a checkpoint was kept —',
-        'wait, then try again — or when the conversation already has an active',
-        'turn (a paused one: finish it with `namzu drain`, or abandon it in the',
-        'TUI with /abandon), and 77 when the folder has not been trusted and',
-        'nothing was done.',
-        '',
-        'With --json:',
-        '',
-        'Each line is one event as the turn unfolds — text deltas, tool starts and',
-        'ends, usage, then a terminal done event. done.text is the settled answer;',
-        'earlier deltas may include progress or answers later rejected by',
-        'verification. History is bound with --session <id>; --continue, --resume',
-        'and --wait-for-provider are refused. Without --session, optional stdin',
-        'must be one complete JSON Message[]; invalid or provider-incomplete tool',
-        'history is refused before a turn.',
-        '',
-        'Every failure is an event on stdout. The exit code says whether YOU can',
-        'do anything about it: 0 when changing what you send would reach the turn',
-        '(a wrong option, no prompt, a bad --cwd) and when a turn started and',
-        'failed; 1 when it would not (no provider, a tool server that is not',
-        'there, a conversation that cannot be opened); 75 when the --session',
-        'conversation already has an active turn (a paused one: finish it with',
-        '`namzu drain`), and the error event carries code "turn_in_progress"; 77',
-        'when the folder has not been trusted, which only a person can change.',
-    ].join('\n'),
-    handler: withTerminationHandling(async (args, termination) => {
-        const flags = parseExecFlags(args.rawArgs);
-        const structuredOutput = loadExecOutputSchema(flags.outputSchema);
-        return flags.json
-            ? execJson(args, termination, flags, structuredOutput)
-            : execPrint(args, termination, flags, structuredOutput);
-    }),
-};
-//# sourceMappingURL=exec.js.map