@north-light/crouter 0.3.302 → 0.3.303

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,190 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/bash-guard.test.ts
+//
+// BUG REGRESSION: a node ran
+//   cd star-theory-2 && HOME="$(mktemp -d …)" godot …; rm -rf "$HOME" …
+// The `HOME=` prefix applied only to `godot`, so the trailing `rm -rf "$HOME"`
+// expanded to the real home directory and deleted for ~108s before another node
+// killed it. The guard refuses that command text before bash ever sees it.
+import assert from 'node:assert/strict';
+import { homedir, userInfo } from 'node:os';
+import { test } from 'node:test';
+import { bashCommandRefusal } from '../bash-guard.js';
+const HOME = homedir();
+const CWD = `${HOME}/Code/cli/crouter`;
+function refusal(command, cwd = CWD) {
+    return bashCommandRefusal(command, cwd);
+}
+function assertRefused(command, expectedTarget, cwd = CWD) {
+    const message = refusal(command, cwd);
+    assert.notEqual(message, null, `expected refusal for: ${command}`);
+    assert.ok(message.includes(expectedTarget), `refusal for ${command} should name ${expectedTarget}, got: ${message}`);
+}
+function assertAllowed(command, cwd = CWD) {
+    assert.equal(refusal(command, cwd), null, `expected to allow: ${command}`);
+}
+// The incident
+test('the incident command is refused and names the segment and resolved target', () => {
+    const command = 'cd star-theory-2 && HOME="$(mktemp -d /tmp/st2-legend-proof.XXXXXX)" godot --headless --path . ' +
+        '--script "$CRTR_CONTEXT_DIR/legend_proof.gd"; status=$?; rm -rf "$HOME" 2>/dev/null || true; exit $status';
+    const message = refusal(command);
+    assert.notEqual(message, null);
+    assert.ok(message.includes('rm -rf "$HOME"'), `should quote the offending segment: ${message}`);
+    assert.ok(message.includes(HOME), `should name the resolved target: ${message}`);
+});
+// Home, however it is spelled
+test('every textual spelling of the home directory is refused', () => {
+    for (const target of ['~', '~/', '"$HOME"', '$HOME', '${HOME}', '"${HOME}/"', HOME, `${HOME}/`, '~/*', '"$HOME"/*']) {
+        assertRefused(`rm -rf ${target}`, HOME);
+    }
+});
+// System roots
+test('system roots are refused', () => {
+    for (const target of ['/', '/Users', '/home', '/private', '/var', '/etc', '/tmp', '/usr', '/opt', '/System', '/Library', '/Applications', '/private/var']) {
+        assertRefused(`rm -rf ${target}`, target);
+    }
+});
+test('the canvas home is refused', () => {
+    assertRefused('rm -rf ~/.crouter', `${HOME}/.crouter`);
+});
+// Ancestors of the working directory
+test('a strict ancestor of the working directory is refused', () => {
+    assertRefused(`rm -rf ${HOME}/Code/cli`, `${HOME}/Code/cli`);
+    assertRefused('rm -rf ..', `${HOME}/Code/cli`);
+});
+test('a relative target is read against every directory the line could be in', () => {
+    assertRefused('cd packages && rm -rf ../..', `${HOME}/Code/cli`);
+    // The guard cannot know a `cd` succeeded: after a failed one bash stays put,
+    // so `..` really is the ancestor and the refusal must still fire.
+    assertRefused('cd definitely-does-not-exist; rm -rf ..', `${HOME}/Code/cli`);
+    // Nowhere knowable to resolve from, so nothing relative is refused.
+    assertAllowed('cd "$SOMEWHERE" && rm -rf ..');
+    assertRefused('cd "$SOMEWHERE" && rm -rf ~', HOME);
+});
+test('the working directory itself still removes — a node may delete its own merged worktree', () => {
+    const worktree = `${HOME}/.crouter/canvas/worktrees/node-1`;
+    assertAllowed('rm -rf .', worktree);
+    assertAllowed(`rm -rf ${worktree}`, worktree);
+});
+// Recursive flag spellings
+test('every recursive flag spelling is refused', () => {
+    for (const flags of ['-rf', '-fr', '-r', '-R', '-Rf', '-rvf', '--recursive -f', '-f --recursive', '-f -r', '-r --', '-rf --']) {
+        assertRefused(`rm ${flags} ~`, HOME);
+    }
+});
+test('a non-recursive rm is not this guard\u2019s business', () => {
+    assertAllowed('rm ~');
+    assertAllowed('rm -f ~/.zshrc');
+});
+// Prefixes that hide the verb
+test('a command prefix does not hide the rm', () => {
+    for (const prefix of ['sudo', 'sudo -E', 'command', 'nice -n 10', 'nohup', 'time', 'env', 'doas']) {
+        assertRefused(`${prefix} rm -rf ~`, HOME);
+    }
+});
+test('a leading VAR=value assignment does not hide the rm', () => {
+    assertRefused('FOO=bar rm -rf ~', HOME);
+});
+// The distinction the incident turned on: an `export` changes $HOME for the
+// rest of the line, a `HOME=… cmd` PREFIX changes it for that one command.
+test('a reassigned HOME is honoured for the rest of the line', () => {
+    assertAllowed('export HOME=/tmp/st2home_5e && rm -rf "$HOME"');
+    assertAllowed('export HOME=/tmp/st2home_5e\nfind "$HOME" -name settings.cfg -delete');
+    assertAllowed('cd star-theory-2 && export HOME=/tmp/x && rm -rf "$HOME" && mkdir -p "$HOME"');
+    assertAllowed('HOME=/tmp/x\nrm -rf ~');
+    // Reassigned to something the guard cannot read: unknowable, so allowed.
+    assertAllowed('export HOME="$(mktemp -d)"; rm -rf "$HOME"');
+});
+test('a HOME= prefix on one command does not carry to the next', () => {
+    assertRefused('HOME=/tmp/x godot --headless; rm -rf "$HOME"', HOME);
+});
+test('a HOME= prefix does apply to its own command', () => {
+    assertAllowed('HOME=/tmp/x rm -rf "$HOME"');
+});
+test('a backgrounded assignment runs in a subshell and does not carry', () => {
+    assertRefused('HOME=/tmp/x & rm -rf "$HOME"', HOME);
+    assertRefused('export HOME=/tmp/x & rm -rf "$HOME"', HOME);
+    assertAllowed('export HOME=/tmp/x && rm -rf "$HOME"');
+});
+test('an assignment to a builtin that exports it persists', () => {
+    assertAllowed('HOME=/tmp/x export HOME; rm -rf "$HOME"');
+});
+test('$USER and $LOGNAME expand — a per-user path spelled that way still resolves', () => {
+    // Anchored on the working directory rather than the home path, whose per-user
+    // segment is not the username on every platform this runs on.
+    const user = userInfo().username;
+    const parent = `/srv/people/${user}`;
+    assertRefused('rm -rf /srv/people/$USER', parent, `${parent}/project`);
+    assertRefused('rm -rf "/srv/people/${LOGNAME}"', parent, `${parent}/project`);
+});
+test('a redirection is not a target', () => {
+    assertAllowed('rm -rf ./dist 2>/dev/null');
+    assertAllowed('rm -rf ./dist > /dev/null 2>&1');
+    assertRefused('rm -rf ~ 2>/dev/null', HOME);
+});
+// Segment separators
+test('the rm is found in any shell segment', () => {
+    for (const command of ['ls && rm -rf ~', 'ls; rm -rf ~', 'ls || rm -rf ~', 'ls | rm -rf ~', 'ls &\nrm -rf ~']) {
+        assertRefused(command, HOME);
+    }
+});
+// Must still run
+test('ordinary removals still run', () => {
+    assertAllowed('rm -rf "$d"');
+    assertAllowed('rm -rf node_modules');
+    assertAllowed('rm -rf /tmp/foo.XXXX');
+    assertAllowed('rm -rf "$CRTR_CONTEXT_DIR/jobs/x"');
+    assertAllowed('rm -rf ~/Code/cli/crouter/dist');
+    assertAllowed('rm -rf ./dist .dist-build-*');
+    assertAllowed('rm -rf "$HOME/.cache/crouter/termrender"');
+    assertAllowed('rm -rf ~/.crouter/canvas/scratch/old');
+    assertAllowed('rm -rf /tmp/crtr-build.1234');
+});
+test('a quoted mention of a dangerous command is data, not a command', () => {
+    assertAllowed('echo "rm -rf ~"');
+    assertAllowed("git commit -m 'never rm -rf $HOME'");
+});
+test('a heredoc body is data, not a command', () => {
+    assertAllowed('cat > note.md <<\'EOF\'\nrm -rf ~\nEOF');
+});
+// Other operations that can destroy a home or system tree
+test('moving a protected path away is refused', () => {
+    assertRefused('mv ~ /tmp/old-home', HOME);
+    assertRefused('mv /etc /tmp/etc', '/etc');
+});
+test('a recursive permission or ownership change on a protected path is refused', () => {
+    assertRefused('chmod -R 777 /', '/');
+    assertRefused('sudo chown -R root ~', HOME);
+    assertRefused('chgrp -R staff /usr', '/usr');
+    assertAllowed('chmod -R 755 ./scripts');
+    assertAllowed('chmod 600 ~/.ssh/config');
+});
+test('a find that deletes or executes over a protected path is refused', () => {
+    assertRefused('find ~ -name "*.log" -delete', HOME);
+    assertRefused('find / -name core -exec rm -f {} \\;', '/');
+    assertAllowed('find ~ -name "*.log"');
+    assertAllowed('find . -name "*.log" -delete');
+});
+test('find’s leading global options do not hide its start path', () => {
+    assertRefused('find -H ~ -delete', HOME);
+    assertRefused('find -- ~ -delete', HOME);
+    assertRefused('find -L -x /etc -delete', '/etc');
+    assertRefused('find -f ~ -delete', HOME);
+    assertAllowed('find -H ./logs -delete');
+});
+test('writing a raw disk or reformatting one is refused', () => {
+    assertRefused('dd if=/dev/zero of=/dev/disk0 bs=1m', '/dev/disk0');
+    assertRefused('dd if=/dev/zero of=/dev/rdisk3 bs=1m', '/dev/rdisk3');
+    assertRefused('sudo mkfs.ext4 /dev/sda1', 'mkfs.ext4');
+    assertRefused('diskutil eraseDisk JHFS+ Blank /dev/disk2', 'diskutil eraseDisk');
+    assertAllowed('dd if=/dev/zero of=./blob bs=1m count=1');
+    // A character device is ordinary output, not a disk.
+    assertAllowed('dd if=/dev/zero of=/dev/null bs=1m count=1');
+    assertAllowed('dd if=./blob of=/dev/stdout');
+});
+// The long-sleep refusal moved here with the rest of the bash refusals.
+test('a long leading sleep is still refused, a short one still runs', () => {
+    assert.notEqual(refusal('sleep 300'), null);
+    assert.notEqual(refusal('sleep 5m'), null);
+    assert.equal(refusal('sleep 5'), null);
+    assert.equal(refusal('sleep "$n"'), null);
+});

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -148,6 +148,7 @@ declare class FakeSession {
     /** Compiled-seam graceful-teardown vehicle: a real active turn that only settles
      * after abort(), so the broker's bounded abort wait is observable. */
     private heldTurn;
+    private retryAbort;
     private readonly listeners;
     /** Idle watcher sends received while bindExtensions is still running. They
      * start naturally as soon as broker.ts subscribes, without a retry loop that
@@ -195,6 +196,9 @@ declare class FakeSession {
     };
     get isStreaming(): boolean;
     getSessionStats(): Record<string, unknown>;
+    getContextUsage(): {
+        tokens: number;
+    } | undefined;
     private syncTreeSnapshot;
     /** Reads the crashed process's last `fake-pi.tree.json` (if any) and rebuilds
      *  this process's tree from it. Best-effort: a first boot (no snapshot yet)
@@ -238,6 +242,7 @@ declare class FakeSession {
         deliverAs?: string;
     }): Promise<void>;
     abort(): Promise<void>;
+    abortRetry(): void;
     /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
      *  contract: the session file is unchanged, the live history is truncated,
      *  and the navigated-to user message's text comes back as `editorText`. The
@@ -274,6 +279,7 @@ interface FakeModel {
     provider: string;
     id: string;
     api?: string;
+    contextWindow?: number;
 }
 /** The fake `ModelRuntime` — the runtime-method subset broker.ts's
  *  `registryOf` facade (and its model-less construction mask) actually reads. */

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -298,6 +298,7 @@ class FakeSession {
     /** Compiled-seam graceful-teardown vehicle: a real active turn that only settles
      * after abort(), so the broker's bounded abort wait is observable. */
     heldTurn;
+    retryAbort;
     // The broker's fan-out subscribers (broker.ts `session.subscribe(...)`) and the
     // accumulating message history the catch-up snapshot serializes (G3).
     listeners = new Set();
@@ -458,6 +459,15 @@ class FakeSession {
     getSessionStats() {
         return { messages: 0, tokens: 0 };
     }
+    getContextUsage() {
+        try {
+            const tokens = Number(readFileSync(join(this.dir, 'fake-pi.context-tokens'), 'utf8'));
+            return Number.isFinite(tokens) ? { tokens } : undefined;
+        }
+        catch {
+            return { tokens: 1000 };
+        }
+    }
     syncTreeSnapshot() {
         try {
             writeFileSync(join(this.dir, 'fake-pi.tree.json'), JSON.stringify({
@@ -571,6 +581,9 @@ class FakeSession {
         this.bashAbort?.abort();
         return this.bashRun ?? Promise.resolve();
     }
+    abortRetry() {
+        this.retryAbort?.();
+    }
     /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
      *  contract: the session file is unchanged, the live history is truncated,
      *  and the navigated-to user message's text comes back as `editorText`. The
@@ -938,7 +951,7 @@ class FakeSession {
                 getBranch: () => this.tree.getBranch(),
                 getEntries: () => this.tree.getEntries(),
             },
-            getContextUsage: () => ({ tokens: 1000 }),
+            getContextUsage: () => this.getContextUsage(),
             // Wired to the broker's shutdownHandler: the stophook calls ctx.shutdown()
             // in exactly its done / idle-release / refresh branches → disposeAndExit.
             shutdown: () => {
@@ -1068,8 +1081,9 @@ class FakeSession {
                 this.emit({ type: 'agent_settled' });
                 break;
             case 'stop': {
-                // Match pi's lifecycle: the stophook sees agent_end while the run is
-                // active, then the subscriber receives agent_settled after it clears.
+                // Match pi's lifecycle: message_end reaches broker fallback policy
+                // before the stophook sees agent_end while the run is active; the
+                // subscriber receives agent_settled after it clears.
                 this.streaming = true;
                 const stopMessages = [
                     {
@@ -1097,6 +1111,7 @@ class FakeSession {
                         content: [{ type: 'text', text: cmd.text ?? '' }],
                     },
                 ];
+                this.emit({ type: 'message_end', message: stopMessages[0] });
                 await this.fire('agent_end', { messages: stopMessages }, ctx);
                 // Every attempt reaches the broker subscriber while streaming; only the
                 // following settled event may publish its fault or arm a retry timer.
@@ -1174,16 +1189,29 @@ class FakeSession {
                 writeFileSync(join(this.dir, 'fake-pi.overflow.json'), JSON.stringify({ outcome: cmd.outcome ?? 'uncompacted' }));
                 break;
             }
-            case 'auto_retry':
-                // Drive the exact broker subscription event that pi emits before its
-                // retry timer, so provider fallback policy runs in the live broker.
+            case 'auto_retry': {
+                // Pi emits agent_end for the failed attempt, then auto_retry_start, and
+                // only then creates the AbortController for its delay. The capacity
+                // fallback must defer abortRetry one microtask to cancel this retry.
+                const retryMessages = [{
+                        role: 'assistant', stopReason: 'error', errorMessage: cmd.errorMessage ?? 'rate limit exceeded', content: [],
+                    }];
+                this.streaming = true;
+                await this.fire('agent_end', { messages: retryMessages }, ctx);
+                this.emit({ type: 'agent_end', messages: retryMessages, willRetry: true });
                 this.emit({ type: 'auto_retry_start', errorMessage: cmd.errorMessage ?? 'rate limit exceeded' });
-                // The broker begins its fallback async; the next check phase follows
-                // its resolved registry/setModel microtasks and is a deterministic
-                // receipt for a rejected target (which intentionally never changes model).
+                let aborted = false;
+                this.retryAbort = () => { aborted = true; };
                 await new Promise((resolve) => setImmediate(resolve));
-                writeFileSync(join(this.dir, 'fake-pi.auto-retry.json'), JSON.stringify({ at: Date.now() }));
+                this.retryAbort = undefined;
+                if (aborted)
+                    this.emit({ type: 'auto_retry_end', success: false, finalError: 'Retry cancelled' });
+                this.streaming = false;
+                await this.fire('agent_settled', { type: 'agent_settled' }, ctx);
+                this.emit({ type: 'agent_settled' });
+                writeFileSync(join(this.dir, 'fake-pi.auto-retry.json'), JSON.stringify({ at: Date.now(), aborted }));
                 break;
+            }
             case 'display':
                 // Paint through the broker's REAL uiContext exactly as an extension does.
                 // These are LEVELS with no pi getter, so the broker is their only holder
@@ -1221,6 +1249,18 @@ class FakeSession {
         }
     }
 }
+function fakeModel(provider, id) {
+    try {
+        const capacities = JSON.parse(readFileSync(join(nodeDirFromEnv(), 'fake-pi.model-capacities.json'), 'utf8'));
+        const contextWindow = capacities[`${provider}/${id}`];
+        return typeof contextWindow === 'number' && Number.isFinite(contextWindow)
+            ? { provider, id, contextWindow }
+            : { provider, id };
+    }
+    catch {
+        return { provider, id };
+    }
+}
 /** The real pi SDK's model-less sentinel (Agent.DEFAULT_MODEL). The fake mirrors
  *  it so `session.model` is NEVER literally `undefined` after a model-less boot,
  *  matching prod — see the FakeSession constructor. */
@@ -1292,7 +1332,7 @@ export async function createAgentSessionServices(options) {
             // A minimal model stub for any spec — the set_model regression test drives
             // the broker's findModelSpec → session.setModel path through it. Nothing is
             // findable during a zero-auth window.
-            getModel: (provider, id) => (zeroAuth() ? undefined : { provider, id }),
+            getModel: (provider, id) => (zeroAuth() ? undefined : fakeModel(provider, id)),
             // Always-authenticated single fake model — the M-9 no-boot-model branch
             // (broker.ts) picks `available[0]` and must never see an empty list here —
             // EXCEPT during a zero-auth window, when nothing is available/registered.

package/dist/core/__tests__/seam/broker-provider-retry.test.js

@@ -43,6 +43,33 @@ function seedPool(provider, cooling) {
             rateLimitedUntil: cooling ? Date.now() + 60_000 : 0, lastAttemptAt: 0, lastRateLimitedAt: 0,
         }]));
 }
+function modelRoute(spec) {
+    return { ultra: spec, strong: spec, medium: spec, light: spec };
+}
+function seedCapacityFallbackRoutes() {
+    const userConfigDir = join(h.agentHome, '.crouter');
+    const userConfigPath = join(userConfigDir, 'config.json');
+    mkdirSync(userConfigDir, { recursive: true });
+    writeFileSync(userConfigPath, JSON.stringify({
+        kinds: { 'test/capacity-fallback': { whenToUse: 'Capacity fallback regression.', model: 'anthropic/medium' } },
+        modelRoutes: {
+            primary: { family: 'anthropic', credentialSource: 'user', providerId: 'fake-primary', models: modelRoute('fake-primary/primary') },
+            fallback: { family: 'anthropic', credentialSource: 'northlight', providerId: 'fake-small', models: modelRoute('fake-small/small') },
+            largerFallback: { family: 'anthropic', credentialSource: 'third', providerId: 'fake-large', models: modelRoute('fake-large/large') },
+        },
+        modelRouting: { credentialSourceOrder: ['user', 'northlight', 'third'], familyOrder: ['anthropic'], strengthFallback: ['medium'] },
+    }));
+    return userConfigPath;
+}
+function seedCapacityFixture(id, largeContextWindow = 999) {
+    const dir = join(h.home, 'nodes', id);
+    writeFileSync(join(dir, 'fake-pi.context-tokens'), '1000');
+    writeFileSync(join(dir, 'fake-pi.model-capacities.json'), JSON.stringify({
+        'fake-primary/primary': 2000,
+        'fake-small/small': 999,
+        'fake-large/large': largeContextWindow,
+    }));
+}
 // The node's recorded model (fake-pi.model.json, written by the fake's
 // recordModel) — `null` for a model-less boot. A disk read, so it survives the
 // broker exiting after its kickoff turn idle-releases.
@@ -395,6 +422,36 @@ test('a recovered compact-and-retry commits nothing, while a definitive failure
     const notices = h.inbox(parent).filter((entry) => /exceeded its model context window/i.test(entry.label));
     assert.equal(notices.length, 1, 'the parent receives exactly one structured overflow notice');
 });
+test('provider-retry and model-not-found fallback both terminate when every available target has a smaller known context window', { timeout: 30_000 }, async () => {
+    const userConfigPath = seedCapacityFallbackRoutes();
+    try {
+        const parent = h.spawnRoot('capacity fallback parent');
+        const providerRetry = await h.spawnHeadlessChild(parent, 'provider retry capacity fallback', { kind: 'test/capacity-fallback' });
+        await h.waitFor(() => agentStartCount(providerRetry) >= 1, { label: 'provider retry capacity fixture started' });
+        seedCapacityFixture(providerRetry, 2000);
+        h.fakeCmd(providerRetry, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
+        await h.waitFor(() => model(providerRetry)?.provider === 'fake-large' ? true : null, { label: 'provider retry skips the too-small target for the large enough target' });
+        assert.equal(model(providerRetry).provider, 'fake-large', 'a large enough fallback remains eligible after the smaller route is rejected');
+        const exhaustedProviderRetry = await h.spawnHeadlessChild(parent, 'exhausted provider retry capacity fallback', { kind: 'test/capacity-fallback' });
+        await h.waitFor(() => agentStartCount(exhaustedProviderRetry) >= 1, { label: 'exhausted provider retry capacity fixture started' });
+        seedCapacityFixture(exhaustedProviderRetry);
+        h.fakeCmd(exhaustedProviderRetry, { cmd: 'auto_retry', errorMessage: 'rate limit exceeded' });
+        const providerRetryFault = await h.waitFor(() => readFault(exhaustedProviderRetry)?.kind === 'context-overflow' ? readFault(exhaustedProviderRetry) : null, { label: 'provider retry rejects every too-small fallback target' });
+        assert.equal(providerRetryFault.retry.disposition, 'fatal', 'all known-too-small provider retry targets produce a fatal context-overflow fault');
+        assert.match(providerRetryFault.message, /1000 tokens/, 'the terminal fault identifies the current conversation size');
+        assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', exhaustedProviderRetry, 'fake-pi.auto-retry.json'), 'utf8')).aborted, true, 'the retry delay is cancelled after Pi creates its retry controller');
+        const modelNotFound = await h.spawnHeadlessChild(parent, 'model-not-found capacity fallback', { kind: 'test/capacity-fallback' });
+        await h.waitFor(() => agentStartCount(modelNotFound) >= 1, { label: 'model-not-found capacity fixture started' });
+        seedCapacityFixture(modelNotFound);
+        h.fakeCmd(modelNotFound, { cmd: 'stop', reason: 'error', errorMessage: 'Model not found' });
+        const modelNotFoundFault = await h.waitFor(() => readFault(modelNotFound)?.kind === 'context-overflow' ? readFault(modelNotFound) : null, { label: 'model-not-found rejects the too-small fallback target' });
+        assert.equal(modelNotFoundFault.retry.disposition, 'fatal', 'all known-too-small model-not-found targets produce a fatal context-overflow fault');
+        assert.match(modelNotFoundFault.message, /1000 tokens/, 'the terminal fault survives ordinary settlement staging');
+    }
+    finally {
+        rmSync(userConfigPath, { force: true });
+    }
+});
 // Two real logical launches keep both user paths non-vacuous: the picker first
 // proves an explicit concrete choice pins and clears routing, while Alt+M runs
 // directly against still-present logical intent before Shift+Tab and replay.

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;