ai-runtime-engine 2.9.0 → 3.0.1

package/dist/store/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Typed store-layer errors. Decryption failures carry an HONEST code: an AEAD (GCM) authentication
+ * failure does NOT prove the key is wrong — it means wrong key OR tampering OR corruption, and the code
+ * says exactly that. Higher layers may infer "likely key mismatch" only from AGGREGATE evidence (most/
+ * all encrypted records failing at once), never from a single record.
+ */
+export class StoreDecryptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'StoreDecryptError';
+        this.code = code;
+    }
+}

package/dist/store/store.d.ts

@@ -64,8 +64,28 @@ export declare class RuntimeStore {
     /**
      * Advisory per-project lock. Best-effort: acquires an exclusive lock file, steals a stale one, and
      * otherwise proceeds anyway (advisory). Hard mutual exclusion for executions is a Phase 7 lease.
+     *
+     * The lock carries an ownership TOKEN so stealing a stale lock is atomic (unlink + exclusive re-create —
+     * exactly one racer wins) and release only removes a lock we still hold, never a stealer's.
      */
     withLock<T>(fn: () => T, staleMs?: number): T;
-    /** Aggregate integrity check across the project areas (plus the org area when configured). */
+    /**
+     * @internal Acquire the lock file exclusively, stealing it only if stale. Returns whether WE hold it
+     * (a live foreign lock ⇒ false ⇒ the caller proceeds advisory, unlocked). Exposed for deterministic
+     * concurrency tests; `hooks.afterStaleUnlink` runs between removing a stale lock and re-creating it,
+     * letting a test interleave a competing stealer in that exact window.
+     */
+    acquireLock(lockPath: string, token: string, staleMs?: number, hooks?: {
+        afterStaleUnlink?: () => void;
+    }): boolean;
+    /** @internal Release a lock ONLY if its on-disk token matches ours — never delete a stealer's lock. */
+    releaseLock(lockPath: string, token: string): void;
+    /**
+     * Aggregate integrity check across the project's DURABLE areas (plus the org area when configured).
+     * Covers memory (all scopes), conversations, indexes, and the record stores that hold real state —
+     * mcp, executions, artifacts. `cache` is intentionally excluded (disposable — `cleanup` clears it
+     * wholesale, so a checksum issue there is noise); `learning`/`preferences` are store/user-wide rather
+     * than project-scoped and are left to a future store-wide check.
+     */
     check(): IntegrityIssue[];
 }

package/dist/store/store.js

@@ -4,6 +4,7 @@
  * per-project lock, and an aggregate integrity check. In stateless mode every area is a NullArea.
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
 import { systemClock } from '../util/clock.js';
 import { FileArea, NullArea } from './area.js';
@@ -98,10 +99,10 @@ export class RuntimeStore {
     stampMeta() {
         if (!this.enabled || this.metaStamped)
             return;
-        mkdirSync(this.projectDir, { recursive: true });
+        mkdirSync(this.projectDir, { recursive: true, mode: 0o700 });
         const metaPath = join(this.projectDir, 'meta.json');
         if (!existsSync(metaPath))
-            writeFileSync(metaPath, JSON.stringify({ version: STORE_VERSION, projectId: this.projectId }));
+            writeFileSync(metaPath, JSON.stringify({ version: STORE_VERSION, projectId: this.projectId }), { mode: 0o600 });
         this.metaStamped = true;
     }
     /** The stored version, or undefined when absent — a migration hook seam for future versions. */
@@ -119,43 +120,97 @@ export class RuntimeStore {
     /**
      * Advisory per-project lock. Best-effort: acquires an exclusive lock file, steals a stale one, and
      * otherwise proceeds anyway (advisory). Hard mutual exclusion for executions is a Phase 7 lease.
+     *
+     * The lock carries an ownership TOKEN so stealing a stale lock is atomic (unlink + exclusive re-create —
+     * exactly one racer wins) and release only removes a lock we still hold, never a stealer's.
      */
     withLock(fn, staleMs = 30_000) {
         if (!this.enabled)
             return fn();
-        mkdirSync(this.projectDir, { recursive: true });
+        mkdirSync(this.projectDir, { recursive: true, mode: 0o700 });
         const lockPath = join(this.projectDir, '.lock');
-        let held = false;
+        const token = randomBytes(16).toString('hex');
+        const held = this.acquireLock(lockPath, token, staleMs);
         try {
-            writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
-            held = true;
+            return fn();
+        }
+        finally {
+            if (held)
+                this.releaseLock(lockPath, token);
+        }
+    }
+    /**
+     * @internal Acquire the lock file exclusively, stealing it only if stale. Returns whether WE hold it
+     * (a live foreign lock ⇒ false ⇒ the caller proceeds advisory, unlocked). Exposed for deterministic
+     * concurrency tests; `hooks.afterStaleUnlink` runs between removing a stale lock and re-creating it,
+     * letting a test interleave a competing stealer in that exact window.
+     */
+    acquireLock(lockPath, token, staleMs = 30_000, hooks) {
+        const content = JSON.stringify({ pid: process.pid, token, acquiredAt: this.clock.now() });
+        try {
+            writeFileSync(lockPath, content, { flag: 'wx', mode: 0o600 }); // exclusive create — no lock held
+            return true;
         }
         catch {
-            // Held already — steal if stale.
+            // A lock exists. Steal ONLY if stale, and atomically: remove it, then race an exclusive re-create —
+            // exactly one concurrent stealer's `wx` can succeed.
+            let stale;
+            try {
+                stale = this.clock.now() - statSync(lockPath).mtimeMs > staleMs;
+            }
+            catch {
+                return false; // vanished/unreadable mid-check — proceed advisory, unlocked
+            }
+            if (!stale)
+                return false; // a live lock — do not steal; proceed advisory, unlocked
             try {
-                const age = this.clock.now() - statSync(lockPath).mtimeMs;
-                if (age > staleMs) {
-                    writeFileSync(lockPath, String(process.pid));
-                    held = true;
-                }
+                rmSync(lockPath); // drop the stale lock (a competing stealer may have already removed it)
             }
             catch {
-                /* proceed advisory */
+                /* already gone — still race the exclusive create below */
+            }
+            hooks?.afterStaleUnlink?.();
+            try {
+                writeFileSync(lockPath, content, { flag: 'wx', mode: 0o600 });
+                return true; // won the steal
+            }
+            catch {
+                return false; // a competing stealer won the race — proceed advisory, unlocked
             }
         }
+    }
+    /** @internal Release a lock ONLY if its on-disk token matches ours — never delete a stealer's lock. */
+    releaseLock(lockPath, token) {
         try {
-            return fn();
-        }
-        finally {
-            if (held && existsSync(lockPath))
+            const cur = JSON.parse(readFileSync(lockPath, 'utf8'));
+            if (cur.token === token)
                 rmSync(lockPath);
         }
+        catch {
+            /* lock gone or unreadable — nothing of ours to release */
+        }
     }
-    /** Aggregate integrity check across the project areas (plus the org area when configured). */
+    /**
+     * Aggregate integrity check across the project's DURABLE areas (plus the org area when configured).
+     * Covers memory (all scopes), conversations, indexes, and the record stores that hold real state —
+     * mcp, executions, artifacts. `cache` is intentionally excluded (disposable — `cleanup` clears it
+     * wholesale, so a checksum issue there is noise); `learning`/`preferences` are store/user-wide rather
+     * than project-scoped and are left to a future store-wide check.
+     */
     check() {
         if (!this.enabled)
             return [];
         const org = this.orgDir ? this.memory('organization').check() : [];
-        return [...this.memory('project').check(), ...this.memory('user').check(), ...this.memory('repository').check(), ...org, ...this.conversations().check(), ...this.indexes().check()];
+        return [
+            ...this.memory('project').check(),
+            ...this.memory('user').check(),
+            ...this.memory('repository').check(),
+            ...org,
+            ...this.conversations().check(),
+            ...this.indexes().check(),
+            ...this.mcp().check(),
+            ...this.executions().check(),
+            ...this.artifacts().check(),
+        ];
     }
 }

package/dist/telemetry/sinks/file.js

@@ -11,7 +11,9 @@ export class FileSink {
     constructor(path) {
         this.path = path;
         try {
-            mkdirSync(dirname(path), { recursive: true });
+            // Owner-only by default (0700 dir / 0600 file): the spool commonly lives under `.ai-runtime/` and
+            // carries routing/perf metadata. Mode applies only on creation; POSIX-only, a no-op on Windows.
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         }
         catch {
             /* ignore — a telemetry setup failure must not break the router */
@@ -19,7 +21,7 @@ export class FileSink {
     }
     emit(event) {
         try {
-            appendFileSync(this.path, `${JSON.stringify(redact(event))}\n`);
+            appendFileSync(this.path, `${JSON.stringify(redact(event))}\n`, { mode: 0o600 });
         }
         catch {
             /* a telemetry write must never fail a run */

package/dist/telemetry/sinks/otlp.d.ts

@@ -17,15 +17,25 @@ export interface OtlpSinkOptions {
     authHeader?: string;
     /** Flush when this many events are buffered (default 20). */
     batchSize?: number;
+    /** Per-POST deadline (ms, default 5000). Bounds the shutdown drain so a stalled collector can never
+     *  hang process exit — mirrors the AbortSignal.timeout every provider HTTP call already uses. */
+    timeoutMs?: number;
 }
 export declare class OtlpSink implements TelemetrySink {
     private readonly endpoint;
     private readonly fetchImpl;
     private readonly authHeader?;
     private readonly batchSize;
+    private readonly timeoutMs;
     private buffer;
+    /** In-flight POSTs, so `flush()` (called on shutdown) can await them instead of dropping them. */
+    private readonly inflight;
     constructor(opts: OtlpSinkOptions);
     emit(event: TelemetryEvent): void;
-    /** POST the buffered batch. Fire-and-forget; every error is swallowed. */
-    flush(): void;
+    /**
+     * POST any buffered batch, then await every in-flight POST. Awaitable so `close()` truly drains before
+     * exit — a short-lived process that emitted fewer than `batchSize` events no longer loses them. Every
+     * network error is still swallowed; telemetry must never fail a run.
+     */
+    flush(): Promise<void>;
 }

package/dist/telemetry/sinks/otlp.js

@@ -35,42 +35,57 @@ export class OtlpSink {
     fetchImpl;
     authHeader;
     batchSize;
+    timeoutMs;
     buffer = [];
+    /** In-flight POSTs, so `flush()` (called on shutdown) can await them instead of dropping them. */
+    inflight = new Set();
     constructor(opts) {
         this.endpoint = opts.endpoint;
         this.fetchImpl = opts.fetchImpl ?? fetch;
         if (opts.authHeader)
             this.authHeader = opts.authHeader;
         this.batchSize = opts.batchSize && opts.batchSize > 0 ? opts.batchSize : 20;
+        this.timeoutMs = opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : 5_000;
     }
     emit(event) {
         this.buffer.push(redact(event));
+        // At the batch threshold, kick off a POST but don't block the caller (telemetry is off the hot path).
         if (this.buffer.length >= this.batchSize)
-            this.flush();
+            void this.flush();
     }
-    /** POST the buffered batch. Fire-and-forget; every error is swallowed. */
-    flush() {
-        if (this.buffer.length === 0)
-            return;
-        const batch = this.buffer;
-        this.buffer = [];
-        const payload = {
-            resourceLogs: [
-                {
-                    resource: { attributes: [{ key: 'service.name', value: { stringValue: 'ai-runtime' } }] },
-                    scopeLogs: [{ scope: { name: 'ai-runtime.router' }, logRecords: batch.map(toLogRecord) }],
-                },
-            ],
-        };
-        const headers = { 'content-type': 'application/json' };
-        if (this.authHeader)
-            headers.authorization = this.authHeader;
-        try {
-            // Fire-and-forget: never await, never let a rejection escape (telemetry must not fail a run).
-            void Promise.resolve(this.fetchImpl(this.endpoint, { method: 'POST', headers, body: JSON.stringify(payload) })).catch(() => { });
-        }
-        catch {
-            /* a telemetry export must never fail a run */
+    /**
+     * POST any buffered batch, then await every in-flight POST. Awaitable so `close()` truly drains before
+     * exit — a short-lived process that emitted fewer than `batchSize` events no longer loses them. Every
+     * network error is still swallowed; telemetry must never fail a run.
+     */
+    async flush() {
+        if (this.buffer.length > 0) {
+            const batch = this.buffer;
+            this.buffer = [];
+            const payload = {
+                resourceLogs: [
+                    {
+                        resource: { attributes: [{ key: 'service.name', value: { stringValue: 'ai-runtime' } }] },
+                        scopeLogs: [{ scope: { name: 'ai-runtime.router' }, logRecords: batch.map(toLogRecord) }],
+                    },
+                ],
+            };
+            const headers = { 'content-type': 'application/json' };
+            if (this.authHeader)
+                headers.authorization = this.authHeader;
+            const post = (async () => {
+                try {
+                    // A bounded signal so a stalled collector can never hang the awaited shutdown drain.
+                    await this.fetchImpl(this.endpoint, { method: 'POST', headers, body: JSON.stringify(payload), signal: AbortSignal.timeout(this.timeoutMs) });
+                }
+                catch {
+                    /* a telemetry export must never fail a run (a timeout abort lands here too) */
+                }
+            })();
+            this.inflight.add(post);
+            void post.finally(() => this.inflight.delete(post));
         }
+        // Drain in-flight POSTs (including the one just started). allSettled: a failed POST never blocks close.
+        await Promise.allSettled([...this.inflight]);
     }
 }

package/dist/telemetry/telemetry.d.ts

@@ -6,6 +6,9 @@ import type { TelemetryEvent } from '../types.js';
 export interface TelemetrySink {
     emit(event: TelemetryEvent): void;
     events?(): TelemetryEvent[];
+    /** Optional: drain any buffered/in-flight export before shutdown. Called by AI.close() / Runtime.close().
+     *  A sink with nothing to drain (memory/null/file) omits it; a batching/network sink implements it. */
+    flush?(): void | Promise<void>;
 }
 export declare class MemorySink implements TelemetrySink {
     private readonly limit;
@@ -33,4 +36,6 @@ export declare class MultiSink implements TelemetrySink {
     constructor(sinks: TelemetrySink[]);
     emit(event: TelemetryEvent): void;
     events(): TelemetryEvent[];
+    /** Drain every child sink that can flush; one failing flush never blocks the others. */
+    flush(): Promise<void>;
 }

package/dist/telemetry/telemetry.js

@@ -60,4 +60,8 @@ export class MultiSink {
         }
         return [];
     }
+    /** Drain every child sink that can flush; one failing flush never blocks the others. */
+    async flush() {
+        await Promise.allSettled(this.sinks.map((sink) => sink.flush?.()));
+    }
 }

package/dist/tools/builtins/shell.d.ts

@@ -1,8 +1,9 @@
 /**
  * Shell tool — allowlist-FIRST: a command runs only if `shell.enabled` AND its argv[0] is in the
- * allowlist; anything else needs interactive approval. A destructive-command denylist is a backstop
- * that requires approval EVEN when allowlisted (rm -rf, git reset --hard, force-push, sudo, …). Runs
- * in the workspace with a timeout, abort signal, and a secret-free environment.
+ * allowlist; anything else needs interactive approval. Two denylists are backstops that require approval
+ * EVEN when allowlisted: destructive commands (rm -rf, git reset --hard, force-push, sudo, …) and
+ * eval-capable commands (interpreters with inline code, package/script runners, container exec, argv
+ * indirection). Runs in the workspace with a timeout, abort signal, and a secret-free environment.
  */
 import type { Tool } from '../tool.js';
 import type { CommandRunner } from '../runner.js';
@@ -12,6 +13,32 @@ import type { CommandRunner } from '../runner.js';
  * `rm --recursive --force` and `git push +main` are caught, not just `rm -rf`.
  */
 export declare function isDestructive(command: string, args?: string[]): boolean;
+/**
+ * Whether a command can execute ARBITRARY code through its arguments — an interpreter, a package/script
+ * runner, an exec-wrapper, a container escape, or an argv-indirection tool. The allowlist only matches
+ * argv[0], so allowlisting `npm` or `node` would otherwise silently grant `npm exec …`/`node -e …` = full
+ * code execution outside the jail. Such invocations are escalated to human approval (like `isDestructive`),
+ * never hard-denied.
+ *
+ * BEST-EFFORT, NOT EXHAUSTIVE. This is a denylist of well-known code-execution vectors; it cannot cover
+ * every interpreter, wrapper, or runner in existence. Allowlisting an interpreter (python, node, awk, …),
+ * an exec-wrapper (nice, timeout, …), or a package manager INHERENTLY grants code execution — operators
+ * should allowlist specific leaf tools, not code-execution engines. `docs/security.md` states this limit.
+ *
+ * Deliberately NOT flagged (documented scope): `npm|pnpm|yarn install|ci|add|rebuild|link` and lifecycle
+ * scripts `npm test|start|stop|restart` — installing dependencies runs their lifecycle scripts BY DESIGN
+ * and is the single most common allowlisted operation; and a plain `make`/`make <target>` (the workspace's
+ * own Makefile, same trust domain as `npm test`). Flagging those would prompt on the common case while
+ * `node script.js` stays open — theater, not security. A NON-default makefile (`make -f`) IS flagged.
+ *
+ * KNOWN RESIDUAL (accepted, verified by an adversarial bypass hunt): running a SCRIPT FILE via an
+ * interpreter (`tclsh x.tcl`, `deno run x.ts`) is not flagged — that is the same file-execution case as
+ * `node build.js`, deliberately allowed; dependency-install lifecycle scripts (above); the obscure sed/
+ * `rename` `e`-flag exec (reliable detection needs full script parsing); and git aliases / custom
+ * `git-<x>` subcommands (require a pre-existing gitconfig alias or a git-* binary the model cannot plant
+ * from inside the jail). These reflect the best-effort nature above; `docs/security.md` states the limit.
+ */
+export declare function isEvalCapable(command: string, args?: string[]): boolean;
 export declare function createShellTool(runner?: CommandRunner): Tool;
 /** The shell tool with the default (real) runner. */
 export declare const shellTool: Tool;

package/dist/tools/builtins/shell.js

@@ -1,9 +1,12 @@
 /**
  * Shell tool — allowlist-FIRST: a command runs only if `shell.enabled` AND its argv[0] is in the
- * allowlist; anything else needs interactive approval. A destructive-command denylist is a backstop
- * that requires approval EVEN when allowlisted (rm -rf, git reset --hard, force-push, sudo, …). Runs
- * in the workspace with a timeout, abort signal, and a secret-free environment.
+ * allowlist; anything else needs interactive approval. Two denylists are backstops that require approval
+ * EVEN when allowlisted: destructive commands (rm -rf, git reset --hard, force-push, sudo, …) and
+ * eval-capable commands (interpreters with inline code, package/script runners, container exec, argv
+ * indirection). Runs in the workspace with a timeout, abort signal, and a secret-free environment.
  */
+import { resolve, relative, isAbsolute } from 'node:path';
+import { realpathSync } from 'node:fs';
 import { authorize, denied } from '../tool.js';
 import { defaultRunner, safeEnv } from '../runner.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -51,6 +54,206 @@ export function isDestructive(command, args = []) {
     }
     return DESTRUCTIVE_STRING.some((re) => re.test(full));
 }
+/** Version-suffixed interpreters are ubiquitous (`python3.12`, `python3.11`) — match them all. */
+const isPython = (cmd) => /^python(?:\d+(?:\.\d+)?)?$/.test(cmd);
+/**
+ * Whether argv carries any of the given short (single-letter) or long eval flags, in ANY spelling the
+ * real interpreter accepts: bare (`-e`, `--eval`), attached (`-eCODE`, `-cCODE`, `--eval=CODE`), or
+ * clustered short (`-pe`). Exact-equality matching missed every attached/clustered form — which the
+ * binaries all execute — so match structurally (mirrors `hasRecursiveFlag`'s prefix matching above).
+ */
+function hasEvalFlag(args, short, long) {
+    return args.some((a) => {
+        if (a.startsWith('--'))
+            return long.includes(a.slice(2).split('=')[0] ?? '');
+        if (a.startsWith('-') && a.length > 1) {
+            const body = a.slice(1);
+            if (short.includes(body[0]))
+                return true; // -e, -eCODE, -cCODE, -mMOD
+            if (/^[A-Za-z]+$/.test(body))
+                return body.split('').some((c) => short.includes(c)); // clustered -pe
+        }
+        return false;
+    });
+}
+/**
+ * Whether a gated subcommand token appears ANYWHERE in argv. Robust to leading global options that take a
+ * value (`npm -C <dir> exec …`, `docker --context <c> run …`), which shift the subcommand out of args[0].
+ * Over-escalation (a package literally named `run`) only prompts — it never denies — so scanning is safe.
+ */
+function hasSubcommand(args, gated) {
+    return args.some((a) => gated.includes(a));
+}
+/** pnpm/yarn also RUN package.json scripts directly (`yarn build` == `yarn run build`), so a leading
+ *  bare token that is not a known package-management builtin is a script invocation and must escalate.
+ *  Kept in parity with npm's excluded lifecycle scripts (test/start/stop/restart). */
+const YARN_PNPM_SAFE = new Set([
+    'install', 'i', 'add', 'remove', 'rm', 'up', 'update', 'upgrade', 'why', 'list', 'ls', 'info', 'outdated',
+    'audit', 'dedupe', 'init', 'link', 'unlink', 'pack', 'publish', 'version', 'config', 'cache', 'licenses',
+    'import', 'login', 'logout', 'store', 'fetch', 'patch', 'set', 'bin', 'test', 'start', 'stop', 'restart',
+]);
+/**
+ * Interpreters whose "run a file" use (e.g. `node build.js`) is benign but whose inline-code/preload/
+ * module flags execute arbitrary code. Keyed basename → the code-bearing short/long flags. Completing an
+ * interpreter here (e.g. node/ruby `-r`, perl `-M`) closes the same class the -e/-c gates already cover.
+ */
+const INTERPRETER_EVAL_FLAGS = [
+    { match: (c) => c === 'node' || c === 'nodejs' || c === 'bun', short: ['e', 'p', 'r'], long: ['eval', 'print', 'require'] },
+    { match: isPython, short: ['c', 'm'], long: [] },
+    { match: (c) => c === 'perl', short: ['e', 'E', 'M'], long: [] },
+    { match: (c) => c === 'ruby', short: ['e', 'r'], long: ['require'] },
+    { match: (c) => c === 'php', short: ['r', 'R'], long: ['run'] },
+    { match: (c) => c === 'lua' || c === 'luajit', short: ['e'], long: [] },
+    { match: (c) => c === 'Rscript' || c === 'R', short: ['e'], long: ['eval'] },
+    { match: (c) => c === 'julia', short: ['e', 'E'], long: ['eval'] },
+    { match: (c) => c === 'elixir' || c === 'iex', short: ['e'], long: ['eval'] },
+    { match: (c) => c === 'ghc' || c === 'runghc' || c === 'runhaskell', short: ['e'], long: [] },
+    { match: (c) => c === 'groovy' || c === 'scala', short: ['e'], long: ['eval'] },
+    { match: (c) => c === 'osascript', short: ['e'], long: [] },
+];
+/**
+ * Wrapper commands whose entire purpose is to run ANOTHER command passed as an argument — so the argv0
+ * allowlist check never sees the real command. Flagged whenever they carry a non-flag argument (env/xargs
+ * are handled with the always-runners above). This is a curated set of the well-known wrappers, not an
+ * exhaustive one — see the isEvalCapable docstring on the best-effort nature of this backstop.
+ */
+const EXEC_WRAPPERS = new Set([
+    'nice', 'nohup', 'timeout', 'stdbuf', 'setsid', 'taskset', 'chrt', 'ionice', 'time', 'flock', 'setarch',
+    'unshare', 'nsenter', 'strace', 'ltrace', 'valgrind', 'watch', 'script', 'runuser', 'su', 'parallel',
+    'setpriv',
+]);
+const isAwk = (cmd) => cmd === 'awk' || cmd === 'gawk' || cmd === 'mawk' || cmd === 'nawk';
+/**
+ * Whether a command can execute ARBITRARY code through its arguments — an interpreter, a package/script
+ * runner, an exec-wrapper, a container escape, or an argv-indirection tool. The allowlist only matches
+ * argv[0], so allowlisting `npm` or `node` would otherwise silently grant `npm exec …`/`node -e …` = full
+ * code execution outside the jail. Such invocations are escalated to human approval (like `isDestructive`),
+ * never hard-denied.
+ *
+ * BEST-EFFORT, NOT EXHAUSTIVE. This is a denylist of well-known code-execution vectors; it cannot cover
+ * every interpreter, wrapper, or runner in existence. Allowlisting an interpreter (python, node, awk, …),
+ * an exec-wrapper (nice, timeout, …), or a package manager INHERENTLY grants code execution — operators
+ * should allowlist specific leaf tools, not code-execution engines. `docs/security.md` states this limit.
+ *
+ * Deliberately NOT flagged (documented scope): `npm|pnpm|yarn install|ci|add|rebuild|link` and lifecycle
+ * scripts `npm test|start|stop|restart` — installing dependencies runs their lifecycle scripts BY DESIGN
+ * and is the single most common allowlisted operation; and a plain `make`/`make <target>` (the workspace's
+ * own Makefile, same trust domain as `npm test`). Flagging those would prompt on the common case while
+ * `node script.js` stays open — theater, not security. A NON-default makefile (`make -f`) IS flagged.
+ *
+ * KNOWN RESIDUAL (accepted, verified by an adversarial bypass hunt): running a SCRIPT FILE via an
+ * interpreter (`tclsh x.tcl`, `deno run x.ts`) is not flagged — that is the same file-execution case as
+ * `node build.js`, deliberately allowed; dependency-install lifecycle scripts (above); the obscure sed/
+ * `rename` `e`-flag exec (reliable detection needs full script parsing); and git aliases / custom
+ * `git-<x>` subcommands (require a pre-existing gitconfig alias or a git-* binary the model cannot plant
+ * from inside the jail). These reflect the best-effort nature above; `docs/security.md` states the limit.
+ */
+export function isEvalCapable(command, args = []) {
+    const cmd = baseName(command);
+    const sub = args.find((a) => !a.startsWith('-')); // effective subcommand (skips leading -flags)
+    const hasNonFlagArg = args.some((a) => !a.startsWith('-'));
+    // Shells: the only reason to invoke one from an argv-based tool is expansion/chaining we cannot inspect.
+    if (cmd === 'sh' || cmd === 'bash' || cmd === 'zsh' || cmd === 'dash' || cmd === 'ksh' || cmd === 'fish' || cmd === 'tcsh' || cmd === 'csh' || cmd === 'rc')
+        return true;
+    // Registry/script runners and argv-indirection tools: arbitrary code regardless of args.
+    if (cmd === 'npx' || cmd === 'pnpx' || cmd === 'bunx' || cmd === 'corepack' || cmd === 'env' || cmd === 'xargs')
+        return true;
+    // Exec-wrappers: run another command passed as their argument (the argv0 check never sees it).
+    if (EXEC_WRAPPERS.has(cmd) && hasNonFlagArg)
+        return true;
+    // Interpreters flagged on a code/eval/preload flag (glued/clustered forms included — see hasEvalFlag).
+    for (const it of INTERPRETER_EVAL_FLAGS)
+        if (it.match(cmd) && hasEvalFlag(args, it.short, it.long))
+            return true;
+    // The awk family takes its PROGRAM as the first positional (or gawk's -e/--source): always inline code.
+    // A -f/--file program is file-based (treated like a script file, unflagged, mirroring `node build.js`).
+    if (isAwk(cmd) && !args.some((a) => a === '-f' || a === '--file' || a.startsWith('--file=')) && (hasNonFlagArg || args.some((a) => a === '-e' || a === '--source' || a.startsWith('--source='))))
+        return true;
+    // deno: `eval`/`task`, inline eval flags, a remote URL target, or an allow-all/allow-run/allow-ffi grant.
+    if (cmd === 'deno' && (sub === 'eval' || sub === 'task' || hasEvalFlag(args, ['e', 'A'], ['eval', 'allow-all', 'allow-run', 'allow-ffi']) || args.some((a) => /^https?:\/\//.test(a))))
+        return true;
+    // Package-manager run/exec/init/create (fetch-and-run or run a package.json script), and a config
+    // mutation that can repoint the script shell. install/ci/add/… stay unflagged — see docstring.
+    if (cmd === 'npm' && hasSubcommand(args, ['run', 'run-script', 'exec', 'x', 'init', 'create', 'explore']))
+        return true;
+    if (cmd === 'npm' && args.includes('config') && args.some((a) => a === 'set' || a === 'edit'))
+        return true;
+    if (cmd === 'bun' && hasSubcommand(args, ['run', 'x', 'exec', 'create']))
+        return true;
+    if (cmd === 'pnpm' || cmd === 'yarn') {
+        if (hasSubcommand(args, ['run', 'exec', 'dlx', 'create', 'node', 'x']))
+            return true;
+        // Direct script form: `yarn <script>` with no `run`. Only when it is the leading bare token (a global
+        // flag's value is never mistaken for a script — those runner forms are caught by the scan above).
+        if (sub !== undefined && args[0] === sub && !YARN_PNPM_SAFE.has(sub))
+            return true;
+    }
+    // Containers: `run`/`exec` execute an arbitrary command inside/as a container.
+    if ((cmd === 'docker' || cmd === 'podman' || cmd === 'nerdctl') && hasSubcommand(args, ['run', 'exec']))
+        return true;
+    // find -exec/-execdir/-ok/-okdir run a command per match.
+    if (cmd === 'find' && args.some((a) => a === '-exec' || a === '-execdir' || a === '-ok' || a === '-okdir'))
+        return true;
+    // git: config/exec-path injection, and rebase's per-commit command exec.
+    if (cmd === 'git') {
+        if (args.some((a) => a === '-c' || a.startsWith('--exec-path')))
+            return true;
+        if (args[0] === 'rebase' && args.some((a) => a === '-x' || a === '--exec' || a.startsWith('--exec=')))
+            return true;
+    }
+    // make loading a NON-default makefile runs an arbitrary recipe file (a plain `make`/`make <target>`
+    // uses the workspace's own Makefile and stays unflagged — see docstring).
+    if (cmd === 'make' && args.some((a) => a === '-f' || /^-f./.test(a) || a === '--file' || a === '--makefile' || a.startsWith('--file=') || a.startsWith('--makefile=')))
+        return true;
+    // Remote-exec tools with a LOCAL-command option (ProxyCommand/LocalCommand, rsync's remote-shell).
+    if ((cmd === 'ssh' || cmd === 'scp' || cmd === 'sftp') && args.some((a, i) => (a === '-o' && /command\s*=/i.test(args[i + 1] ?? '')) || /^-o(Proxy|Local)Command/i.test(a) || /^(Proxy|Local)Command\s*=/i.test(a)))
+        return true;
+    if (cmd === 'rsync' && args.some((a) => a === '-e' || a === '--rsh' || a.startsWith('--rsh=')))
+        return true;
+    // Non-interactive editor command execution (`vim -c '!cmd'`, `emacs --batch --eval`).
+    if ((cmd === 'vim' || cmd === 'vi' || cmd === 'nvim' || cmd === 'ex' || cmd === 'view') && args.some((a) => a === '-c' || a === '--cmd' || a === '-S' || a.startsWith('+')))
+        return true;
+    if (cmd === 'emacs' && args.some((a) => a === '--eval' || a === '--batch' || a === '-batch' || a === '--script'))
+        return true;
+    return false;
+}
+/** Canonicalize a path (resolving symlinks AND case on case-insensitive filesystems) when it exists;
+ *  fall back to a lexical resolve when it does not (a not-yet-created path, or a synthetic test root). */
+function canonical(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/**
+ * Whether an absolute path resolves at or under the workspace root (where the model can write files, so
+ * its basename must NOT be trusted against the allowlist). realpath is used so a workspace-internal file
+ * reached via a symlink or a case-variant path (`/users/…` vs `/Users/…` on a case-insensitive FS) is
+ * still recognized as inside — a lexical compare alone missed both.
+ */
+function isInsideWorkspace(root, command) {
+    const rel = relative(canonical(root), canonical(command));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * Allowlist matching. An exact string match always wins (back-compat). For an ABSOLUTE path (…/npm,
+ * C:\…\npm) the basename is also matched against the allowlist, so a real `/usr/bin/npm` counts as `npm`
+ * — UNLESS the path resolves INSIDE the workspace, where the model can write an executable and point at
+ * it (the same reason a relative `./bin/npm` never matches). Workspace-local and relative paths must go
+ * through interactive approval.
+ */
+function allowlistMatch(list, command, workspaceRoot) {
+    if (list.includes(command))
+        return true;
+    if (/^(\/|[A-Za-z]:[\\/]|\\\\)/.test(command)) {
+        if (workspaceRoot && isInsideWorkspace(workspaceRoot, command))
+            return false;
+        return list.includes(baseName(command));
+    }
+    return false;
+}
 export function createShellTool(runner = defaultRunner) {
     return {
         id: 'shell',
@@ -64,15 +267,23 @@ export function createShellTool(runner = defaultRunner) {
             if (!ctx.permissions.shell.enabled)
                 return denied('PERMISSION', 'shell execution is not enabled');
             const full = [command, ...args].join(' ');
-            const allowlisted = ctx.permissions.shell.allowedCommands.includes(command);
+            const allowlisted = allowlistMatch(ctx.permissions.shell.allowedCommands, command, ctx.workspaceRoot);
             const dangerous = isDestructive(command, args);
+            const evalCapable = isEvalCapable(command, args);
+            // Destructive OR eval-capable ⇒ a human must confirm even when the base command is allowlisted.
+            const mustConfirm = dangerous || evalCapable;
             const allowed = await authorize(ctx, allowlisted, {
                 action: `run shell command: ${full}`,
-                risk: dangerous ? 'high' : 'medium',
-                alwaysConfirm: dangerous, // destructive commands need a human even when allowlisted
+                risk: mustConfirm ? 'high' : 'medium',
+                alwaysConfirm: mustConfirm,
             });
             if (!allowed) {
-                return denied('PERMISSION', dangerous ? `destructive command needs approval: ${full}` : `command not allowlisted: ${command}`);
+                const why = dangerous
+                    ? `destructive command needs approval: ${full}`
+                    : evalCapable
+                        ? `eval-capable command needs approval: ${full}`
+                        : `command not allowlisted: ${command}`;
+                return denied('PERMISSION', why);
             }
             const res = await runner.run(command, args, {
                 cwd: ctx.workspaceRoot,