npm - tamperward - Versions diffs - 2.17.1 → 2.18.0 - Mend

tamperward 2.17.1 → 2.18.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

@@ -240,6 +240,7 @@ platforms.
 | `watch` / observer telemetry | Supported; backend health is reported | Supported/degraded according to `fs.watch` health | Supported/degraded according to `fs.watch` health |
 | checkpointed-local `verify` | Supported via `/bin/sh` | Supported via `/bin/sh` | **Unsupported; fails before candidate execution** |
 | isolated-container `verify` | Supported when Docker authority preflight passes | Not claimed beyond Docker preflight | Not claimed beyond Docker preflight |
+| advisory `trace-verify` | **Supported with `strace` + `tar`** | **Unsupported; reports no parity** | **Unsupported; reports no parity** |
 | authoritative `run` | **Supported only with trusted non-root subreaper backend** | **Unsupported; fails before agent start** | **Unsupported; fails before agent start** |
 | CI coverage for this contract | Full suite + platform contract | Platform-contract job | Platform-contract job |
@@ -430,6 +431,30 @@ restored `"test": "sh scripts/test.sh"` will happily call a script nothing
 restored. It bounds the class rather than closing it — see
 [the threat model](./docs/THREAT-MODEL-pristine-run.md).
+From **2.18.0**, Linux can turn that residual into an auditable observation with
+`tamperward trace-verify`. It materialises the caller-selected trusted base, runs the
+known-good verifier under `strace`, repeats the trace (two runs by default), unions the
+file/exec observations, and reports:
+- tracked repository inputs the verifier actually read or executed;
+- likely config inputs;
+- external dependency/runtime paths;
+- paths seen in only some runs as **dynamic**;
+- whether each tracked input is already covered by the same pristine-verification
+  surface used by `verify`;
+- exact uncovered paths as candidate `verify.inputs` entries for **human review**.
+It is advisory only: it never edits `.tamperward.yml`, never widens a glob, and never
+treats absence from one or several traces as proof a path can never be read. Use a
+known-good base; `trace-verify` observes what those executions did, it does not prove
+the base or external runtime/dependencies are trustworthy. macOS and Windows report the
+feature unsupported rather than implying parity.
+Example:
+```bash
+npx tamperward trace-verify --base main --cmd "npm test" --runs 3
+```
 From **2.16.0**, verifier suite output is diagnostic evidence instead of discarded
 noise. Both visible and pristine stages continuously drain stdout/stderr through a
 trusted supervisor, retain only the final **16 KiB per stream**, and count the total
@@ -448,6 +473,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 trace-verify --base main --runs 2 # advisory observed-input discovery (Linux)
 npx tamperward run --agent-budget 1800 -- <agent command...>  # optional agent-runtime bound
 ```
@@ -470,6 +496,7 @@ option can never be reinterpreted as the agent command.
 | --- | --- |
 | `check` | one view — `--staged` · `--worktree` · `--diff <base>...<head>` — plus `--format text\|json\|github\|auto` (default `auto`) · `--json` (alias for `--format json`) · `--cwd <dir>` |
 | `verify` | `--base <rev>` (default `HEAD`) · `--cmd <suite command>` · `--budget <seconds>` · `--json` · `--keep` (keep the two materialised copies and report their paths) · `--require-ancestor` (refuse a base that is not an ancestor of `HEAD`) · `--cwd <dir>` |
+| `trace-verify` | Linux-only advisory discovery: `--base <rev>` (default `HEAD`) · `--cmd <suite command>` · `--budget <seconds>` · `--runs <positive integer>` (default 2) · `--json` · `--cwd <dir>` |
 | `doctor` | `--base <rev>` (trusted policy revision) · `--workflow <path>` · `--cwd <dir>` · `--json` · `--github` · `--repo <owner/repo>` · `--branch <name>` — read-only installation/authority posture plus CI verifier outer-time validation |
 | `run` | `--base <rev>` · `--cmd <suite command>` · `--budget <seconds>` (per verifier suite) · `--agent-budget <seconds>` (optional wrapped-agent wall clock) · `--observe-transients` (start a session-scoped transient observer) · `--allow-dirty` · `--settle <seconds>` (wait before the final quiescence check) · `--allow-dep-drift` · `--cwd <dir>` · then `-- <agent command...>` |
 | `allow` | `<rule>` · `--file <path>` · `--reason "<why>"` (required) · `--cwd <dir>` |
@@ -483,6 +510,7 @@ option can never be reinterpreted as the agent command.
 | --- | --- | --- | --- | --- |
 | `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 | — |
+| `trace-verify` | all requested known-good traces exited 0; advisory report emitted | one or more traced verifier runs were non-zero/incomplete; report still emitted | unsupported platform, missing tracer/materialiser, bad base/policy/options, or tracing failure | — |
 | `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 | — |

package/dist/cli/index.js CHANGED Viewed

@@ -2010,8 +2010,8 @@ function numericOf(e) {
   }
   return void 0;
 }
-function metricsOf(expr, resolve9) {
-  const obj = resolve9(expr);
+function metricsOf(expr, resolve10) {
+  const obj = resolve10(expr);
   if (!ts3.isObjectLiteralExpression(obj)) return void 0;
   const out2 = { values: {}, opaque: false };
   let any = false;
@@ -2025,7 +2025,7 @@ function metricsOf(expr, resolve9) {
     const k = keyName(p.name);
     if (k === null || !isMetric(k)) continue;
     any = true;
-    const n = numericOf(resolve9(p.initializer));
+    const n = numericOf(resolve10(p.initializer));
     if (n === void 0) out2.opaque = true;
     else out2.values[k] = n;
   }
@@ -2071,17 +2071,17 @@ function parseThresholds(src) {
   const res = { paths: /* @__PURE__ */ new Map(), present: false, opaque: false };
   try {
     const sf = sourceOf(src);
-    const resolve9 = resolverFor(sf);
+    const resolve10 = resolverFor(sf);
     const visit = (node) => {
       if (ts3.isPropertyAssignment(node)) {
         const key2 = keyName(node.name);
         if (key2 === "coverageThreshold" || key2 === "thresholds" && underKey(node, "coverage")) {
           res.present = true;
-          const init = resolve9(node.initializer);
+          const init = resolve10(node.initializer);
           if (!ts3.isObjectLiteralExpression(init)) {
             res.opaque = true;
           } else {
-            const flat = metricsOf(init, resolve9);
+            const flat = metricsOf(init, resolve10);
             if (flat) res.global = merge(res.global, flat);
             for (const p of init.properties) {
               if (ts3.isSpreadAssignment(p)) {
@@ -2095,7 +2095,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, resolve9);
+              const m = metricsOf(p.initializer, resolve10);
               if (!m) continue;
               if (k === "global") res.global = merge(res.global, m);
               else res.paths.set(norm(k), m);
@@ -2128,18 +2128,18 @@ function parseLists(src) {
   const res = { collectFrom: null, collectKey: "collectCoverageFrom", ignore: [], opaqueCollect: false, opaqueIgnore: false };
   try {
     const sf = sourceOf(src);
-    const resolve9 = resolverFor(sf);
+    const resolve10 = resolverFor(sf);
     const visit = (node) => {
       if (ts3.isPropertyAssignment(node)) {
         const k = keyName(node.name);
         const vitestCoverage = ownerKey(node) === "coverage";
         if (k === "collectCoverageFrom" || k === "include" && vitestCoverage) {
-          const { items, opaque } = literals(resolve9(node.initializer));
+          const { items, opaque } = literals(resolve10(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(resolve9(node.initializer));
+          const { items, opaque } = literals(resolve10(node.initializer));
           res.ignore.push(...items);
           if (opaque) res.opaqueIgnore = true;
         }
@@ -10695,6 +10695,17 @@ function verifierInputs(cmd, atBase, policy) {
   }
   return picked;
 }
+function verifierCoveredInputs(cmd, atBase, policy) {
+  const verifierOwned = verifierInputs(cmd, atBase, policy);
+  const verifierGlobs = policy.verify?.inputs ?? [];
+  const covered = /* @__PURE__ */ new Set();
+  for (const path of atBase) {
+    if (OVERLAY_CLASSES.some((category) => isProtected(path, policy, category)) || matchesAny(path, VERIFICATION_SURFACE) || verifierOwned.has(path) || verifierGlobs.length > 0 && matchesAny(path, verifierGlobs)) {
+      covered.add(path);
+    }
+  }
+  return covered;
+}
 function baseEntries(base, cwd) {
   return git2(["ls-tree", "-r", "-z", base], cwd).split("\0").filter(Boolean).map((rec) => {
     const tab = rec.indexOf("	");
@@ -10722,9 +10733,12 @@ function overlayDigest(dest, paths) {
 function overlayPristine(cwd, base, dest, policy, cmd, dependencyRoot) {
   const entries = baseEntries(base, cwd);
   const atBase = entries.map((e) => e.path);
-  const verifierOwned = verifierInputs(cmd, atBase, policy);
   const verifierGlobs = policy.verify?.inputs ?? [];
-  const isOverlay = (p) => OVERLAY_CLASSES.some((c) => isProtected(p, policy, c)) || matchesAny(p, VERIFICATION_SURFACE) || verifierOwned.has(p) || verifierGlobs.length > 0 && matchesAny(p, verifierGlobs);
+  const coveredBaseInputs = verifierCoveredInputs(cmd, atBase, policy);
+  const isOverlay = (p) => coveredBaseInputs.has(p) || // Candidate-added files do not exist in atBase and therefore cannot appear
+  // in the precomputed set. They still must be removed when they land on a
+  // protected class or the built-in verification surface.
+  OVERLAY_CLASSES.some((category) => isProtected(p, policy, category)) || matchesAny(p, VERIFICATION_SURFACE) || verifierGlobs.length > 0 && matchesAny(p, verifierGlobs);
   const restored = [];
   const restoredLinks = [];
   const baseProtected = /* @__PURE__ */ new Set();
@@ -12627,6 +12641,384 @@ function runDoctor(opts = {}) {
   return 0;
 }
+// src/cli/trace-verify.ts
+import { execFileSync as execFileSync11, spawnSync as spawnSync5 } from "node:child_process";
+import {
+  existsSync as existsSync13,
+  mkdtempSync as mkdtempSync5,
+  readFileSync as readFileSync18,
+  readdirSync as readdirSync6,
+  realpathSync as realpathSync7,
+  rmSync as rmSync6,
+  symlinkSync as symlinkSync2
+} from "node:fs";
+import { tmpdir as tmpdir5 } from "node:os";
+import { isAbsolute as isAbsolute11, join as join19, relative as relative6, resolve as resolve9, sep as sep3 } from "node:path";
+var TRACE_ROOT = "/__tamperward_trusted_base__";
+function unescapeStraceString(s) {
+  return s.replace(/\\([0-7]{1,3})/g, (_m, oct) => String.fromCharCode(parseInt(oct, 8))).replace(/\\x([0-9a-fA-F]{2})/g, (_m, hex) => String.fromCharCode(parseInt(hex, 16))).replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+}
+function parseStraceFileAccess(raw) {
+  const out2 = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const line of raw.split("\n")) {
+    if (!line.trim() || /\)\s+=\s+-1\b/.test(line)) continue;
+    const call = line.match(/\b(execveat|execve|openat2|openat|open|newfstatat|fstatat|statx|lstat|stat|access|readlinkat|readlink)\s*\(/);
+    if (!call) continue;
+    const afterCall = line.slice((call.index ?? 0) + call[0].length);
+    const quoted = afterCall.match(/"((?:\\.|[^"])*)"/);
+    if (!quoted) continue;
+    const path = unescapeStraceString(quoted[1]);
+    if (!path) continue;
+    const access = call[1].startsWith("execve") ? "exec" : "read";
+    const key2 = `${access}\0${path}`;
+    if (seen.has(key2)) continue;
+    seen.add(key2);
+    out2.push({ path, access });
+  }
+  return out2;
+}
+function inside3(root, path) {
+  const rel = relative6(resolve9(root), resolve9(path));
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep3}`) && !isAbsolute11(rel);
+}
+function normalRepoPath(root, raw) {
+  const abs2 = isAbsolute11(raw) ? resolve9(raw) : resolve9(root, raw);
+  if (!inside3(root, abs2)) return null;
+  const rel = relative6(root, abs2).split(sep3).join("/");
+  return rel && rel !== ".." ? rel : null;
+}
+var CONFIG_BASENAMES = /* @__PURE__ */ new Set([
+  "package.json",
+  "pytest.ini",
+  ".pytest.ini",
+  "setup.cfg",
+  "setup.py",
+  "tox.ini",
+  "pyproject.toml",
+  ".npmrc",
+  ".yarnrc",
+  ".yarnrc.yml",
+  "pnpm-workspace.yaml",
+  ".pnpmfile.cjs",
+  ".pnp.cjs",
+  ".pnp.js",
+  ".pnp.loader.mjs",
+  ".nvmrc",
+  ".node-version",
+  ".python-version",
+  ".gitattributes",
+  ".rspec",
+  "phpunit.xml",
+  "phpunit.xml.dist"
+]);
+function likelyConfig(path) {
+  const base = path.split("/").at(-1) ?? path;
+  return CONFIG_BASENAMES.has(base) || /(?:^|\/)(?:config|configs)\//.test(path) || /^\.env(?:\.|$)/.test(base) || /^(?:jest|vitest|playwright|cypress|vite|babel|karma|ava)\.config\./.test(base) || /^tsconfig(?:\..+)?\.json$/.test(base) || /^\.?(?:babelrc|swcrc|nycrc|c8rc)/.test(base) || /(?:^|\/)conftest\.py$/.test(path);
+}
+function sortAccesses(values) {
+  return [...values].sort((a, b) => a.localeCompare(b));
+}
+function summarizeTraceRuns(opts) {
+  const repo = /* @__PURE__ */ new Map();
+  const external = /* @__PURE__ */ new Map();
+  opts.runs.forEach((run, index) => {
+    const perRun = /* @__PURE__ */ new Set();
+    for (const item of run) {
+      const rel = normalRepoPath(opts.root, item.path);
+      const isTracked = rel !== null && opts.tracked.has(rel);
+      const keyPath = isTracked ? rel : rel === null ? resolve9(opts.root, item.path) : null;
+      if (keyPath === null) continue;
+      const target = isTracked ? repo : external;
+      const key2 = `${isTracked ? "repo" : "external"}\0${keyPath}`;
+      let acc2 = target.get(keyPath);
+      if (!acc2) {
+        acc2 = { accesses: /* @__PURE__ */ new Set(), runs: /* @__PURE__ */ new Set() };
+        target.set(keyPath, acc2);
+      }
+      acc2.accesses.add(item.access);
+      if (!perRun.has(key2)) {
+        acc2.runs.add(index);
+        perRun.add(key2);
+      }
+    }
+  });
+  const totalRuns = opts.runs.length;
+  const repository_inputs = [...repo.entries()].map(([path, acc2]) => ({
+    path,
+    accesses: sortAccesses(acc2.accesses),
+    config: likelyConfig(path),
+    covered: opts.covered.has(path),
+    observed_runs: acc2.runs.size,
+    dynamic: acc2.runs.size < totalRuns
+  })).sort((a, b) => a.path.localeCompare(b.path));
+  const external_inputs = [...external.entries()].map(([path, acc2]) => ({
+    path,
+    accesses: sortAccesses(acc2.accesses),
+    observed_runs: acc2.runs.size,
+    dynamic: acc2.runs.size < totalRuns
+  })).sort((a, b) => a.path.localeCompare(b.path));
+  const uncovered_repository_inputs = repository_inputs.filter((x) => !x.covered).map((x) => x.path);
+  return {
+    repository_inputs,
+    external_inputs,
+    uncovered_repository_inputs,
+    // Exact paths are intentionally conservative. A maintainer may widen them to
+    // reviewed globs, but TamperWard never invents a broader trust surface.
+    suggested_verify_inputs: [...uncovered_repository_inputs]
+  };
+}
+function git4(args, cwd) {
+  return execFileSync11("git", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+    env: trustedGitEnv(),
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+}
+function commandExists(command) {
+  const r = spawnSync5(command, ["--version"], { stdio: "ignore" });
+  return !r.error && r.status === 0;
+}
+function trackedAt(base, cwd) {
+  return git4(["ls-tree", "-r", "-z", "--name-only", base], cwd).split("\0").filter(Boolean);
+}
+function materializeBase(base, cwd, dest) {
+  const archive = spawnSync5("git", ["archive", "--format=tar", base], {
+    cwd,
+    env: trustedGitEnv(),
+    maxBuffer: 256 * 1024 * 1024
+  });
+  if (archive.error || archive.status !== 0 || !archive.stdout) {
+    throw new Error(
+      `git archive failed${archive.stderr?.length ? `: ${String(archive.stderr).trim()}` : ""}`
+    );
+  }
+  const untar = spawnSync5("tar", ["-xf", "-", "-C", dest], {
+    input: archive.stdout,
+    maxBuffer: 256 * 1024 * 1024
+  });
+  if (untar.error || untar.status !== 0) {
+    throw new Error(
+      `tar extraction failed${untar.stderr?.length ? `: ${String(untar.stderr).trim()}` : ""}`
+    );
+  }
+  const hostModules = join19(cwd, "node_modules");
+  const tracedModules = join19(dest, "node_modules");
+  if (existsSync13(hostModules) && !existsSync13(tracedModules)) {
+    symlinkSync2(resolve9(hostModules), tracedModules, "dir");
+  }
+}
+function traceFiles(prefix) {
+  const dir = resolve9(prefix, "..");
+  const base = prefix.split(sep3).at(-1);
+  return readdirSync6(dir).filter((name) => name === base || name.startsWith(base + ".")).map((name) => join19(dir, name)).sort();
+}
+function rewriteTraceRoot(accesses, actualRoot) {
+  return accesses.map((item) => {
+    const abs2 = isAbsolute11(item.path) ? resolve9(item.path) : resolve9(actualRoot, item.path);
+    if (!inside3(actualRoot, abs2)) return { ...item, path: abs2 };
+    const rel = relative6(actualRoot, abs2).split(sep3).join("/");
+    try {
+      const real = resolve9(realpathSync7(abs2));
+      if (!inside3(actualRoot, real)) return { ...item, path: real };
+    } catch {
+    }
+    return { ...item, path: join19(TRACE_ROOT, ...rel.split("/")) };
+  });
+}
+function runOneTrace(cwd, base, command, budget) {
+  const root = mkdtempSync5(join19(tmpdir5(), "tw-trace-base-"));
+  const traceDir = mkdtempSync5(join19(tmpdir5(), "tw-trace-log-"));
+  try {
+    materializeBase(base, cwd, root);
+    const prefix = join19(traceDir, "trace");
+    const traced = spawnSync5(
+      "strace",
+      [
+        "-ff",
+        "-qq",
+        "-s",
+        "4096",
+        "-e",
+        "trace=%file",
+        "-o",
+        prefix,
+        "--",
+        "timeout",
+        "--signal=TERM",
+        "--kill-after=2s",
+        `${budget}s`,
+        "sh",
+        "-c",
+        command
+      ],
+      {
+        cwd: root,
+        env: process.env,
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024
+      }
+    );
+    if (traced.error) throw traced.error;
+    const logs = traceFiles(prefix);
+    if (logs.length === 0) {
+      throw new Error("strace produced no trace files");
+    }
+    const accesses = logs.flatMap((path) => parseStraceFileAccess(readFileSync18(path, "utf8")));
+    return {
+      exit: traced.status ?? 1,
+      accesses: rewriteTraceRoot(accesses, root)
+    };
+  } finally {
+    rmSync6(root, { recursive: true, force: true });
+    rmSync6(traceDir, { recursive: true, force: true });
+  }
+}
+function renderText2(report2) {
+  const out2 = (s = "") => void process.stdout.write(s + "\n");
+  out2("tamperward trace-verify \u2014 ADVISORY observation, not an enforcement verdict");
+  out2(`trusted base: ${report2.base}`);
+  out2(`command: ${report2.command}`);
+  out2(`runs: ${report2.runs_completed}/${report2.runs_requested}; exits: ${report2.run_exits.join(", ")}`);
+  out2();
+  out2("repository inputs observed:");
+  if (!report2.repository_inputs.length) out2("  (none)");
+  for (const item of report2.repository_inputs) {
+    const flags = [
+      item.covered ? "covered" : "UNCOVERED",
+      item.config ? "config" : null,
+      item.dynamic ? `dynamic ${item.observed_runs}/${report2.runs_completed}` : null,
+      item.accesses.join("+")
+    ].filter(Boolean).join(", ");
+    out2(`  ${item.path}  [${flags}]`);
+  }
+  out2();
+  out2("external dependency/runtime paths observed:");
+  if (!report2.external_inputs.length) out2("  (none)");
+  for (const item of report2.external_inputs) {
+    out2(
+      `  ${item.path}  [${item.accesses.join("+")}${item.dynamic ? `, dynamic ${item.observed_runs}/${report2.runs_completed}` : ""}]`
+    );
+  }
+  out2();
+  out2("candidate verify.inputs entries for HUMAN REVIEW:");
+  if (!report2.suggested_verify_inputs.length) out2("  (none \u2014 all observed tracked inputs are already covered)");
+  for (const path of report2.suggested_verify_inputs) out2(`  - ${JSON.stringify(path)}`);
+  out2();
+  for (const note of report2.notes) out2(`note: ${note}`);
+}
+function runTraceVerify(opts = {}) {
+  const cwd = resolve9(opts.cwd ?? process.cwd());
+  if (process.platform !== "linux") {
+    process.stderr.write("tamperward trace-verify: Linux only in this release; unsupported platform \u2014 no parity is implied.\n");
+    return 2;
+  }
+  if (!commandExists("strace")) {
+    process.stderr.write("tamperward trace-verify: strace is required on Linux but was not found.\n");
+    return 2;
+  }
+  if (!commandExists("tar")) {
+    process.stderr.write("tamperward trace-verify: tar is required to materialize the trusted base but was not found.\n");
+    return 2;
+  }
+  if (!commandExists("timeout")) {
+    process.stderr.write("tamperward trace-verify: GNU timeout is required to bound traced verifier runs but was not found.\n");
+    return 2;
+  }
+  const runs = opts.runs ?? 2;
+  if (!Number.isInteger(runs) || runs <= 0) {
+    process.stderr.write(`tamperward trace-verify: --runs needs a positive integer (got ${JSON.stringify(opts.runs)}).
+`);
+    return 2;
+  }
+  const requestedBase = opts.base ?? "HEAD";
+  let base;
+  try {
+    const baseArg = assertRev(requestedBase);
+    base = git4(["rev-parse", "--verify", `${baseArg}^{commit}`], cwd).trim();
+  } catch (e) {
+    process.stderr.write(`tamperward trace-verify: cannot resolve trusted base ${JSON.stringify(requestedBase)} (${e instanceof Error ? e.message : String(e)}).
+`);
+    return 2;
+  }
+  let policy;
+  try {
+    policy = loadPolicyAt(base, cwd) ?? defaultPolicy();
+  } catch (e) {
+    process.stderr.write(`tamperward trace-verify: cannot load policy at trusted base (${e instanceof Error ? e.message : String(e)}).
+`);
+    return 2;
+  }
+  const command = opts.cmd ?? policy.verify?.command;
+  if (!command) {
+    process.stderr.write("tamperward trace-verify: no verifier command; set verify.command at the base or pass --cmd.\n");
+    return 2;
+  }
+  const budget = opts.budget ?? policy.verify?.budget ?? 300;
+  if (!Number.isFinite(budget) || budget <= 0) {
+    process.stderr.write(`tamperward trace-verify: --budget needs a positive number of seconds (got ${JSON.stringify(budget)}).
+`);
+    return 2;
+  }
+  const atBase = trackedAt(base, cwd);
+  const tracked = new Set(atBase);
+  const covered = verifierCoveredInputs(command, atBase, policy);
+  const observed = [];
+  const runExits = [];
+  try {
+    for (let i = 0; i < runs; i++) {
+      const result = runOneTrace(cwd, base, command, budget);
+      observed.push(result.accesses);
+      runExits.push(result.exit);
+    }
+  } catch (e) {
+    process.stderr.write(`tamperward trace-verify: tracing failed (${e instanceof Error ? e.message : String(e)}).
+`);
+    return 2;
+  }
+  const summary = summarizeTraceRuns({
+    root: TRACE_ROOT,
+    runs: observed,
+    tracked,
+    covered
+  });
+  const report2 = {
+    advisory: true,
+    platform: process.platform,
+    base,
+    command,
+    runs_requested: runs,
+    runs_completed: observed.length,
+    run_exits: runExits,
+    trace_complete: runExits.every((code2) => code2 === 0),
+    ...summary,
+    notes: [
+      "Observed reads are evidence from these runs, not proof that an unobserved path can never be read.",
+      "Dynamic paths are those observed in fewer than all repeated traces.",
+      "Suggestions are exact tracked paths only; TamperWard never edits .tamperward.yml or widens a glob automatically.",
+      "Review every suggestion before adding it to verify.inputs."
+    ]
+  };
+  if (opts.json) process.stdout.write(JSON.stringify(report2) + "\n");
+  else renderText2(report2);
+  return report2.trace_complete ? 0 : 1;
+}
+function parseTraceVerify(args) {
+  const out2 = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") out2.json = true;
+    else if (a === "--base") out2.base = args[++i];
+    else if (a === "--cmd") out2.cmd = args[++i];
+    else if (a === "--cwd") out2.cwd = args[++i];
+    else if (a === "--budget") out2.budget = Number(args[++i]);
+    else if (a === "--runs") out2.runs = Number(args[++i]);
+  }
+  return out2;
+}
 // src/cli/main.ts
 function parseAllow(args) {
   const o = {};
@@ -12715,6 +13107,11 @@ function validateFlatArgs(args, grammar) {
         if (!Number.isFinite(n) || n <= 0) {
           return { error: `${a} needs a positive number (got "${v}")`, seen, positionals };
         }
+      } else if (rule === "positive-integer") {
+        const n = Number(v);
+        if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+          return { error: `${a} needs a positive integer (got "${v}")`, seen, positionals };
+        }
       } else if (rule === "non-negative") {
         const n = Number(v);
         if (!Number.isFinite(n) || n < 0) {
@@ -12817,6 +13214,18 @@ function validateCliArgs(cmd, args) {
       }
     }).error;
   }
+  if (cmd === "trace-verify") {
+    return validateFlatArgs(args, {
+      flags: ["--json"],
+      values: {
+        "--base": "string",
+        "--cmd": "string",
+        "--cwd": "string",
+        "--budget": "positive",
+        "--runs": "positive-integer"
+      }
+    }).error;
+  }
   if (cmd === "watch") {
     return validateFlatArgs(args, {
       values: { "--dir": "string", "--log": "string", "--base": "string" }
@@ -12857,6 +13266,14 @@ Formats:
                                             (exit 1, or 0 under an out-of-band
                                             verify@<head-sha> approval); cannot-verify
                                             fails closed (2)
+  tamperward trace-verify [--base R]          advisory Linux verifier-input discovery:
+             [--cmd C] [--budget S] [--runs N] trace a trusted/known-good base with
+             [--json] [--cwd D]                strace, union repeated observations,
+                                               mark dynamic/config/external reads,
+                                               and suggest uncovered exact paths for
+                                               HUMAN review as verify.inputs. Never
+                                               edits policy; unsupported platforms
+                                               fail explicitly rather than claiming parity.
   tamperward run [opts] -- <agent cmd...>   enforcement envelope: record the trusted
              [--base R] [--cmd C]           base, run the agent, treat its exit as
              [--budget S] [--agent-budget S] untrusted, then re-adjudicate the tree it
@@ -12930,6 +13347,8 @@ function main(argv2) {
       return runWatch(rest);
     case "verify":
       return runVerify(parseVerify(rest));
+    case "trace-verify":
+      return runTraceVerify(parseTraceVerify(rest));
     case "run":
       return runEnvelope({
         ...parseRun(rest),

package/package.json CHANGED Viewed

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