@north-light/crouter 0.3.301 → 0.3.303

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -22,6 +22,7 @@ import assert from 'node:assert/strict';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { appendInbox, readCursor, readInboxSince } from '../../feed/inbox.js';
+import { acquireCronRunLease, armCron, setCronState } from '../../canvas/crons.js';
 import { registerWarmSpare, subscribe, subscriptionsOf, updateNode } from '../../canvas/index.js';
 import { isPidAlive } from '../../canvas/pid.js';
 import { reviveNode } from '../../runtime/revive.js';
@@ -45,6 +46,47 @@ async function awaitReleased(nodeId) {
         return node?.status === 'idle' && node.intent === 'idle-release' && typeof node.pi_pid === 'number' && !isPidAlive(node.pi_pid);
     }, { label: `idle-release broker exit for ${nodeId}` });
 }
+async function assertCronWakeReleases(nodeId, running) {
+    const cronId = `${nodeId}-cron`;
+    const target = h.fabricateBrokerNode({ id: nodeId, parent: root, status: 'active' });
+    const now = new Date();
+    armCron({
+        cron_id: cronId,
+        name: cronId,
+        created_by: null,
+        command: 'printf wake',
+        fire_at: new Date(now.getTime() + 3_600_000).toISOString(),
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: nodeId,
+        cancel_on_wake: false,
+        cwd: h.home,
+        env_json: null,
+        profile: null,
+        scope: 'profile',
+        run_timeout_s: 30,
+        overlap: 'skip',
+        on_output: 'always',
+        sink: JSON.stringify({ node: nodeId }),
+        tier: 'normal',
+    });
+    if (running) {
+        assert.equal(acquireCronRunLease(cronId, 'seam-fixture', process.pid, now.toISOString(), false), true);
+        setCronState(cronId, 'paused');
+    }
+    updateNode(target, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
+    await reviveNode(target, { resume: true, capacity: 'freeze' });
+    await h.awaitBoot(target);
+    await h.stop(target);
+    await awaitReleased(target);
+    await h.awaitFleetExit(target);
+    assert.equal(h.node(target)?.status, 'idle', `${running ? 'running' : 'scheduled'} cron did not trigger a stop-guard reprompt`);
+}
+test('an anchored node-sink cron releases a terminal broker when scheduled or in flight', { timeout: 60_000 }, async () => {
+    await assertCronWakeReleases('scheduled-cron-wake', false);
+    await assertCronWakeReleases('running-cron-wake', true);
+});
 test('idle-release settles its real watcher before exit; daemon revives exactly once for a later row', { timeout: 30_000 }, async () => {
     // Reproduce the observed #353/#362 edge: real pi reported
     // ctx.hasPendingMessages() === true at the sole agent_settled even though the

package/dist/core/__tests__/stop-guard.test.js

@@ -9,7 +9,9 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, deliverAndSettleMessageWait, getNode, subscribe, setMessageWait, setStatus } from '../canvas/canvas.js';
+import { armCron, cancelCron, setCronState } from '../canvas/crons.js';
 import { closeDb, openDb } from '../canvas/db.js';
+import { hasLiveObligation } from '../../daemon/reconcilers/live-obligation.js';
 import { contextDir } from '../canvas/paths.js';
 import { bashJobPaths } from '../bash-jobs.js';
 import { evaluateStop } from '../runtime/stop-guard.js';
@@ -29,6 +31,29 @@ function node(id, over = {}) {
     };
 }
 const noSignals = { pushedFinal: false, requestedHumanReply: false };
+function arm(overrides) {
+    armCron({
+        name: overrides.cron_id,
+        created_by: null,
+        command: 'printf cron',
+        fire_at: new Date(Date.now() + 3_600_000).toISOString(),
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: null,
+        cancel_on_wake: false,
+        cwd: home,
+        env_json: null,
+        profile: null,
+        scope: 'profile',
+        run_timeout_s: 30,
+        overlap: 'skip',
+        on_output: 'always',
+        sink: '{}',
+        tier: 'normal',
+        ...overrides,
+    });
+}
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-stopguard-'));
     process.env['CRTR_HOME'] = home;
@@ -82,6 +107,45 @@ test('a TERMINAL node awaiting a background bash job may dorm until its completi
     assert.equal(completed.action, 'reprompt');
     assert.equal(completed.reason, 'stalled');
 });
+test('a pending node-sink cron wake releases terminal nodes and holds unattended nodes', () => {
+    createNode(node('target'));
+    const assertsWake = (id) => {
+        assert.deepEqual(evaluateStop('target', noSignals), { action: 'allow', reason: 'scheduled' }, id);
+        assert.equal(hasLiveObligation('target'), true, `${id} holds the unattended node`);
+    };
+    const assertsNoWake = (id) => {
+        assert.equal(evaluateStop('target', noSignals).action, 'reprompt', id);
+        assert.equal(hasLiveObligation('target'), false, `${id} does not hold the unattended node`);
+    };
+    arm({ cron_id: 'scheduled', anchor_node: 'target', sink: JSON.stringify({ node: 'target' }) });
+    assertsWake('an anchored scheduled always sink');
+    cancelCron('scheduled');
+    arm({ cron_id: 'running', anchor_node: 'target', sink: JSON.stringify({ node: 'target' }) });
+    openDb().prepare("UPDATE crons SET run_state = 'running' WHERE cron_id = ?").run('running');
+    setCronState('running', 'paused');
+    assertsWake('a paused in-flight sink');
+    cancelCron('running');
+    arm({ cron_id: 'unanchored-change', on_output: 'on-change', sink: JSON.stringify({ node: 'target' }) });
+    assertsWake('an unanchored on-change sink');
+    cancelCron('unanchored-change');
+    arm({ cron_id: 'other-target', sink: JSON.stringify({ node: 'other' }) });
+    assertsNoWake('a sink for another node');
+    cancelCron('other-target');
+    arm({ cron_id: 'silent', on_output: 'silent', sink: JSON.stringify({ node: 'target' }) });
+    assertsNoWake('a silent cron');
+    cancelCron('silent');
+    arm({ cron_id: 'on-failure', on_output: 'on-failure', sink: JSON.stringify({ node: 'target' }) });
+    assertsNoWake('an on-failure cron');
+    cancelCron('on-failure');
+    arm({ cron_id: 'expired', expires_at: new Date(Date.now() - 1_000).toISOString(), sink: JSON.stringify({ node: 'target' }) });
+    assertsNoWake('an expired idle cron');
+    cancelCron('expired');
+    arm({ cron_id: 'canceled', sink: JSON.stringify({ node: 'target' }) });
+    cancelCron('canceled');
+    assertsNoWake('a canceled cron');
+    arm({ cron_id: 'deadline', anchor_node: 'target', cancel_on_wake: true, on_output: 'on-failure' });
+    assertsWake('an active deadline');
+});
 test('only an explicit live controller wait permits dormancy; ancestry alone does not', () => {
     createNode(node('parent', { lifecycle: 'terminal', status: 'active' }));
     createNode(node('child', { parent: 'parent' }));

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,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/canvas/crons.d.ts

@@ -3,6 +3,16 @@ export type CronOverlap = 'skip' | 'queue' | 'replace';
 export type CronOnOutput = 'silent' | 'on-failure' | 'always' | 'on-change';
 export type CronState = 'active' | 'paused';
 export type CronRunState = 'idle' | 'running';
+/** The decoded delivery target of a stored cron sink. */
+export type ParsedCronSink = {
+    kind: 'node';
+    node: string;
+} | {
+    kind: 'spawn';
+    spawn: string;
+} | {
+    kind: 'human';
+} | null;
 /** A hydrated `crons` row. */
 export interface Cron {
     cron_id: string;
@@ -96,6 +106,10 @@ export interface CronRunRecord {
 /** Ring bound for `cron_runs`: recordCronRun prunes each cron's history to
  *  its most recent this-many rows. */
 export declare const CRON_RUN_RING = 20;
+/** Decode the stored cron sink JSON. A malformed or unrecognised value has no sink. */
+export declare function parseCronSink(sinkJson: string): ParsedCronSink;
+/** Render a stored cron sink as the arm-time CLI spec, or null when it has no destination. */
+export declare function cronSinkDisplay(sinkJson: string): string | null;
 /** The ONLY sanctioned way to signal a cron run's process group from a stored
  *  row. Re-captures the CURRENT identity of `run_pid` and signals only when it
  *  MATCHES the fingerprint recorded at lease acquisition. Returns whether the
@@ -180,10 +194,12 @@ export declare function setCronState(cron_id: string, state: CronState): boolean
  *  previous run's stdout. Written after EVERY settled run of an on-change
  *  cron, delivered or not. */
 export declare function setCronLastOutputHash(cron_id: string, hash: string): void;
-/** True when this node has a pending cancel-on-wake cron. The stop guard uses
- *  this focused deadline check to distinguish legitimate clock dormancy from a
- *  terminal node that stopped without finishing. */
-export declare function hasPendingCancelOnWakeCron(anchor_node: string): boolean;
+/** True when a cron can still wake this node. An active deadline is a wake
+ * source by its anchor; output delivery is a wake source by its decoded node
+ * sink. Scheduled rows must remain active and unexpired, while a leased run
+ * remains eligible through settlement even if it has since been paused or
+ * expired. */
+export declare function hasPendingCronWake(nodeId: string): boolean;
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
  *  A real wake consumes the wait at its delivery boundary or, as a dormant
  *  fallback, in reviveNode; recovery replacement is not a wake. Terminal

package/dist/core/canvas/crons.js

@@ -60,6 +60,36 @@ function cronFrom(r) {
         updated: r['updated'],
     };
 }
+/** Decode the stored cron sink JSON. A malformed or unrecognised value has no sink. */
+export function parseCronSink(sinkJson) {
+    try {
+        const sink = JSON.parse(sinkJson);
+        if (typeof sink['node'] === 'string')
+            return { kind: 'node', node: sink['node'] };
+        if (typeof sink['spawn'] === 'string')
+            return { kind: 'spawn', spawn: sink['spawn'] };
+        if (sink['human'] === true)
+            return { kind: 'human' };
+    }
+    catch {
+        // A malformed stored value cannot deliver but remains listable and runnable.
+    }
+    return null;
+}
+/** Render a stored cron sink as the arm-time CLI spec, or null when it has no destination. */
+export function cronSinkDisplay(sinkJson) {
+    const sink = parseCronSink(sinkJson);
+    if (sink === null)
+        return null;
+    switch (sink.kind) {
+        case 'node':
+            return `node:${sink.node}`;
+        case 'spawn':
+            return `spawn:${sink.spawn}`;
+        case 'human':
+            return 'human';
+    }
+}
 // Signal safety
 /** The ONLY sanctioned way to signal a cron run's process group from a stored
  *  row. Re-captures the CURRENT identity of `run_pid` and signals only when it
@@ -261,13 +291,30 @@ export function setCronLastOutputHash(cron_id, hash) {
         .prepare('UPDATE crons SET last_output_hash = ?, updated = ? WHERE cron_id = ?')
         .run(hash, new Date().toISOString(), cron_id);
 }
-/** True when this node has a pending cancel-on-wake cron. The stop guard uses
- *  this focused deadline check to distinguish legitimate clock dormancy from a
- *  terminal node that stopped without finishing. */
-export function hasPendingCancelOnWakeCron(anchor_node) {
-    return (openDb()
-        .prepare("SELECT 1 FROM crons WHERE anchor_node = ? AND cancel_on_wake = 1 AND state = 'active' LIMIT 1")
-        .get(anchor_node) !== undefined);
+/** True when a cron can still wake this node. An active deadline is a wake
+ * source by its anchor; output delivery is a wake source by its decoded node
+ * sink. Scheduled rows must remain active and unexpired, while a leased run
+ * remains eligible through settlement even if it has since been paused or
+ * expired. */
+export function hasPendingCronWake(nodeId) {
+    const rows = openDb().prepare(`SELECT anchor_node, cancel_on_wake, sink
+     FROM crons
+     WHERE (anchor_node = ? AND cancel_on_wake = 1 AND state = 'active')
+        OR (
+          on_output IN ('always', 'on-change')
+          AND (
+            run_state = 'running'
+            OR (run_state = 'idle' AND state = 'active' AND (expires_at IS NULL OR expires_at > ?))
+          )
+        )`).all(nodeId, new Date().toISOString());
+    for (const row of rows) {
+        if (row['anchor_node'] === nodeId && Number(row['cancel_on_wake']) !== 0)
+            return true;
+        const sink = parseCronSink(row['sink']);
+        if (sink?.kind === 'node' && sink.node === nodeId)
+            return true;
+    }
+    return false;
 }
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
  *  A real wake consumes the wait at its delivery boundary or, as a dormant