tamperward 2.13.2 → 2.13.3

package/README.md

@@ -149,7 +149,14 @@ 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.
 
 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

package/dist/cli/index.js

@@ -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,19 +7137,91 @@ 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();
@@ -7120,7 +7233,7 @@ function runWatch(args) {
   const policy = loadPolicy(dir);
   const out2 = log ?? defaultEventLog(dir);
   startWatcher(dir, out2, policy);
-  process.stdout.write(`tamperward watch: recording protected-file events under ${dir} -> ${out2}
+  process.stdout.write(`tamperward watch: recording protected-file events under ${dir} -> ${out2} (health: ${watcherHealthPath(out2)})
 `);
   return -1;
 }
@@ -7441,6 +7554,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 +7568,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 +7583,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 +7597,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 +7728,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 +7962,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 +8034,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 +8127,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 +8142,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 +8237,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 +8246,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 +8659,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 +9802,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 +9858,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 = " ";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "2.13.2",
+  "version": "2.13.3",
   "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",