aiden-runtime 4.1.5 → 4.5.0

package/dist/core/v4/sandboxConfig.js

@@ -0,0 +1,285 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRealPath = resolveRealPath;
+exports._clearRealPathCacheForTests = _clearRealPathCacheForTests;
+exports.inferDefaultRiskTier = inferDefaultRiskTier;
+exports.readSandboxConfig = readSandboxConfig;
+exports.getSandboxConfig = getSandboxConfig;
+exports._resetSandboxConfigForTests = _resetSandboxConfigForTests;
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+const runtimeToggles_1 = require("./runtimeToggles");
+/**
+ * core/v4/sandboxConfig.ts — v4.4 Phase 1: Execution sandbox configuration.
+ *
+ * Single source of truth for sandbox enablement + resource policies +
+ * filesystem allow/deny lists + Docker hardening flags. Read from
+ * environment variables at construction time (matches v4.2's TurnState
+ * + v4.3's BrowserState env-driven pattern).
+ *
+ * Phase 1 ships the config types + reader + default-tier inference;
+ * downstream phases consume:
+ *   - Phase 2 — fsAllowList / fsDenyList used by file_* tools
+ *   - Phase 3 — defaultBackend / resourceLimits / networkMode /
+ *               persistent / idleReaperMs used by shell_exec + Docker
+ *               backend (long-lived container reuse, hardening flags)
+ *   - Phase 4 — dryRun used by all `mutates: true` tools
+ *   - Phase 5 — riskTier annotations consumed by FailureClassifier +
+ *               ApprovalEngine (as a FLOOR; patterns can escalate)
+ *
+ * v4.4 Phase 6 — default-on transition. AIDEN_SANDBOX is now
+ * enabled by default; users opt out with `AIDEN_SANDBOX=0`. The
+ * strict `!== '0'` flip mirrors v4.2 Phase 6 (TCE) + v4.3 Phase 6
+ * (browser depth) semantics exactly.
+ *
+ * AIDEN_DRYRUN is orthogonal — independent flag, independent semantics.
+ * Phase 6 does NOT flip dry-run; it stays opt-in by design (dry-run
+ * is a deliberate "preview-only" mode users opt into, not a default).
+ *
+ * Pure module — no I/O, no side effects, no Playwright/Docker
+ * dependencies. Just env-var reads + path normalization helpers.
+ * Easy to unit test by passing a stubbed `env` argument.
+ */
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+// ── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_RESOURCE_LIMITS = {
+    memory: '1g',
+    cpus: '2',
+    pidsLimit: 256,
+};
+const DEFAULT_IDLE_REAPER_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_IMAGE = 'node:22-alpine';
+/**
+ * v4.4 Phase 2 — default write-permitted paths. Real-resolved at
+ * config-build time to handle symlinked HOME / cwd. Caller can
+ * extend via `AIDEN_SANDBOX_ALLOW=p1:p2:...`.
+ */
+function buildDefaultAllowList() {
+    const home = node_os_1.default.homedir();
+    const tmp = node_os_1.default.tmpdir();
+    const cwd = process.cwd();
+    const paths = [
+        cwd,
+        node_path_1.default.join(home, 'Documents'),
+        node_path_1.default.join(home, 'Downloads'),
+        node_path_1.default.join(home, 'Desktop'),
+        tmp,
+    ];
+    return resolveRealPaths(paths);
+}
+/**
+ * v4.4 Phase 2 — default write-denied paths. Always wins over the
+ * allow list. Mirrors the consult-shaped deny-list pattern (sensitive
+ * configs, system dirs).
+ */
+function buildDefaultDenyList() {
+    const home = node_os_1.default.homedir();
+    const paths = [
+        node_path_1.default.join(home, '.ssh'),
+        node_path_1.default.join(home, '.aws'),
+        node_path_1.default.join(home, '.gnupg'),
+        node_path_1.default.join(home, '.env'),
+        node_path_1.default.join(home, '.netrc'),
+        node_path_1.default.join(home, '.pgpass'),
+        node_path_1.default.join(home, '.npmrc'),
+        node_path_1.default.join(home, '.pypirc'),
+        node_path_1.default.join(home, '.bashrc'),
+        node_path_1.default.join(home, '.zshrc'),
+        node_path_1.default.join(home, '.profile'),
+        '/etc',
+        '/var',
+        '/usr',
+        '/boot',
+        '/sys',
+        '/proc',
+    ];
+    return resolveRealPaths(paths);
+}
+// ── Path normalization ──────────────────────────────────────────────────────
+const _realPathCache = new Map();
+/**
+ * Resolve a path to its canonical absolute form. `path.resolve` first
+ * (handles relative + `..`); then `fs.realpathSync` to follow symlinks.
+ * Symlink resolution defeats the bypass attack where an allowlisted
+ * directory contains a symlink to a denied path.
+ *
+ * Results cached for the lifetime of the module (paths rarely change
+ * during a process; the cache hit rate is high on the file-tool path
+ * where every call resolves the same handful of allowlist entries).
+ *
+ * Falls back gracefully when the path doesn't exist (returns the
+ * resolved-but-unrealpath form) — caller may be checking a path
+ * about to be created.
+ */
+function resolveRealPath(input) {
+    if (_realPathCache.has(input))
+        return _realPathCache.get(input);
+    const resolved = node_path_1.default.resolve(input);
+    let real = resolved;
+    try {
+        real = node_fs_1.default.realpathSync.native ? node_fs_1.default.realpathSync.native(resolved) : node_fs_1.default.realpathSync(resolved);
+    }
+    catch {
+        // Path may not exist yet (e.g. file_write target). Use the
+        // resolved form; symlink-bypass on a non-existent path isn't
+        // a real attack vector.
+    }
+    _realPathCache.set(input, real);
+    return real;
+}
+/** Resolve an array of paths to their canonical forms; deduplicate. */
+function resolveRealPaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const p of paths) {
+        const real = resolveRealPath(p);
+        if (!seen.has(real)) {
+            seen.add(real);
+            out.push(real);
+        }
+    }
+    return out;
+}
+/** Public for tests — clears the realpath cache so env-var changes
+ *  in test isolation pick up fresh resolutions. Production code never
+ *  calls this. */
+function _clearRealPathCacheForTests() {
+    _realPathCache.clear();
+}
+// ── Env-var parsing helpers ─────────────────────────────────────────────────
+function parseList(raw) {
+    if (!raw)
+        return [];
+    return raw.split(':').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function parseIntSafe(raw, fallback) {
+    if (raw === undefined || raw === null || raw === '')
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function parseNetworkMode(raw) {
+    if (raw === 'none')
+        return 'none';
+    return 'bridge'; // bridge for unset / 'bridge' / junk
+}
+// ── Risk-tier inference ─────────────────────────────────────────────────────
+/**
+ * Default risk tier for a tool that doesn't carry an explicit
+ * `riskTier` annotation. Leverages the existing `mutates: boolean`
+ * field — mutating tools default to `caution`, read-only tools
+ * default to `safe`. Plugin tools without annotation get a safe
+ * default for free.
+ *
+ * Phase 5 ApprovalEngine integration treats explicit annotations as
+ * a FLOOR — DANGEROUS_PATTERNS can escalate but never demote. The
+ * inference here is the floor when no annotation exists at all.
+ */
+function inferDefaultRiskTier(mutates) {
+    return mutates ? 'caution' : 'safe';
+}
+// ── Reader ──────────────────────────────────────────────────────────────────
+/**
+ * Pure factory. Reads env vars + defaults into a frozen-snapshot
+ * SandboxConfig. Idempotent for a given env. The CLI calls this
+ * once at boot via the singleton factory below; tests pass a custom
+ * `env` argument.
+ */
+function readSandboxConfig(env = process.env) {
+    // v4.4 Phase 6 — default-on transition. AIDEN_SANDBOX is now
+    // enabled by default; users opt out with `AIDEN_SANDBOX=0`.
+    //
+    // v4.5 Phase 8a — the actual read goes through the runtimeToggles
+    // singleton so /sandbox slash-command flips and config.yaml
+    // overrides take effect without restart. When the singleton was
+    // initialised by the CLI it consults env > config.yaml > default;
+    // when not initialised (test bench) it falls back to env > default
+    // — the existing semantics.
+    //   unset / '1' / 'true' / junk → enabled
+    //   '0'                          → disabled
+    // Mirrors v4.2 Phase 6 (TCE) + v4.3 Phase 6 (browser depth)
+    // semantics exactly. The strict `!== '0'` check matches the
+    // pattern those phases set: any explicit "off" value disables;
+    // everything else (including unset) enables.
+    // v4.5 Phase 8a — when env (the readSandboxConfig input) is not the
+    // process env (test bench passing a custom env), honour the input
+    // directly to keep test isolation. Otherwise route through the
+    // runtimeToggles singleton.
+    const enabled = env === process.env
+        ? (0, runtimeToggles_1.getRuntimeToggles)().isEnabled('sandbox')
+        : env.AIDEN_SANDBOX !== '0';
+    // Allow/deny lists: defaults + user-provided extensions.
+    const customAllow = parseList(env.AIDEN_SANDBOX_ALLOW).map(resolveRealPath);
+    const customDeny = parseList(env.AIDEN_SANDBOX_DENY).map(resolveRealPath);
+    const fsAllowList = Array.from(new Set([...buildDefaultAllowList(), ...customAllow]));
+    const fsDenyList = Array.from(new Set([...buildDefaultDenyList(), ...customDeny]));
+    // Resource limits — string values pass through Docker as-is.
+    const resourceLimits = {
+        memory: env.AIDEN_SANDBOX_MEMORY ?? DEFAULT_RESOURCE_LIMITS.memory,
+        cpus: env.AIDEN_SANDBOX_CPUS ?? DEFAULT_RESOURCE_LIMITS.cpus,
+        pidsLimit: parseIntSafe(env.AIDEN_SANDBOX_PIDS, DEFAULT_RESOURCE_LIMITS.pidsLimit),
+    };
+    const networkMode = parseNetworkMode(env.AIDEN_SANDBOX_NETWORK);
+    const persistent = env.AIDEN_SANDBOX_PERSISTENT !== '0'; // default true
+    const idleReaperMs = parseIntSafe(env.AIDEN_SANDBOX_IDLE_MS, DEFAULT_IDLE_REAPER_MS);
+    const dryRun = env.AIDEN_DRYRUN === '1';
+    const image = typeof env.AIDEN_SANDBOX_IMAGE === 'string' && env.AIDEN_SANDBOX_IMAGE.trim().length > 0
+        ? env.AIDEN_SANDBOX_IMAGE.trim()
+        : DEFAULT_IMAGE;
+    // Phase 3 will route to 'docker' when enabled AND docker is
+    // available. Phase 1 reports the abstract default — Phase 3's
+    // runtime probe decides the actual route.
+    const defaultBackend = enabled ? 'docker' : 'local';
+    return {
+        enabled,
+        fsAllowList,
+        fsDenyList,
+        defaultBackend,
+        persistent,
+        resourceLimits,
+        networkMode,
+        idleReaperMs,
+        dryRun,
+        image,
+    };
+}
+// ── Singleton ───────────────────────────────────────────────────────────────
+let _singleton = null;
+let _toggleHookInstalled = false;
+/**
+ * Read the singleton sandbox config. Initialized on first call from
+ * `process.env` (matches v4.2 TurnState / v4.3 BrowserState lifecycle).
+ * Tests construct fresh configs via `readSandboxConfig(env)` directly
+ * — the singleton path is for production CLI startup.
+ */
+function getSandboxConfig() {
+    if (!_toggleHookInstalled) {
+        // v4.5 Phase 8a — invalidate the singleton when /sandbox toggles.
+        // Registered lazily on first read so test benches that build
+        // their own runtimeToggles + reset between cases don't carry
+        // hooks across instances.
+        try {
+            (0, runtimeToggles_1.getRuntimeToggles)().onChange('sandbox', () => { _singleton = null; });
+            _toggleHookInstalled = true;
+        }
+        catch { /* runtimeToggles import / init race — best-effort */ }
+    }
+    if (!_singleton)
+        _singleton = readSandboxConfig();
+    return _singleton;
+}
+/** Reset the singleton for test isolation. Production code never calls this. */
+function _resetSandboxConfigForTests() {
+    _singleton = null;
+    _toggleHookInstalled = false;
+    _clearRealPathCacheForTests();
+}

package/dist/core/v4/sandboxFs.js

@@ -0,0 +1,316 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/sandboxFs.ts — v4.4 Phase 2: filesystem allowlist enforcement.
+ *
+ * Pure in-process path policy decision module. Consulted by the six
+ * file_* tools (file_read, file_list, file_write, file_patch,
+ * file_copy, file_move, file_delete) BEFORE any disk I/O, so a
+ * decision can be returned to the agent without ever touching the
+ * filesystem when the answer is "no".
+ *
+ * Two-list model (mirrors Phase 1's `SandboxConfig`):
+ *   - fsDenyList  — sensitive paths the user never wants touched
+ *                   (.ssh, .aws, .env, /etc, /var, ...). Wins for
+ *                   BOTH read and write operations. Denylist always
+ *                   takes precedence over allowlist.
+ *   - fsAllowList — write-permitted roots (cwd, ~/Documents,
+ *                   ~/Downloads, ~/Desktop, os.tmpdir()). Writes /
+ *                   deletes outside these roots are refused. Reads
+ *                   are NOT constrained by the allowlist — reads
+ *                   only have to clear the denylist.
+ *
+ * Symlink defense:
+ *   - Realpath the target (or its first existing ancestor for
+ *     non-existent paths like file_write destinations). Symlink
+ *     bypass on allowlist roots is the canonical attack vector;
+ *     this module canonicalizes before checking.
+ *   - A path that is LEXICALLY under an allowlist root but
+ *     REALPATH'd outside (via a symlink) yields a distinct
+ *     `fs.symlink_escape` violation code.
+ *
+ * Non-existent path handling (Q-P2-3 default):
+ *   - Walk up to the first existing ancestor, realpath that, then
+ *     rejoin the trailing segments. This defends against
+ *     `<allowlist-root>/<symlinked-dir>/new-file.txt` writes.
+ *
+ * TOCTOU posture (Q-P2-5 default):
+ *   - Phase 2 is in-process. A racing actor could rename a
+ *     directory between our policy check and the tool's open()
+ *     call. Phase 3 (Docker sandbox) closes this gap at the OS
+ *     layer via container isolation. Phase 2 documents the gap
+ *     and accepts it for the strict-opt-in `AIDEN_SANDBOX=1`
+ *     period (default-off until Phase 6).
+ *
+ * Short-circuit semantics:
+ *   - When `config.enabled === false` (default through Phase 5),
+ *     `isPathAllowed` returns `{ allowed: true, resolvedPath: ...,
+ *     ... }` with no denylist/allowlist evaluation. Zero overhead
+ *     for users who haven't opted in. Phase 6 flips the gate but
+ *     the wire-in stays.
+ *
+ * The returned `PathPolicyDecision` shape is also forward-compatible
+ * with Phase 5's `FailureCategory.sandbox_violation` — the
+ * `violation.category` field is pre-populated with the constant
+ * Phase 5 will register in FailureClassifier.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWithin = isWithin;
+exports.realpathWithFallback = realpathWithFallback;
+exports.isPathAllowed = isPathAllowed;
+exports.violationEnvelope = violationEnvelope;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const sandboxConfig_1 = require("./sandboxConfig");
+// ── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * `tools/v4/utils/paths.ts#expandPath` re-implemented locally so the
+ * core module doesn't depend on a tools-layer helper. Keeps the
+ * import direction core ← tools (never the reverse).
+ */
+function expandPathInline(input, cwd) {
+    const home = node_os_1.default.homedir();
+    let p = input;
+    if (/^~[\\/]/i.test(p))
+        p = home + p.slice(1);
+    else if (/^Desktop[\\/]?$/i.test(p))
+        p = node_path_1.default.join(home, 'Desktop');
+    else if (/^Desktop[\\/]/i.test(p))
+        p = node_path_1.default.join(home, 'Desktop', p.slice(8));
+    if (node_path_1.default.isAbsolute(p))
+        return p;
+    if (/^[A-Z]:/i.test(p))
+        return p;
+    return node_path_1.default.join(cwd, p);
+}
+/**
+ * Boundary-aware containment check. `path.relative` avoids the
+ * `/home/user-evil` vs `/home/user` false positive that a naive
+ * `startsWith` would produce.
+ */
+function isWithin(child, parent) {
+    if (!child || !parent)
+        return false;
+    const rel = node_path_1.default.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !node_path_1.default.isAbsolute(rel));
+}
+/**
+ * Realpath a path that may not yet exist. Walks up to the first
+ * existing ancestor, realpaths that, then rejoins the trailing
+ * segments. Defends against `<allowlist>/<symlink>/new-file.txt`
+ * writes where the symlink mid-path points outside the allowlist.
+ *
+ * Idempotent: existing paths are realpath'd directly (single
+ * `resolveRealPath` call).
+ */
+function realpathWithFallback(input) {
+    // First, resolve the whole thing optimistically — if it exists,
+    // realpath handles it directly and we're done.
+    const resolved = node_path_1.default.resolve(input);
+    try {
+        if (node_fs_1.default.existsSync(resolved)) {
+            return (0, sandboxConfig_1.resolveRealPath)(resolved);
+        }
+    }
+    catch {
+        // existsSync shouldn't throw, but a permissions error on a
+        // parent dir could surface here on Windows. Fall through.
+    }
+    // Path doesn't exist yet — walk up.
+    let cur = resolved;
+    let tail = '';
+    // Guard against infinite loop on malformed paths (path.dirname
+    // of a root returns the root itself).
+    for (let i = 0; i < 4096; i++) {
+        const parent = node_path_1.default.dirname(cur);
+        if (parent === cur) {
+            // Reached filesystem root without finding any existing
+            // ancestor. Return the lexical resolve.
+            return resolved;
+        }
+        let parentExists = false;
+        try {
+            parentExists = node_fs_1.default.existsSync(parent);
+        }
+        catch {
+            parentExists = false;
+        }
+        if (parentExists) {
+            const parentReal = (0, sandboxConfig_1.resolveRealPath)(parent);
+            tail = tail ? node_path_1.default.join(node_path_1.default.basename(cur), tail) : node_path_1.default.basename(cur);
+            return node_path_1.default.join(parentReal, tail);
+        }
+        tail = tail ? node_path_1.default.join(node_path_1.default.basename(cur), tail) : node_path_1.default.basename(cur);
+        cur = parent;
+    }
+    return resolved;
+}
+function fmtList(list, max = 5) {
+    if (list.length === 0)
+        return '(none)';
+    if (list.length <= max)
+        return list.join(', ');
+    return list.slice(0, max).join(', ') + `, ... (${list.length - max} more)`;
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Evaluate a path against the active sandbox policy.
+ *
+ * @param rawPath  The original path string from tool args (untrusted).
+ * @param op       'read' | 'write' | 'delete' — determines whether the
+ *                 allowlist applies. 'read' = deny-only; 'write' /
+ *                 'delete' = allowlist required.
+ * @param cwd      The tool context's working directory, used to resolve
+ *                 relative paths the same way the file tools do.
+ * @param config   Optional config override (default = singleton from
+ *                 `getSandboxConfig()`). Tests pass a custom config.
+ *
+ * @returns `{ allowed: true, ... }` when the operation may proceed,
+ *          or `{ allowed: false, violation: {...}, ... }` with a
+ *          structured `FsViolation` when it must be refused. Tools
+ *          should forward the violation into a `sandbox_violation`
+ *          envelope on the result object alongside `success: false`.
+ *
+ * Behavior when `config.enabled === false` (Phase 1-5 default):
+ * the function still resolves the path (so the caller can use
+ * `resolvedPath` uniformly), but returns `allowed: true` without
+ * evaluating either list. Zero runtime cost beyond expand+resolve.
+ */
+function isPathAllowed(rawPath, op, cwd, config = (0, sandboxConfig_1.getSandboxConfig)()) {
+    const requestedPath = rawPath;
+    const expandedPath = expandPathInline(rawPath, cwd);
+    // Short-circuit when sandbox is disabled. Still produce a useful
+    // resolvedPath so the tool can keep its current single-codepath
+    // structure (resolve once, use the resolved path).
+    if (!config.enabled) {
+        return {
+            allowed: true,
+            resolvedPath: expandedPath,
+            requestedPath,
+            expandedPath,
+            op,
+        };
+    }
+    // Lexical path-traversal sniff: if `rawPath` was a relative input
+    // that escapes `cwd` via `..`, refuse with a clear code BEFORE
+    // realpath touches the disk. This is belt-and-suspenders — realpath
+    // would catch most cases via the symlink-escape branch — but a
+    // structured `fs.path_traversal` reads more cleanly in logs.
+    if (!node_path_1.default.isAbsolute(rawPath) && !/^[A-Z]:/i.test(rawPath) && !/^~[\\/]/i.test(rawPath)) {
+        const cwdReal = (0, sandboxConfig_1.resolveRealPath)(cwd);
+        const expReal = node_path_1.default.resolve(cwd, rawPath);
+        if (!isWithin(expReal, cwdReal) && rawPath.includes('..')) {
+            // Don't treat this as fatal yet — a relative path can legitimately
+            // escape cwd (e.g. `../tmp/x` when cwd is under tmp). We only flag
+            // it if it ALSO lands outside both lists, which the standard checks
+            // below will catch. Leaving the sniff in as a `path_traversal`
+            // upgrade for the escape-with-no-allowlist-hit case.
+        }
+    }
+    const resolvedPath = realpathWithFallback(expandedPath);
+    const base = {
+        resolvedPath,
+        requestedPath,
+        expandedPath,
+        op,
+    };
+    // ── Denylist (always wins, both read and write) ───────────────────────
+    for (const denied of config.fsDenyList) {
+        if (isWithin(resolvedPath, denied) || resolvedPath === denied) {
+            return {
+                ...base,
+                allowed: false,
+                violation: {
+                    code: 'fs.sensitive_path',
+                    matchedPolicy: denied,
+                    category: 'sandbox_violation',
+                    retryable: false,
+                    message: `Sandbox: path "${resolvedPath}" is under the sensitive denylist entry ` +
+                        `"${denied}". Reads and writes are both refused. ` +
+                        `(Override by extending AIDEN_SANDBOX_ALLOW is not sufficient — the ` +
+                        `denylist takes precedence.)`,
+                },
+            };
+        }
+    }
+    // ── Allowlist (write/delete only — reads pass through after denylist) ─
+    if (op === 'read') {
+        return { ...base, allowed: true };
+    }
+    // Symlink-escape detection: resolvedPath escaped the allowlist
+    // tree, but expandedPath was LEXICALLY under it. That's the
+    // classic allowlist-bypass-via-symlink pattern.
+    let lexicalUnderAllow = false;
+    let realUnderAllow = false;
+    let matchedAllow = '';
+    for (const allowed of config.fsAllowList) {
+        if (isWithin(expandedPath, allowed) || expandedPath === allowed) {
+            lexicalUnderAllow = true;
+        }
+        if (isWithin(resolvedPath, allowed) || resolvedPath === allowed) {
+            realUnderAllow = true;
+            matchedAllow = allowed;
+            break;
+        }
+    }
+    if (realUnderAllow) {
+        return { ...base, allowed: true };
+    }
+    if (lexicalUnderAllow) {
+        return {
+            ...base,
+            allowed: false,
+            violation: {
+                code: 'fs.symlink_escape',
+                matchedPolicy: '',
+                category: 'sandbox_violation',
+                retryable: false,
+                message: `Sandbox: path "${expandedPath}" appears to live under an allowlisted ` +
+                    `root, but its real path "${resolvedPath}" is outside every allowlist ` +
+                    `entry. A symlink in the path likely points outside the sandbox.`,
+            },
+        };
+    }
+    // Plain write-outside-allowlist. Most common refusal.
+    return {
+        ...base,
+        allowed: false,
+        violation: {
+            code: 'fs.write_outside_allowlist',
+            matchedPolicy: matchedAllow,
+            category: 'sandbox_violation',
+            retryable: false,
+            message: `Sandbox: ${op} target "${resolvedPath}" is not under any allowlisted ` +
+                `directory. Allowed roots: ${fmtList(config.fsAllowList)}. ` +
+                `(Extend via AIDEN_SANDBOX_ALLOW=<colon-separated-paths>.)`,
+        },
+    };
+}
+/**
+ * Convenience: build the structured envelope the file tools attach
+ * to their result objects when a policy denial occurs. Centralises
+ * the wire format so all six tools serialise the same shape.
+ */
+function violationEnvelope(decision) {
+    if (!decision.violation) {
+        // Defensive — callers should only call this on denied decisions.
+        throw new Error('violationEnvelope called on allowed decision');
+    }
+    return {
+        code: decision.violation.code,
+        matched_policy: decision.violation.matchedPolicy,
+        requested_path: decision.requestedPath,
+        resolved_path: decision.resolvedPath,
+        retryable: false,
+        category: 'sandbox_violation',
+    };
+}

package/dist/core/v4/suggestionCatalog.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/suggestionCatalog.ts — v4.5 Phase 8b.
+ *
+ * Pre-rendered user-facing copy for each contextual suggestion slot.
+ * Centralised here so future tone tuning / i18n can change one file
+ * without touching the engine.
+ *
+ * Style guide (approved tone Q-P8b-5(b)):
+ *   - One line per tip.
+ *   - ≤ 90 visible chars (room for indentation + emoji).
+ *   - "💡 tip:" prefix, lowercase command + brief why.
+ *   - No trailing punctuation gymnastics.
+ *   - No second-person preaching ("you should" → drop).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUGGESTION_COPY = void 0;
+exports.suggestionMessageFor = suggestionMessageFor;
+/**
+ * Slot → message map. The engine resolves the slot and the
+ * catalog renders the matching copy.
+ */
+exports.SUGGESTION_COPY = Object.freeze({
+    sandbox: '💡 tip: enable /sandbox on for a safer guardrail against destructive ops.',
+    browser_depth: '💡 tip: enable /browser-depth on to capture page state + auto-retry stale refs.',
+    daemon_scheduling: '💡 tip: this looks like a recurring task — `aiden cron add` or `aiden trigger add file` can run it on a schedule.',
+    tce_recovery: '💡 tip: enable /tce on so Aiden classifies tool failures + auto-recovers.',
+});
+/**
+ * Look up the rendered tip string for a slot. Pure — caller decides
+ * when to display (`display.dim()` is the conventional sink).
+ */
+function suggestionMessageFor(slot) {
+    return exports.SUGGESTION_COPY[slot];
+}