@miller-tech/uap 1.128.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":"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"}

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/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.128.0",
+  "version": "1.128.1",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",