@north-light/crouter 0.3.302 → 0.3.304

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/bash-jobs.d.ts

@@ -12,6 +12,9 @@ export interface BashJobPaths {
      * Inspector's cancel) — without it on disk, only the agent's own handoff
      * notice knows the group to signal. */
     jobPgid: string;
+    /** Launch-time identity of the detached supervisor, used to refuse a PID that
+     * has since been reused by an unrelated process. */
+    jobPgidIdentity: string;
     /** Human-readable label supplied with the bash call, when any. */
     jobPurpose: string;
     /** Epoch-ms cancel deadline for an AUTO-backgrounded job. Present only when
@@ -33,6 +36,9 @@ export declare function bashJobPaths(contextDir: string, jobId: string): BashJob
 /** The job's supervisor process group, or undefined for a job started before
  * pgid was persisted (or a partially-written dir). */
 export declare function readJobPgid(contextDir: string, jobId: string): number | undefined;
+/** Launch-time identity of the supervisor. Missing for jobs created before
+ * process-identity persistence, which are deliberately not safe to signal. */
+export declare function readJobPgidIdentity(contextDir: string, jobId: string): string | undefined;
 /** The optional human-readable job label. Jobs created before labels existed
  * have no file and deliberately project null. */
 export declare function readJobPurpose(contextDir: string, jobId: string): string | null;
@@ -73,6 +79,12 @@ export declare function clearJobDeadline(paths: BashJobPaths): void;
  *  means the group exists but cannot be signaled by this process; it is still
  *  live for the status surface. */
 export declare function isBashJobProcessGroupAlive(pgid: number): boolean;
+/** Best-effort cancellation for a detached bash supervisor. It snapshots the
+ * observable descendant tree while the supervisor is still alive, signals its
+ * leaves before their parents, then uses the shared identity-guarded KILL
+ * escalation. A descendant that detached and reparented before this snapshot
+ * is outside this guarantee. */
+export declare function cancelBashJobProcessTree(pgid: number, expectedIdentity: string): Promise<boolean>;
 export type StopBackgroundBashJobResult = {
     kind: 'stopped';
     signaled: boolean;
@@ -87,15 +99,15 @@ export type StopBackgroundBashJobResult = {
     kind: 'not-stoppable';
     logPath: string;
 };
-/** Stop one live background job using the same process-group and sentinel
- *  semantics as `crtr node bash kill`. The caller owns the user-facing
- *  notification; this primitive owns only the job control-plane mutation.
+/** Stop one live background job using the same best-effort tree cancellation
+ * semantics as inline abort and timeout. The caller owns the user-facing
+ * notification; this primitive owns only the job control-plane mutation.
  *
- *  Only a job in the live-background state the roster projects (job.bg
- *  present, job.exit absent) may be signaled. Job directories persist after
- *  the supervisor exits, so a retired, still-foreground, or already-stopped
- *  job would otherwise have its recorded pgid signaled long after the OS
- *  could have reused that id for an unrelated process group. */
+ * Only a job in the live-background state the roster projects (job.bg present,
+ * job.exit absent) may be signaled. Job directories persist after the
+ * supervisor exits, so a retired, still-foreground, or already-stopped job
+ * would otherwise have its recorded pgid signaled long after the OS could have
+ * reused that id for an unrelated process group. */
 export declare function stopBackgroundBashJob(contextDir: string, jobId: string): Promise<StopBackgroundBashJobResult>;
 /** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
  * rather than the whole file, which for a long-running job can be enormous. */

package/dist/core/bash-jobs.js

@@ -5,6 +5,7 @@
 import { randomBytes } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { captureTeardownSnapshot, isAnyPidAlive, killProcessTreePids } from './canvas/pid.js';
 const MAX_BASH_JOB_PURPOSE_BYTES = 280;
 /** A purpose is display text, never shell input. Keep the file-backed control
  * plane to one bounded, visible line so old or hand-written job directories
@@ -41,6 +42,7 @@ export function bashJobPaths(contextDir, jobId) {
         jobBg: join(dir, 'job.bg'),
         jobDone: join(dir, 'job.done'),
         jobPgid: join(dir, 'job.pgid'),
+        jobPgidIdentity: join(dir, 'job.pgid-identity'),
         jobPurpose: join(dir, 'purpose'),
         jobDeadline: join(dir, 'job.deadline'),
     };
@@ -56,6 +58,17 @@ export function readJobPgid(contextDir, jobId) {
         return undefined;
     }
 }
+/** Launch-time identity of the supervisor. Missing for jobs created before
+ * process-identity persistence, which are deliberately not safe to signal. */
+export function readJobPgidIdentity(contextDir, jobId) {
+    try {
+        const identity = readFileSync(bashJobPaths(contextDir, jobId).jobPgidIdentity, 'utf8').trim();
+        return identity === '' ? undefined : identity;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The optional human-readable job label. Jobs created before labels existed
  * have no file and deliberately project null. */
 export function readJobPurpose(contextDir, jobId) {
@@ -143,15 +156,31 @@ export function isBashJobProcessGroupAlive(pgid) {
         return err.code === 'EPERM';
     }
 }
-/** Stop one live background job using the same process-group and sentinel
- *  semantics as `crtr node bash kill`. The caller owns the user-facing
- *  notification; this primitive owns only the job control-plane mutation.
+/** Best-effort cancellation for a detached bash supervisor. It snapshots the
+ * observable descendant tree while the supervisor is still alive, signals its
+ * leaves before their parents, then uses the shared identity-guarded KILL
+ * escalation. A descendant that detached and reparented before this snapshot
+ * is outside this guarantee. */
+export async function cancelBashJobProcessTree(pgid, expectedIdentity) {
+    const snapshot = captureTeardownSnapshot(pgid, expectedIdentity);
+    if (snapshot.reused || snapshot.tree.length === 0)
+        return false;
+    const tree = [...snapshot.tree].reverse();
+    const signaled = isAnyPidAlive(tree);
+    killProcessTreePids(tree, 'SIGTERM', snapshot.identities);
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    killProcessTreePids(tree, 'SIGKILL', snapshot.identities);
+    return signaled;
+}
+/** Stop one live background job using the same best-effort tree cancellation
+ * semantics as inline abort and timeout. The caller owns the user-facing
+ * notification; this primitive owns only the job control-plane mutation.
  *
- *  Only a job in the live-background state the roster projects (job.bg
- *  present, job.exit absent) may be signaled. Job directories persist after
- *  the supervisor exits, so a retired, still-foreground, or already-stopped
- *  job would otherwise have its recorded pgid signaled long after the OS
- *  could have reused that id for an unrelated process group. */
+ * Only a job in the live-background state the roster projects (job.bg present,
+ * job.exit absent) may be signaled. Job directories persist after the
+ * supervisor exits, so a retired, still-foreground, or already-stopped job
+ * would otherwise have its recorded pgid signaled long after the OS could have
+ * reused that id for an unrelated process group. */
 export async function stopBackgroundBashJob(contextDir, jobId) {
     const paths = bashJobPaths(contextDir, jobId);
     if (!existsSync(paths.dir))
@@ -159,7 +188,8 @@ export async function stopBackgroundBashJob(contextDir, jobId) {
     if (!existsSync(paths.jobBg) || existsSync(paths.jobExit))
         return { kind: 'retired', logPath: paths.jobLog };
     const pgid = readJobPgid(contextDir, jobId);
-    if (pgid === undefined)
+    const pgidIdentity = readJobPgidIdentity(contextDir, jobId);
+    if (pgid === undefined || pgidIdentity === undefined)
         return { kind: 'not-stoppable', logPath: paths.jobLog };
     // Claim the stop by creating job.exit exclusively, before signaling. The
     // loser of two concurrent stops — and a stop that races the supervisor's own
@@ -179,18 +209,7 @@ export async function stopBackgroundBashJob(contextDir, jobId) {
             return { kind: 'retired', logPath: paths.jobLog };
         throw err;
     }
-    let signaled = true;
-    try {
-        process.kill(-pgid, 'SIGTERM');
-    }
-    catch {
-        signaled = false;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 400));
-    try {
-        process.kill(-pgid, 'SIGKILL');
-    }
-    catch { /* already gone */ }
+    const signaled = await cancelBashJobProcessTree(pgid, pgidIdentity);
     return { kind: 'stopped', signaled, pgid, logPath: paths.jobLog };
 }
 /** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB

package/dist/core/canvas/types.d.ts

@@ -76,11 +76,13 @@ export interface LaunchSpec {
     env: Record<string, string>;
 }
 /** The repository fingerprint a refusal was decided against. An examination
- *  that reads the same three values can skip the whole proof cascade: nothing
- *  about the refusal can have changed. */
+ *  that reads the same values can skip the whole proof cascade: nothing about
+ *  the refusal can have changed. */
 export interface ManagedWorktreeObservation {
     /** Tip of `refs/heads/<base_ref>`, or null when it no longer resolves. */
     base: string | null;
+    /** Tip of the base branch's upstream (or `origin/<base_ref>` fallback). */
+    upstream: string | null;
     /** Tip of `refs/heads/<branch>`, or null when the branch is gone. */
     branch: string | null;
     /** `absent`, or a hash of the checkout's HEAD plus `git status --porcelain`. */

package/dist/core/command.js

@@ -403,7 +403,7 @@ export async function parseArgv(params, tokens, options) {
                 continue;
             }
             const rawVal = inlineValue !== undefined ? inlineValue : tokens[++i];
-            if (rawVal === undefined || rawVal.startsWith('--')) {
+            if (rawVal === undefined || (inlineValue === undefined && rawVal.startsWith('--'))) {
                 const focusedNext = flagDef.focusedHelp !== undefined && (options?.leafPath?.length ?? 0) > 0
                     ? `Run \`crtr ${options.leafPath.join(' ')} --${flagName} -h\` and read the focused value contract before retrying.`
                     : undefined;

package/dist/core/fault-classifier.d.ts

@@ -1,5 +1,5 @@
 import type { ErrorClass, OperationId } from './events/types.js';
-export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'daemon→node' | 'crtr→pi';
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'broker↔crtrd' | 'daemon→node' | 'crtr→pi';
 export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
 export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
 export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';

package/dist/core/runtime/broker/event-projection.d.ts

@@ -11,8 +11,6 @@ type EventProjectionDeps = {
     notifyTurnAccepted: () => void;
     emitStartupMilestone: (event: string, model: string | null) => void;
     formatModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
-    refreshIntent: () => Promise<boolean>;
-    onRefreshIntentError: (error: unknown) => void;
 };
 /** Projects one live engine event stream to broker viewers and owns its relay timers. */
 export declare class EventProjection {
@@ -40,7 +38,6 @@ export declare class EventProjection {
     private flushPendingUpdate;
     private invalidatePendingBroadcasts;
     private broadcast;
-    private broadcastMessageEnd;
     private setPendingBroadcast;
 }
 export {};

package/dist/core/runtime/broker/event-projection.js

@@ -128,8 +128,8 @@ export class EventProjection {
             return;
         }
         this.flushPendingUpdate();
-        if (type === 'message_end') {
-            this.broadcastMessageEnd(event);
+        if (type === 'message_end' && generation.stagedRefreshAbort) {
+            this.broadcast({ ...event, message: withoutYieldAbort(event.message) });
             return;
         }
         this.broadcast(event);
@@ -183,19 +183,6 @@ export class EventProjection {
             this.deps.registry.broadcast(frame);
         }));
     }
-    broadcastMessageEnd(event) {
-        const preceding = this.pendingBroadcast ?? Promise.resolve();
-        const generation = this.broadcastGeneration;
-        this.setPendingBroadcast(preceding.then(async () => {
-            const refresh = await this.deps.refreshIntent();
-            if (this.broadcastGeneration !== generation)
-                return;
-            this.deps.registry.broadcast(refresh ? { ...event, message: withoutYieldAbort(event.message) } : event);
-        }).catch((error) => {
-            if (this.broadcastGeneration === generation)
-                this.deps.onRefreshIntentError(error);
-        }));
-    }
     setPendingBroadcast(work) {
         this.pendingBroadcast = work;
         void work.then(() => {

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;