@miller-tech/uap 1.128.0 → 1.128.2

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.2",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "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:enforcers": "python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_schema_diff_gate 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/src/policies/enforcers/delivery_enforcement.py

@@ -86,32 +86,40 @@ def main() -> None:
     op, args = parse_cli()
     if op not in EDIT_OPS:
         emit(True, "not a file-edit operation")
+        return
 
     target = args.get("file_path") or args.get("path") or args.get("target") or ""
     if not target:
         emit(True, "no file path in args")
+        return
 
     root = repo_root()
     try:
         rel = str(Path(target).resolve().relative_to(root))
     except ValueError:
         emit(True, "target outside repo")
+        return
 
     rel_posix = rel.replace(os.sep, "/")
     low = rel_posix.lower()
 
     if not low.endswith(SOURCE_EXTS):
         emit(True, "not source code")
+        return
     if any(rel_posix.startswith(p) for p in EXEMPT_PREFIXES):
         emit(True, f"exempt path: {rel_posix}")
+        return
     if any(m in "/" + low for m in TEST_MARKERS):
         emit(True, "test file (protected by deliver itself)")
+        return
 
     # Escape hatches.
     if os.environ.get("UAP_DELIVER_ACTIVE") == "1":
         emit(True, "inside a deliver-driven run")
+        return
     if os.environ.get("UAP_DELIVER_BYPASS") == "1":
         emit(True, "UAP_DELIVER_BYPASS override set")
+        return
 
     # #3-F: terse, imperative, model-parseable. Weak local models otherwise
     # retry the blocked edit or hallucinate completion ("the files exist") when
@@ -143,6 +151,7 @@ def main() -> None:
             route="deliver",
             deliverHint=f'implement the intended change to {rel_posix}',
         )
+        return
 
     # Advisory (opt-out): never blocks. Surface the nudge, then allow.
     print(f"[delivery-enforcement advisory] {msg}", file=sys.stderr)
@@ -150,4 +159,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/src/policies/enforcers/schema_diff_gate.py

@@ -16,7 +16,10 @@ WATCHED_RE = re.compile(
     r"infra/helm_charts/[^/]*envoy|infra/helm_charts/[^/]*sentinel)",
     re.I,
 )
-COMMIT_OPS = {"git-commit", "git commit", "Bash"}
+# NOTE: bare "Bash" used to be in this set, which made EVERY shell command a
+# gate point — including the `uap schema-diff` remedy itself (self-deadlock).
+# Gate only actual commit/push commands (main() also inspects cmd content).
+COMMIT_OPS = {"git-commit", "git commit"}
 RECENT_SEC = 3600
 
 
@@ -35,17 +38,31 @@ def schema_diff_ok(root: Path) -> bool:
         return False
     try:
         con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1.0)
-        cur = con.execute(
-            "SELECT timestamp FROM session_memories "
-            "WHERE content LIKE '%schema-diff%pass%' "
-            "ORDER BY id DESC LIMIT 1"
-        )
-        row = cur.fetchone()
+        # `uap memory store` writes to `memories` (type 'action'), while older
+        # UAP wrote session rows to `session_memories` — accept the marker from
+        # either table so the documented remedy actually clears the gate.
+        row = None
+        for table in ("memories", "session_memories"):
+            try:
+                cur = con.execute(
+                    f"SELECT timestamp FROM {table} "
+                    "WHERE content LIKE '%schema-diff%pass%' "
+                    "ORDER BY id DESC LIMIT 1"
+                )
+                r = cur.fetchone()
+                if r and (row is None or r[0] > row[0]):
+                    row = r
+            except sqlite3.Error:
+                continue
         con.close()
         if not row:
             return False
         try:
-            ts = time.mktime(time.strptime(row[0][:19], "%Y-%m-%dT%H:%M:%S"))
+            # Timestamps are stored as UTC ISO-8601 (trailing 'Z'); parse them
+            # as UTC — time.mktime would misread them as local time and expire
+            # the marker hours early (or late) depending on the host TZ.
+            import calendar
+            ts = calendar.timegm(time.strptime(row[0][:19], "%Y-%m-%dT%H:%M:%S"))
         except Exception:  # noqa: BLE001
             return False
         return (time.time() - ts) < RECENT_SEC

package/tools/agents/tests/test_schema_diff_gate.py

@@ -0,0 +1,115 @@
+"""Tests for the schema-diff-gate enforcer fixes (self-deadlock + marker read).
+
+Covers the 2026-07-08 mid-session incident: bare "Bash" in COMMIT_OPS gated
+EVERY shell command (including the `uap schema-diff` remedy — self-deadlock),
+and the pass-marker check read only the legacy session_memories table and
+parsed UTC timestamps with time.mktime (host-timezone skew).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import subprocess
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[3]
+ENFORCER = REPO / "src" / "policies" / "enforcers" / "schema_diff_gate.py"
+
+
+def run_gate(op: str, args: dict, root: Path, tz: str | None = None):
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+    env["UAP_REPO_ROOT"] = str(root)
+    env["UAP_WORKTREE_ROOT"] = str(root)
+    if tz:
+        env["TZ"] = tz
+    r = subprocess.run(
+        ["python3", str(ENFORCER), "--operation", op, "--args", json.dumps(args)],
+        cwd=root,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    try:
+        payload = json.loads(r.stdout or "{}")
+    except json.JSONDecodeError:
+        payload = {}
+    return r.returncode, payload.get("allowed", False), payload.get("reason", "")
+
+
+class SchemaDiffGateTest(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory(prefix="schema-gate-")
+        self.root = Path(self._tmp.name)
+        subprocess.run(["git", "init", "-q"], cwd=self.root, check=True)
+        subprocess.run(
+            ["git", "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "init"],
+            cwd=self.root,
+            check=True,
+        )
+        (self.root / "migrations").mkdir()
+        (self.root / "migrations" / "001_add_table.sql").write_text("CREATE TABLE t (id int);")
+        subprocess.run(["git", "add", "migrations"], cwd=self.root, check=True)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def write_marker(self, iso_timestamp: str, table: str = "memories"):
+        mem = self.root / "agents" / "data" / "memory"
+        mem.mkdir(parents=True)
+        con = sqlite3.connect(mem / "short_term.db")
+        con.execute(f"CREATE TABLE {table} (id INTEGER PRIMARY KEY, content TEXT, timestamp TEXT)")
+        con.execute(
+            f"INSERT INTO {table} (content, timestamp) VALUES (?, ?)",
+            ("schema-diff pass: verified", iso_timestamp),
+        )
+        con.commit()
+        con.close()
+
+    def test_ordinary_bash_is_not_a_gate_point(self):
+        """Regression: bare Bash op must not gate — that deadlocked the remedy itself."""
+        code, allowed, reason = run_gate("Bash", {"command": "uap schema-diff"}, self.root)
+        self.assertEqual(code, 0)
+        self.assertTrue(allowed)
+        self.assertIn("not a commit/push gate point", reason)
+
+    def test_commit_command_still_gated(self):
+        code, allowed, reason = run_gate("Bash", {"command": 'git commit -m "add migration"'}, self.root)
+        self.assertEqual(code, 2)
+        self.assertFalse(allowed)
+        self.assertIn("uap schema-diff", reason)
+
+    def test_fresh_marker_in_memories_table_clears_gate(self):
+        """`uap memory store` writes to `memories`; the gate must accept it."""
+        self.write_marker(datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"))
+        code, allowed, reason = run_gate("git-commit", {}, self.root)
+        self.assertEqual(code, 0)
+        self.assertTrue(allowed)
+        self.assertIn("recent schema-diff pass", reason)
+
+    def test_legacy_session_memories_table_still_accepted(self):
+        self.write_marker(
+            datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), table="session_memories"
+        )
+        code, allowed, _ = run_gate("git-commit", {}, self.root)
+        self.assertEqual(code, 0)
+        self.assertTrue(allowed)
+
+    def test_stale_marker_blocks_regardless_of_host_timezone(self):
+        """Pre-fix, time.mktime read UTC timestamps as local: east-of-UTC hosts
+        saw stale markers shifted into the future and the gate cleared on a
+        2h-old pass."""
+        stale = (datetime.now(timezone.utc) - timedelta(hours=2)).strftime("%Y-%m-%dT%H:%M:%SZ")
+        self.write_marker(stale)
+        code, allowed, _ = run_gate("git-commit", {}, self.root, tz="Australia/Sydney")
+        self.assertEqual(code, 2)
+        self.assertFalse(allowed)
+
+
+if __name__ == "__main__":
+    unittest.main()