npm - tamperward - Versions diffs - 2.13.2 → 2.14.0 - Mend

tamperward 2.13.2 → 2.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -149,7 +149,23 @@ weakening operations, detect protected-tree drift, and sweep the turn's net
 changes. The `Stop` hook runs that sweep — it does **not** invoke `verify`.
 `tamperward watch` can additionally record transient mutations, but it is an
 optional observer that `init` neither starts nor supervises, and it is not an
-enforcement boundary.
+enforcement boundary. Since **2.13.3** the observer writes a health sidecar next to
+its JSONL event log, recording backend, PID/start time, watched-directory count,
+successful appends, dropped events and errors. `tamperward doctor` reports that
+channel as **healthy**, **degraded**, or **unavailable**, and Stop writes the same
+non-authoritative state into the audit log when `TAMPERWARD_DENYLOG` is enabled.
+This distinguishes “healthy observer, zero events” from “observer telemetry was
+unavailable” without turning absence of watcher telemetry into an enforcement pass
+or failure.
+Since **2.14.0**, `tamperward run --observe-transients -- <agent...>` can supervise
+that observer as part of the envelope lifecycle. It creates a unique session log under
+the repository git directory, pins the watcher's protected-path policy to the same
+trusted base used by the envelope, waits for observer health before launching the
+agent, consumes the temporal events itself after the agent exits, and shuts the
+observer down deterministically. Observer health remains advisory; transient findings
+remain warnings by default and affect the envelope only when the operator explicitly
+sets `TAMPERWARD_TRANSIENT=block`.
 After the runtime exits its exit code is treated as untrusted, and the envelope
 checks that post-agent `HEAD` still descends from the entry commit; the committed
@@ -349,7 +365,7 @@ option can never be reinterpreted as the agent command.
 | `check` | one view — `--staged` · `--worktree` · `--diff <base>...<head>` — plus `--format text\|json\|github\|auto` (default `auto`) · `--json` (alias for `--format json`) · `--cwd <dir>` |
 | `verify` | `--base <rev>` (default `HEAD`) · `--cmd <suite command>` · `--budget <seconds>` · `--json` · `--keep` (keep the two materialised copies and report their paths) · `--require-ancestor` (refuse a base that is not an ancestor of `HEAD`) · `--cwd <dir>` |
 | `doctor` | `--base <rev>` (trusted policy revision) · `--workflow <path>` (default `.github/workflows/tamperward.yml`) · `--cwd <dir>` — validates every job that runs `tamperward verify` has a static outer timeout covering visible + pristine + authority reserve |
-| `run` | `--base <rev>` · `--cmd <suite command>` · `--budget <seconds>` (per verifier suite) · `--agent-budget <seconds>` (optional wrapped-agent wall clock) · `--allow-dirty` · `--settle <seconds>` (wait before the final quiescence check) · `--allow-dep-drift` · `--cwd <dir>` · then `-- <agent command...>` |
+| `run` | `--base <rev>` · `--cmd <suite command>` · `--budget <seconds>` (per verifier suite) · `--agent-budget <seconds>` (optional wrapped-agent wall clock) · `--observe-transients` (start a session-scoped transient observer) · `--allow-dirty` · `--settle <seconds>` (wait before the final quiescence check) · `--allow-dep-drift` · `--cwd <dir>` · then `-- <agent command...>` |
 | `allow` | `<rule>` · `--file <path>` · `--reason "<why>"` (required) · `--cwd <dir>` |
 | `init` | `--cwd <dir>` · `--dry-run` · `--force-workflow` |
 | `watch` | `--dir <dir>` · `--log <file>` — a daemon; it runs until signalled |

package/dist/cli/index.js CHANGED Viewed

@@ -6828,7 +6828,7 @@ function runCheck(opts) {
 }
 // src/cli/hook.ts
-import { readFileSync as readFileSync11, appendFileSync as appendFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync8 } from "node:fs";
+import { readFileSync as readFileSync11, appendFileSync as appendFileSync4, writeFileSync as writeFileSync5, existsSync as existsSync8 } from "node:fs";
 import { createHash as createHash5 } from "node:crypto";
 // src/adapters/claude/deny.ts
@@ -7025,7 +7025,7 @@ function dropTurnTree(cwd, sessionId) {
 }
 // src/cli/watch.ts
-import { appendFileSync as appendFileSync3, lstatSync as lstatSync3, mkdirSync as mkdirSync4, readdirSync as readdirSync2, watch } from "node:fs";
+import { appendFileSync as appendFileSync3, lstatSync as lstatSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync9, readdirSync as readdirSync2, watch, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join11 } from "node:path";
 import { createHash as createHash4 } from "node:crypto";
 var SKIP2 = /(^|\/)(\.git|node_modules)(\/|$)/;
@@ -7040,17 +7040,51 @@ function defaultEventLog(cwd) {
   if (process.env.TAMPERWARD_FSEVENTS) return process.env.TAMPERWARD_FSEVENTS;
   return join11(gitDir(cwd) ?? join11(cwd, ".git"), "tamperward", "fsevents.jsonl");
 }
-function watchTree(dir, cb) {
+function watcherHealthPath(log) {
+  return `${log}.health.json`;
+}
+function readWatcherHealth(log) {
+  try {
+    const value = JSON.parse(readFileSync9(watcherHealthPath(log), "utf8"));
+    if (value.version !== 1 || typeof value.pid !== "number" || typeof value.started_at !== "string" || !["healthy", "degraded", "stopped"].includes(String(value.state))) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function watcherTelemetry(log) {
+  const health = readWatcherHealth(log);
+  if (!health) return { state: "unavailable", health: null, reason: "no health record" };
+  if (health.state === "stopped")
+    return { state: "unavailable", health, reason: "observer stopped" };
+  if (!pidAlive(health.pid))
+    return { state: "unavailable", health, reason: `observer pid ${health.pid} is not running` };
+  if (health.state === "degraded")
+    return { state: "degraded", health, reason: health.last_error ?? "observer reported an error" };
+  return { state: "healthy", health };
+}
+function watchTree(dir, cb, onState, onError) {
   if (process.env.TAMPERWARD_WATCH_NO_RECURSIVE !== "1") {
     try {
       const w = watch(dir, { recursive: true }, (kind, fname) => {
         if (fname) cb(kind, String(fname));
       });
+      onState("recursive", 1);
       return { close: () => w.close() };
     } catch {
     }
   }
   const watchers = /* @__PURE__ */ new Map();
+  onState("fallback", 0);
   const addDir = (rel) => {
     if (watchers.has(rel) || SKIP2.test(rel + "/")) return;
     let w;
@@ -7064,17 +7098,24 @@ function watchTree(dir, cb) {
         } catch {
         }
       });
-    } catch {
+    } catch (e) {
+      onError(
+        `watch directory ${rel || "."}: ${e instanceof Error ? e.message : String(e)}`
+      );
       return;
     }
     watchers.set(rel, w);
+    onState("fallback", watchers.size);
   };
   const walk2 = (rel) => {
     addDir(rel);
     let names = [];
     try {
       names = readdirSync2(rel ? join11(dir, rel) : dir);
-    } catch {
+    } catch (e) {
+      onError(
+        `enumerate directory ${rel || "."}: ${e instanceof Error ? e.message : String(e)}`
+      );
       return;
     }
     for (const name of names) {
@@ -7096,32 +7137,117 @@ function startWatcher(dir, log, policy) {
     mkdirSync4(join11(log, ".."), { recursive: true });
   } catch {
   }
-  const last = /* @__PURE__ */ new Map();
-  return watchTree(dir, (kind, rel) => {
-    if (SKIP2.test(rel) || !isProtected(rel, policy)) return;
-    const s = snap(join11(dir, rel));
-    const key2 = `${s.hash}:${s.mode}`;
-    if (last.get(rel) === key2) return;
-    last.set(rel, key2);
-    const ev = { ts: (/* @__PURE__ */ new Date()).toISOString(), path: rel, kind: kind === "rename" ? "rename" : "change", ...s };
+  const healthPath = watcherHealthPath(log);
+  const health = {
+    version: 1,
+    state: "healthy",
+    backend: "initializing",
+    pid: process.pid,
+    started_at: (/* @__PURE__ */ new Date()).toISOString(),
+    stopped_at: null,
+    watched_dirs: 0,
+    last_append_at: null,
+    event_count: 0,
+    dropped_events: 0,
+    error_count: 0,
+    last_error: null,
+    log
+  };
+  let healthWriteWarningEmitted = false;
+  const persistHealth = () => {
     try {
-      appendFileSync3(log, JSON.stringify(ev) + "\n");
-    } catch {
+      writeFileSync4(healthPath, JSON.stringify(health) + "\n", { mode: 384 });
+      healthWriteWarningEmitted = false;
+    } catch (e) {
+      if (!healthWriteWarningEmitted) {
+        process.stderr.write(
+          `tamperward watch: WARNING: observer health cannot be recorded at ${healthPath} (${e instanceof Error ? e.message : String(e)}); telemetry availability is unknown.
+`
+        );
+        healthWriteWarningEmitted = true;
+      }
     }
-  });
+  };
+  const degrade = (detail, droppedEvent = false) => {
+    health.state = "degraded";
+    health.error_count++;
+    if (droppedEvent) health.dropped_events++;
+    health.last_error = detail;
+    persistHealth();
+    process.stderr.write(
+      `tamperward watch: WARNING: observer degraded \u2014 ${detail}. Transient telemetry may be incomplete.
+`
+    );
+  };
+  persistHealth();
+  const last = /* @__PURE__ */ new Map();
+  const tree = watchTree(
+    dir,
+    (kind, rel) => {
+      if (SKIP2.test(rel) || !isProtected(rel, policy)) return;
+      const s = snap(join11(dir, rel));
+      const key2 = `${s.hash}:${s.mode}`;
+      if (last.get(rel) === key2) return;
+      last.set(rel, key2);
+      const ev = {
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        path: rel,
+        kind: kind === "rename" ? "rename" : "change",
+        ...s
+      };
+      try {
+        appendFileSync3(log, JSON.stringify(ev) + "\n");
+        health.event_count++;
+        health.last_append_at = (/* @__PURE__ */ new Date()).toISOString();
+        persistHealth();
+      } catch (e) {
+        degrade(
+          `append event to ${log}: ${e instanceof Error ? e.message : String(e)}`,
+          true
+        );
+      }
+    },
+    (backend, watchedDirs) => {
+      health.backend = backend;
+      health.watched_dirs = watchedDirs;
+      persistHealth();
+    },
+    (detail) => degrade(detail)
+  );
+  return {
+    close: () => {
+      tree.close();
+      health.state = "stopped";
+      health.stopped_at = (/* @__PURE__ */ new Date()).toISOString();
+      persistHealth();
+    }
+  };
 }
 function runWatch(args) {
   let dir = process.cwd();
   let log = null;
+  let base = null;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--dir" && args[i + 1]) dir = args[++i];
     else if (args[i] === "--log" && args[i + 1]) log = args[++i];
+    else if (args[i] === "--base" && args[i + 1]) base = args[++i];
   }
-  const policy = loadPolicy(dir);
+  const policy = base ? loadPolicyAt(base, dir) ?? defaultPolicy() : loadPolicy(dir);
   const out2 = log ?? defaultEventLog(dir);
-  startWatcher(dir, out2, policy);
-  process.stdout.write(`tamperward watch: recording protected-file events under ${dir} -> ${out2}
-`);
+  const watcher = startWatcher(dir, out2, policy);
+  let closing = false;
+  const shutdown = () => {
+    if (closing) return;
+    closing = true;
+    watcher.close();
+    process.exit(0);
+  };
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+  process.stdout.write(
+    `tamperward watch: recording protected-file events under ${dir} -> ${out2} (health: ${watcherHealthPath(out2)}${base ? `; trusted base: ${base}` : ""})
+`
+  );
   return -1;
 }
@@ -7441,6 +7567,10 @@ function turnTransientBlocks(cwd, sessionId, policy, changes) {
   const none = { blocks: [], commit: () => {
   } };
   const log = defaultEventLog(cwd);
+  const telemetry = watcherTelemetry(log);
+  if (telemetry.state !== "healthy") {
+    recordObserverHealth(telemetry.state, telemetry.reason);
+  }
   const cp = cursorPath(cwd, sessionId);
   if (!existsSync8(log)) return none;
   let offset = 0;
@@ -7451,7 +7581,7 @@ function turnTransientBlocks(cwd, sessionId, policy, changes) {
   const { events, newOffset } = readEvents(log, offset);
   if (events.length === 0) return { ...none, commit: () => {
     if (cp) try {
-      writeFileSync4(cp, String(newOffset));
+      writeFileSync5(cp, String(newOffset));
     } catch {
     }
   } };
@@ -7466,7 +7596,7 @@ function turnTransientBlocks(cwd, sessionId, policy, changes) {
     blocks: findings.filter((f) => f.severity === "block"),
     commit: () => {
       if (cp) try {
-        writeFileSync4(cp, String(newOffset));
+        writeFileSync5(cp, String(newOffset));
       } catch {
       }
     }
@@ -7480,6 +7610,19 @@ function recordWarns(warns) {
   } catch {
   }
 }
+function recordObserverHealth(state, reason) {
+  const log = process.env.TAMPERWARD_DENYLOG;
+  if (!log) return;
+  const detail = (reason ?? "").replace(/[\r\n]+/g, " ").trim();
+  try {
+    appendFileSync4(
+      log,
+      `warn:transient-observer:${state}${detail ? ":" + detail : ""}
+`
+    );
+  } catch {
+  }
+}
 function stopVerdict(input) {
   if (input.stop_hook_active) return { exitCode: 0, stdout: "" };
   const cwd = input.cwd ?? process.cwd();
@@ -7598,7 +7741,7 @@ Honored at LOCAL pre-commit only. The agent-layer hook ignores this file; CI req
 // src/cli/init.ts
 import { execFileSync as execFileSync6 } from "node:child_process";
 import { createHash as createHash6 } from "node:crypto";
-import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync12, writeFileSync as writeFileSync5, chmodSync, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync12, writeFileSync as writeFileSync6, chmodSync, statSync as statSync2 } from "node:fs";
 import { basename as basename2, dirname as dirname4, isAbsolute as isAbsolute8, join as join12, relative as relative3, resolve as resolve3 } from "node:path";
 // src/verifier-limits.ts
@@ -7832,7 +7975,7 @@ function planPolicy(cwd) {
     path: POLICY_FILE,
     status: "create",
     detail: "baseline policy with commented overrides",
-    apply: () => writeFileSync5(path, POLICY_CONTENT)
+    apply: () => writeFileSync6(path, POLICY_CONTENT)
   };
 }
 function planClaudeHooks(cwd) {
@@ -7904,7 +8047,7 @@ function planClaudeHooks(cwd) {
       }
       if (needDisableFalse) settings.disableAllHooks = false;
       mkdirSync5(dirname4(path), { recursive: true });
-      writeFileSync5(path, JSON.stringify(settings, null, 2) + "\n");
+      writeFileSync6(path, JSON.stringify(settings, null, 2) + "\n");
     }
   };
 }
@@ -7997,7 +8140,7 @@ function planPreCommit(cwd) {
       detail: `create via ${note}`,
       apply: () => {
         mkdirSync5(dirname4(path), { recursive: true });
-        writeFileSync5(path, `#!/bin/sh
+        writeFileSync6(path, `#!/bin/sh
 ${block.join("\n")}
 `);
         chmodSync(path, 493);
@@ -8012,7 +8155,7 @@ ${block.join("\n")}
   const dead = unconditionalExitAt(lines);
   const at = lines.findIndex((l) => PRECOMMIT_RE.test(l));
   const write = (out2) => {
-    writeFileSync5(path, out2.join("\n"));
+    writeFileSync6(path, out2.join("\n"));
     chmodSync(path, 493);
   };
   if (at !== -1 && (dead === -1 || at < dead)) {
@@ -8107,7 +8250,7 @@ ${CODEOWNERS_MARK}
     } : {},
     apply: () => {
       mkdirSync5(dirname4(path), { recursive: true });
-      writeFileSync5(path, existing === null ? block.replace(/^\n/, "") : existing.replace(/\n?$/, "\n") + block);
+      writeFileSync6(path, existing === null ? block.replace(/^\n/, "") : existing.replace(/\n?$/, "\n") + block);
     }
   };
 }
@@ -8116,7 +8259,7 @@ function planWorkflow(cwd, force) {
   const path = join12(cwd, rel);
   const write = () => {
     mkdirSync5(dirname4(path), { recursive: true });
-    writeFileSync5(path, workflowFile(WORKFLOW_CONTENT));
+    writeFileSync6(path, workflowFile(WORKFLOW_CONTENT));
   };
   if (!existsSync9(path)) {
     return {
@@ -8529,13 +8672,30 @@ function runDoctor(opts = {}) {
       "tamperward doctor: GitHub repository authority OK \u2014 " + github.repo + "#" + github.branch + " requires tamperward, Code Owner review, and stale-review dismissal on new pushes.\n"
     );
   }
+  const observer = watcherTelemetry(defaultEventLog(cwd));
+  if (observer.state === "healthy" && observer.health) {
+    process.stdout.write(
+      `tamperward doctor: transient observer: healthy \u2014 ${observer.health.backend}, ${observer.health.watched_dirs} watched dir(s), ${observer.health.event_count} event(s); advisory telemetry only, not verification authority.
+`
+    );
+  } else if (observer.state === "degraded" && observer.health) {
+    process.stdout.write(
+      `tamperward doctor: transient observer: degraded \u2014 ${observer.health.error_count} error(s), ${observer.health.dropped_events} dropped event(s); ${observer.reason ?? "telemetry may be incomplete"}. Advisory only; zero events are not evidence of no transient activity.
+`
+    );
+  } else {
+    process.stdout.write(
+      `tamperward doctor: transient observer: unavailable${observer.reason ? " \u2014 " + observer.reason : ""}. Observer telemetry is optional/advisory; zero events are not evidence of no transient activity.
+`
+    );
+  }
   return 0;
 }
 // src/cli/verify.ts
 import { execFileSync as execFileSync9, spawnSync as spawnSync2 } from "node:child_process";
 import { createHash as createHash10 } from "node:crypto";
-import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync5, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync5, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync7 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { dirname as dirname7, isAbsolute as isAbsolute10, join as join16, relative as relative5, resolve as resolve7, sep as sep2 } from "node:path";
@@ -9655,7 +9815,7 @@ function overlayPristine(cwd, base, dest, policy, cmd, dependencyRoot) {
       safeSymlink(target, out2, dest, `the base's ${e.path}`);
       restoredLinks.push({ path: e.path, out: out2, target });
     } else {
-      writeFileSync6(out2, content);
+      writeFileSync7(out2, content);
       chmodSync2(out2, parseInt(e.mode.slice(-4), 8) & 511);
     }
     restored.push(e.path);
@@ -9711,7 +9871,7 @@ function suiteEnv(scratch) {
   }
   const userRc = join16(scratch, "npmrc-user");
   const globalRc = join16(scratch, "npmrc-global");
-  for (const f of [userRc, globalRc]) writeFileSync6(f, "", { mode: 292 });
+  for (const f of [userRc, globalRc]) writeFileSync7(f, "", { mode: 292 });
   env.npm_config_userconfig = userRc;
   env.npm_config_globalconfig = globalRc;
   env.npm_config_node_options = " ";
@@ -10035,7 +10195,8 @@ function parseVerify(args) {
 }
 // src/cli/run.ts
-import { execFileSync as execFileSync10, spawnSync as spawnSync3 } from "node:child_process";
+import { execFileSync as execFileSync10, spawn, spawnSync as spawnSync3 } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { mkdtempSync as mkdtempSync3, readdirSync as readdirSync5, readFileSync as readFileSync17, readlinkSync as readlinkSync4, realpathSync as realpathSync6, rmSync as rmSync4 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join17, resolve as resolve8 } from "node:path";
@@ -10257,6 +10418,124 @@ function runAgentWithBudget(argv2, cwd, budgetSecs) {
     rmSync4(stateDir, { recursive: true, force: true });
   }
 }
+var waitCell = new Int32Array(new SharedArrayBuffer(4));
+function waitMs(ms) {
+  Atomics.wait(waitCell, 0, 0, ms);
+}
+function pidAlive2(pid) {
+  if (!pid || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function supervisedObserverLog(cwd) {
+  const gd = gitDir(cwd) ?? join17(cwd, ".git");
+  return join17(
+    gd,
+    "tamperward",
+    `run-observer-${process.pid}-${Date.now()}-${randomBytes(4).toString("hex")}.jsonl`
+  );
+}
+function startSupervisedObserver(cwd, base, entry) {
+  const log = supervisedObserverLog(cwd);
+  const cliEntry = entry ?? process.argv[1];
+  if (!cliEntry) return { log, pid: null, finished: false };
+  let child;
+  try {
+    child = spawn(
+      process.execPath,
+      [resolve8(cliEntry), "watch", "--dir", cwd, "--log", log, "--base", base],
+      {
+        cwd,
+        stdio: ["ignore", "ignore", "inherit"],
+        env: process.env
+      }
+    );
+  } catch {
+    return { log, pid: null, finished: false };
+  }
+  const pid = child.pid ?? null;
+  const deadline = Date.now() + 3e3;
+  while (Date.now() < deadline) {
+    const telemetry = watcherTelemetry(log);
+    if (telemetry.state === "healthy" || telemetry.state === "degraded") break;
+    if (!pidAlive2(pid)) break;
+    waitMs(25);
+  }
+  return { log, pid, finished: false };
+}
+function stopObserverProcess(observer) {
+  waitMs(100);
+  const beforeStop = watcherTelemetry(observer.log);
+  const pid = observer.pid;
+  if (pidAlive2(pid)) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+    }
+    const deadline = Date.now() + 2e3;
+    while (Date.now() < deadline) {
+      const health = watcherTelemetry(observer.log);
+      if (health.health?.state === "stopped" || !pidAlive2(pid)) break;
+      waitMs(25);
+    }
+    if (pidAlive2(pid)) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+      }
+    }
+  }
+  observer.finished = true;
+  return beforeStop;
+}
+function observerSummary(observer, telemetry) {
+  const h = telemetry.health;
+  const counts = h ? `${h.event_count} event(s), ${h.dropped_events} dropped, ${h.error_count} error(s)` : "no valid health record";
+  const reason = telemetry.reason ? `; ${telemetry.reason}` : "";
+  out(
+    `tamperward run \u2014 transient observer: ${telemetry.state} (advisory; ${counts}; log ${observer.log}${reason})`
+  );
+}
+function collectObserverFindings(observer, telemetry, cwd, base, head, policy) {
+  observerSummary(observer, telemetry);
+  const { events } = readEvents(observer.log, 0);
+  if (events.length === 0) return { blocking: false };
+  let persistent = /* @__PURE__ */ new Set();
+  try {
+    const changes = [
+      ...head !== base ? diffRange(base, head, { cwd }) : [],
+      ...diffWorktreeWithUntracked({ cwd }, (rel) => isProtected(rel, policy))
+    ];
+    persistent = new Set(
+      changes.filter((change) => change.kind === "file").map((change) => change.path)
+    );
+  } catch (e) {
+    out(
+      `tamperward run \u2014 transient observer: recorded ${events.length} event(s), but could not classify them against the final diff (${e instanceof Error ? e.message : String(e)}).`
+    );
+    return { blocking: false };
+  }
+  const finalHash = (path) => {
+    const e = inspectRel(cwd, path);
+    return e.kind === "file" && e.content != null ? contentHash(e.content) : null;
+  };
+  const findings = transientFindings(events, persistent, policy, finalHash);
+  for (const finding of findings) {
+    out(
+      `[observer] ${finding.severity === "block" ? "BLOCK" : "warn"} ${finding.rule}${finding.file ? " " + finding.file : ""}: ${finding.message}`
+    );
+  }
+  return { blocking: findings.some((finding) => finding.severity === "block") };
+}
+function finishObserverAdvisory(observer) {
+  if (!observer || observer.finished) return;
+  const telemetry = stopObserverProcess(observer);
+  observerSummary(observer, telemetry);
+}
 function git3(args, cwd) {
   return execFileSync10("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
 }
@@ -10383,6 +10662,10 @@ function runEnvelope(opts) {
   } else {
     out(`tamperward run \u2014 dependency environment: verifier-owned by ${verifierBackend.image ?? "isolated image"}`);
   }
+  const observer = opts.observeTransients ? startSupervisedObserver(cwd, base, opts.observerEntry) : null;
+  if (!observer) {
+    out("tamperward run \u2014 transient observer: disabled (advisory; pass --observe-transients to enable)");
+  }
   const rewritesBefore = objectRewriteState(cwd);
   const spawnTicks = nowTicks();
   const agentRun = opts.agentBudget === void 0 ? (() => {
@@ -10410,6 +10693,7 @@ function runEnvelope(opts) {
     err2("read against the anchor we started from. That is the finding.");
     out(`
 tamperward run \u2014 agent exit ${agentExit}; OBJECT_REWRITE \u2192 ENFORCEMENT_FAILED`);
+    finishObserverAdvisory(observer);
     return 1;
   }
   const dependencyBeforeAdjudication = dependencyEnvironment ? checkDependencyEnvironment(cwd, dependencyEnvironment) : { ok: true };
@@ -10419,6 +10703,7 @@ tamperward run \u2014 agent exit ${agentExit}; OBJECT_REWRITE \u2192 ENFORCEMENT
     if (!opts.allowDepDrift) {
       out(`
 tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEMENT_FAILED`);
+      finishObserverAdvisory(observer);
       return 1;
     }
     err2("(--allow-dep-drift: proceeding anyway, on the operator's judgement.)");
@@ -10430,6 +10715,7 @@ tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEME
     err2("the agent rewrote history out from under the anchor. That is the finding.");
     out(`
 tamperward run \u2014 agent exit ${agentExit}; HISTORY_REWRITE \u2192 ENFORCEMENT_FAILED`);
+    finishObserverAdvisory(observer);
     return 1;
   }
   const protectedIgnored = (rel) => isProtected(rel, frozenPolicy);
@@ -10480,11 +10766,24 @@ tamperward run \u2014 agent exit ${agentExit}; HISTORY_REWRITE \u2192 ENFORCEMEN
     err2(`tamperward run: ${survivors.length} process(es) started during this run still hold the`);
     err2(`working tree (pid ${survivors.join(", ")}). A verdict cannot outlive the tree it describes.`);
   }
+  let observerBlocked = false;
+  if (observer && !observer.finished) {
+    const telemetry = stopObserverProcess(observer);
+    const observed = collectObserverFindings(
+      observer,
+      telemetry,
+      cwd,
+      base,
+      head,
+      frozenPolicy
+    );
+    observerBlocked = observed.blocking;
+  }
   const notQuiescent = mutatedDuringAdjudication || survivors.length > 0 || depsDrifted || rewrote;
   const cannot = !notQuiescent && (diffCode === 2 || workCode === 2 || verifyCode === 2);
-  const blocked = diffCode === 1 || workCode === 1 || verifyCode === 1 || notQuiescent;
+  const blocked = diffCode === 1 || workCode === 1 || verifyCode === 1 || notQuiescent || observerBlocked;
   const enforcement = cannot ? 2 : blocked ? 1 : 0;
-  const verdict2 = enforcement === 2 ? "CANNOT_ADJUDICATE (fail closed)" : rewrote ? "OBJECT_REWRITE \u2014 the base the checks read is not the base we anchored to" : depsDrifted ? "DEPENDENCY_DRIFT \u2014 the suite runner changed under the envelope" : notQuiescent ? "NOT_QUIESCENT \u2014 the tree moved, or something still holds it" : enforcement === 1 ? "ENFORCEMENT_FAILED \u2014 the tree the runtime released does not stand" : agentTimedOut ? "AGENT_TIMEOUT \u2014 runtime budget expired; post-timeout enforcement clean" : agentExit !== 0 ? `agent exited ${agentExit} (enforcement clean)` : "GREEN MEANS GREEN";
+  const verdict2 = enforcement === 2 ? "CANNOT_ADJUDICATE (fail closed)" : rewrote ? "OBJECT_REWRITE \u2014 the base the checks read is not the base we anchored to" : depsDrifted ? "DEPENDENCY_DRIFT \u2014 the suite runner changed under the envelope" : notQuiescent ? "NOT_QUIESCENT \u2014 the tree moved, or something still holds it" : observerBlocked ? "TRANSIENT_OBSERVER_BLOCK \u2014 observed temporal weakening under strict transient policy" : enforcement === 1 ? "ENFORCEMENT_FAILED \u2014 the tree the runtime released does not stand" : agentTimedOut ? "AGENT_TIMEOUT \u2014 runtime budget expired; post-timeout enforcement clean" : agentExit !== 0 ? `agent exited ${agentExit} (enforcement clean)` : "GREEN MEANS GREEN";
   const agentSummary = agentTimedOut ? `AGENT_TIMEOUT (${opts.agentBudget}s; exit 124)` : `agent exit ${agentExit}`;
   out(`
 tamperward run \u2014 ${agentSummary}; checks diff=${diffCode} worktree=${workCode} verify=${verifyCode} \u2192 ${verdict2}`);
@@ -10504,6 +10803,7 @@ function parseRun(args) {
     else if (a === "--allow-dirty") o.allowDirty = true;
     else if (a === "--settle") o.settle = Number(args[++i]);
     else if (a === "--allow-dep-drift") o.allowDepDrift = true;
+    else if (a === "--observe-transients") o.observeTransients = true;
     else if (a === "--cwd") o.cwd = args[++i];
     else {
       o.argv = args.slice(i);
@@ -10637,7 +10937,7 @@ function validateCliArgs(cmd, args) {
     const prefix = args.slice(0, delimiter3);
     const command = args.slice(delimiter3 + 1);
     const parsed = validateFlatArgs(prefix, {
-      flags: ["--allow-dirty", "--allow-dep-drift"],
+      flags: ["--allow-dirty", "--allow-dep-drift", "--observe-transients"],
       values: {
         "--base": "string",
         "--cmd": "string",
@@ -10704,7 +11004,7 @@ function validateCliArgs(cmd, args) {
   }
   if (cmd === "watch") {
     return validateFlatArgs(args, {
-      values: { "--dir": "string", "--log": "string" }
+      values: { "--dir": "string", "--log": "string", "--base": "string" }
     }).error;
   }
   return void 0;
@@ -10731,8 +11031,10 @@ Formats:
   tamperward hook claude                    PreToolUse gate (reads hook JSON on stdin)
   tamperward sweep claude                   Stop sweep (re-scan the turn's working tree)
   tamperward watch [--dir D] [--log F]      filesystem-event observer daemon: records
-                                            protected-file events so the sweep can
-                                            observe supported transient effects
+             [--base R]                     protected-file events so the sweep can
+                                            observe supported transient effects.
+                                            --base freezes observer policy to a
+                                            trusted revision
   tamperward verify [--base R] [--cmd C]    pristine-suite re-execution: run the suite
              [--budget S] [--json] [--keep] as-is AND with protected files restored
              [--require-ancestor] [--cwd D]  from the trusted base; a visible-green /
@@ -10744,9 +11046,13 @@ Formats:
              [--base R] [--cmd C]           base, run the agent, treat its exit as
              [--budget S] [--agent-budget S] untrusted, then re-adjudicate the tree it
              [--allow-dirty] [--settle S]   left (policy over base...HEAD and the
-             [--allow-dep-drift] [--cwd D]  worktree, plus verify). --agent-budget
-                                            bounds the agent runtime itself and still
-                                            adjudicates after timeout. Exit: agent's
+             [--allow-dep-drift] [--cwd D]  worktree, plus verify).
+             [--observe-transients]          --observe-transients starts a session-
+                                            scoped observer before the agent and
+                                            reports temporal evidence/health after it.
+                                            --agent-budget bounds the agent runtime
+                                            itself and still adjudicates after timeout.
+                                            Exit: agent's
                                             code when clean; 124 on clean AGENT_TIMEOUT;
                                             1 on any blocking finding/masked failure;
                                             2 when it cannot adjudicate (fails closed)
@@ -10809,7 +11115,12 @@ function main(argv2) {
     case "verify":
       return runVerify(parseVerify(rest));
     case "run":
-      return runEnvelope(parseRun(rest));
+      return runEnvelope({
+        ...parseRun(rest),
+        // The supervised observer re-launches this exact TamperWard CLI under
+        // process.execPath rather than resolving another binary from PATH.
+        observerEntry: process.argv[1]
+      });
     case void 0:
     case "-h":
     case "--help":

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "2.13.2",
+  "version": "2.14.0",
   "description": "The deterministic agent-integrity gate. One ruleset, evaluated on the actual diff/commands as a verdict, enforced everywhere a change can be made.",
   "license": "Apache-2.0",
   "author": "hexrift",