@north-light/crouter 0.3.154

package/dist/core/command.js

@@ -0,0 +1,636 @@
+// Registration kit for the agent-first crtr CLI.
+// Hand-rolled path walker — no commander. Rationale: the spec requires flags
+// and positional args on input (argv model). Commander's abstraction is more
+// complexity than a plain array walk for this interface contract.
+// A plain array walk + a small flag parser is ~120 lines and has no surprising
+// edge cases.
+import { renderRoot, renderBranch, renderLeafArgv } from './help.js';
+import { readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
+import { renderResult } from './render.js';
+import { CrtrError } from './errors.js';
+import { operationIdContext } from './events/operation-id.js';
+import { ExitCode } from '../types.js';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+import { isatty } from 'node:tty';
+// ---------------------------------------------------------------------------
+// Factory functions
+// ---------------------------------------------------------------------------
+export function defineLeaf(opts) {
+    return {
+        kind: 'leaf',
+        name: opts.name,
+        description: opts.description,
+        whenToUse: opts.whenToUse,
+        tier: opts.tier,
+        help: opts.help,
+        slash: opts.slash,
+        run: opts.run,
+        render: opts.render,
+    };
+}
+/** Number of a node's own non-hidden subcommands (direct children). Leaves and
+ *  childless branches return 0. */
+function visibleSubCount(def) {
+    if (def.kind !== 'branch')
+        return 0;
+    return (def.help.listing ?? []).filter((c) => c.tier !== 'hidden').length;
+}
+export function defineBranch(opts) {
+    // A passthrough branch must be childless: walk() only stops at the deepest
+    // matched node, so a passthrough branch with children would let some
+    // invocations descend into a child (tree dispatch) while others hit the
+    // passthrough interception — silently inconsistent transparency. Fail loudly
+    // at construction instead of letting that split happen at runtime.
+    if (opts.passthrough !== undefined && opts.children.length > 0) {
+        throw new Error(`defineBranch("${opts.name}"): a passthrough branch must declare no children (found ${opts.children.length})`);
+    }
+    // Assemble the parent-level listing straight from the child defs — each node
+    // owns its own description/whenToUse/tier, so the parent copies nothing
+    // (principle 16). Bottom-up construction guarantees a child branch's listing
+    // is already computed, so subCount is available here.
+    opts.help.listing = opts.children.map((c) => {
+        const subCount = visibleSubCount(c);
+        return {
+            name: c.name,
+            description: c.description ?? '',
+            whenToUse: c.whenToUse ?? '',
+            tier: c.tier ?? 'normal',
+            ...(subCount > 0 ? { subCount } : {}),
+        };
+    });
+    return {
+        kind: 'branch',
+        name: opts.name,
+        description: opts.description,
+        whenToUse: opts.whenToUse,
+        tier: opts.tier,
+        help: opts.help,
+        rootEntry: opts.rootEntry,
+        slash: opts.slash,
+        passthrough: opts.passthrough,
+        children: opts.children,
+    };
+}
+/** Walk the whole tree and collect every node's SlashSpec (depth-first). Used
+ *  by the bootstrap to discover which commands opted into slash exposure. */
+export function collectSlashSpecs(root) {
+    const out = [];
+    const visit = (node) => {
+        if (node.slash !== undefined)
+            out.push(node.slash);
+        if (node.kind === 'branch')
+            for (const c of node.children)
+                visit(c);
+    };
+    for (const s of root.subtrees)
+        visit(s);
+    return out;
+}
+/** Assemble root -h from the subtrees themselves. Root owns only the tagline
+ *  and globals; every subtree's concept line, selection rubric, and dynamic
+ *  block come from its own RootEntry. A subtree without a rootEntry does not
+ *  appear in root -h — declaring the parent-level representation is how a
+ *  subtree opts into being listed. */
+export function defineRoot(opts) {
+    // Each listed subtree becomes one <name> block at root, assembled straight
+    // from its RootEntry. Root composes nothing and hardcodes nothing: add a
+    // subtree with a rootEntry and it surfaces; its concept, rubric, state tag,
+    // and dynamic block all travel with it.
+    const commands = opts.subtrees
+        .filter((s) => s.rootEntry !== undefined)
+        .map((s) => {
+        // Promote this subtree's common/important children into root, and count
+        // how many other (non-hidden) direct subcommands stay behind `<name> -h`.
+        const visible = (s.help.listing ?? []).filter((c) => c.tier !== 'hidden');
+        const promoted = visible
+            .filter((c) => c.tier === 'common' || c.tier === 'important')
+            .map((c) => ({
+            path: `${s.name} ${c.name}`,
+            // important carries its shortform desc; common shows the bare path.
+            desc: c.tier === 'important' ? c.description : undefined,
+        }));
+        return {
+            name: s.name,
+            concept: s.rootEntry.concept,
+            desc: s.rootEntry.desc,
+            useWhen: s.rootEntry.useWhen,
+            dynamicState: s.rootEntry.dynamicState,
+            subcommands: promoted.length > 0 ? promoted : undefined,
+            otherSubcommandCount: visible.length - promoted.length,
+        };
+    });
+    const help = {
+        tagline: opts.tagline,
+        commands,
+        globals: opts.globals,
+    };
+    return { kind: 'root', help, subtrees: opts.subtrees };
+}
+/** Validate and return child names for an unknown-path error. */
+function childNames(node) {
+    if (node.kind === 'root')
+        return node.subtrees.map((s) => s.name);
+    if (node.kind === 'branch')
+        return node.children.map((c) => c.name);
+    return [];
+}
+/** Walk argv tokens to the deepest matched node.
+ *  Returns { node, path, remaining } where path is the sequence of matched node
+ *  names from root (excluding root itself) and remaining are unconsumed tokens.
+ *  -h / --help tokens are NOT consumed here — the caller checks for them. */
+export function walk(root, tokens) {
+    let current = root;
+    const path = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        // Stop consuming on -h / --help — leave them for caller to detect
+        if (token === '-h' || token === '--help')
+            break;
+        if (current.kind === 'root') {
+            const nextNode = current.subtrees.find((s) => s.name === token);
+            if (nextNode === undefined)
+                break;
+            current = nextNode;
+            path.push(nextNode.name);
+            i++;
+        }
+        else if (current.kind === 'branch') {
+            const nextNode = current.children.find((c) => c.name === token);
+            if (nextNode === undefined)
+                break;
+            current = nextNode;
+            path.push(nextNode.name);
+            i++;
+        }
+        else {
+            // leaf — cannot descend further
+            break;
+        }
+    }
+    return { node: current, path, remaining: tokens.slice(i) };
+}
+function renderNode(node) {
+    if (node.kind === 'root')
+        return renderRoot(node.help);
+    if (node.kind === 'branch')
+        return renderBranch(node.help);
+    return renderLeafArgv(node.help);
+}
+function helpRequested(remaining) {
+    return remaining.some((t) => t === '-h' || t === '--help');
+}
+/** Recover the RAW argv slice after a matched passthrough branch's path,
+ *  unaffected by the `--json`-stripping done to build `tokens`. `path` is a
+ *  prefix of non-`--json` tokens in order, so walking `rawTokens` while
+ *  skipping `--json` occurrences until `path` is fully matched lands the
+ *  cursor exactly where the branch's own args begin — including a literal
+ *  `--json` the external binary itself accepts. */
+function rawArgsAfterPath(rawTokens, path) {
+    let matched = 0;
+    for (let i = 0; i < rawTokens.length; i++) {
+        if (matched === path.length)
+            return rawTokens.slice(i);
+        if (rawTokens[i] === '--json')
+            continue;
+        if (rawTokens[i] === path[matched])
+            matched++;
+    }
+    return [];
+}
+/** Forward `args` to an external binary verbatim: stdio inherited (streaming
+ *  preserved), and the child's exit code propagated. Never returns — either
+ *  exits with the child's status or throws a structured CrtrError (ENOENT ->
+ *  install hint) for the caller's existing error handler to render. */
+function runPassthrough(passthrough, args) {
+    const result = spawnSync(passthrough.bin, args, { stdio: 'inherit' });
+    if (result.error !== undefined) {
+        // Any launch-time failure (not found, not executable, ...) means this
+        // binary isn't usable from here — surface one structured error with the
+        // install hint rather than branching on a specific errno. (Node/libuv can
+        // report EACCES instead of ENOENT for a genuinely-missing binary when PATH
+        // contains malformed entries — e.g. a literal `~/...` segment — so a
+        // ENOENT-only check would miss real missing-binary cases on such hosts.)
+        const err = result.error;
+        throw new CrtrError('binary_missing', `${passthrough.bin} could not be run (${err.code ?? err.message})`, ExitCode.USAGE, {
+            received: passthrough.bin,
+            next: passthrough.installHint,
+        });
+    }
+    if (result.status !== null) {
+        process.exit(result.status);
+    }
+    if (result.signal !== null) {
+        // Signal-terminated: exit(1) would break the transparent exit-propagation
+        // contract (a direct shell invocation would show 128+signal, e.g. 143 for
+        // SIGTERM). Map to the standard 128+signal-number convention.
+        const signalNumber = osConstants.signals[result.signal];
+        if (signalNumber !== undefined) {
+            process.exit(128 + signalNumber);
+        }
+    }
+    // Truly impossible per Node's spawnSync contract (status and signal are
+    // mutually exclusive and one is always set on a completed run) — fallback only.
+    process.exit(1);
+}
+/** Build a structured unknown-path error. Names valid children of the deepest
+ *  matched node and names the entry command per the spec. The entry command is
+ *  the full path to the matched node (not just its local name), so the recovery
+ *  hint is a command that actually exists. No fuzzy matching. */
+export function unknownPathError(node, path, bad) {
+    const valid = childNames(node);
+    const validStr = valid.length > 0 ? valid.join(', ') : '(none)';
+    const entryCmd = path.length > 0 ? `crtr ${path.join(' ')} -h` : 'crtr -h';
+    return new CrtrError('unknown_path', `unknown subcommand: ${bad}`, ExitCode.USAGE, {
+        received: bad,
+        next: `Valid children: ${validStr}. Run \`${entryCmd}\` for the full list.`,
+    });
+}
+// ---------------------------------------------------------------------------
+// Argv parser
+// ---------------------------------------------------------------------------
+function parseArgvError(code, message, received, field, next) {
+    return new CrtrError(code, message, ExitCode.USAGE, {
+        received,
+        field,
+        next: next !== undefined ? next : 'Run the command with -h to see the parameter schema.',
+    });
+}
+/** Convert kebab-case flag name to camelCase key. e.g. context-file → contextFile */
+function flagNameToKey(name) {
+    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** Parse remaining argv tokens against the leaf's InputParam schema.
+ *  Returns a plain object whose keys are camelCase parameter names.
+ *  Optionally tracks which parameters were explicitly provided via a callback. */
+export async function parseArgv(params, tokens, options) {
+    const result = {};
+    const provided = new Set(); // Track explicitly-provided parameter names
+    // Index params by kind for quick lookup
+    const positionalParam = params.find((p) => p.kind === 'positional');
+    const stdinParam = params.find((p) => p.kind === 'stdin');
+    const contextFileParam = params.find((p) => p.kind === 'context-file');
+    const flagParams = params.filter((p) => p.kind === 'flag');
+    const flagsByName = new Map(flagParams.map((f) => [f.name, f]));
+    // Apply defaults for bool flags
+    for (const f of flagParams) {
+        if (f.type === 'bool') {
+            result[flagNameToKey(f.name)] = f.default !== undefined ? f.default : false;
+        }
+        else if (f.default !== undefined) {
+            result[flagNameToKey(f.name)] = f.default;
+        }
+    }
+    let positionalValue;
+    let positionalWasSupplied = false; // Track if positional came from argv (not stdin)
+    let forcedPositional = false; // true after bare --
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if (token === '--' && !forcedPositional) {
+            forcedPositional = true;
+            i++;
+            continue;
+        }
+        if (!forcedPositional && token.startsWith('--')) {
+            // Flag: --name or --name=value
+            const eqIdx = token.indexOf('=');
+            let flagName;
+            let inlineValue;
+            if (eqIdx !== -1) {
+                flagName = token.slice(2, eqIdx);
+                inlineValue = token.slice(eqIdx + 1);
+            }
+            else {
+                flagName = token.slice(2);
+            }
+            // --context-file is handled specially regardless of declared schema
+            if (flagName === 'context-file') {
+                if (contextFileParam === undefined) {
+                    throw parseArgvError('unknown_flag', `unknown flag: --context-file`, '--context-file', undefined, 'This leaf does not accept --context-file.');
+                }
+                const pathVal = inlineValue !== undefined ? inlineValue : tokens[++i];
+                if (pathVal === undefined) {
+                    throw parseArgvError('missing_parameter', '--context-file requires a PATH argument', '--context-file', 'context-file');
+                }
+                let fileContent;
+                try {
+                    fileContent = readFileSync(pathVal, 'utf8');
+                }
+                catch (err) {
+                    throw parseArgvError('invalid_type', `--context-file: cannot read file: ${pathVal}`, pathVal, 'context-file', 'Provide a readable file path.');
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(fileContent);
+                }
+                catch {
+                    throw parseArgvError('invalid_type', `--context-file: file is not valid JSON: ${pathVal}`, pathVal, 'context-file', 'Ensure the file contains a valid JSON object.');
+                }
+                const contextFileKey = flagNameToKey(contextFileParam.name);
+                result[contextFileKey] = parsed;
+                provided.add(contextFileKey);
+                i++;
+                continue;
+            }
+            const flagDef = flagsByName.get(flagName);
+            if (flagDef === undefined) {
+                throw parseArgvError('unknown_flag', `unknown flag: --${flagName}`, `--${flagName}`, undefined, 'Use --<flag-name> for declared flags only. Run -h for the schema.');
+            }
+            const key = flagNameToKey(flagName);
+            provided.add(key);
+            if (flagDef.type === 'bool') {
+                if (inlineValue !== undefined) {
+                    throw parseArgvError('invalid_type', `boolean flag --${flagName} takes no value`, `--${flagName}=${inlineValue}`, flagName, `Use --${flagName} (presence = true) with no value.`);
+                }
+                result[key] = true;
+                i++;
+                continue;
+            }
+            const rawVal = inlineValue !== undefined ? inlineValue : tokens[++i];
+            if (rawVal === undefined || rawVal.startsWith('--')) {
+                throw parseArgvError('missing_parameter', `--${flagName} requires a value`, `--${flagName}`, flagName);
+            }
+            let parsedValue;
+            if (flagDef.type === 'int') {
+                const n = Number(rawVal);
+                if (!Number.isInteger(n)) {
+                    throw parseArgvError('invalid_type', `--${flagName} must be an integer`, rawVal, flagName, `Provide an integer value for --${flagName}.`);
+                }
+                parsedValue = n;
+            }
+            else if (flagDef.type === 'enum') {
+                const choices = flagDef.choices;
+                if (choices !== undefined && !choices.includes(rawVal)) {
+                    throw parseArgvError('invalid_type', `--${flagName} must be one of: ${choices.join(', ')}`, rawVal, flagName, `Retry with one of: ${choices.join(', ')}.`);
+                }
+                parsedValue = rawVal;
+            }
+            else {
+                // string or path
+                parsedValue = rawVal;
+            }
+            if (flagDef.repeatable === true) {
+                const existing = result[key];
+                const arr = Array.isArray(existing) ? existing : [];
+                arr.push(parsedValue);
+                result[key] = arr;
+            }
+            else {
+                result[key] = parsedValue;
+            }
+            i++;
+            continue;
+        }
+        // Positional (or token after --)
+        if (positionalValue !== undefined) {
+            // A leaf that also declares a `stdin` param treats its stdin value as
+            // write-only/sensitive by convention (`profile env set`'s value, etc.).
+            // An unexpected extra positional here is the single most likely misuse
+            // of that contract — a caller typing the secret as an argv token instead
+            // of piping it — so never echo the token or the full argv back; a
+            // sensitive value must not be disclosed by the very error that rejects
+            // the mistake.
+            if (stdinParam !== undefined) {
+                throw parseArgvError('bad_invocation', `unexpected extra positional argument (value withheld: this leaf reads "${stdinParam.name}" from stdin, never argv)`, undefined, undefined, `Pipe it on stdin instead of passing it as a positional argument.`);
+            }
+            throw parseArgvError('bad_invocation', `unexpected extra positional argument: ${token}`, tokens.join(' '), undefined, 'Use --flag for parameters; only one positional allowed.');
+        }
+        // A bare positional is accepted when the leaf declares a positional param,
+        // OR when it declares a stdin param (the positional supplies the stdin
+        // value as an ergonomic alternative to piping). Otherwise it's an error.
+        if (positionalParam === undefined && stdinParam === undefined) {
+            throw parseArgvError('bad_invocation', `this leaf takes no positional arguments: ${token}`, token, undefined, 'Use --flag for parameters. Run -h for the schema.');
+        }
+        positionalValue = token;
+        positionalWasSupplied = true;
+        i++;
+    }
+    // Assign positional (already tracked in provided set above)
+    if (positionalValue !== undefined && positionalParam !== undefined) {
+        result[flagNameToKey(positionalParam.name)] = positionalValue;
+    }
+    // Resolve stdin if declared. A positional token (when there's no dedicated
+    // positional param to claim it) satisfies the stdin param directly, so
+    // `crtr node new "Say hi"` works as well as piping on stdin. `-` is the
+    // standard Unix convention for "read stdin instead" — it always reads,
+    // never becomes the literal value. And a positional alongside genuinely
+    // piped, non-empty stdin is ambiguous: never silently pick one, error loud
+    // and name both sources.
+    let stdinWasSupplied = false;
+    if (stdinParam !== undefined) {
+        if (positionalValue !== undefined && positionalParam === undefined) {
+            if (positionalValue === '-') {
+                const raw = await readStdinRaw();
+                // Empty required stdin is NOT thrown here: it is left unset so the
+                // completeness check below reports it together with every other
+                // missing required parameter in ONE error.
+                if (raw.trim() !== '' || !stdinParam.required) {
+                    result[flagNameToKey(stdinParam.name)] = raw;
+                }
+                stdinWasSupplied = true;
+            }
+            else {
+                // A bounded peek, not a full drain: a non-TTY stdin that's merely
+                // inherited and held open (e.g. this leaf invoked as a subprocess by
+                // another agent that never closes its own stdin) must not hang the
+                // whole invocation waiting for a close that will never come.
+                const piped = await peekStdinRaw();
+                if (piped.trim() !== '') {
+                    throw parseArgvError('bad_invocation', `both a positional argument ("${positionalValue}") and piped stdin were provided for ${stdinParam.name}`, positionalValue, stdinParam.name, `Pass exactly one: either the positional argument or piped stdin, not both.`);
+                }
+                result[flagNameToKey(stdinParam.name)] = positionalValue;
+                stdinWasSupplied = true; // positional supplying stdin counts as supplied
+            }
+        }
+        else {
+            // Check if stdin is non-TTY (piped, redirected, or positional)
+            const stdinIsTTY = isatty(0);
+            // Unbounded drain to EOF — the standard Unix stdin-body contract. A
+            // heredoc/pipe/redirect/procsub all write and close before this
+            // process finishes reading, so this always resolves for genuine
+            // input; a slow producer's bytes must never be silently discarded.
+            // The non-hang guarantee lives at the spawn boundary instead: every
+            // crtr-owned subprocess (pi bash tool, the bash valve, async
+            // execFile('crtr', …) call sites) gives its child an ignored/closed
+            // stdin, so this only ever blocks on a foreign caller that hands crtr
+            // a held-open pipe — exactly the contract `cat`/`jq`/`wc` honor too.
+            const raw = await readStdinRaw();
+            // As above: an empty required stdin falls through to the completeness
+            // check so it is reported alongside any missing flags/positional.
+            if (raw.trim() !== '' || !stdinParam.required) {
+                result[flagNameToKey(stdinParam.name)] = raw;
+            }
+            // stdin is supplied if it was non-TTY (piped) OR if a positional was used
+            stdinWasSupplied = !stdinIsTTY || positionalWasSupplied;
+        }
+    }
+    // Track provided positional param
+    if (positionalWasSupplied && positionalParam !== undefined) {
+        provided.add(flagNameToKey(positionalParam.name));
+    }
+    // Track provided stdin param
+    if (stdinWasSupplied && stdinParam !== undefined) {
+        provided.add(flagNameToKey(stdinParam.name));
+    }
+    // Ambient defaults: a param declaring `defaultFromEnv` that the caller did not
+    // supply takes its value from that environment variable when it is set and
+    // non-empty. It is recorded as PROVIDED — the caller's environment is a real
+    // source, not a display default — so it satisfies the required check below and
+    // ships through the configured-CLI invoker's presence rule (a static `default`
+    // deliberately does neither).
+    for (const p of params) {
+        if (p.kind !== 'flag' && p.kind !== 'positional')
+            continue;
+        if (p.defaultFromEnv === undefined)
+            continue;
+        const key = flagNameToKey(p.name);
+        if (provided.has(key))
+            continue;
+        const envValue = process.env[p.defaultFromEnv];
+        if (envValue === undefined || envValue === '')
+            continue;
+        result[key] = envValue;
+        provided.add(key);
+    }
+    // Validate required params — COMPLETE, never first-failure. Drip-feeding one
+    // missing parameter per invocation turns a single correction into a round
+    // trip per field, so collect every violated requirement (flag, positional,
+    // context-file, stdin) and report them in ONE error. A missing parameter is
+    // proof the leaf was invoked without its contract in context, so `Next:`
+    // mandates the schema read rather than offering the one-field patch.
+    const missing = [];
+    for (const p of params) {
+        const key = flagNameToKey(p.name);
+        if (p.required && (result[key] === undefined || result[key] === null)) {
+            const display = p.kind === 'positional'
+                ? `positional ${p.name.toUpperCase()}`
+                : p.kind === 'flag'
+                    ? `--${p.name}`
+                    : p.kind === 'context-file'
+                        ? `--context-file`
+                        : 'stdin';
+            missing.push({ display, name: p.name });
+        }
+    }
+    if (missing.length > 0) {
+        const displays = missing.map((m) => m.display).join(', ');
+        const leafPath = options?.leafPath;
+        const cmd = leafPath !== undefined && leafPath.length > 0
+            ? `\`crtr ${leafPath.join(' ')} -h\``
+            : 'this command with -h';
+        throw parseArgvError('missing_parameter', missing.length === 1
+            ? `required parameter is missing: ${displays}`
+            : `required parameters are missing: ${displays}`, undefined, missing.map((m) => m.name).join(', '), `Run ${cmd} and read the full schema before re-issuing — do not guess parameters one at a time.`);
+    }
+    // Notify caller of which parameters were explicitly provided
+    if (options?.onProvidedParams !== undefined) {
+        options.onProvidedParams(provided);
+    }
+    return result;
+}
+export async function runCli(root, argv, options) {
+    // argv is process.argv — strip node binary + script path. `--json` is a
+    // global: pull it out anywhere it appears so the rest of argv parses against
+    // the leaf schema unchanged, and switch stdout from rendered prose to raw
+    // JSON. It is intentionally undocumented — the default prose output is the
+    // agent contract; --json exists only for programmatic/tooling consumers.
+    // `--no-autostart` is likewise a global: it suppresses cold-socket daemon
+    // autostart (read from `process.argv` in `cliClient`, spec §7.1) and applies
+    // to every API-backed verb, so strip it here rather than declaring it on each
+    // leaf schema (an undeclared flag would otherwise be rejected as unknown).
+    const rawTokens = argv.slice(2);
+    const jsonStripped = rawTokens.filter((t) => t !== '--json');
+    if (jsonStripped.length !== rawTokens.length)
+        setJsonOutput(true);
+    const tokens = jsonStripped.filter((t) => t !== '--no-autostart');
+    // Bare root invocation or -h at root
+    if (tokens.length === 0 || (tokens.length === 1 && (tokens[0] === '-h' || tokens[0] === '--help'))) {
+        process.stdout.write(renderRoot(root.help) + '\n');
+        process.exitCode = ExitCode.SUCCESS;
+        return;
+    }
+    let { node, path, remaining } = walk(root, tokens);
+    try {
+        // The ONE unknown-first-token retry (§5.1): an unknown FIRST token — walk
+        // stopped at root (path empty) on a real, non-help token — is the only site
+        // absent-store configured-CLI hydration may fire. A deeper unknown token
+        // under a known command (path non-empty) NEVER triggers it. Invoke the seam
+        // exactly once; if it hydrated new commands it returns a rebuilt root and we
+        // re-walk the original argv once, then dispatch proceeds normally against the
+        // re-resolved node. Kept inside the try so a seam throw routes through the
+        // same error handler as everything else.
+        if (options?.onUnknownFirstTokenMiss !== undefined &&
+            node.kind === 'root' &&
+            path.length === 0 &&
+            remaining.length > 0 &&
+            remaining[0] !== '-h' &&
+            remaining[0] !== '--help') {
+            const rebuilt = await options.onUnknownFirstTokenMiss();
+            if (rebuilt !== undefined)
+                ({ node, path, remaining } = walk(rebuilt, tokens));
+        }
+        // Passthrough branches (e.g. `crtr capture`) opt out of the tree model
+        // entirely: forward every token after the branch verbatim to an external
+        // binary before any of the normal unknown-path / help / dispatch logic
+        // runs, so `crtr capture -h`, `crtr capture <args>`, and bare `crtr capture`
+        // all reach the external CLI untouched.
+        if (node.kind === 'branch' && node.passthrough !== undefined) {
+            runPassthrough(node.passthrough, rawArgsAfterPath(rawTokens, path));
+        }
+        // A root/branch node's `remaining` is only non-empty because walk hit
+        // -h/--help or an unmatched child name (a leaf always consumes the rest
+        // of the path itself). So a non-help leading token here is always the
+        // latter: reject it as an unknown path before rendering any help, even
+        // when a -h/--help token also appears later in `remaining` — otherwise a
+        // removed/misspelled subcommand followed by -h would render the parent's
+        // help and exit 0 instead of failing.
+        if ((node.kind === 'root' || node.kind === 'branch')
+            && remaining.length > 0
+            && remaining[0] !== '-h' && remaining[0] !== '--help') {
+            throw unknownPathError(node, path, remaining[0]);
+        }
+        // Help anywhere in remaining tokens → print node help and exit
+        if (helpRequested(remaining)) {
+            process.stdout.write(renderNode(node) + '\n');
+            process.exitCode = ExitCode.SUCCESS;
+            return;
+        }
+        // Bare branch or bare root (no -h, remaining fully consumed) → help surface
+        if (node.kind === 'root' || node.kind === 'branch') {
+            process.stdout.write(renderNode(node) + '\n');
+            process.exitCode = ExitCode.SUCCESS;
+            return;
+        }
+        // Leaf dispatch — argv input model only. Bind the leaf to a const so the
+        // narrowing established by the branch/root guards above survives the awaits
+        // below: `node` is now a reassignable `let` (the §5.1 retry re-walks it),
+        // which TS re-widens to the node union across an `await`.
+        const leaf = node;
+        const params = leaf.help.params !== undefined ? leaf.help.params : [];
+        let providedParams = new Set();
+        const input = await parseArgv(params, remaining, {
+            leafPath: path,
+            onProvidedParams: (provided) => {
+                providedParams = provided;
+            },
+        });
+        const context = { providedParams };
+        const result = await operationIdContext.fresh(() => leaf.run(input, context));
+        if (result !== undefined && result !== null) {
+            if (isJsonOutput()) {
+                emit(result);
+            }
+            else {
+                const text = leaf.render !== undefined ? leaf.render(result) : renderResult(result, leaf.help);
+                process.stdout.write(text + '\n');
+            }
+        }
+        // JSONL leaves call emitLine themselves and return void
+    }
+    catch (e) {
+        handle(e);
+    }
+}