npm - tamperward - Versions diffs - 2.11.2 → 2.11.3 - Mend

tamperward 2.11.2 → 2.11.3

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

@@ -155,7 +155,15 @@ 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
 changes; dependency drift and whether the tree stayed quiescent; and the
-verification outcome.
+verification outcome. For agent runtimes that may hang, `--agent-budget <seconds>`
+adds an operator-owned wall-clock boundary around the **agent itself** (separate from
+the verifier's `--budget`). On expiry TamperWard terminates the owned process tree,
+then still performs the same post-timeout adjudication. A clean timeout is
+`AGENT_TIMEOUT` / exit 124; any enforcement failure or cannot-adjudicate result
+still outranks that runtime status. On POSIX the agent starts in its own process
+group; on Linux the timeout also enumerates the agent's `/proc` descendant tree so
+a child that escaped the group with `setsid()` is terminated before adjudication.
+Windows uses `taskkill /T /F` as the explicit process-tree fallback.
 `tamperward verify` materialises two temporary copies — they are **not
 sandboxes**, and both execute agent-controlled code. The visible copy runs the
@@ -175,6 +183,7 @@ semantic correctness nor a substitute for independent held-out tests.
 | Enforcement clean and agent exits 0 | exit 0 |
 | Blocking finding, masked failure, dependency drift, or non-quiescent tree | exit 1 |
 | Required adjudication cannot be completed | exit 2, failing closed |
+| Enforcement clean but the agent exceeded `--agent-budget` | `AGENT_TIMEOUT`, exit 124 |
 | Enforcement clean but the agent failed | the agent's non-zero exit is preserved |
 ### CI authority
@@ -294,7 +303,7 @@ The four primitives:
 npx tamperward check --staged                # pre-commit view
 npx tamperward check --diff "main...HEAD"    # CI view over the PR's commit range
 npx tamperward verify --base main            # pristine-suite re-execution
-npx tamperward run -- <agent command...>     # same-host envelope (local verifier only)
+npx tamperward run --agent-budget 1800 -- <agent command...>  # optional agent-runtime bound
 ```
 The isolated backend is a **frozen-artifact final verifier**. `tamperward run`
@@ -312,7 +321,7 @@ commands ignore what they do not know.
 | --- | --- |
 | `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>` |
-| `run` | `--base <rev>` · `--cmd <suite command>` · `--budget <seconds>` · `--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) · `--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 |
@@ -320,15 +329,15 @@ commands ignore what they do not know.
 **Exit codes** — part of the public surface:
-| command | 0 | 1 | 2 |
-| --- | --- | --- | --- |
-| `check` | no blocking finding | at least one blocking finding | cannot evaluate: policy parse error, malformed `--diff` range, no view given, not a git repository, or an unresolvable revision — any failure the gate cannot recover from is one clean `tamperward: …` line on stderr at exit 2, never a stack trace at exit 1 |
-| `verify` | `VERIFIED` — visible and pristine both green; or a `MASKED_FAILURE` cleared by an out-of-band `verify@<head-sha>` approval | `MASKED_FAILURE` (visible green, pristine red) or `SUITE_RED` | cannot verify, failing closed: no suite command, unresolvable base, `--require-ancestor` refused, budget exceeded, or the working or dependency tree moved during the run |
-| `run` | enforcement clean and the agent exited 0 — a non-zero agent exit is passed through unchanged | any blocking finding or masked failure, whatever the agent returned | cannot adjudicate: dirty start, policy error, verify cannot run |
-| `hook claude` / `sweep claude` | always — a deny is JSON on stdout at exit 0, never exit 2 | — | only for an unsupported agent name |
-| `allow` | sign-off recorded | — | no rule or `--reason`, not a git repo, or no current blocking finding to sign off |
-| `init` | wired, or already wired | — | an item needs attention |
-| no or unknown command | help printed (no command) | — | unknown command, help printed |
+| command | 0 | 1 | 2 | 124 |
+| --- | --- | --- | --- | --- |
+| `check` | no blocking finding | at least one blocking finding | cannot evaluate: policy parse error, malformed `--diff` range, no view given, not a git repository, or an unresolvable revision — any failure the gate cannot recover from is one clean `tamperward: …` line on stderr at exit 2, never a stack trace at exit 1 | — |
+| `verify` | `VERIFIED` — visible and pristine both green; or a `MASKED_FAILURE` cleared by an out-of-band `verify@<head-sha>` approval | `MASKED_FAILURE` (visible green, pristine red) or `SUITE_RED` | cannot verify, failing closed: no suite command, unresolvable base, `--require-ancestor` refused, budget exceeded, or the working or dependency tree moved during the run | — |
+| `run` | enforcement clean and the agent exited 0 — another non-zero agent exit is passed through unchanged | any blocking finding or masked failure, including a non-quiescent process after timeout | cannot adjudicate: dirty start, policy error, verify cannot run | `AGENT_TIMEOUT`: `--agent-budget` expired and post-timeout enforcement was clean |
+| `hook claude` / `sweep claude` | always — a deny is JSON on stdout at exit 0, never exit 2 | — | only for an unsupported agent name | — |
+| `allow` | sign-off recorded | — | no rule or `--reason`, not a git repo, or no current blocking finding to sign off | — |
+| `init` | wired, or already wired | — | an item needs attention | — |
+| no or unknown command | help printed (no command) | — | unknown command, help printed | — |
 ### Environment variables

package/dist/cli/index.js CHANGED Viewed

@@ -9694,10 +9694,227 @@ function parseVerify(args) {
 // src/cli/run.ts
 import { execFileSync as execFileSync9, spawnSync as spawnSync3 } from "node:child_process";
-import { readdirSync as readdirSync4, readFileSync as readFileSync16, readlinkSync as readlinkSync4, realpathSync as realpathSync6 } from "node:fs";
-import { resolve as resolve7 } from "node:path";
+import { mkdtempSync as mkdtempSync3, readdirSync as readdirSync4, readFileSync as readFileSync16, readlinkSync as readlinkSync4, realpathSync as realpathSync6, rmSync as rmSync4 } from "node:fs";
+import { tmpdir as tmpdir3 } from "node:os";
+import { join as join16, resolve as resolve7 } from "node:path";
 var out = (s) => process.stdout.write(s + "\n");
 var err = (s) => process.stderr.write(s + "\n");
+var AGENT_SUPERVISOR = String.raw`
+const { spawn, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const [resultFile, budgetRaw, command, ...args] = process.argv.slice(1);
+const budgetMs = Number(budgetRaw);
+let child;
+let timedOut = false;
+let finished = false;
+function writeResult(value) {
+  try { fs.writeFileSync(resultFile, JSON.stringify(value)); } catch {}
+}
+function linuxDescendants(rootPid) {
+  if (process.platform !== 'linux') return [];
+  const byParent = new Map();
+  let names = [];
+  try { names = fs.readdirSync('/proc').filter((x) => /^\d+$/.test(x)); } catch { return []; }
+  for (const name of names) {
+    const pid = Number(name);
+    try {
+      const stat = fs.readFileSync('/proc/' + name + '/stat', 'utf8');
+      const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+      const ppid = Number(fields[1]);
+      if (!Number.isFinite(ppid)) continue;
+      const kids = byParent.get(ppid) || [];
+      kids.push(pid);
+      byParent.set(ppid, kids);
+    } catch {}
+  }
+  const out = [];
+  const seen = new Set([rootPid]);
+  const stack = [rootPid];
+  while (stack.length) {
+    const parent = stack.pop();
+    for (const childPid of (byParent.get(parent) || [])) {
+      if (seen.has(childPid)) continue;
+      seen.add(childPid);
+      out.push(childPid);
+      stack.push(childPid);
+    }
+  }
+  return out;
+}
+function killTree(pid) {
+  if (!pid) return;
+  if (process.platform === 'win32') {
+    try { spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore' }); } catch {}
+    return;
+  }
+  // Snapshot Linux descendants BEFORE killing the process-group leader. A
+  // descendant may have called setsid() and escaped the group while remaining
+  // in the agent's parent/child tree; /proc still lets us identify it.
+  const descendants = linuxDescendants(pid);
+  try { process.kill(-pid, 'SIGKILL'); } catch {
+    try { process.kill(pid, 'SIGKILL'); } catch {}
+  }
+  for (const childPid of descendants.reverse()) {
+    try { process.kill(childPid, 'SIGKILL'); } catch {}
+  }
+}
+try {
+  child = spawn(command, args, {
+    stdio: 'inherit',
+    detached: process.platform !== 'win32',
+  });
+} catch (e) {
+  writeResult({ exit: 1, timedOut: false, failure: String(e) });
+  process.exit(0);
+}
+writeResult({ pid: child.pid, started: true });
+const timer = setTimeout(() => {
+  timedOut = true;
+  killTree(child.pid);
+}, budgetMs);
+timer.unref();
+child.once('error', (e) => {
+  if (finished) return;
+  finished = true;
+  clearTimeout(timer);
+  writeResult({ exit: 1, timedOut, failure: String(e) });
+  process.exit(0);
+});
+child.once('exit', (code, signal) => {
+  if (finished) return;
+  finished = true;
+  clearTimeout(timer);
+  // A timeout owns the public status even when the killed process reports a
+  // shell-specific signal/exit value. The envelope will still adjudicate.
+  writeResult({
+    exit: timedOut ? 124 : (code == null ? 1 : code),
+    timedOut,
+    signal: signal == null ? null : String(signal),
+  });
+  process.exit(0);
+});
+`;
+function linuxDescendantPids(rootPid) {
+  if (process.platform !== "linux") return [];
+  const byParent = /* @__PURE__ */ new Map();
+  let names;
+  try {
+    names = readdirSync4("/proc").filter((x) => /^\d+$/.test(x));
+  } catch {
+    return [];
+  }
+  for (const name of names) {
+    const pid = Number(name);
+    try {
+      const stat = readFileSync16(`/proc/${name}/stat`, "utf8");
+      const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+      const ppid = Number(fields[1]);
+      if (!Number.isFinite(ppid)) continue;
+      const kids = byParent.get(ppid) ?? [];
+      kids.push(pid);
+      byParent.set(ppid, kids);
+    } catch {
+    }
+  }
+  const out2 = [];
+  const seen = /* @__PURE__ */ new Set([rootPid]);
+  const stack = [rootPid];
+  while (stack.length) {
+    const parent = stack.pop();
+    for (const childPid of byParent.get(parent) ?? []) {
+      if (seen.has(childPid)) continue;
+      seen.add(childPid);
+      out2.push(childPid);
+      stack.push(childPid);
+    }
+  }
+  return out2;
+}
+function killAgentTree(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) return;
+  if (process.platform === "win32") {
+    try {
+      spawnSync3("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore", timeout: 5e3 });
+    } catch {
+    }
+    return;
+  }
+  const descendants = linuxDescendantPids(pid);
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+  for (const childPid of descendants.reverse()) {
+    try {
+      process.kill(childPid, "SIGKILL");
+    } catch {
+    }
+  }
+}
+function runAgentWithBudget(argv2, cwd, budgetSecs) {
+  const stateDir = mkdtempSync3(join16(tmpdir3(), "tw-agent-supervisor-"));
+  const resultFile = join16(stateDir, "result.json");
+  let supervisorTimedOut = false;
+  try {
+    const supervisor = spawnSync3(
+      process.execPath,
+      ["-e", AGENT_SUPERVISOR, resultFile, String(budgetSecs * 1e3), ...argv2],
+      {
+        cwd,
+        stdio: "inherit",
+        // Backstop only. The inner supervisor owns the intended budget and
+        // process-tree kill. This prevents a broken supervisor hanging run.
+        timeout: Math.ceil(budgetSecs * 1e3) + 1e4,
+        killSignal: "SIGKILL"
+      }
+    );
+    supervisorTimedOut = Boolean(supervisor.error) && supervisor.error.code === "ETIMEDOUT";
+    let state = {};
+    try {
+      state = JSON.parse(readFileSync16(resultFile, "utf8"));
+    } catch {
+    }
+    if (supervisorTimedOut || state.timedOut) {
+      if (state.pid) killAgentTree(state.pid);
+      return {
+        exit: 124,
+        timedOut: true,
+        signal: state.signal ?? null,
+        ...state.failure ? { failure: state.failure } : {}
+      };
+    }
+    if (typeof state.exit === "number") {
+      return {
+        exit: state.exit,
+        timedOut: false,
+        signal: state.signal ?? null,
+        ...state.failure ? { failure: state.failure } : {}
+      };
+    }
+    if (state.pid) killAgentTree(state.pid);
+    return {
+      exit: 1,
+      timedOut: false,
+      failure: state.failure ?? "agent supervisor did not produce a final status"
+    };
+  } finally {
+    rmSync4(stateDir, { recursive: true, force: true });
+  }
+}
 function git3(args, cwd) {
   return execFileSync9("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
 }
@@ -9759,6 +9976,12 @@ function runEnvelope(opts) {
     err("tamperward run: no agent command given (usage: tamperward run [options] -- <command...>)");
     return 2;
   }
+  if (opts.agentBudget !== void 0 && (!Number.isFinite(opts.agentBudget) || opts.agentBudget <= 0)) {
+    err(
+      `tamperward run: --agent-budget needs a positive number of seconds (got ${JSON.stringify(opts.agentBudget)}) \u2014 failing closed.`
+    );
+    return 2;
+  }
   let base;
   try {
     base = git3(["rev-parse", "--verify", `${opts.base ?? "HEAD"}^{commit}`], cwd).trim();
@@ -9820,8 +10043,25 @@ function runEnvelope(opts) {
   }
   const rewritesBefore = objectRewriteState(cwd);
   const spawnTicks = nowTicks();
-  const agent = spawnSync3(opts.argv[0], opts.argv.slice(1), { cwd, stdio: "inherit" });
-  const agentExit = agent.status ?? 1;
+  const agentRun = opts.agentBudget === void 0 ? (() => {
+    const agent = spawnSync3(opts.argv[0], opts.argv.slice(1), { cwd, stdio: "inherit" });
+    return {
+      exit: agent.status ?? 1,
+      timedOut: false,
+      signal: agent.signal ? String(agent.signal) : null,
+      ...agent.error ? { failure: agent.error.message } : {}
+    };
+  })() : runAgentWithBudget(opts.argv, cwd, opts.agentBudget);
+  const agentExit = agentRun.exit;
+  const agentTimedOut = agentRun.timedOut;
+  if (agentRun.failure && !agentTimedOut) {
+    err(`tamperward run: agent runtime failed to start/report cleanly (${agentRun.failure}) \u2014 continuing to adjudicate the released tree.`);
+  }
+  if (agentTimedOut) {
+    err(
+      `tamperward run: AGENT_TIMEOUT \u2014 wrapped agent exceeded ${opts.agentBudget}s; its owned process tree was terminated. Post-timeout adjudication continues.`
+    );
+  }
   if (objectRewriteState(cwd) !== rewritesBefore) {
     err("tamperward run: git object-replacement state changed during this run \u2014 a replace ref, graft");
     err("or shallow boundary now redirects what the trusted base resolves to. Nothing below could be");
@@ -9902,10 +10142,11 @@ tamperward run \u2014 agent exit ${agentExit}; HISTORY_REWRITE \u2192 ENFORCEMEN
   const cannot = !notQuiescent && (diffCode === 2 || workCode === 2 || verifyCode === 2);
   const blocked = diffCode === 1 || workCode === 1 || verifyCode === 1 || notQuiescent;
   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" : 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" : 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 agent exit ${agentExit}; checks diff=${diffCode} worktree=${workCode} verify=${verifyCode} \u2192 ${verdict2}`);
-  return enforcement !== 0 ? enforcement : agentExit;
+tamperward run \u2014 ${agentSummary}; checks diff=${diffCode} worktree=${workCode} verify=${verifyCode} \u2192 ${verdict2}`);
+  return enforcement !== 0 ? enforcement : agentTimedOut ? 124 : agentExit;
 }
 function parseRun(args) {
   const o = { argv: [] };
@@ -9917,6 +10158,7 @@ function parseRun(args) {
     } else if (a === "--base") o.base = args[++i];
     else if (a === "--cmd") o.cmd = args[++i];
     else if (a === "--budget") o.budget = Number(args[++i]);
+    else if (a === "--agent-budget") o.agentBudget = Number(args[++i]);
     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;
@@ -10014,13 +10256,14 @@ Formats:
                                             fails closed (2)
   tamperward run [opts] -- <agent cmd...>   enforcement envelope: record the trusted
              [--base R] [--cmd C]           base, run the agent, treat its exit as
-             [--budget S] [--allow-dirty]   untrusted, then re-adjudicate the tree it
-             [--settle S] [--allow-dep-drift] left (policy over base...HEAD and the
-             [--cwd D]
-                                            worktree, plus verify). Exit: agent's code
-                                            when clean; 1 on any blocking finding or
-                                            masked failure; 2 when it cannot
-                                            adjudicate (fails closed)
+             [--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
+                                            code when clean; 124 on clean AGENT_TIMEOUT;
+                                            1 on any blocking finding/masked failure;
+                                            2 when it cannot adjudicate (fails closed)
   tamperward allow <rule> --reason "..."    record a human sign-off (local audit ledger)
              [--file F] [--cwd D]
   tamperward init [--dry-run]               wire the policy file plus every

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "2.11.2",
+  "version": "2.11.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",