@north-light/api 0.3.580 → 0.3.587

package/dist/core/auth-interaction.js

@@ -0,0 +1,94 @@
+// auth-interaction.ts — the one adapter from pi 0.82's `AuthInteraction` onto pi's
+// `LoginDialogComponent`.
+//
+// pi 0.82 collapsed the old six-callback login bag (`onAuth`/`onPrompt`/`onProgress`/
+// `onManualCodeInput`/`onDeviceCode`/`onSelect`) into a single `AuthInteraction`
+// (`signal` + `prompt()` + `notify()`). Both crouter login surfaces — `crtr sys setup`'s
+// Providers panel and the attach viewer's `/login` overlay — drive the SAME
+// `LoginDialogComponent`, so the mapping lives here once instead of twice.
+/** Race a pending prompt against EVERY live signal, rejecting with pi's own cancel
+ *  error. Both the interaction-wide signal (cancel of the whole login) and the
+ *  per-prompt signal must be honored: an OAuth flow may issue a prompt with no
+ *  signal of its own after the flow was already cancelled, and racing only the
+ *  per-prompt signal would strand that prompt forever. */
+async function withAbort(pending, signals) {
+    const live = signals.filter((s) => s !== undefined);
+    if (live.length === 0)
+        return pending;
+    const cleanups = [];
+    const aborted = new Promise((_resolve, reject) => {
+        for (const signal of live) {
+            const onAbort = () => reject(new Error('Login cancelled'));
+            signal.addEventListener('abort', onAbort, { once: true });
+            cleanups.push(() => signal.removeEventListener('abort', onAbort));
+        }
+    });
+    try {
+        return await Promise.race([pending, aborted]);
+    }
+    finally {
+        for (const cleanup of cleanups)
+            cleanup();
+    }
+}
+/**
+ * Build the `AuthInteraction` for one login flow on `dialog`.
+ *
+ * `select` prompts render as a numbered list through the dialog's normal text input:
+ * the dialog occupies crouter's single inline slot in both surfaces, so swapping in pi's
+ * separate selector component (what pi's own interactive mode does) has nowhere to go.
+ */
+export function dialogAuthInteraction(dialog, options = {}) {
+    const { openBrowser, onChange, isActive } = options;
+    const active = () => (isActive ? isActive() : !dialog.signal.aborted);
+    const changed = () => onChange?.();
+    return {
+        signal: dialog.signal,
+        notify(event) {
+            if (!active())
+                return;
+            switch (event.type) {
+                case 'auth_url':
+                    dialog.showAuth(event.url, event.instructions);
+                    openBrowser?.(event.url);
+                    break;
+                case 'device_code':
+                    dialog.showDeviceCode(event);
+                    dialog.showWaiting('Waiting for authentication...');
+                    openBrowser?.(event.verificationUri);
+                    break;
+                case 'info':
+                    dialog.showInfo(event.message, event.links);
+                    break;
+                case 'progress':
+                    dialog.showProgress(event.message);
+                    break;
+            }
+            changed();
+        },
+        async prompt(prompt) {
+            // Already cancelled: reject WITHOUT putting the dialog into a prompt state
+            // it would never leave.
+            if (dialog.signal.aborted || prompt.signal?.aborted === true)
+                throw new Error('Login cancelled');
+            let pending;
+            if (prompt.type === 'select') {
+                const menu = prompt.options.map((option, index) => `${index + 1}. ${option.label}`).join('\n');
+                pending = dialog.showPrompt(`${prompt.message}\n${menu}`, '1').then((answer) => {
+                    const id = prompt.options[Number.parseInt(answer, 10) - 1]?.id;
+                    if (id === undefined)
+                        throw new Error('Login cancelled');
+                    return id;
+                });
+            }
+            else if (prompt.type === 'manual_code') {
+                pending = dialog.showManualInput(prompt.message);
+            }
+            else {
+                pending = dialog.showPrompt(prompt.message, prompt.placeholder);
+            }
+            changed();
+            return withAbort(pending, [dialog.signal, prompt.signal]);
+        },
+    };
+}

package/dist/core/bash-guard.d.ts

@@ -0,0 +1,6 @@
+/** 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 declare function leadingSleepSeconds(command: string): number | null;
+/** The refusal this command earns before it runs, or null when it may run.
+ *  `cwd` is the directory the command will execute in. */
+export declare function bashCommandRefusal(command: string, cwd: string, home?: string): string | null;

package/dist/core/bash-guard.js

@@ -0,0 +1,527 @@
+// 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.
+//
+// Three refusals live here, for the same reason: each is something no correct
+// agent command ever does, and each is 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.
+//  - A recursive search rooted at the home directory, the canvas home, or a
+//    filesystem root reads hundreds of gigabytes. A node ran
+//    `grep -rl "…" ~/.crouter` across a 2.9 GB canvas.db and ~3,800 node
+//    directories; the disk contention starved crtrd until every open viewer
+//    crashed on request timeouts. Documents live in canvas.db, so that grep
+//    could never have found what it was looking for anyway.
+//
+// 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 command: crtr node bash run '<command>' starts it as a job and wakes you with its exit code\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',
+];
+/** Roots a recursive search may never start from, matched EXACTLY after
+ *  resolution: `~/.crouter` is refused, `~/.crouter/apps/terminal/nodes/<id>`
+ *  is ordinary work. Ancestors of the working directory are NOT included —
+ *  searching `~/Code` from inside a repo is wide but bounded. */
+function broadSearchReason(target, home) {
+    if (target === '/' || target === '/Users' || target === '/home' || target === '/System/Volumes/Data')
+        return 'a filesystem root';
+    if (target === home)
+        return 'your home directory';
+    if (target === `${home}/.crouter`)
+        return 'the canvas home (a multi-gigabyte canvas.db, every node directory and worktree)';
+    return null;
+}
+/** 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;
+    }
+}
+// The broad searches
+/** Flags that consume the next word as their value, per search tool. A value
+ *  word must not be read as the pattern or as a path. */
+const SEARCH_VALUE_FLAGS = {
+    grep: new Set(['-e', '-f', '-A', '-B', '-C', '-m', '-d', '-D', '--regexp', '--file', '--max-count', '--context', '--after-context', '--before-context', '--include', '--exclude', '--exclude-dir', '--directories', '--devices', '--label']),
+    rg: new Set(['-e', '-f', '-A', '-B', '-C', '-m', '-g', '-t', '-T', '-j', '-M', '-E', '-r', '--regexp', '--file', '--max-count', '--context', '--after-context', '--before-context', '--glob', '--iglob', '--type', '--type-not', '--threads', '--max-columns', '--encoding', '--replace', '--max-depth', '--max-filesize', '--sort', '--sortr', '--type-add', '--pre', '--pre-glob', '--ignore-file', '--color', '--colors', '--engine']),
+    ag: new Set(['-A', '-B', '-C', '-m', '-G', '-g', '--depth', '--ignore', '--file-search-regex', '--max-count', '--context', '--after', '--before']),
+};
+/** Words of a segment that are neither flags, flag values, nor redirections. */
+function searchOperands(tokens, valueFlags) {
+    const words = [];
+    let patternGiven = false;
+    let flagsEnded = false;
+    for (let i = 1; i < tokens.length; i += 1) {
+        const text = tokens[i].text;
+        const redirection = REDIRECTION.exec(text);
+        if (redirection !== null && !tokens[i].opaque) {
+            if (text === redirection[0])
+                i += 1;
+            continue;
+        }
+        if (!flagsEnded && text === '--') {
+            flagsEnded = true;
+            continue;
+        }
+        if (!flagsEnded && text.startsWith('-') && text !== '-') {
+            const bare = text.includes('=') ? text.slice(0, text.indexOf('=')) : text;
+            if (bare === '-e' || bare === '-f' || bare === '--regexp' || bare === '--file' || /^-[^-]*[ef]/.test(text))
+                patternGiven = true;
+            if (!text.includes('=') && valueFlags.has(text))
+                i += 1;
+            continue;
+        }
+        words.push(text);
+    }
+    return { words, patternGiven };
+}
+/** The roots this segment would search recursively. `implicitCwd` marks a
+ *  search with no path operand, which walks the directory it runs in. `[]`
+ *  with `implicitCwd: false` means the segment is not a recursive search. */
+function searchRoots(tokens) {
+    const none = { roots: [], implicitCwd: false };
+    const head = tokens[0];
+    if (head === undefined || head.opaque)
+        return none;
+    const name = head.text.slice(head.text.lastIndexOf('/') + 1);
+    const patternThenPaths = (valueFlags) => {
+        const { words, patternGiven } = searchOperands(tokens, valueFlags);
+        const paths = patternGiven ? words : words.slice(1);
+        return { roots: paths, implicitCwd: paths.length === 0 };
+    };
+    switch (name) {
+        case 'grep':
+        case 'egrep':
+        case 'fgrep':
+            return isRecursive(tokens) ? patternThenPaths(SEARCH_VALUE_FLAGS.grep) : none;
+        case 'rgrep':
+            return patternThenPaths(SEARCH_VALUE_FLAGS.grep);
+        // ripgrep, the silver searcher, and ack recurse by default. `rg --files`
+        // takes no pattern, only paths.
+        case 'rg':
+            if (tokens.some((t) => t.text === '--files')) {
+                const { words } = searchOperands(tokens, SEARCH_VALUE_FLAGS.rg);
+                return { roots: words, implicitCwd: words.length === 0 };
+            }
+            return patternThenPaths(SEARCH_VALUE_FLAGS.rg);
+        case 'ag':
+        case 'ack':
+            return patternThenPaths(SEARCH_VALUE_FLAGS.ag);
+        // `find` with a depth limit is a bounded listing, not a sweep.
+        case 'find': {
+            if (tokens.some((t) => t.text === '-maxdepth'))
+                return none;
+            const paths = findPaths(tokens);
+            return { roots: paths, implicitCwd: paths.length === 0 };
+        }
+        // `du` walks the whole tree even with `-d 0`.
+        case 'du': {
+            const paths = operands(tokens);
+            return { roots: paths, implicitCwd: paths.length === 0 };
+        }
+        default:
+            return none;
+    }
+}
+function broadSearchRefusalMessage(segment, target, reason) {
+    return (`Refused: \`${segment}\` searches ${target} recursively, which is ${reason}.\n` +
+        `A sweep that wide reads hundreds of gigabytes, starves crtrd of disk, and has crashed every open viewer on this machine before.\n` +
+        `Search where the answer can actually be:\n` +
+        `  - a document (knowledge, preference, spec, report): crtr canvas search "<text>" or crtr canvas read <name> — documents live in canvas.db, never as files, so grep cannot find them.\n` +
+        `  - code: the one repo or directory you are working in, e.g. rg -l '<text>' <repo>.\n` +
+        `  - a node's files: its own context dir, e.g. ~/.crouter/apps/<app>/nodes/<id>/context.\n` +
+        `If you believe a whole-tree search is genuinely required, ask the user — do not work around this refusal.`);
+}
+/** 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);
+                }
+            }
+            const search = searchRoots(tokens);
+            const searchBases = bases.length === 0 ? [null] : bases;
+            // A search with no path walks the directory the shell is in now: the
+            // innermost `cd`, not every candidate the destructive check keeps.
+            const here = bases[bases.length - 1];
+            if (search.implicitCwd && here !== undefined) {
+                const reason = broadSearchReason(here, home);
+                if (reason !== null)
+                    return broadSearchRefusalMessage(segment.text, here, reason);
+            }
+            for (const root of search.roots) {
+                for (const base of searchBases) {
+                    const resolved = resolveTarget(root, local, base);
+                    if (resolved === null)
+                        continue;
+                    const reason = broadSearchReason(resolved, home);
+                    if (reason !== null)
+                        return broadSearchRefusalMessage(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-job-supervisor.d.ts

@@ -0,0 +1,5 @@
+export declare const MAX_BACKGROUND_BASH_LOG_BYTES: number;
+export declare const BACKGROUND_BASH_LOG_TRUNCATION_MARKER = "\n[background bash job output truncated at 10 MiB; remaining output discarded]\n";
+/** File-backed command supervisor. Beside the job it runs the activity sampler. It writes the exit code to job.exit and, for a foreground
+ * command, claims job.done; the daemon reads job.exit of a backgrounded job and publishes `exited`. */
+export declare const BASH_JOB_SUPERVISOR_SCRIPT: string;