npm - tamperward - Versions diffs - 2.13.3 → 2.14.1 - Mend

tamperward 2.13.3 → 2.14.1

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

@@ -158,6 +158,15 @@ This distinguishes “healthy observer, zero events” from “observer telemetr
 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
 changes over `entry...HEAD`; staged, unstaged and untracked non-ignored worktree
@@ -356,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

@@ -7226,15 +7226,28 @@ function startWatcher(dir, log, policy) {
 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} (health: ${watcherHealthPath(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;
 }
@@ -10182,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";
@@ -10404,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() });
 }
@@ -10530,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 ? (() => {
@@ -10557,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 };
@@ -10566,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.)");
@@ -10577,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);
@@ -10627,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}`);
@@ -10651,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);
@@ -10784,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",
@@ -10851,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;
@@ -10878,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 /
@@ -10891,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)
@@ -10956,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.3",
+  "version": "2.14.1",
   "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",