@north-light/crouter 0.3.302 → 0.3.303

package/dist/core/bash-guard.js

@@ -0,0 +1,393 @@
+// bash-guard.ts — the refusals the bash valve applies to a command's TEXT
+// before any of it runs. Pure: command text and the node's cwd in, a refusal
+// message or null out.
+//
+// Two refusals live here, for the same reason: both are things no correct
+// agent command ever does, and both are cheaper to stop than to recover from.
+//
+//  - A long leading `sleep` burns a live window on a clock the runtime already
+//    owns a cheaper primitive for.
+//  - A destructive command aimed at the home directory, a system root, or a
+//    directory above the node's own working directory is unrecoverable.
+//
+// The second exists because of a real incident. A node ran:
+//
+//   cd star-theory-2 && HOME="$(mktemp -d …)" godot … ; rm -rf "$HOME" …
+//
+// A `VAR=value cmd` prefix applies only to that ONE command, so the trailing
+// `rm -rf "$HOME"` used the real home directory and deleted for 108 seconds
+// before another node killed it. A memory doc telling agents not to do this
+// already exists; it is advisory and did not survive contact. This is the
+// block.
+//
+// What this is NOT: a sandbox. Command text is read best-effort — expansions,
+// subshells, `eval`, and a script the command invokes are all out of reach. It
+// stops the plausible mistake a competent agent makes, not an agent trying to
+// get around it. Anything it cannot resolve, it allows: a guard that guesses
+// would refuse ordinary work, and an agent that learns the guard is noisy
+// starts routing around it.
+import { homedir, userInfo } from 'node:os';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { commandSegments, stripHeredocs } from './shell-segments.js';
+// Long-sleep guard. A command that opens with `sleep <long>` is a node burning
+// a live window to wait on a clock — the runtime already has waiting primitives
+// that cost nothing (`crtr cron` for a scheduled wake, `crtr node wait deadline`
+// for an inbox-vs-deadline race). Anything over 10s is refused before it runs.
+const MAX_INLINE_SLEEP_SECONDS = 10;
+const SLEEP_UNIT_SECONDS = { s: 1, m: 60, h: 3600, d: 86400 };
+/** Seconds a leading `sleep ...` will block for, or null when the command does
+ *  not open with a sleep (or its duration isn't statically knowable). */
+export function leadingSleepSeconds(command) {
+    const match = /^\s*sleep(\s+[^;&|\n]+)/.exec(command);
+    if (!match)
+        return null;
+    // `sleep 1 2m 3` sums its operands.
+    let total = 0;
+    for (const operand of match[1].trim().split(/\s+/)) {
+        const parsed = /^([0-9]*\.?[0-9]+)([smhd]?)$/.exec(operand);
+        if (!parsed)
+            return null; // variable/expansion/flag — not statically knowable
+        total += Number(parsed[1]) * SLEEP_UNIT_SECONDS[parsed[2] || 's'];
+    }
+    return total;
+}
+function longSleepRefusal(command) {
+    const seconds = leadingSleepSeconds(command);
+    if (seconds === null || seconds <= MAX_INLINE_SLEEP_SECONDS)
+        return null;
+    return (`Refused: this command starts by sleeping ${seconds}s, over the ${MAX_INLINE_SLEEP_SECONDS}s inline limit.\n` +
+        `Holding a live window on a clock is never how you wait here. Instead:\n` +
+        `  - schedule the wake and end your turn: crtr cron -h (one-shot at a time, or recurring)\n` +
+        `  - race an inbox message against a deadline: crtr node wait deadline -h\n` +
+        `  - waiting on a child, a reply from the user, or any spine event: just stop — the runtime wakes you.\n` +
+        `If you truly need a short pause inline, sleep ${MAX_INLINE_SLEEP_SECONDS}s or less.`);
+}
+// Protected paths
+/** System directories whose removal, relocation, or recursive permission
+ *  change breaks the machine rather than the task. Matched EXACTLY after
+ *  resolution — `/tmp` is protected, `/tmp/build-1234` is ordinary work. */
+const PROTECTED_SYSTEM_PATHS = [
+    '/',
+    '/Applications',
+    '/bin',
+    '/dev',
+    '/etc',
+    '/home',
+    '/Library',
+    '/opt',
+    '/private',
+    '/private/etc',
+    '/private/tmp',
+    '/private/var',
+    '/sbin',
+    '/System',
+    '/tmp',
+    '/usr',
+    '/Users',
+    '/var',
+    '/Volumes',
+];
+/** Why a resolved target is protected, in the words the refusal uses. `null`
+ *  when the target is ordinary and the command may run. */
+function protectedReason(target, home, cwd) {
+    if (PROTECTED_SYSTEM_PATHS.includes(target))
+        return 'a system directory';
+    if (target === home)
+        return 'your home directory';
+    if (target === `${home}/.crouter`)
+        return 'the canvas home — every node\u2019s conversation and state';
+    // Strict ancestors only: a node may delete its OWN working directory (a
+    // merged worktree is a real case), just nothing that contains it.
+    if (cwd === target || !cwd.startsWith(target.endsWith(sep) ? target : target + sep))
+        return null;
+    return `a directory containing your working directory (${cwd})`;
+}
+function initialVariables(home, cwd) {
+    const user = userInfo().username;
+    return new Map([['HOME', home], ['PWD', cwd], ['USER', user], ['LOGNAME', user]]);
+}
+/** The text with `~` and every known `$VAR` substituted, or null when what is
+ *  left still depends on something the guard cannot see. */
+function expandText(text, vars) {
+    let t = text;
+    if (t === '~' || t.startsWith('~/')) {
+        const home = vars.get('HOME');
+        if (home === undefined)
+            return null;
+        t = home + t.slice(1);
+    }
+    else if (t.startsWith('~')) {
+        return null; // ~otheruser — not ours to resolve
+    }
+    t = t.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (whole, braced, bare) => vars.get(braced ?? bare) ?? whole);
+    // Anything still carrying an expansion or a glob is not statically knowable.
+    return /[$`*?[]/.test(t) ? null : t;
+}
+/** The absolute path an operand names, or null when it is not statically
+ *  knowable. A trailing `/*` or `/.` is stripped first: `rm -rf ~/*` empties
+ *  the same tree as `rm -rf ~`. A relative operand resolves against `base` —
+ *  null when an earlier `cd` in the same line went somewhere the guard cannot
+ *  follow. */
+function resolveTarget(text, vars, base) {
+    const expanded = expandText(text.replace(/\/+\*?\.?$/, '') || '/', vars);
+    if (expanded === null)
+        return null;
+    if (isAbsolute(expanded))
+        return resolve(expanded);
+    return base === null ? null : resolve(base, expanded);
+}
+/** Fold `VAR=value` assignments into a variable map. A value the guard cannot
+ *  expand deletes the variable rather than leaving a stale one behind: reading
+ *  a later `$HOME` as the real home when the line reassigned it is exactly the
+ *  false refusal that would teach agents to route around this guard. */
+function applyAssignments(vars, assignments) {
+    for (const assignment of assignments) {
+        const eq = assignment.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const name = assignment.slice(0, eq);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            continue;
+        const value = expandText(assignment.slice(eq + 1), vars);
+        if (value === null)
+            vars.delete(name);
+        else
+            vars.set(name, value);
+    }
+}
+// The destructive operations
+/** A redirection, whole (`2>/dev/null`) or as its bare operator (`>`), which
+ *  takes the next word as its file. Neither is an operand of the command. */
+const REDIRECTION = /^[0-9]*(&?>>?|<<?|>&|<&)/;
+/** Operands of a segment, minus flags, the `--` end-of-flags marker, and
+ *  redirections. */
+function operands(tokens) {
+    const out = [];
+    let flagsEnded = false;
+    let skipNext = false;
+    for (const token of tokens.slice(1)) {
+        if (skipNext) {
+            skipNext = false;
+            continue;
+        }
+        const redirection = REDIRECTION.exec(token.text);
+        if (redirection !== null && !token.opaque) {
+            skipNext = token.text === redirection[0]; // bare operator — its file is the next word
+            continue;
+        }
+        if (!flagsEnded && token.text === '--') {
+            flagsEnded = true;
+            continue;
+        }
+        if (!flagsEnded && token.text.startsWith('-') && token.text !== '-')
+            continue;
+        out.push(token.text);
+    }
+    return out;
+}
+/** Short and long flags of a segment, short combinations split into letters. */
+function flagLetters(tokens) {
+    const letters = new Set();
+    const long = new Set();
+    for (const token of tokens.slice(1)) {
+        if (token.text === '--')
+            break;
+        if (token.text.startsWith('--'))
+            long.add(token.text.slice(2));
+        else if (token.text.startsWith('-') && token.text.length > 1)
+            for (const ch of token.text.slice(1))
+                letters.add(ch);
+    }
+    return { letters, long };
+}
+function isRecursive(tokens) {
+    const { letters, long } = flagLetters(tokens);
+    return letters.has('r') || letters.has('R') || long.has('recursive');
+}
+/** A block device holding a filesystem. `/dev/null`, `/dev/stdout`, and
+ *  `/dev/zero` are ordinary output; a disk node is not. */
+const RAW_DISK_DEVICE = /^\/dev\/r?(disk|sd[a-z]|nvme|hd[a-z]|vd[a-z]|mmcblk|md)/;
+/** `find`'s start paths: the words between its leading global options and the
+ *  first predicate of the expression. Those options are why the paths cannot
+ *  simply be "everything before the first `-` word" — `find -H ~ -delete` and
+ *  `find -- ~ -delete` both walk the home tree. */
+function findPaths(tokens) {
+    const paths = [];
+    let i = 1;
+    while (i < tokens.length) {
+        const text = tokens[i].text;
+        if (text === '--' || /^-[HLPEdsx]$/.test(text))
+            i += 1;
+        else if (text === '-D' || text === '-O')
+            i += 2; // GNU debug/optimisation, each with a value
+        else if (text === '-f') { // BSD's explicit start path
+            if (i + 1 < tokens.length)
+                paths.push(tokens[i + 1].text);
+            i += 2;
+        }
+        else
+            break;
+    }
+    for (; i < tokens.length; i += 1) {
+        if (tokens[i].text.startsWith('-'))
+            break;
+        paths.push(tokens[i].text);
+    }
+    return paths;
+}
+/** Command names that stand in front of the real command and must be stepped
+ *  over before it can be read. Their own flags are skipped with them. */
+const COMMAND_PREFIXES = new Set(['sudo', 'doas', 'command', 'env', 'nice', 'nohup', 'time', 'stdbuf', 'xargs', 'exec', 'builtin']);
+/** Strip every leading prefix command and its flags, leaving the real command
+ *  as `tokens[0]`. `sudo -E nice -n 10 rm -rf ~` reads as `rm -rf ~`. */
+function stripCommandPrefixes(tokens) {
+    let rest = tokens;
+    while (rest.length > 0 && !rest[0].opaque && COMMAND_PREFIXES.has(rest[0].text)) {
+        let i = 1;
+        while (i < rest.length && rest[i].text.startsWith('-')) {
+            // `nice -n 10` and `env -u VAR` take a value; a lone flag does not.
+            const takesValue = /^-[nu]$/.test(rest[i].text);
+            i += takesValue ? 2 : 1;
+        }
+        // `env FOO=bar cmd` — the assignments belong to env, not to the command.
+        while (i < rest.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(rest[i].text))
+            i += 1;
+        if (i >= rest.length)
+            return [];
+        rest = rest.slice(i);
+    }
+    return rest;
+}
+/** Targets this segment would destroy: the operands whose loss the guard
+ *  cares about, or `[]` when the segment is not a destructive operation. A
+ *  verb appears here only when ONE invocation of it can take out a whole tree.
+ *  A device or subcommand named directly (`mkfs.ext4`, `diskutil eraseDisk`)
+ *  has no path operand to resolve, so it reports itself. */
+function destructiveTargets(tokens) {
+    const none = { targets: [], named: null };
+    const head = tokens[0];
+    if (head === undefined || head.opaque)
+        return none;
+    const name = head.text.slice(head.text.lastIndexOf('/') + 1);
+    const args = operands(tokens);
+    switch (name) {
+        // `rm` without a recursive flag cannot remove a directory at all.
+        case 'rm':
+            return isRecursive(tokens) ? { targets: args, named: null } : none;
+        // Every operand but the destination is a source that stops existing.
+        case 'mv':
+            return args.length >= 2 ? { targets: args.slice(0, -1), named: null } : none;
+        // A recursive mode or ownership sweep over a system tree is as final as a
+        // deletion. The first operand is the mode/owner, not a path.
+        case 'chmod':
+        case 'chown':
+        case 'chgrp':
+            return isRecursive(tokens) && args.length >= 2 ? { targets: args.slice(1), named: null } : none;
+        // `find <path> … -delete` and `-exec` walk the tree and act on every hit.
+        case 'find': {
+            const acts = tokens.some((t) => !t.opaque && (t.text === '-delete' || t.text === '-exec' || t.text === '-execdir'));
+            return acts ? { targets: findPaths(tokens), named: null } : none;
+        }
+        // `dd of=…` overwrites its output in place; a raw disk is unrecoverable,
+        // while `of=/dev/null` and friends are ordinary output redirection.
+        case 'dd': {
+            const of = tokens.find((t) => t.text.startsWith('of='));
+            if (of === undefined)
+                return none;
+            const path = of.text.slice(3);
+            if (RAW_DISK_DEVICE.test(path))
+                return { targets: [], named: path };
+            return path.startsWith('/dev/') ? none : { targets: [path], named: null };
+        }
+        default:
+            // Filesystem creation and disk erasure destroy a volume outright; there
+            // is no safe target for them inside an agent's task.
+            if (/^(mkfs|newfs)([.-].+)?$/.test(name))
+                return { targets: [], named: name };
+            if (name === 'diskutil') {
+                const verb = args[0];
+                if (verb !== undefined && /^(erase|reformat|partition|zeroDisk|randomDisk|secureErase)/i.test(verb)) {
+                    return { targets: [], named: `diskutil ${verb}` };
+                }
+            }
+            return none;
+    }
+}
+/** Walk the line segment by segment, carrying the variable values and working
+ *  directory the shell itself would carry, and refuse the first destructive
+ *  segment aimed at a protected path.
+ *
+ *  Carrying that state IS the guard's core distinction. `export HOME=/tmp/x`
+ *  as its own command changes `$HOME` for everything after it, so a later
+ *  `rm -rf "$HOME"` is a scratch directory and runs. A `HOME=/tmp/x cmd`
+ *  PREFIX applies to that one command only, so a later `rm -rf "$HOME"` is the
+ *  real home — which is precisely the mistake that destroyed one. */
+function destructiveCommandRefusal(command, cwd, home) {
+    const vars = initialVariables(home, cwd);
+    // Every directory a relative operand might be resolved from. A `cd` ADDS its
+    // destination rather than replacing the previous one, because the guard
+    // cannot know whether the shell's `cd` succeeded: after `cd missing-dir`,
+    // bash stays put and `rm -rf ..` really is the ancestor. Refusing when ANY
+    // candidate is protected keeps that case caught; the refusal names the
+    // resolved path, and an absolute operand is never ambiguous.
+    let bases = [cwd];
+    for (const segment of commandSegments(stripHeredocs(command))) {
+        const tokens = stripCommandPrefixes(segment.tokens);
+        const head = tokens[0];
+        if (head !== undefined) {
+            // This segment's own prefix assignments apply to this command only.
+            const local = new Map(vars);
+            applyAssignments(local, segment.assignments);
+            const innermost = bases[bases.length - 1];
+            if (innermost !== undefined)
+                local.set('PWD', innermost);
+            const { targets, named } = destructiveTargets(tokens);
+            if (named !== null)
+                return refusalMessage(segment.text, named, 'a whole disk or volume — never a task boundary');
+            for (const target of targets) {
+                for (const base of bases.length === 0 ? [null] : bases) {
+                    const resolved = resolveTarget(target, local, base);
+                    if (resolved === null)
+                        continue;
+                    const reason = protectedReason(resolved, home, cwd);
+                    if (reason !== null)
+                        return refusalMessage(segment.text, resolved, reason);
+                }
+            }
+        }
+        // Then carry this segment's lasting effects into the rest of the line. A
+        // backgrounded segment runs in a subshell, so it has none.
+        if (segment.background)
+            continue;
+        if (head === undefined)
+            applyAssignments(vars, segment.assignments);
+        else if (!head.opaque && SHELL_VARIABLE_BUILTINS.has(head.text)) {
+            // A prefix assignment to a special builtin persists in the shell.
+            applyAssignments(vars, segment.assignments);
+            applyAssignments(vars, operands(tokens));
+        }
+        else if (!head.opaque && head.text === 'cd') {
+            const destination = operands(tokens)[0];
+            const next = destination === undefined ? vars.get('HOME') ?? null : resolveTarget(destination, vars, bases[bases.length - 1] ?? null);
+            // An unfollowable `cd` leaves no knowable base at all; a relative operand
+            // after it is unresolvable, and unresolvable always means allowed.
+            bases = next === null ? [] : [...bases, next];
+        }
+    }
+    return null;
+}
+/** Builtins that set shell variables for everything after them. */
+const SHELL_VARIABLE_BUILTINS = new Set(['export', 'declare', 'typeset', 'readonly']);
+function refusalMessage(segment, target, reason) {
+    return (`Refused: \`${segment}\` targets ${target}, which is ${reason}.\n` +
+        `Nothing an agent is asked to do requires destroying that path, and it cannot be undone.\n` +
+        `If you meant somewhere else, name that path explicitly and run the command again. Two traps to check first:\n` +
+        `  - a \`VAR=value cmd\` prefix applies ONLY to that one command, so a later \`$VAR\` in the same line is the SHELL's value — this is exactly how a node deleted a home directory.\n` +
+        `  - \`~\` and \`$HOME\` are the real home directory, never a scratch dir; build scratch paths with mktemp -d and hold them in a variable of your own.\n` +
+        `If you believe this path genuinely must be destroyed, ask the user — do not work around this refusal.`);
+}
+/** The refusal this command earns before it runs, or null when it may run.
+ *  `cwd` is the directory the command will execute in. */
+export function bashCommandRefusal(command, cwd, home = homedir()) {
+    return longSleepRefusal(command) ?? destructiveCommandRefusal(command, cwd, home);
+}

package/dist/core/runtime/broker/fault-retry.d.ts

@@ -25,6 +25,7 @@ export declare class FaultRetry {
     private readonly notFoundModels;
     private providerFallbackInFlight;
     private notFoundFallbackInFlight;
+    private stagedCapacityFailure;
     constructor(deps: FaultRetryDeps);
     clearTimer(): void;
     reset(): void;
@@ -54,6 +55,9 @@ export declare class FaultRetry {
     schedule(): void;
     private maybeSwitchProviderForRetry;
     private maybeFallbackOnUnusableModel;
+    private nextEligibleFallbackRoute;
+    private targetCannotFitContext;
+    private stageCapacityFailure;
     private recordPendingProviderFault;
     private sessionFile;
     private pendingEpisodeMatches;

package/dist/core/runtime/broker/fault-retry.js

@@ -22,6 +22,11 @@ export class FaultRetry {
     notFoundModels = new Set();
     providerFallbackInFlight = null;
     notFoundFallbackInFlight = null;
+    // A fallback can learn its target cannot hold this session before the
+    // current turn settles. Keep that outcome here rather than on the engine's
+    // agent_end staging field: message_end precedes agent_end, which resets that
+    // field for the ordinary provider result.
+    stagedCapacityFailure = null;
     constructor(deps) {
         this.deps = deps;
     }
@@ -35,6 +40,7 @@ export class FaultRetry {
         this.clearTimer();
         this.providerFallbackInFlight = null;
         this.notFoundFallbackInFlight = null;
+        this.stagedCapacityFailure = null;
     }
     onEvent(event) {
         this.maybeSwitchProviderForRetry(event);
@@ -54,6 +60,8 @@ export class FaultRetry {
         const watchdogAbort = generation.stagedWatchdogAbort;
         const refreshAbort = generation.stagedRefreshAbort;
         const overflowFailure = generation.stagedOverflowFailure;
+        const capacityFailure = this.stagedCapacityFailure?.generation === generation ? this.stagedCapacityFailure : null;
+        this.stagedCapacityFailure = null;
         generation.stagedProviderAgentEnd = null;
         generation.stagedWatchdogAbort = false;
         generation.stagedRefreshAbort = false;
@@ -76,12 +84,12 @@ export class FaultRetry {
             : { since: episodeFault.since, anchorEntryId: episodeFault.anchorEntryId, attempt: episodeFault.retry.attempt };
         const messages = Array.isArray(agentEnd?.messages) ? agentEnd.messages : [];
         const last = [...messages].reverse().find((message) => typeof message === 'object' && message !== null && message.role === 'assistant');
-        if (overflowFailure !== null) {
+        if (capacityFailure !== null || overflowFailure !== null) {
             clearFault(this.deps.nodeId, { link: 'pi→provider' });
             clearProviderRetryEpisode(this.deps.nodeId);
             recordFault(this.deps.nodeId, {
                 link: 'pi→provider', op: 'context overflow recovery', kind: 'context-overflow', retry: { disposition: 'fatal' },
-                message: overflowFailure.errorMessage, anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
+                message: capacityFailure?.errorMessage ?? overflowFailure.errorMessage, anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
             });
             return;
         }
@@ -250,9 +258,23 @@ export class FaultRetry {
         const routes = expandModelCandidates(routeRequest, envNodeCwd() ?? this.deps.cfg.cwd, envProfileId());
         const current = parseModelSpec(currentSpec);
         const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
-        const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => !this.failedRetryRoutes.has(candidate.routeId) && resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, this.deps.registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0);
-        if (nextRoute === undefined)
+        const fallback = liveRank === undefined
+            ? { route: undefined, capacityExhausted: false }
+            : this.nextEligibleFallbackRoute(routes.slice(liveRank + 1), this.deps.registryOf(candidateServices), candidateSession.getContextUsage()?.tokens, (candidate) => !this.failedRetryRoutes.has(candidate.routeId));
+        if (fallback.route === undefined) {
+            if (fallback.capacityExhausted) {
+                this.stageCapacityFailure(generation, candidateSession);
+                // Pi creates its retry AbortController immediately after it emits this
+                // event. Defer the abort so it cancels that controller, then lets the
+                // normal agent_settled path publish the staged fatal outcome.
+                queueMicrotask(() => {
+                    if (this.deps.installedGeneration() === generation && this.deps.currentSession() === candidateSession)
+                        candidateSession.abortRetry();
+                });
+            }
             return;
+        }
+        const nextRoute = fallback.route;
         const fallbackPromise = (async () => {
             const target = this.deps.registryOf(candidateServices).find(nextRoute.providerId, nextRoute.modelId);
             if (!target)
@@ -290,9 +312,15 @@ export class FaultRetry {
         const routeRequest = modelRequestFromConfig(this.deps.cfg.model, envModelIntent(), false);
         const routes = routeRequest ? expandModelCandidates(routeRequest, envNodeCwd() ?? this.deps.cfg.cwd, envProfileId()) : [];
         const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
-        const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => !this.notFoundModels.has(`${candidate.providerId}/${candidate.modelId}`) && resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, this.deps.registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0);
-        if (!nextRoute)
+        const fallback = liveRank === undefined
+            ? { route: undefined, capacityExhausted: false }
+            : this.nextEligibleFallbackRoute(routes.slice(liveRank + 1), this.deps.registryOf(candidateServices), candidateSession.getContextUsage()?.tokens, (candidate) => !this.notFoundModels.has(`${candidate.providerId}/${candidate.modelId}`));
+        if (fallback.route === undefined) {
+            if (fallback.capacityExhausted)
+                this.stageCapacityFailure(generation, candidateSession);
             return;
+        }
+        const nextRoute = fallback.route;
         const target = `${nextRoute.providerId}/${nextRoute.modelId}${nextRoute.thinkingLevel ? `:${nextRoute.thinkingLevel}` : ''}`;
         const fallbackPromise = (async () => {
             const model = this.deps.registryOf(candidateServices).find(nextRoute.providerId, nextRoute.modelId);
@@ -323,6 +351,38 @@ export class FaultRetry {
         });
         this.notFoundFallbackInFlight = fallbackPromise;
     }
+    nextEligibleFallbackRoute(routes, registry, contextTokens, include) {
+        let available = 0;
+        let tooSmall = 0;
+        for (const candidate of routes) {
+            if (!include(candidate))
+                continue;
+            if (resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, registry), automaticFallback: true }]).candidates.length === 0)
+                continue;
+            const target = registry.find(candidate.providerId, candidate.modelId);
+            if (target === undefined)
+                continue;
+            available++;
+            if (this.targetCannotFitContext(target.contextWindow, contextTokens)) {
+                tooSmall++;
+                continue;
+            }
+            return { route: candidate, capacityExhausted: false };
+        }
+        return { route: undefined, capacityExhausted: available > 0 && available === tooSmall };
+    }
+    targetCannotFitContext(contextWindow, contextTokens) {
+        return Number.isFinite(contextWindow) && Number.isFinite(contextTokens) && contextWindow < contextTokens;
+    }
+    stageCapacityFailure(generation, session) {
+        const tokens = session.getContextUsage()?.tokens;
+        this.stagedCapacityFailure = {
+            generation,
+            errorMessage: Number.isFinite(tokens)
+                ? `All available fallback models have context windows smaller than the current conversation (${tokens} tokens).`
+                : 'All available fallback models have context windows smaller than the current conversation.',
+        };
+    }
     recordPendingProviderFault(session, input) {
         const sessionFile = this.sessionFile(session);
         // A pathless session cannot be crash-recovered, but its live broker still

package/dist/core/shell-segments.d.ts

@@ -0,0 +1,42 @@
+/** One shell word. `opaque` marks a token whose text came from inside quotes:
+ *  it is data, so it must never be treated as an executable or a matched
+ *  command word. */
+export type CommandToken = {
+    text: string;
+    opaque: boolean;
+};
+/** One shell segment: the raw text as the author wrote it, its leading
+ *  `VAR=value` assignments, and the remaining words — so `tokens[0]` is the
+ *  executable. An assignment-only segment (`export`-less `FOO=bar`) has
+ *  assignments and no tokens; the distinction matters, because a leading
+ *  assignment applies ONLY to the command in its own segment.
+ *
+ *  `background` marks a segment ended by a single `&`. It runs in a subshell,
+ *  so nothing it assigns or `cd`s reaches the commands after it. */
+export type CommandSegment = {
+    text: string;
+    assignments: string[];
+    tokens: CommandToken[];
+    background: boolean;
+};
+/** One raw segment and whether a single `&` — not `&&` — ended it. */
+export type RawSegment = {
+    text: string;
+    background: boolean;
+};
+/** Split a command into shell segments on unquoted `;`, newline, `&&`, `||`,
+ *  `|`, and a single `&`. Subshell parentheses and backticks are left inside
+ *  their segment. Heredoc bodies are a separate pre-read concern (see
+ *  `stripHeredocs`). */
+export declare function splitCommandSegments(command: string): RawSegment[];
+/** Tokenize one segment into shell words, marking quoted spans opaque. */
+export declare function tokenizeCommandSegment(segment: string): CommandToken[];
+/** Every non-empty command segment, paired with its raw text. */
+export declare function commandSegments(command: string): CommandSegment[];
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is read. The opening line is kept —
+ *  `crtr push final <<'EOF'` is still a real `push final` invocation — but the
+ *  body lines, which are data fed on stdin and never executed as commands, are
+ *  dropped. Without this, a doc-writing command whose body merely MENTIONS a
+ *  matched invocation would have its whole call held or refused. */
+export declare function stripHeredocs(command: string): string;