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

tamperward 2.11.2 → 2.12.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

@@ -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
@@ -190,6 +199,16 @@ are involved here, and they are not the same thing.
    its policy, verification surface and verifier command and budget from that same
    trusted base — so neither step's verdict is governed by the candidate.
+Since **2.12.0**, the generated job uses GitHub Actions' 360-minute outer timeout and
+runs `tamperward doctor` before verification. The doctor reads the **trusted base**
+policy, finds the job(s) that actually invoke `tamperward verify`, and requires enough
+static outer time for both independently budgeted stages plus a 60-minute authority
+reserve. With the generated 360-minute job that means budgets up to 9,000 seconds per
+stage fit. Larger positive finite policy budgets remain valid — there is no schema cap —
+but this generated GitHub-hosted authority refuses deterministically and tells you how
+much outer time is required, so a custom runner/workflow can provide it instead of
+GitHub killing verification mid-verdict.
 Legitimate exceptions are out-of-band PR labels, `tamperward:allow:<rule>@<head-sha>`.
 The workflow passes the head SHA to both steps through `TAMPERWARD_OOB_HEAD`, so an
 approval is bound to the exact commit it was granted for and a new push invalidates it.
@@ -294,7 +313,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 +331,8 @@ 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...>` |
+| `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...>` |
 | `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 +340,16 @@ 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 | — |
+| `doctor` | configured verify job(s) have sufficient static outer time for the trusted policy | — | missing/invalid workflow, no verify job, missing/malformed/insufficient timeout, or trusted policy cannot be loaded | — |
+| `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

@@ -674,9 +674,9 @@ function git(args, cwd) {
       env: trustedGitEnv()
     });
   } catch (e) {
-    const err2 = e;
-    const detail = String(err2.stderr ?? "").trim();
-    throw new Error(detail ? `git ${args[0]}: ${detail}` : err2.message ?? `git ${args[0]} failed`);
+    const err3 = e;
+    const detail = String(err3.stderr ?? "").trim();
+    throw new Error(detail ? `git ${args[0]}: ${detail}` : err3.message ?? `git ${args[0]} failed`);
   }
 }
 function blobAt(rev, path, cwd) {
@@ -864,11 +864,11 @@ function synthFileChange(displayPath, before, after) {
         maxBuffer: 256 * 1024 * 1024
       });
     } catch (e) {
-      const err2 = e;
-      if (err2.status !== 1) {
-        throw new Error(`cannot diff the incoming edit to ${displayPath}: ${err2.code ?? err2.message ?? String(e)}`);
+      const err3 = e;
+      if (err3.status !== 1) {
+        throw new Error(`cannot diff the incoming edit to ${displayPath}: ${err3.code ?? err3.message ?? String(e)}`);
       }
-      raw = err2.stdout ? String(err2.stdout) : "";
+      raw = err3.stdout ? String(err3.stdout) : "";
     }
   } finally {
     rmSync(dir, { recursive: true, force: true });
@@ -1585,7 +1585,7 @@ function branchExists(name, ctx) {
 }
 function revIsHead(rev, ctx) {
   if (!ctx?.cwd || rev.startsWith("-")) return null;
-  const parse3 = (r) => {
+  const parse4 = (r) => {
     try {
       return execFileSync4("git", ["rev-parse", "--verify", "--quiet", "--end-of-options", `${r}^{commit}`], {
         cwd: ctx.cwd,
@@ -1596,8 +1596,8 @@ function revIsHead(rev, ctx) {
       return null;
     }
   };
-  const head = parse3("HEAD");
-  const target = parse3(rev);
+  const head = parse4("HEAD");
+  const target = parse4(rev);
   if (!head || !target) return null;
   return head === target;
 }
@@ -1651,8 +1651,8 @@ function numericOf(e) {
   }
   return void 0;
 }
-function metricsOf(expr, resolve8) {
-  const obj = resolve8(expr);
+function metricsOf(expr, resolve9) {
+  const obj = resolve9(expr);
   if (!ts2.isObjectLiteralExpression(obj)) return void 0;
   const out2 = { values: {}, opaque: false };
   let any = false;
@@ -1666,7 +1666,7 @@ function metricsOf(expr, resolve8) {
     const k = keyName(p.name);
     if (k === null || !isMetric(k)) continue;
     any = true;
-    const n = numericOf(resolve8(p.initializer));
+    const n = numericOf(resolve9(p.initializer));
     if (n === void 0) out2.opaque = true;
     else out2.values[k] = n;
   }
@@ -1712,17 +1712,17 @@ function parseThresholds(src) {
   const res = { paths: /* @__PURE__ */ new Map(), present: false, opaque: false };
   try {
     const sf = sourceOf(src);
-    const resolve8 = resolverFor(sf);
+    const resolve9 = resolverFor(sf);
     const visit = (node) => {
       if (ts2.isPropertyAssignment(node)) {
         const key2 = keyName(node.name);
         if (key2 === "coverageThreshold" || key2 === "thresholds" && underKey(node, "coverage")) {
           res.present = true;
-          const init = resolve8(node.initializer);
+          const init = resolve9(node.initializer);
           if (!ts2.isObjectLiteralExpression(init)) {
             res.opaque = true;
           } else {
-            const flat = metricsOf(init, resolve8);
+            const flat = metricsOf(init, resolve9);
             if (flat) res.global = merge(res.global, flat);
             for (const p of init.properties) {
               if (ts2.isSpreadAssignment(p)) {
@@ -1736,7 +1736,7 @@ function parseThresholds(src) {
                 res.global = merge(res.global, { values: { branches: 100, functions: 100, lines: 100, statements: 100 }, opaque: false });
                 continue;
               }
-              const m = metricsOf(p.initializer, resolve8);
+              const m = metricsOf(p.initializer, resolve9);
               if (!m) continue;
               if (k === "global") res.global = merge(res.global, m);
               else res.paths.set(norm(k), m);
@@ -1769,18 +1769,18 @@ function parseLists(src) {
   const res = { collectFrom: null, collectKey: "collectCoverageFrom", ignore: [], opaqueCollect: false, opaqueIgnore: false };
   try {
     const sf = sourceOf(src);
-    const resolve8 = resolverFor(sf);
+    const resolve9 = resolverFor(sf);
     const visit = (node) => {
       if (ts2.isPropertyAssignment(node)) {
         const k = keyName(node.name);
         const vitestCoverage = ownerKey(node) === "coverage";
         if (k === "collectCoverageFrom" || k === "include" && vitestCoverage) {
-          const { items, opaque } = literals(resolve8(node.initializer));
+          const { items, opaque } = literals(resolve9(node.initializer));
           res.collectFrom = items;
           res.collectKey = k === "include" ? "coverage.include" : k;
           if (opaque) res.opaqueCollect = true;
         } else if (k === "coveragePathIgnorePatterns" || k === "exclude" && vitestCoverage) {
-          const { items, opaque } = literals(resolve8(node.initializer));
+          const { items, opaque } = literals(resolve9(node.initializer));
           res.ignore.push(...items);
           if (opaque) res.opaqueIgnore = true;
         }
@@ -7600,6 +7600,36 @@ 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 statSync3 } 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
+var VERIFIER_STAGE_COUNT = 2;
+var GENERATED_CI_TIMEOUT_MINUTES = 360;
+var GENERATED_CI_MIN_OVERHEAD_RESERVE_SECS = 60 * 60;
+function assertEnvelopeConstants() {
+  if (!Number.isInteger(VERIFIER_STAGE_COUNT) || VERIFIER_STAGE_COUNT < 1) {
+    throw new Error("TamperWard verifier envelope: stage count must be a positive integer");
+  }
+  if (!Number.isFinite(GENERATED_CI_TIMEOUT_MINUTES) || GENERATED_CI_TIMEOUT_MINUTES <= 0) {
+    throw new Error("TamperWard verifier envelope: generated CI timeout must be positive");
+  }
+  if (!Number.isFinite(GENERATED_CI_MIN_OVERHEAD_RESERVE_SECS) || GENERATED_CI_MIN_OVERHEAD_RESERVE_SECS < 0) {
+    throw new Error("TamperWard verifier envelope: overhead reserve cannot be negative");
+  }
+  if (GENERATED_CI_TIMEOUT_MINUTES * 60 <= GENERATED_CI_MIN_OVERHEAD_RESERVE_SECS) {
+    throw new Error(
+      "TamperWard verifier envelope: generated CI timeout leaves no time for verifier stages"
+    );
+  }
+}
+assertEnvelopeConstants();
+function requiredVerifierAuthoritySeconds(stageBudgetSecs) {
+  if (!Number.isFinite(stageBudgetSecs) || stageBudgetSecs <= 0) {
+    throw new Error("verifier stage budget must be a positive finite number");
+  }
+  return VERIFIER_STAGE_COUNT * stageBudgetSecs + GENERATED_CI_MIN_OVERHEAD_RESERVE_SECS;
+}
+// src/cli/init.ts
 var errText3 = (e) => (e instanceof Error ? e.message : String(e)).replace(/\s+/g, " ").trim();
 var isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function gitConfig(cwd, key2) {
@@ -7690,7 +7720,7 @@ permissions:
 jobs:
   tamperward:
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: ${GENERATED_CI_TIMEOUT_MINUTES}
     steps:
       - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
@@ -7708,6 +7738,12 @@ jobs:
           # Candidate code runs later in this job. Do not leave the checkout
           # token in .git/config where a verifier command can read/reuse it.
           persist-credentials: false
+      - name: Tamperward doctor (CI verifier envelope)
+        # Validate the outer GitHub job budget against the TRUSTED base policy
+        # before starting visible/pristine execution. Large policy budgets remain
+        # valid for custom runners; this generated authority refuses if its host
+        # cannot accommodate both stages plus cleanup/reporting reserve.
+        run: tamperward doctor --base "\${{ github.event.pull_request.base.sha }}" --workflow .github/workflows/tamperward.yml
       - name: Resolve out-of-band sign-off from PR labels
         id: oob
         env:
@@ -8190,12 +8226,139 @@ tamperward init: ${changed} change(s) applied. Commit them so the gate travels w
   return 0;
 }
+// src/cli/doctor.ts
+import { existsSync as existsSync10, readFileSync as readFileSync13, readdirSync as readdirSync3 } from "node:fs";
+import { join as join13, resolve as resolve4 } from "node:path";
+import { parse as parse3 } from "yaml";
+var VERIFY_COMMAND = /\btamperward(?:@\S+)?\s+verify\b/;
+function err(message) {
+  process.stderr.write(`tamperward doctor: ${message}
+`);
+  return 2;
+}
+function policyFor(opts, cwd) {
+  if (!opts.base) return loadPolicy(cwd);
+  const atBase = loadPolicyAt(opts.base, cwd);
+  return atBase ?? defaultPolicy();
+}
+function asMapping(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function verifyJobs(doc) {
+  const root = asMapping(doc);
+  const jobs = asMapping(root?.jobs);
+  if (!jobs) return [];
+  const found = [];
+  for (const [name, raw] of Object.entries(jobs)) {
+    const job = asMapping(raw);
+    if (!job || !Array.isArray(job.steps)) continue;
+    const hasVerify = job.steps.some((step) => {
+      const item = asMapping(step);
+      return typeof item?.run === "string" && VERIFY_COMMAND.test(item.run);
+    });
+    if (hasVerify) found.push({ name, job });
+  }
+  return found;
+}
+function runDoctor(opts = {}) {
+  const cwd = resolve4(opts.cwd ?? process.cwd());
+  let policy;
+  try {
+    policy = policyFor(opts, cwd);
+  } catch (e) {
+    return err(e instanceof PolicyError || e instanceof Error ? e.message : String(e));
+  }
+  if (!policy.verify?.command) {
+    return err("trusted policy has no verify.command; generated CI cannot verify this repository");
+  }
+  const workflowRels = [];
+  if (opts.workflow) {
+    workflowRels.push(opts.workflow);
+  } else {
+    const workflowDirRel = ".github/workflows";
+    const workflowDir = resolve4(cwd, workflowDirRel);
+    if (!existsSync10(workflowDir)) {
+      return err(`${workflowDirRel}: workflow directory does not exist`);
+    }
+    let entries;
+    try {
+      entries = readdirSync3(workflowDir).filter((name) => /\.ya?ml$/i.test(name)).sort();
+    } catch (e) {
+      return err(
+        `${workflowDirRel}: could not enumerate workflows (${e instanceof Error ? e.message : String(e)})`
+      );
+    }
+    for (const name of entries) workflowRels.push(join13(workflowDirRel, name));
+  }
+  const requiredSecs = requiredVerifierAuthoritySeconds(policy.verify.budget);
+  const requiredMinutes = Math.ceil(requiredSecs / 60);
+  let verifyJobCount = 0;
+  for (const workflowRel of workflowRels) {
+    const workflowPath = resolve4(cwd, workflowRel);
+    if (!existsSync10(workflowPath)) {
+      return err(`${workflowRel}: workflow does not exist`);
+    }
+    let doc;
+    try {
+      doc = parse3(readFileSync13(workflowPath, "utf8"));
+    } catch (e) {
+      return err(
+        `${workflowRel}: workflow is not valid YAML (${e instanceof Error ? e.message : String(e)})`
+      );
+    }
+    const jobs = verifyJobs(doc);
+    verifyJobCount += jobs.length;
+    for (const { name, job } of jobs) {
+      const timeout = job["timeout-minutes"];
+      if (timeout === void 0 || timeout === null) {
+        return err(
+          `${workflowRel} job "${name}": timeout-minutes is missing; requires at least ${requiredMinutes} minutes`
+        );
+      }
+      if (typeof timeout === "string" && timeout.includes("${{")) {
+        return err(
+          `${workflowRel} job "${name}": timeout-minutes must be a static numeric value; requires at least ${requiredMinutes} minutes`
+        );
+      }
+      if (typeof timeout !== "number" || !Number.isFinite(timeout)) {
+        return err(
+          `${workflowRel} job "${name}": timeout-minutes must be numeric; got ${JSON.stringify(timeout)}`
+        );
+      }
+      if (timeout <= 0) {
+        return err(
+          `${workflowRel} job "${name}": timeout-minutes must be positive; got ${timeout}`
+        );
+      }
+      if (!Number.isInteger(timeout)) {
+        return err(
+          `${workflowRel} job "${name}": timeout-minutes must be a whole number; got ${timeout}`
+        );
+      }
+      if (timeout < requiredMinutes) {
+        return err(
+          `${workflowRel} job "${name}": timeout-minutes ${timeout} is too small; trusted verify.budget ${policy.verify.budget}s requires at least ${requiredMinutes} minutes for visible + pristine + authority overhead`
+        );
+      }
+    }
+  }
+  if (verifyJobCount === 0) {
+    const scope = opts.workflow ?? ".github/workflows/*.yml|*.yaml";
+    return err(`${scope}: no job contains a tamperward verify step`);
+  }
+  process.stdout.write(
+    `tamperward doctor: CI verifier envelope OK \u2014 ${verifyJobCount} verify job(s), trusted budget ${policy.verify.budget}s/stage, requires >=${requiredMinutes}m outer timeout.
+`
+  );
+  return 0;
+}
 // src/cli/verify.ts
 import { execFileSync as execFileSync8, spawnSync as spawnSync2 } from "node:child_process";
 import { createHash as createHash10 } from "node:crypto";
-import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync4, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync15, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync4, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
-import { dirname as dirname7, isAbsolute as isAbsolute10, join as join15, relative as relative5, resolve as resolve6, sep as sep2 } from "node:path";
+import { dirname as dirname7, isAbsolute as isAbsolute10, join as join16, relative as relative5, resolve as resolve7, sep as sep2 } from "node:path";
 // src/fingerprint.ts
 import { execFileSync as execFileSync7 } from "node:child_process";
@@ -8226,10 +8389,10 @@ function treeFingerprint(cwd, keepIgnored) {
 // src/dependency-env.ts
 import { createHash as createHash8 } from "node:crypto";
 import {
-  existsSync as existsSync10,
+  existsSync as existsSync11,
   lstatSync as lstatSync3,
-  readdirSync as readdirSync3,
-  readFileSync as readFileSync13,
+  readdirSync as readdirSync4,
+  readFileSync as readFileSync14,
   readlinkSync as readlinkSync2,
   realpathSync as realpathSync3,
   statSync as statSync4
@@ -8239,15 +8402,15 @@ import {
   delimiter,
   dirname as dirname5,
   isAbsolute as isAbsolute9,
-  join as join13,
+  join as join14,
   relative as relative4,
-  resolve as resolve4,
+  resolve as resolve5,
   sep
 } from "node:path";
 var Unattestable = class extends Error {
 };
 function inside(root, candidate) {
-  const rel = relative4(resolve4(root), resolve4(candidate));
+  const rel = relative4(resolve5(root), resolve5(candidate));
   return rel === "" || rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute9(rel);
 }
 function modeKind(path) {
@@ -8286,7 +8449,7 @@ function fingerprintRoot(root, cwd, h) {
       st = statSync4(path);
       if (!st.isFile()) throw new Error("not a regular file");
       h.update(label + "\0external-file\0" + path + "\0" + String(st.mode) + "\0");
-      h.update(readFileSync13(path));
+      h.update(readFileSync14(path));
       h.update("\0");
     } catch (e) {
       throw new Unattestable(
@@ -8300,14 +8463,14 @@ function fingerprintRoot(root, cwd, h) {
     visited.add(realDir);
     let entries;
     try {
-      entries = readdirSync3(dir, { withFileTypes: true });
+      entries = readdirSync4(dir, { withFileTypes: true });
     } catch (e) {
       throw new Unattestable(
         "dependency directory " + JSON.stringify(dir) + " cannot be read (" + (e instanceof Error ? e.message : String(e)) + ")"
       );
     }
     for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
-      const path = join13(dir, entry.name);
+      const path = join14(dir, entry.name);
       const rel = namespace ? namespace + "/" + entry.name : entry.name;
       let ident;
       try {
@@ -8320,7 +8483,7 @@ function fingerprintRoot(root, cwd, h) {
       h.update(rel + "\0" + ident.kind + "\0" + String(ident.mode) + "\0");
       if (ident.kind === "file") {
         try {
-          h.update(readFileSync13(path));
+          h.update(readFileSync14(path));
           h.update("\0");
         } catch (e) {
           throw new Unattestable(
@@ -8379,7 +8542,7 @@ function snapshot(roots, probes, cwd) {
   const h = createHash8("sha256");
   for (const probe of probes) {
     h.update(
-      "probe\0" + probe.kind + "\0" + probe.path + "\0" + (existsSync10(probe.path) ? "present" : "absent") + "\0"
+      "probe\0" + probe.kind + "\0" + probe.path + "\0" + (existsSync11(probe.path) ? "present" : "absent") + "\0"
     );
   }
   for (const root of roots) fingerprintRoot(root, cwd, h);
@@ -8390,7 +8553,7 @@ function freezeRoot(kind, path) {
     if (!statSync4(path).isDirectory()) {
       throw new Error("not a directory");
     }
-    return { kind, path: resolve4(path), realPath: realpathSync3(path) };
+    return { kind, path: resolve5(path), realPath: realpathSync3(path) };
   } catch (e) {
     throw new Unattestable(
       kind + " root " + JSON.stringify(path) + " is not resolvable (" + (e instanceof Error ? e.message : String(e)) + ")"
@@ -8426,17 +8589,17 @@ function firstExecutable(command) {
 function resolveExecutable(token, cwd, env) {
   if (!token) return null;
   if (token.includes("/") || token.includes("\\")) {
-    const path = isAbsolute9(token) ? token : resolve4(cwd, token);
+    const path = isAbsolute9(token) ? token : resolve5(cwd, token);
     try {
-      return existsSync10(path) ? realpathSync3(path) : null;
+      return existsSync11(path) ? realpathSync3(path) : null;
     } catch {
       return null;
     }
   }
   for (const entry of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
-    const candidate = resolve4(entry, token);
+    const candidate = resolve5(entry, token);
     try {
-      if (existsSync10(candidate) && statSync4(candidate).isFile()) return realpathSync3(candidate);
+      if (existsSync11(candidate) && statSync4(candidate).isFile()) return realpathSync3(candidate);
     } catch {
     }
   }
@@ -8453,13 +8616,13 @@ function looksPython(command, executable, token) {
 }
 function inferredVenvFromToken(token, cwd) {
   if (!token || !token.includes("/") && !token.includes("\\")) return null;
-  const path = isAbsolute9(token) ? token : resolve4(cwd, token);
+  const path = isAbsolute9(token) ? token : resolve5(cwd, token);
   if (!pythonName(basename3(path))) return null;
   const parent = dirname5(path);
   const parentName = basename3(parent).toLowerCase();
   if (parentName !== "bin" && parentName !== "scripts") return null;
   const root = dirname5(parent);
-  return existsSync10(join13(root, "pyvenv.cfg")) ? root : null;
+  return existsSync11(join14(root, "pyvenv.cfg")) ? root : null;
 }
 function unsupportedEcosystem(command, token) {
   const name = token ? basename3(token).toLowerCase() : "";
@@ -8475,13 +8638,13 @@ function inferredVenv(executable) {
   const parentName = basename3(parent).toLowerCase();
   if (parentName !== "bin" && parentName !== "scripts") return null;
   const root = dirname5(parent);
-  return existsSync10(join13(root, "pyvenv.cfg")) ? root : null;
+  return existsSync11(join14(root, "pyvenv.cfg")) ? root : null;
 }
 function venvProblem(root) {
-  const cfg = join13(root, "pyvenv.cfg");
-  if (!existsSync10(cfg)) return "VIRTUAL_ENV " + JSON.stringify(root) + " has no pyvenv.cfg";
+  const cfg = join14(root, "pyvenv.cfg");
+  if (!existsSync11(cfg)) return "VIRTUAL_ENV " + JSON.stringify(root) + " has no pyvenv.cfg";
   try {
-    const body = readFileSync13(cfg, "utf8");
+    const body = readFileSync14(cfg, "utf8");
     if (/^\s*include-system-site-packages\s*=\s*true\s*$/im.test(body)) {
       return "Python environment " + JSON.stringify(root) + " enables system site-packages; those external package roots are not bounded";
     }
@@ -8491,7 +8654,7 @@ function venvProblem(root) {
   return null;
 }
 function discoverDependencyEnvironment(cwdInput, command, env = process.env) {
-  const cwd = resolve4(cwdInput);
+  const cwd = resolve5(cwdInput);
   const roots = [];
   const probes = [];
   const seen = /* @__PURE__ */ new Set();
@@ -8504,8 +8667,8 @@ function discoverDependencyEnvironment(cwdInput, command, env = process.env) {
     }
   };
   try {
-    const nodeModules = join13(cwd, "node_modules");
-    if (existsSync10(nodeModules)) addRoot("node_modules", nodeModules);
+    const nodeModules = join14(cwd, "node_modules");
+    if (existsSync11(nodeModules)) addRoot("node_modules", nodeModules);
     else probes.push({ kind: "node_modules", path: nodeModules });
     const token = firstExecutable(command);
     const executable = resolveExecutable(token, cwd, env);
@@ -8514,11 +8677,11 @@ function discoverDependencyEnvironment(cwdInput, command, env = process.env) {
       if (!isAbsolute9(env.VIRTUAL_ENV)) {
         throw new Unattestable("VIRTUAL_ENV is relative (" + JSON.stringify(env.VIRTUAL_ENV) + ")");
       }
-      venv = resolve4(env.VIRTUAL_ENV);
+      venv = resolve5(env.VIRTUAL_ENV);
     } else {
       venv = inferredVenv(executable) ?? inferredVenvFromToken(token, cwd);
-      if (!venv && /(?:^|\s)uv\s+run(?:\s|$)/.test(command) && existsSync10(join13(cwd, ".venv", "pyvenv.cfg"))) {
-        venv = join13(cwd, ".venv");
+      if (!venv && /(?:^|\s)uv\s+run(?:\s|$)/.test(command) && existsSync11(join14(cwd, ".venv", "pyvenv.cfg"))) {
+        venv = join14(cwd, ".venv");
       }
     }
     if (venv) {
@@ -8550,7 +8713,7 @@ function checkDependencyEnvironment(cwdInput, descriptor) {
     return { ok: false, reason: descriptor.reason ?? "dependency environment is not attestable" };
   }
   try {
-    const fingerprint2 = snapshot(descriptor.roots, descriptor.probes, resolve4(cwdInput));
+    const fingerprint2 = snapshot(descriptor.roots, descriptor.probes, resolve5(cwdInput));
     if (fingerprint2 !== descriptor.fingerprint) {
       return { ok: false, fingerprint: fingerprint2, reason: "dependency environment fingerprint changed" };
     }
@@ -8579,8 +8742,8 @@ function dependencyEnvironmentSummary(descriptor) {
 // src/verifier-backend.ts
 import { createHash as createHash9, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { accessSync, constants as constants2, readFileSync as readFileSync14, realpathSync as realpathSync4, statSync as statSync5 } from "node:fs";
-import { delimiter as delimiter2, dirname as dirname6, join as join14, resolve as resolve5 } from "node:path";
+import { accessSync, constants as constants2, readFileSync as readFileSync15, realpathSync as realpathSync4, statSync as statSync5 } from "node:fs";
+import { delimiter as delimiter2, dirname as dirname6, join as join15, resolve as resolve6 } from "node:path";
 var DEFAULT_CONTAINER_RESOURCE_LIMITS = Object.freeze({
   memoryBytes: 2 * 1024 * 1024 * 1024,
   // Docker interprets memory-swap == memory as no additional swap allowance.
@@ -8609,7 +8772,7 @@ function writableByCaller(path) {
   }
 }
 function replaceableByCaller(path) {
-  let current = resolve5(path);
+  let current = resolve6(path);
   if (writableByCaller(current)) return true;
   current = dirname6(current);
   while (true) {
@@ -8623,7 +8786,7 @@ function replaceableByCaller(path) {
 function findExecutable(name) {
   for (const raw of (process.env.PATH ?? "").split(delimiter2)) {
     if (!raw) continue;
-    const candidate = join14(raw, name);
+    const candidate = join15(raw, name);
     try {
       accessSync(candidate, constants2.X_OK);
       return realpathSync4(candidate);
@@ -8633,7 +8796,7 @@ function findExecutable(name) {
   return null;
 }
 function fileSha256(path) {
-  return createHash9("sha256").update(readFileSync14(path)).digest("hex");
+  return createHash9("sha256").update(readFileSync15(path)).digest("hex");
 }
 function engineClientEnv() {
   return {
@@ -8955,7 +9118,7 @@ function runContainerStage(backend, dir, command, budgetSecs) {
   const args = containerRunArgs({
     image: backend.image,
     name,
-    workspace: resolve5(dir),
+    workspace: resolve6(dir),
     command,
     uid,
     gid,
@@ -9124,7 +9287,7 @@ function baseIsAncestorOfHead(base, cwd) {
   return r.status === 0;
 }
 function inside2(root, path) {
-  const rel = relative5(resolve6(root), resolve6(path));
+  const rel = relative5(resolve7(root), resolve7(path));
   return rel === "" || rel !== ".." && !rel.startsWith(`..${sep2}`) && !isAbsolute10(rel);
 }
 function linkParts(path) {
@@ -9141,7 +9304,7 @@ function rootedLinkTarget(target) {
   return isAbsolute10(target) || driveRelativeLinkTarget(target);
 }
 function safeSymlink(target, out2, root, label) {
-  if (rootedLinkTarget(target) || !inside2(root, resolve6(dirname7(out2), target))) {
+  if (rootedLinkTarget(target) || !inside2(root, resolve7(dirname7(out2), target))) {
     throw linkEscape(label, target);
   }
   rmSync3(out2, { force: true });
@@ -9167,7 +9330,7 @@ function validateSymlinkGraph(target, out2, root, dependencyRoot, label) {
       continue;
     }
     const base = domain === "tree" ? root : dependencyRoot;
-    const current = join15(base, ...stack);
+    const current = join16(base, ...stack);
     let st;
     try {
       st = lstatSync4(current);
@@ -9193,7 +9356,7 @@ function validateSymlinkGraph(target, out2, root, dependencyRoot, label) {
         throw linkEscape(label, target);
       }
       stack = [];
-      pending.unshift(...linkParts(relative5(dependencyRoot, resolve6(next))));
+      pending.unshift(...linkParts(relative5(dependencyRoot, resolve7(next))));
     } else {
       pending.unshift(...linkParts(next));
     }
@@ -9203,7 +9366,7 @@ function rejectLinkedParent(cwd, rel) {
   const parts = rel.split("/").slice(0, -1);
   let current = cwd;
   for (const part of parts) {
-    current = join15(current, part);
+    current = join16(current, part);
     let st;
     try {
       st = lstatSync4(current);
@@ -9219,7 +9382,7 @@ function materialize(cwd, dest, dependencyRoot) {
   const listed = git2(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], cwd).split("\0").filter(Boolean);
   const links = [];
   for (const rel of listed) {
-    const src = join15(cwd, rel);
+    const src = join16(cwd, rel);
     rejectLinkedParent(cwd, rel);
     let st;
     try {
@@ -9227,7 +9390,7 @@ function materialize(cwd, dest, dependencyRoot) {
     } catch {
       continue;
     }
-    const out2 = join15(dest, rel);
+    const out2 = join16(dest, rel);
     mkdirSync6(dirname7(out2), { recursive: true });
     dropSymlink(out2);
     if (st.isSymbolicLink()) {
@@ -9244,7 +9407,7 @@ function materialize(cwd, dest, dependencyRoot) {
   for (const link of links) {
     validateSymlinkGraph(link.target, link.out, dest, dependencyRoot, link.rel);
   }
-  if (dependencyRoot) symlinkSync(dependencyRoot, join15(dest, "node_modules"), "dir");
+  if (dependencyRoot) symlinkSync(dependencyRoot, join16(dest, "node_modules"), "dir");
 }
 function dropSymlink(p) {
   try {
@@ -9277,11 +9440,11 @@ function overlayDigest(dest, paths) {
   for (const rel of [...paths].sort()) {
     h.update(rel);
     h.update("\0");
-    const p = join15(dest, rel);
+    const p = join16(dest, rel);
     try {
       const st = lstatSync4(p);
       h.update(String(st.mode));
-      h.update(st.isSymbolicLink() ? readlinkSync3(p) : readFileSync15(p));
+      h.update(st.isSymbolicLink() ? readlinkSync3(p) : readFileSync16(p));
     } catch {
       h.update("<gone>");
     }
@@ -9305,7 +9468,7 @@ function overlayPristine(cwd, base, dest, policy, cmd, dependencyRoot) {
       throw new Error(`the base's ${e.path} is a submodule; the pristine copy cannot reproduce it`);
     }
     const content = execFileSync8("git", ["show", `${base}:${e.path}`], { cwd, maxBuffer: 1 << 28, env: trustedGitEnv() });
-    const out2 = join15(dest, e.path);
+    const out2 = join16(dest, e.path);
     mkdirSync6(dirname7(out2), { recursive: true });
     rmSync3(out2, { force: true });
     if (e.mode === "120000") {
@@ -9322,7 +9485,7 @@ function overlayPristine(cwd, base, dest, policy, cmd, dependencyRoot) {
   const inCopy = git2(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], cwd).split("\0").filter(Boolean);
   for (const rel of inCopy) {
     if (!isOverlay(rel) || baseProtected.has(rel)) continue;
-    rmSync3(join15(dest, rel), { force: true });
+    rmSync3(join16(dest, rel), { force: true });
     removed++;
   }
   for (const link of restoredLinks) {
@@ -9367,8 +9530,8 @@ function suiteEnv(scratch) {
     if (DROPPED_ENV.has(k) || PINNED_NPM.test(k)) continue;
     env[k] = v;
   }
-  const userRc = join15(scratch, "npmrc-user");
-  const globalRc = join15(scratch, "npmrc-global");
+  const userRc = join16(scratch, "npmrc-user");
+  const globalRc = join16(scratch, "npmrc-global");
   for (const f of [userRc, globalRc]) writeFileSync6(f, "", { mode: 292 });
   env.npm_config_userconfig = userRc;
   env.npm_config_globalconfig = globalRc;
@@ -9378,8 +9541,8 @@ function suiteEnv(scratch) {
 }
 function runLocalSuite(dir, cmd, budgetSecs) {
   const t0 = Date.now();
-  const outDir = mkdtempSync2(join15(tmpdir2(), "tw-verify-run-"));
-  const outFile = join15(outDir, "result.json");
+  const outDir = mkdtempSync2(join16(tmpdir2(), "tw-verify-run-"));
+  const outFile = join16(outDir, "result.json");
   try {
     spawnSync2(process.execPath, ["-e", SUPERVISOR, cmd, String(budgetSecs * 1e3), outFile], {
       cwd: dir,
@@ -9392,7 +9555,7 @@ function runLocalSuite(dir, cmd, budgetSecs) {
     const secs = Math.round((Date.now() - t0) / 1e3);
     let r;
     try {
-      r = JSON.parse(readFileSync15(outFile, "utf8"));
+      r = JSON.parse(readFileSync16(outFile, "utf8"));
     } catch {
       return { exit: null, secs };
     }
@@ -9484,8 +9647,8 @@ function runVerify(opts) {
     out2(`verify: cannot resolve base rev "${opts.base ?? "HEAD"}" \u2014 failing closed`);
     return 2;
   }
-  const visRoot = mkdtempSync2(join15(tmpdir2(), "tw-verify-vis-"));
-  const visDir = join15(visRoot, "t");
+  const visRoot = mkdtempSync2(join16(tmpdir2(), "tw-verify-vis-"));
+  const visDir = join16(visRoot, "t");
   const cleanup = (dirs) => {
     if (opts.keep) return;
     for (const d of dirs) rmSync3(d, { recursive: true, force: true });
@@ -9542,8 +9705,8 @@ function runVerify(opts) {
     out2((dependencyAfterVisible.reason ?? "dependency identity changed") + ". Failing closed, not open.");
     return 2;
   }
-  const priRoot = mkdtempSync2(join15(tmpdir2(), "tw-verify-pri-"));
-  const priDir = join15(priRoot, "t");
+  const priRoot = mkdtempSync2(join16(tmpdir2(), "tw-verify-pri-"));
+  const priDir = join16(priRoot, "t");
   let restored = [];
   let removedAdded = 0;
   try {
@@ -9694,16 +9857,233 @@ 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 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";
 var out = (s) => process.stdout.write(s + "\n");
-var err = (s) => process.stderr.write(s + "\n");
+var err2 = (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 = readdirSync5("/proc").filter((x) => /^\d+$/.test(x));
+  } catch {
+    return [];
+  }
+  for (const name of names) {
+    const pid = Number(name);
+    try {
+      const stat = readFileSync17(`/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(join17(tmpdir3(), "tw-agent-supervisor-"));
+  const resultFile = join17(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(readFileSync17(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() });
 }
 function nowTicks() {
   try {
-    return Math.floor(parseFloat(readFileSync16("/proc/uptime", "utf8").split(" ")[0]) * 100);
+    return Math.floor(parseFloat(readFileSync17("/proc/uptime", "utf8").split(" ")[0]) * 100);
   } catch {
     return Number.POSITIVE_INFINITY;
   }
@@ -9718,7 +10098,7 @@ function survivorsHoldingTree(cwd, spawnedAfterTicks) {
   }
   let pids;
   try {
-    pids = readdirSync4("/proc").filter((d) => /^\d+$/.test(d));
+    pids = readdirSync5("/proc").filter((d) => /^\d+$/.test(d));
   } catch {
     return out2;
   }
@@ -9726,7 +10106,7 @@ function survivorsHoldingTree(cwd, spawnedAfterTicks) {
     const n = Number(pid);
     if (n === process.pid) continue;
     try {
-      const stat = readFileSync16(`/proc/${pid}/stat`, "utf8");
+      const stat = readFileSync17(`/proc/${pid}/stat`, "utf8");
       const startTicks = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19]);
       if (!Number.isFinite(startTicks) || startTicks < spawnedAfterTicks) continue;
     } catch {
@@ -9734,14 +10114,14 @@ function survivorsHoldingTree(cwd, spawnedAfterTicks) {
     }
     const procLinks = [`/proc/${pid}/cwd`, `/proc/${pid}/exe`];
     try {
-      for (const fd of readdirSync4(`/proc/${pid}/fd`)) procLinks.push(`/proc/${pid}/fd/${fd}`);
+      for (const fd of readdirSync5(`/proc/${pid}/fd`)) procLinks.push(`/proc/${pid}/fd/${fd}`);
     } catch {
     }
     let holds = false;
     for (const link of procLinks) {
       try {
         const raw = readlinkSync4(link).replace(/ \(deleted\)$/, "");
-        const held = raw.startsWith("/") ? resolve7(raw) : raw;
+        const held = raw.startsWith("/") ? resolve8(raw) : raw;
         if (held === real || held.startsWith(real + "/")) {
           holds = true;
           break;
@@ -9754,16 +10134,22 @@ function survivorsHoldingTree(cwd, spawnedAfterTicks) {
   return out2;
 }
 function runEnvelope(opts) {
-  const cwd = resolve7(opts.cwd ?? process.cwd());
+  const cwd = resolve8(opts.cwd ?? process.cwd());
   if (!opts.argv.length) {
-    err("tamperward run: no agent command given (usage: tamperward run [options] -- <command...>)");
+    err2("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)) {
+    err2(
+      `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();
   } catch {
-    err(`tamperward run: cannot resolve trusted base ${opts.base ?? "HEAD"} \u2014 failing closed.`);
+    err2(`tamperward run: cannot resolve trusted base ${opts.base ?? "HEAD"} \u2014 failing closed.`);
     return 2;
   }
   let frozenPolicy;
@@ -9774,19 +10160,19 @@ function runEnvelope(opts) {
     frozenCmd = opts.cmd ?? frozenPolicy.verify?.command;
     frozenBudget = opts.budget ?? frozenPolicy.verify?.budget;
   } catch (e) {
-    err(`tamperward run: cannot load the entry-time policy (${e instanceof Error ? e.message : String(e)}) \u2014 failing closed.`);
+    err2(`tamperward run: cannot load the entry-time policy (${e instanceof Error ? e.message : String(e)}) \u2014 failing closed.`);
     return 2;
   }
   if (!frozenCmd) {
-    err("tamperward run: no suite command at entry (policy `verify: { command: ... }` or --cmd) \u2014");
-    err("refusing to start: a verifier that appears after the agent runs would be agent-authored.");
+    err2("tamperward run: no suite command at entry (policy `verify: { command: ... }` or --cmd) \u2014");
+    err2("refusing to start: a verifier that appears after the agent runs would be agent-authored.");
     return 2;
   }
   if (!opts.allowDirty) {
     const dirty = git3(["status", "--porcelain"], cwd).trim();
     if (dirty) {
-      err("tamperward run: working tree is dirty before the agent starts \u2014 the envelope cannot");
-      err("attribute changes. Commit or stash first, or pass --allow-dirty to own the risk.");
+      err2("tamperward run: working tree is dirty before the agent starts \u2014 the envelope cannot");
+      err2("attribute changes. Commit or stash first, or pass --allow-dirty to own the risk.");
       return 2;
     }
   }
@@ -9794,25 +10180,25 @@ function runEnvelope(opts) {
   out(`tamperward run \u2014 trusted base ${base.slice(0, 10)}; agent exit is untrusted.`);
   out(`tamperward run \u2014 verifier backend: ${verifierBackendSummary(verifierBackend)}`);
   if (!verifierBackend.available) {
-    err("tamperward run: the requested verifier backend cannot be established \u2014");
-    err(`${verifierBackend.reason ?? "unknown backend failure"}. Failing closed before the agent starts.`);
+    err2("tamperward run: the requested verifier backend cannot be established \u2014");
+    err2(`${verifierBackend.reason ?? "unknown backend failure"}. Failing closed before the agent starts.`);
     return 2;
   }
   if (verifierBackend.kind === "container") {
-    err("tamperward run: container verification requires a frozen candidate handoff from an");
-    err("agent domain that cannot control the verifier engine. `run` executes the agent under");
-    err("this host identity, so it cannot honestly provide that separation. Failing closed");
-    err("before the agent starts; use standalone `tamperward verify` in trusted CI or after");
-    err("an externally isolated agent produces the frozen candidate artifact.");
+    err2("tamperward run: container verification requires a frozen candidate handoff from an");
+    err2("agent domain that cannot control the verifier engine. `run` executes the agent under");
+    err2("this host identity, so it cannot honestly provide that separation. Failing closed");
+    err2("before the agent starts; use standalone `tamperward verify` in trusted CI or after");
+    err2("an externally isolated agent produces the frozen candidate artifact.");
     return 2;
   }
   const dependencyEnvironment = verifierBackend.kind === "local" ? discoverDependencyEnvironment(cwd, frozenCmd) : null;
   if (dependencyEnvironment) {
     out(`tamperward run \u2014 dependency environment: ${dependencyEnvironmentSummary(dependencyEnvironment)}`);
     if (dependencyEnvironment.status === "unattestable" && !opts.allowDepDrift) {
-      err("tamperward run: the verifier dependency environment cannot be attested \u2014");
-      err(`${dependencyEnvironment.reason ?? "unknown dependency environment"}. Failing closed before the agent starts.`);
-      err("(Pass --allow-dep-drift only if you explicitly own this dependency-integrity risk.)");
+      err2("tamperward run: the verifier dependency environment cannot be attested \u2014");
+      err2(`${dependencyEnvironment.reason ?? "unknown dependency environment"}. Failing closed before the agent starts.`);
+      err2("(Pass --allow-dep-drift only if you explicitly own this dependency-integrity risk.)");
       return 2;
     }
   } else {
@@ -9820,32 +10206,49 @@ 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) {
+    err2(`tamperward run: agent runtime failed to start/report cleanly (${agentRun.failure}) \u2014 continuing to adjudicate the released tree.`);
+  }
+  if (agentTimedOut) {
+    err2(
+      `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");
-    err("read against the anchor we started from. That is the finding.");
+    err2("tamperward run: git object-replacement state changed during this run \u2014 a replace ref, graft");
+    err2("or shallow boundary now redirects what the trusted base resolves to. Nothing below could be");
+    err2("read against the anchor we started from. That is the finding.");
     out(`
 tamperward run \u2014 agent exit ${agentExit}; OBJECT_REWRITE \u2192 ENFORCEMENT_FAILED`);
     return 1;
   }
   const dependencyBeforeAdjudication = dependencyEnvironment ? checkDependencyEnvironment(cwd, dependencyEnvironment) : { ok: true };
   if (!dependencyBeforeAdjudication.ok) {
-    err("tamperward run: the frozen dependency environment changed before adjudication began \u2014");
-    err(`${dependencyBeforeAdjudication.reason ?? "dependency identity changed"}.`);
+    err2("tamperward run: the frozen dependency environment changed before adjudication began \u2014");
+    err2(`${dependencyBeforeAdjudication.reason ?? "dependency identity changed"}.`);
     if (!opts.allowDepDrift) {
       out(`
 tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEMENT_FAILED`);
       return 1;
     }
-    err("(--allow-dep-drift: proceeding anyway, on the operator's judgement.)");
+    err2("(--allow-dep-drift: proceeding anyway, on the operator's judgement.)");
   }
   const head = git3(["rev-parse", "HEAD"], cwd).trim();
   const isAncestor = spawnSync3("git", ["merge-base", "--is-ancestor", base, head], { cwd, env: trustedGitEnv() });
   if (isAncestor.status !== 0) {
-    err(`tamperward run: HEAD ${head.slice(0, 10)} is not a descendant of the trusted base ${base.slice(0, 10)} \u2014`);
-    err("the agent rewrote history out from under the anchor. That is the finding.");
+    err2(`tamperward run: HEAD ${head.slice(0, 10)} is not a descendant of the trusted base ${base.slice(0, 10)} \u2014`);
+    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`);
     return 1;
@@ -9879,33 +10282,34 @@ tamperward run \u2014 agent exit ${agentExit}; HISTORY_REWRITE \u2192 ENFORCEMEN
   }
   const mutatedDuringAdjudication = treeFingerprint(cwd, protectedIgnored) !== fpBefore;
   if (mutatedDuringAdjudication) {
-    err("tamperward run: the working tree changed while it was being adjudicated \u2014");
-    err("the verdict below would describe a tree that no longer exists.");
+    err2("tamperward run: the working tree changed while it was being adjudicated \u2014");
+    err2("the verdict below would describe a tree that no longer exists.");
   }
   const dependencyAfter = dependencyEnvironment ? checkDependencyEnvironment(cwd, dependencyEnvironment) : { ok: true };
   const depsDrifted = Boolean(dependencyEnvironment) && !opts.allowDepDrift && !dependencyAfter.ok;
   if (depsDrifted) {
-    err("tamperward run: the frozen dependency environment changed during this run \u2014");
-    err(`${dependencyAfter.reason ?? "dependency identity changed"}. Both verification runs depend on it.`);
+    err2("tamperward run: the frozen dependency environment changed during this run \u2014");
+    err2(`${dependencyAfter.reason ?? "dependency identity changed"}. Both verification runs depend on it.`);
   }
   const rewrote = objectRewriteState(cwd) !== rewritesBefore;
   if (rewrote) {
-    err("tamperward run: git object-replacement state changed WHILE the tree was being adjudicated \u2014");
-    err("the checks above read the trusted base through an object layer that has since moved.");
+    err2("tamperward run: git object-replacement state changed WHILE the tree was being adjudicated \u2014");
+    err2("the checks above read the trusted base through an object layer that has since moved.");
   }
   const survivors = survivorsHoldingTree(cwd, spawnTicks);
   if (survivors.length) {
-    err(`tamperward run: ${survivors.length} process(es) started during this run still hold the`);
-    err(`working tree (pid ${survivors.join(", ")}). A verdict cannot outlive the tree it describes.`);
+    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.`);
   }
   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 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 +10321,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;
@@ -9960,6 +10365,16 @@ function parseInit(args) {
   }
   return o;
 }
+function parseDoctor(args) {
+  const o = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd") o.cwd = args[++i];
+    else if (a === "--base") o.base = args[++i];
+    else if (a === "--workflow") o.workflow = args[++i];
+  }
+  return o;
+}
 function parseCheck(args) {
   const o = {};
   for (let i = 0; i < args.length; i++) {
@@ -10014,13 +10429,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
@@ -10033,6 +10449,11 @@ Formats:
                                             every tool the gate must see.
                                             --force-workflow replaces a workflow it
                                             did not write, or one you have edited.
+  tamperward doctor [--base R]              validate the CI verifier's outer-time
+             [--workflow F] [--cwd D]       envelope against the trusted policy.
+                                            Generated PR CI passes the base SHA so
+                                            candidate policy edits cannot choose
+                                            their own timing requirement.
 Exit codes: 0 clean \xB7 1 a blocking finding (check), MASKED_FAILURE or SUITE_RED
             (verify), any blocking finding or masked failure (run) \xB7 2 cannot
@@ -10057,6 +10478,8 @@ function main(argv2) {
       return runAllow(parseAllow(rest));
     case "init":
       return runInit(parseInit(rest));
+    case "doctor":
+      return runDoctor(parseDoctor(rest));
     case "verify":
       return runVerify(parseVerify(rest));
     case "run":

package/package.json CHANGED Viewed

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