@miller-tech/uap 1.127.0 → 1.128.1

package/dist/delivery/snapshot.js

@@ -3,31 +3,314 @@
  *
  * Captures the project state before the convergence loop runs so deliver can
  * roll back if it ends up worse (by the real gates' measure) than it started.
- * Excludes heavy/derived trees (.git, node_modules) — they aren't part of the
- * task's source and would make snapshots slow.
+ * Excludes heavy/derived DIRECTORIES (.git, node_modules, target, .venv, …):
+ * they aren't part of the task's source and would make snapshots slow. The
+ * contract is symmetric — an excluded directory is neither snapshotted nor
+ * touched by restore, at any depth. Files sharing an excluded name (e.g. a
+ * script called `build`) are snapshotted normally.
+ *
+ * Hardening (2026-07-08, after the project-i incident where a 424 GB Rust
+ * `target/` tree was copied into a 61 GB RAM tmpfs):
+ *  - snapshots land on real disk (~/.cache/uap/snapshots, UAP_SNAPSHOT_DIR
+ *    overrides — absolute paths only), never os.tmpdir(), which is RAM-backed
+ *    on many Linux setups;
+ *  - the source tree is size-guarded before copying (UAP_SNAPSHOT_MAX_MB,
+ *    default 4096) — over the cap, snapshotTree returns null and the caller
+ *    degrades to "no rollback this run" instead of exhausting the machine;
+ *  - snapshotTree never throws: any failure cleans up its partial copy and
+ *    returns null;
+ *  - restoreTree validates the snapshot before touching the project, restores
+ *    copy-first (prune extras, then merge back) so an interrupted restore
+ *    never leaves a gutted tree, and marks the snapshot preserve-on-failure
+ *    so the reaper won't collect the only good copy;
+ *  - each snapshot carries a pid marker; stale snapshots from dead processes
+ *    (crashes, SIGKILL, ENOSPC mid-copy) are reaped before a new one is taken.
+ */
+import { cpSync, rmSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, writeFileSync, lstatSync, statSync, } from 'fs';
+import { join, basename, isAbsolute, resolve } from 'path';
+import { tmpdir, homedir } from 'os';
+const EXCLUDE = new Set([
+    // VCS / UAP-internal
+    '.git',
+    '.worktrees',
+    '.uap-deliver',
+    '.uap-backups',
+    // JS
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    '.turbo',
+    '.cache',
+    '.parcel-cache',
+    // Rust / JVM / Go
+    'target',
+    '.gradle',
+    'vendor',
+    // Python
+    '.venv',
+    'venv',
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    '.ruff_cache',
+    '.tox',
+]);
+/** Marker written inside each snapshot so the reaper can tell live from stale. */
+const META_FILE = '.uap-snap.json';
+const SNAP_PREFIX = 'uap-snap-';
+/** Age past which a marker-less (legacy/partial) snapshot is considered stale. */
+const LEGACY_STALE_MS = 24 * 60 * 60 * 1000;
+/** Backstop against pid reuse pinning a dead snapshot forever. */
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_MB = 4096;
+/** True for a directory whose name marks it as derived/heavy (dir-only contract). */
+function isExcludedDir(path, name) {
+    if (!EXCLUDE.has(name))
+        return false;
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Disk-backed base directory for snapshots (never os.tmpdir — often RAM tmpfs). */
+export function snapshotBaseDir() {
+    const raw = process.env.UAP_SNAPSHOT_DIR?.trim();
+    // Relative/garbage overrides silently landing inside the project tree would
+    // snapshot into the thing being snapshotted — absolute paths only.
+    const base = raw && isAbsolute(raw) ? resolve(raw) : join(homedir(), '.cache', 'uap', 'snapshots');
+    mkdirSync(base, { recursive: true });
+    return base;
+}
+function maxSnapshotBytes() {
+    const mb = Number(process.env.UAP_SNAPSHOT_MAX_MB);
+    return (Number.isFinite(mb) && mb > 0 ? mb : DEFAULT_MAX_MB) * 1024 * 1024;
+}
+/**
+ * Sum file sizes under root (skipping excluded dirs and symlinks), bailing out
+ * as soon as the running total exceeds `limit` so huge trees cost one early
+ * partial walk, not a full traversal.
+ */
+function treeSizeExceeds(root, limit) {
+    let total = 0;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue; // unreadable dir — the copy will surface real problems
+        }
+        for (const name of entries) {
+            const path = join(dir, name);
+            let st;
+            try {
+                st = lstatSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink())
+                continue;
+            if (st.isDirectory()) {
+                if (!EXCLUDE.has(name))
+                    stack.push(path);
+            }
+            else {
+                total += st.size;
+                if (total > limit)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but isn't ours.
+        return err.code === 'EPERM';
+    }
+}
+function isStaleSnapshot(path) {
+    try {
+        const metaPath = join(path, META_FILE);
+        // The tmpdir sweep reads world-writable locations: a planted FIFO or
+        // symlink-to-/dev/zero marker must not hang or balloon the read.
+        const st = lstatSync(metaPath);
+        if (!st.isFile() || st.size > 4096)
+            throw new Error('untrusted marker');
+        const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+        if (meta.preserve === true)
+            return false;
+        if (!Number.isInteger(meta.pid) || meta.pid <= 1)
+            return true;
+        const created = Date.parse(meta.created ?? '');
+        if (Number.isFinite(created) && Date.now() - created > MAX_AGE_MS)
+            return true;
+        return !pidAlive(meta.pid);
+    }
+    catch {
+        // No/unreadable/untrusted marker: a partial copy or a pre-hardening
+        // snapshot. Only reap once it is old enough that no live run can
+        // plausibly own it.
+        try {
+            return Date.now() - statSync(path).mtimeMs > LEGACY_STALE_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Remove snapshots left behind by dead processes (crash, SIGKILL, ENOSPC
+ * mid-copy). Sweeps the snapshot base dir, plus os.tmpdir() for snapshots
+ * created by pre-hardening versions (UAP_SNAPSHOT_SKIP_TMP_SWEEP=1 disables
+ * the legacy sweep). Fail-soft: reaping must never block a delivery run.
+ */
+export function reapStaleSnapshots() {
+    const bases = new Set([snapshotBaseDir()]);
+    if (process.env.UAP_SNAPSHOT_SKIP_TMP_SWEEP !== '1')
+        bases.add(tmpdir());
+    for (const base of bases) {
+        let entries;
+        try {
+            entries = readdirSync(base);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (!name.startsWith(SNAP_PREFIX))
+                continue;
+            const path = join(base, name);
+            try {
+                if (isStaleSnapshot(path))
+                    rmSync(path, { recursive: true, force: true });
+            }
+            catch {
+                /* fail-soft */
+            }
+        }
+    }
+}
+/**
+ * Copy the project tree (minus excluded dirs) to a disk-backed snapshot dir.
+ * Returns the snapshot path, or null when the snapshot is skipped (tree over
+ * the size cap) or fails for any reason — callers must treat null as "no
+ * rollback available for this run", not as an error. Never throws.
  */
-import { cpSync, rmSync, mkdtempSync, readdirSync } from 'fs';
-import { join, basename } from 'path';
-import { tmpdir } from 'os';
-const EXCLUDE = new Set(['.git', 'node_modules', '.uap-deliver']);
-/** Copy the project tree (minus excluded dirs) to a temp dir; return its path. */
 export function snapshotTree(root) {
-    const snap = mkdtempSync(join(tmpdir(), 'uap-snap-'));
-    cpSync(root, snap, {
-        recursive: true,
-        filter: (src) => !EXCLUDE.has(basename(src)),
-    });
-    return snap;
-}
-/** Restore the project tree from a snapshot: drop current entries, copy back. */
-export function restoreTree(root, snap) {
-    for (const entry of readdirSync(root)) {
-        if (EXCLUDE.has(entry))
+    let snap;
+    try {
+        reapStaleSnapshots();
+        const limit = maxSnapshotBytes();
+        if (treeSizeExceeds(root, limit)) {
+            console.warn(`  no-regress: snapshot skipped — project tree exceeds ${Math.round(limit / (1024 * 1024))} MB ` +
+                '(raise UAP_SNAPSHOT_MAX_MB to override)');
+            return null;
+        }
+        snap = mkdtempSync(join(snapshotBaseDir(), SNAP_PREFIX));
+    }
+    catch (err) {
+        console.warn(`  no-regress: snapshot unavailable (${err.message}) — rollback disabled for this run`);
+        return null;
+    }
+    try {
+        cpSync(root, snap, {
+            recursive: true,
+            // Never filter the root itself — a project dir named `build`/`dist`/…
+            // must still snapshot its contents, not produce an empty snapshot.
+            filter: (src) => src === root || !isExcludedDir(src, basename(src)),
+        });
+        writeFileSync(join(snap, META_FILE), JSON.stringify({ pid: process.pid, created: new Date().toISOString() }));
+        return snap;
+    }
+    catch (err) {
+        // Never leak a partial snapshot (the original failure mode: ENOSPC
+        // mid-copy left tens of GB behind).
+        rmSync(snap, { recursive: true, force: true });
+        console.warn(`  no-regress: snapshot failed (${err.message}) — rollback disabled for this run`);
+        return null;
+    }
+}
+/**
+ * Delete entries under rootDir that the snapshot doesn't contain (or whose
+ * file/dir type flipped), recursing with the same excluded-dir contract as
+ * the snapshot filter so nested excluded trees (a workspace's node_modules,
+ * a nested target/) survive rollback untouched.
+ */
+function pruneToSnapshot(rootDir, snapDir) {
+    for (const entry of readdirSync(rootDir)) {
+        const rootPath = join(rootDir, entry);
+        let rootStat;
+        try {
+            rootStat = lstatSync(rootPath);
+        }
+        catch {
+            continue;
+        }
+        if (rootStat.isDirectory() && EXCLUDE.has(entry))
             continue;
-        rmSync(join(root, entry), { recursive: true, force: true });
+        let snapStat = null;
+        try {
+            snapStat = lstatSync(join(snapDir, entry));
+        }
+        catch {
+            /* not in snapshot */
+        }
+        if (!snapStat) {
+            rmSync(rootPath, { recursive: true, force: true });
+        }
+        else if (rootStat.isDirectory() && snapStat.isDirectory()) {
+            pruneToSnapshot(rootPath, join(snapDir, entry));
+        }
+        else if (rootStat.isDirectory() !== snapStat.isDirectory()) {
+            // Type flip (file↔dir): remove so the merge copy can recreate it.
+            rmSync(rootPath, { recursive: true, force: true });
+        }
+    }
+}
+/**
+ * Restore the project tree from a snapshot. Validates the snapshot BEFORE
+ * touching the project, then prunes extras and merge-copies the snapshot
+ * back — copy-first ordering so an interruption leaves a recoverable union
+ * of both trees, never a gutted project. On failure the snapshot is marked
+ * preserve (reaper-immune) and the error is rethrown.
+ */
+export function restoreTree(root, snap) {
+    const entries = readdirSync(snap); // throws if the snapshot is gone — root untouched
+    if (!entries.includes(META_FILE)) {
+        throw new Error(`refusing to restore from ${snap}: missing ${META_FILE} marker`);
+    }
+    try {
+        pruneToSnapshot(root, snap);
+        for (const entry of entries) {
+            if (entry === META_FILE)
+                continue;
+            cpSync(join(snap, entry), join(root, entry), { recursive: true });
+        }
     }
-    for (const entry of readdirSync(snap)) {
-        cpSync(join(snap, entry), join(root, entry), { recursive: true });
+    catch (err) {
+        try {
+            writeFileSync(join(snap, META_FILE), JSON.stringify({ pid: process.pid, created: new Date().toISOString(), preserve: true }));
+        }
+        catch {
+            /* marker rewrite is best-effort */
+        }
+        console.warn(`  no-regress: restore FAILED — snapshot preserved at ${snap}`);
+        throw err;
     }
 }
 /** Remove a snapshot directory. */

package/dist/delivery/snapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/delivery/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC;AAElE,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC;IACtD,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE;QACjB,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;KAC7C,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY;IACpD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QACjC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/delivery/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,MAAM,EACN,MAAM,EACN,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,aAAa,EACb,SAAS,EACT,QAAQ,GACT,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAErC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC;IACtB,qBAAqB;IACrB,MAAM;IACN,YAAY;IACZ,cAAc;IACd,cAAc;IACd,KAAK;IACL,cAAc;IACd,MAAM;IACN,OAAO;IACP,KAAK;IACL,UAAU;IACV,OAAO;IACP,OAAO;IACP,aAAa;IACb,QAAQ;IACR,QAAQ;IACR,eAAe;IACf,kBAAkB;IAClB,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,SAAS;IACT,OAAO;IACP,MAAM;IACN,aAAa;IACb,eAAe;IACf,aAAa;IACb,aAAa;IACb,MAAM;CACP,CAAC,CAAC;AAEH,kFAAkF;AAClF,MAAM,SAAS,GAAG,gBAAgB,CAAC;AAEnC,MAAM,WAAW,GAAG,WAAW,CAAC;AAEhC,kFAAkF;AAClF,MAAM,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE5C,kEAAkE;AAClE,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3C,MAAM,cAAc,GAAG,IAAI,CAAC;AAS5B,qFAAqF;AACrF,SAAS,aAAa,CAAC,IAAY,EAAE,IAAY;IAC/C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACjD,4EAA4E;IAC5E,mEAAmE;IACnE,MAAM,IAAI,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IACnG,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACnD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,IAAY,EAAE,KAAa;IAClD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;IACrB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACzB,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,uDAAuD;QACnE,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC7B,IAAI,EAAE,CAAC;YACP,IAAI,CAAC;gBACH,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,IAAI,EAAE,CAAC,cAAc,EAAE;gBAAE,SAAS;YAClC,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;gBACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3C,CAAC;iBAAM,CAAC;gBACN,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC;gBACjB,IAAI,KAAK,GAAG,KAAK;oBAAE,OAAO,IAAI,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,iDAAiD;QACjD,OAAQ,GAA6B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACvC,qEAAqE;QACrE,iEAAiE;QACjE,MAAM,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;QACxE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAa,CAAC;QACrE,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAK,IAAI,CAAC,GAAc,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC/C,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,UAAU;YAAE,OAAO,IAAI,CAAC;QAC/E,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAa,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,iEAAiE;QACjE,oBAAoB;QACpB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,eAAe,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;IAC3C,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,KAAK,GAAG;QAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACzE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;gBAAE,SAAS;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC;gBACH,IAAI,eAAe,CAAC,IAAI,CAAC;oBAAE,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5E,CAAC;YAAC,MAAM,CAAC;gBACP,eAAe;YACjB,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,kBAAkB,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,IAAI,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CACV,yDAAyD,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,MAAM;gBAC9F,yCAAyC,CAC5C,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,uCAAwC,GAAa,CAAC,OAAO,oCAAoC,CAAC,CAAC;QAChH,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE;YACjB,SAAS,EAAE,IAAI;YACf,sEAAsE;YACtE,mEAAmE;YACnE,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;SACpE,CAAC,CAAC;QACH,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;QAC9G,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,mEAAmE;QACnE,oCAAoC;QACpC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,kCAAmC,GAAa,CAAC,OAAO,oCAAoC,CAAC,CAAC;QAC3G,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,OAAe,EAAE,OAAe;IACvD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtC,IAAI,QAAQ,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,CAAC,WAAW,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAC3D,IAAI,QAAQ,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACH,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,qBAAqB;QACvB,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;aAAM,IAAI,QAAQ,CAAC,WAAW,EAAE,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;YAC5D,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAClD,CAAC;aAAM,IAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;YAC7D,kEAAkE;YAClE,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY;IACpD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,kDAAkD;IACrF,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,aAAa,SAAS,SAAS,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,CAAC;QACH,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAClC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YACH,aAAa,CACX,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EACrB,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CACxF,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;QACrC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,wDAAwD,IAAI,EAAE,CAAC,CAAC;QAC7E,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACjD,CAAC"}

package/docs/INDEX.md

@@ -1,6 +1,11 @@
 # UAP Documentation
 
-The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.93.1) — the discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line.
+The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.124.1) — the discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line.
+
+> **Reviewing the system?** The reverse-engineered, code-verified reference set lives in
+> [`documentation/`](../documentation/architecture.md): architecture, flows, permissions
+> (incl. trust boundaries and enforcement gaps), variables/secrets, scheduled work, and
+> embedded automation. Start there for an honest map of what's enforced vs. documented.
 
 New here? The friendliest way in is the **[Delivery Pipeline tour](guides/DELIVERY_PIPELINE.md)** — it walks the whole factory floor, station by station, showing where agents normally break and what UAP puts in place to catch it. Then grab the [Quickstart](getting-started/QUICKSTART.md).
 
@@ -45,6 +50,7 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [Memory](guides/MEMORY.md) | The 4-tier memory system, write-gates, semantic recall |
 | [MCP Router](guides/MCP_ROUTER.md) | Token-optimizing tool proxy + FTS5 output compression |
 | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) | Branch-per-feature isolation, auto-PR, enforcement |
+| [Sandbox](guides/SANDBOX.md) | Kernel-level (bubblewrap) write isolation — the boundary that survives `--dangerously-skip-permissions` |
 | [Policies](guides/POLICIES.md) | Executable policy gates that block non-compliant tool calls |
 | [Multi-Model Routing](guides/MULTI_MODEL.md) | Plan → route → execute across 7 model profiles |
 | [Droids & Skills](guides/DROIDS_AND_SKILLS.md) | 38 expert droids, 32 skills, the expert router |

package/docs/architecture/OVERVIEW.md

@@ -1,6 +1,11 @@
 # UAP Architecture Overview
 
-`v1.93.1` · 223 TypeScript modules across 18 `src/` subsystems · 170+ test suites
+`v1.124.1` · ~223 TypeScript modules across 18 `src/` subsystems · 200+ test suites
+
+> **Code-verified reference:** this narrative overview is the intent-level floor plan. For
+> the reverse-engineered, implementation-accurate map — including trust boundaries,
+> enforcement planes, and where enforcement diverges from the prose — see
+> [`documentation/architecture.md`](../../documentation/architecture.md).
 
 > **🏭 Where this fits:** Whole pipeline — this is the factory-floor map. A bare
 > agent walks work from an idea to a shipped change with no stations in between,

package/docs/guides/DELIVER.md

@@ -137,6 +137,19 @@ uap deliver "add the orders endpoint" --until-deployed
 | `--project-root <path>` | Project whose gates define delivery (default: cwd) |
 | `--dry-run` | Show detected gates and plan without calling the model |
 | `--json` | Emit a JSON result |
+| `--keep-best` | Never regress: snapshot the project first, roll back if the run ends with a worse required-gate score |
+
+### `--keep-best` snapshots
+
+The pre-run snapshot lands on real disk under `~/.cache/uap/snapshots`
+(`UAP_SNAPSHOT_DIR` overrides; absolute paths only) — never `/tmp`, which is
+RAM-backed on many Linux systems. Derived directories (`.git`,
+`node_modules`, `target`, `.venv`, `dist`, `build`, …) are neither
+snapshotted nor touched by a rollback, at any depth. Trees larger than
+`UAP_SNAPSHOT_MAX_MB` (default 4096) skip the snapshot and the run proceeds
+with rollback disabled. Snapshots orphaned by killed runs are reaped
+automatically on the next `--keep-best` run; a snapshot whose restore failed
+is preserved and its path printed.
 
 ---
 

package/docs/guides/SANDBOX.md

@@ -0,0 +1,99 @@
+# The Sandbox — kernel-level isolation for skip-permissions sessions
+
+> **🏭 Where this fits:** Isolation station. The hook-based worktree/workdir guards
+> (`PreToolUse`) are the everyday boundary, but a harness launched with
+> `--dangerously-skip-permissions` ignores hook denials entirely. The sandbox is the
+> compensating control that *can't* be skipped — because it's enforced by the Linux
+> kernel, not by a hook the agent's flags can wave away.
+> **What it delivers:** an agent that can read your whole machine but can only *write*
+> inside the job's workdir (plus a few caches), so a mis-fired `rm -rf` or an errant Write
+> to `~/.ssh` fails at the kernel with `EROFS`.
+
+## What it is
+
+`uap sandbox -- <command>` runs `<command>` inside a **bubblewrap (`bwrap`)** mount
+namespace: the whole filesystem is bind-mounted **read-only**, with a small set of
+**writable holes** punched through. This binds Write/Edit tools, `Bash`, and every
+subprocess they spawn equally — nothing that runs inside can write outside the holes.
+
+It is *not* a container, *not* a VM, and *not* env-variable restriction. It is a Linux
+namespace, so it has near-zero startup cost and shares the host network (deliberately — the
+agent still needs to reach the local proxy at `127.0.0.1:4000`).
+
+```bash
+# Typical wiring: sandbox wraps the whole harness invocation
+uap sandbox -- env … claude --dangerously-skip-permissions …
+```
+
+## What's writable (and nothing else)
+
+`src/cli/sandbox.ts:86-105` binds these as read-write; everything else is read-only:
+
+- the **resolved workdir** (the job's project directory)
+- `/tmp`, a fresh tmpfs `/var/tmp`, and `/run`
+- `~/.claude`, `~/.cache`, `~/.npm` (if present) — so the harness and package tooling work
+- anything listed in **`UAP_SANDBOX_ALLOW`** (colon-separated extra prefixes)
+
+Plus `--unshare-pid --die-with-parent --new-session` so the sandboxed process tree can't
+outlive or escape its parent.
+
+**Guardrail:** it refuses to sandbox an over-broad workdir — `$HOME`, `/`, and `/home` are
+rejected (`sandbox.ts:81-83`), because a writable hole that big would defeat the point.
+
+**Requires bwrap:** if `bwrap` isn't installed, `uap sandbox` fails with exit 127 rather
+than silently running your command unsandboxed. There is no unsafe fallback.
+
+## Why hooks aren't enough
+
+The `workdir-scope` and `worktree_required` `PreToolUse` enforcers return an exit-2 deny to
+block an out-of-bounds edit — but a harness run with `--dangerously-skip-permissions`
+**does not consult PreToolUse hooks at all**, so those denials never fire. The sandbox is
+the answer: the kernel doesn't care what flags the harness was launched with. This is the
+one boundary that survives skip-permissions (see also `documentation/permissions.md`, which
+maps every enforcement plane and where each one holds or fails).
+
+## Browser MCP tool stripping (why it's here)
+
+A subtlety worth knowing: when a session runs under `uap sandbox`, the Chrome extension
+socket that the `mcp__claude-in-chrome__*` browser tools rely on is **not** bound into the
+namespace — so those tools would connect to nothing and the model loops on a dead end.
+
+The sandbox handles this without changing the tool list itself. `sandboxCustomHeaders()`
+(`sandbox.ts:30-39`) appends a marker header `X-Uap-Sandbox: 1` to
+`ANTHROPIC_CUSTOM_HEADERS`, which the harness forwards on every request. The **proxy** reads
+it and calls `_strip_sandbox_unreachable_tools` (`anthropic_proxy.py:4393`), removing any
+tool whose name starts with a prefix in `PROXY_SANDBOX_UNREACHABLE_PREFIXES` (default
+`mcp__claude-in-chrome__`). The model never sees the unreachable browser tools and falls
+back to `WebFetch` / local reads instead. (This is the "strip unreachable browser MCP tools
+from sandboxed sessions" change from v1.63.0.)
+
+## Escape hatches (operator-only)
+
+| Variable | Effect |
+|---|---|
+| `UAP_SANDBOX_OFF=1` | Run the command as-is, no sandbox (for debugging). |
+| `UAP_SANDBOX_ALLOW=/path:/other` | Extra writable prefixes. |
+| `UAP_SANDBOX_WORKDIR=/path` | Override the resolved workdir. |
+| `PROXY_SANDBOX_UNREACHABLE_PREFIXES` | Change which tool prefixes are stripped (proxy side). |
+
+Treat all of these as trusted-launch-environment settings — they widen the boundary, and
+the model should never be able to set them for itself.
+
+## Limits (be honest about them)
+
+- **Network is not restricted.** A sandboxed agent can still make outbound network calls;
+  the sandbox is a *filesystem* boundary. Egress control is the proxy's job
+  (`ANTHROPIC_PASSTHROUGH_MODELS=__local_only__` for the cloud path).
+- **The writable holes are real writable areas.** Anything under the workdir, `/tmp`, or
+  `~/.cache`/`~/.claude`/`~/.npm` can be modified — including caches that persist across
+  runs.
+- **It only helps if you actually launch under it.** The workdir boundary is only real for
+  sessions started with `uap sandbox`; a plain skip-permissions session has no filesystem
+  boundary at all.
+
+## Related
+
+- `documentation/permissions.md` — all enforcement planes, the resource matrix, and the
+  findings (including why the hook plane doesn't survive skip-permissions)
+- [Worktree Workflow](WORKTREE_WORKFLOW.md) — the everyday (hook-based) isolation boundary
+- [Policies](POLICIES.md) — the PreToolUse gate the sandbox backstops

package/docs/reference/CONFIGURATION.md

@@ -89,6 +89,8 @@ Top level: `version`, `project`, `memory`, `worktree`, `costOptimization`,
 | `UAP_PARALLEL` | `false` disables parallelism | enabled |
 | `UAP_BENCHMARK_MODE` | `true` enables benchmark template mode | off |
 | `UAP_BENCHMARK_PARALLEL` | Parallel model count in benchmarks | — |
+| `UAP_SNAPSHOT_DIR` | Base dir for `--keep-best` snapshots (absolute path) | `~/.cache/uap/snapshots` |
+| `UAP_SNAPSHOT_MAX_MB` | Skip the `--keep-best` snapshot (rollback disabled) when the tree exceeds this size | `4096` |
 | `HERMES_HOME` | Hermes home dir | `~/.hermes` |
 | `FACTORY_PROJECT_DIR` | Project dir in Factory hook commands | — |
 | `FORGE_UAP_PROJECT` | Project dir in ForgeCode hook scripts | `.` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.127.0",
+  "version": "1.128.1",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,8 @@
     "dev": "tsc --watch",
     "start": "node dist/bin/cli.js",
     "test": "vitest",
+    "test:ci": "vitest run",
+    "test:enforcers": "python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
     "lint": "eslint src --ext .ts",

package/templates/hooks/uap-policy-gate.sh

@@ -42,18 +42,73 @@ ARGS="$(printf '%s' "$PAYLOAD" | python3 -c 'import json,sys; d=json.load(sys.st
 
 [[ -z "$TOOL" ]] && exit 0
 
+# FAIL-CLOSED for the enforcement control surface. The gate is fail-SOFT by
+# design (a broken/absent enforcer must not wedge ALL work) — but that same
+# fail-open makes anything that BREAKS the enforcer a silent bypass of the
+# self-protect control. So: if THIS operation touches the enforcement surface
+# (policy DB/enforcers, .uap.json, proxy env, hook scripts) or sets a
+# bypass/relax flag, the gate fails CLOSED (exit 2) whenever the self-protect
+# enforcer cannot actually run and make the call. Normal ops keep failing open.
+SEC_SENSITIVE="$(printf '%s' "$ARGS" | TOOL="$TOOL" python3 -c '
+import json, os, re, sys
+try: a = json.loads(sys.stdin.read() or "{}")
+except Exception: a = {}
+markers = ("/.policy-tools/", "/src/policies/", "/policies/", "/.uap.json",
+           ".uap.json", "/.uap/", "anthropic-proxy.env", "uap-policy-gate.sh",
+           "uap-reactor-prompt.sh", "pre-tool-use")
+target = a.get("file_path") or a.get("path") or a.get("target") or ""
+cmd = a.get("command") or ""
+low = ("/" + str(target)).lower()
+hit = any(m in low for m in markers)
+bypass = re.search(
+    r"UAP_DELIVER_BYPASS\s*=\s*[\x27\"]?1|UAP_ENFORCE_DELIVERY\s*=\s*[\x27\"]?(advisory|off|0|false|no)"
+    r"|UAP_SELF_PROTECT_OFF\s*=\s*[\x27\"]?1|UAP_NO_WORKTREE\s*=\s*[\x27\"]?1|UAP_WORKDIR_SCOPE_OFF\s*=\s*[\x27\"]?1",
+    cmd, re.I)
+print("1" if (hit or bypass) else "0")
+' 2>/dev/null || echo 1)"
+
+# Operator out-of-band override disables the fail-closed guard too.
+[[ "${UAP_SELF_PROTECT_OFF:-}" == "1" ]] && SEC_SENSITIVE=0
+
+fail_closed() {
+  echo "[UAP policy gate] FAIL-CLOSED: this operation touches the enforcement control surface but the self-protect enforcer could not run (${1:-machinery unavailable}). Blocked so a broken/absent gate can't become a bypass. (Operator override: UAP_SELF_PROTECT_OFF=1.)" >&2
+  exit 2
+}
+
 DB="$MAIN_ROOT/agents/data/memory/policies.db"
-[[ ! -f "$DB" ]] && exit 0
+if [[ ! -f "$DB" ]]; then
+  [[ "$SEC_SENSITIVE" == "1" ]] && fail_closed "policies.db not found"
+  exit 0
+fi
+if ! command -v sqlite3 >/dev/null 2>&1; then
+  [[ "$SEC_SENSITIVE" == "1" ]] && fail_closed "sqlite3 not on PATH"
+  exit 0
+fi
+
+# Did the self-protect enforcer actually run and make a decision this call?
+sec_enforcer_ran=0
 
 # Iterate active policies with attached executable tools
 while IFS='|' read -r pid pname tool; do
   [[ -z "$pid" ]] && continue
   enforcer="$MAIN_ROOT/.policy-tools/${pid}_${tool}.py"
-  [[ ! -f "$enforcer" ]] && continue
+  if [[ ! -f "$enforcer" ]]; then
+    # A missing self-protect enforcer on a sensitive op = fail closed.
+    [[ "$SEC_SENSITIVE" == "1" && "$tool" == "enforcement_self_protect" ]] && fail_closed "enforcer file missing"
+    continue
+  fi
   out="$(python3 "$enforcer" --operation "$TOOL" --args "$ARGS" 2>/dev/null || true)"
   allowed="$(printf '%s' "$out" | python3 -c 'import json,sys;
 try: d=json.loads(sys.stdin.read()); print("1" if d.get("allowed",True) else "0")
-except: print("1")' 2>/dev/null || echo 1)"
+except: print("2")' 2>/dev/null || echo 2)"
+  # allowed=2 => enforcer errored / emitted unparseable output. For a sensitive
+  # op via the self-protect enforcer, that error must NOT default to allow.
+  if [[ "$tool" == "enforcement_self_protect" ]]; then
+    [[ "$SEC_SENSITIVE" == "1" && "$allowed" == "2" ]] && fail_closed "enforcer errored"
+    sec_enforcer_ran=1
+  fi
+  # For all other enforcers, an error still fails open (unchanged behavior).
+  [[ "$allowed" == "2" ]] && allowed=1
   if [[ "$allowed" == "0" ]]; then
     # R1: consume the enforcer's route:deliver signal (log intent, opt-in
     # background auto-route to `uap deliver`). Falls back to the plain reason if
@@ -73,4 +128,8 @@ except: print("")' 2>/dev/null || echo "")"
   fi
 done < <(sqlite3 "$DB" "SELECT p.id, p.name, t.toolName FROM policies p JOIN executable_tools t ON t.policyId=p.id WHERE p.isActive=1;")
 
+# A sensitive op that no self-protect enforcer ever evaluated = the control
+# surface is unguarded (self-protect not registered/active). Fail closed.
+[[ "$SEC_SENSITIVE" == "1" && "$sec_enforcer_ran" == "0" ]] && fail_closed "self-protect not registered/active"
+
 exit 0