tamperward 2.18.0 → 2.19.0

package/dist/cli/index.js

@@ -7084,6 +7084,12 @@ function oobFromEnv(env = process.env) {
   return (env.TAMPERWARD_OOB_SIGNOFF ?? "").split(",").map((s) => s.trim().replace(/^tamperward:allow:/, "")).filter(Boolean);
 }
 
+// src/machine-output.ts
+var MACHINE_SCHEMA_VERSION = 1;
+function machineOutput(payload) {
+  return { ...payload, schema_version: MACHINE_SCHEMA_VERSION };
+}
+
 // src/cli/render/text.ts
 var ESC = "\x1B";
 var RESET = `${ESC}[0m`;
@@ -7303,7 +7309,7 @@ function report(input) {
       JSON.stringify(
         // `findings`, `scanned` and `ignoredFiles` keep their exact prior shape; `summary`
         // is additive, so an existing consumer reading only the old keys is unaffected.
-        { findings, scanned, ignoredFiles, summary: { block: blocks2, warn: findings.length - blocks2 } },
+        machineOutput({ findings, scanned, ignoredFiles, summary: { block: blocks2, warn: findings.length - blocks2 } }),
         null,
         2
       ) + "\n"
@@ -7379,7 +7385,9 @@ function check(opts) {
     process.stderr.write(`tamperward: ${cleared.length} blocking finding(s) cleared by ${how}: ${cleared.map((f) => f.rule + (f.file ? `(${f.file})` : "")).join(", ")}
 `);
   }
-  report({ findings, scanned: changes.length, ignoredFiles, json: opts.json, format: opts.format });
+  if (!opts.silent) {
+    report({ findings, scanned: changes.length, ignoredFiles, json: opts.json, format: opts.format });
+  }
   return hasBlocking(findings) ? 1 : 0;
 }
 function runCheck(opts) {
@@ -10894,10 +10902,24 @@ function renderStageDiagnostics(out2, stage, result) {
 }
 function runVerify(opts) {
   const cwd = opts.cwd ?? process.cwd();
-  const out2 = (s) => void process.stdout.write(s + "\n");
-  if (opts.invalid) {
-    out2(`verify: ${opts.invalid} \u2014 failing closed`);
+  const out2 = opts.silent ? (_s) => {
+  } : (s) => void process.stdout.write(s + "\n");
+  const cannotVerify = (reason, detail, extra = {}) => {
+    if (opts.json) {
+      out2(JSON.stringify({
+        schema_version: MACHINE_SCHEMA_VERSION,
+        verdict: "CANNOT_VERIFY",
+        reason,
+        ...detail ? { detail } : {},
+        ...extra
+      }));
+    } else if (detail) {
+      out2(`verify: ${detail} \u2014 failing closed`);
+    }
     return 2;
+  };
+  if (opts.invalid) {
+    return cannotVerify("INVALID_ARGUMENTS", opts.invalid);
   }
   let policy;
   try {
@@ -10905,24 +10927,24 @@ function runVerify(opts) {
     else if (opts.base) policy = loadPolicyAt(resolveBase(opts.base, cwd), cwd) ?? defaultPolicy();
     else policy = loadPolicy(cwd);
   } catch (e) {
-    out2(`verify: cannot load policy (${e instanceof Error ? e.message : String(e)}) \u2014 failing closed`);
-    return 2;
+    return cannotVerify("POLICY_ERROR", `cannot load policy (${e instanceof Error ? e.message : String(e)})`);
   }
   if (opts.requireAncestor) {
     const requested = git2(["rev-parse", "--verify", `${opts.base ?? "HEAD"}^{commit}`], cwd).trim();
     if (!baseIsAncestorOfHead(requested, cwd)) {
-      out2(
-        `verify: --require-ancestor: ${requested.slice(0, 10)} is not an ancestor of HEAD \u2014 the anchor would silently resolve to an older commit. Failing closed.`
+      return cannotVerify(
+        "BASE_NOT_ANCESTOR",
+        `--require-ancestor: ${requested.slice(0, 10)} is not an ancestor of HEAD; the anchor would silently resolve to an older commit`,
+        { base: requested }
       );
-      return 2;
     }
   }
   const cmd = opts.cmd ?? policy.verify?.command;
   if (!cmd) {
-    out2(
-      opts.base ? "verify: no suite command in the policy at the trusted base \u2014 the base governs the verifier, so a `verify:` block added only on the candidate is not used. Add it at the base, or pass --cmd explicitly." : "verify: no suite command \u2014 set policy `verify: { command: ... }` or pass --cmd"
+    return cannotVerify(
+      "NO_SUITE_COMMAND",
+      opts.base ? "no suite command in the policy at the trusted base; add it at the base or pass --cmd explicitly" : "no suite command; set policy verify.command or pass --cmd"
     );
-    return 2;
   }
   const budget = opts.budget ?? policy.verify?.budget ?? 300;
   const verifierBackend = opts.verifierBackend ?? prepareVerifierBackend(policy.verify);
@@ -10930,6 +10952,7 @@ function runVerify(opts) {
   if (!verifierBackend.available) {
     if (opts.json) {
       out2(JSON.stringify({
+        schema_version: MACHINE_SCHEMA_VERSION,
         verdict: "CANNOT_VERIFY",
         reason: "VERIFIER_BACKEND_UNAVAILABLE",
         verifier_backend: backendReport(),
@@ -10945,6 +10968,7 @@ function runVerify(opts) {
   if (!isolated && !localVerifierShell(process.platform, cmd)) {
     if (opts.json) {
       out2(JSON.stringify({
+        schema_version: MACHINE_SCHEMA_VERSION,
         verdict: "CANNOT_VERIFY",
         reason: "LOCAL_VERIFIER_UNSUPPORTED_PLATFORM",
         platform: process.platform,
@@ -10967,6 +10991,7 @@ function runVerify(opts) {
   if (dependencyEnvironment?.status === "unattestable" && !opts.allowDepDrift) {
     if (opts.json) {
       out2(JSON.stringify({
+        schema_version: MACHINE_SCHEMA_VERSION,
         verdict: "CANNOT_VERIFY",
         reason: "DEPENDENCY_ENVIRONMENT_UNATTESTABLE",
         verifier_backend: backendReport(),
@@ -10986,8 +11011,7 @@ function runVerify(opts) {
   try {
     base = resolveBase(opts.base ?? "HEAD", cwd);
   } catch {
-    out2(`verify: cannot resolve base rev "${opts.base ?? "HEAD"}" \u2014 failing closed`);
-    return 2;
+    return cannotVerify("BASE_UNRESOLVABLE", `cannot resolve base rev "${opts.base ?? "HEAD"}"`);
   }
   const visRoot = mkdtempSync3(join16(tmpdir3(), "tw-verify-vis-"));
   const visDir = join16(visRoot, "t");
@@ -11004,17 +11028,22 @@ function runVerify(opts) {
   ) ?? checkDeps() : { ok: true };
   if (!dependencyAtEntry.ok && !opts.allowDepDrift) {
     cleanup([visRoot]);
-    out2("verify: the frozen dependency environment changed before the visible suite ran \u2014");
-    out2((dependencyAtEntry.reason ?? "dependency identity changed") + ". Failing closed, not open.");
-    return 2;
+    return cannotVerify(
+      "DEPENDENCY_DRIFT",
+      dependencyAtEntry.reason ?? "dependency identity changed before the visible suite ran",
+      { dependency_environment: dependencyReport(), verifier_backend: backendReport(), oracle_assurance: oracleAssuranceReport() }
+    );
   }
   try {
     mkdirSync6(visDir);
     materialize(cwd, visDir, frozenNodeModules);
   } catch (e) {
     cleanup([visRoot]);
-    out2(`verify: could not materialize (${e instanceof Error ? e.message : String(e)}) \u2014 failing closed`);
-    return 2;
+    return cannotVerify(
+      "MATERIALIZATION_FAILED",
+      `could not materialize (${e instanceof Error ? e.message : String(e)})`,
+      { verifier_backend: backendReport(), dependency_environment: dependencyReport(), oracle_assurance: oracleAssuranceReport() }
+    );
   }
   const visible = runStage(visDir);
   if (visible.failure === "backend" || visible.failure === "resource") {
@@ -11022,6 +11051,7 @@ function runVerify(opts) {
     const exhausted = visible.failure === "resource";
     if (opts.json) {
       out2(JSON.stringify({
+        schema_version: MACHINE_SCHEMA_VERSION,
         verdict: "CANNOT_VERIFY",
         reason: exhausted ? "VERIFIER_RESOURCE_EXHAUSTED" : "VERIFIER_BACKEND_RUNTIME_FAILURE",
         stage: "visible",
@@ -11042,16 +11072,20 @@ function runVerify(opts) {
   }
   if (treeFingerprint(cwd, protectedIgnored) !== treeBefore) {
     cleanup([visRoot]);
-    out2("verify: the working tree changed while the visible suite was running \u2014 the pristine copy");
-    out2("would be materialised from a tree the candidate just edited. Failing closed, not open.");
-    return 2;
+    return cannotVerify(
+      "WORKTREE_CHANGED",
+      "the working tree changed while the visible suite was running",
+      { stage: "visible", verifier_backend: backendReport(), dependency_environment: dependencyReport(), oracle_assurance: oracleAssuranceReport() }
+    );
   }
   const dependencyAfterVisible = checkDeps();
   if (!dependencyAfterVisible.ok && !opts.allowDepDrift) {
     cleanup([visRoot]);
-    out2("verify: the frozen dependency environment changed while the visible suite was running \u2014");
-    out2((dependencyAfterVisible.reason ?? "dependency identity changed") + ". Failing closed, not open.");
-    return 2;
+    return cannotVerify(
+      "DEPENDENCY_DRIFT",
+      dependencyAfterVisible.reason ?? "dependency identity changed while the visible suite was running",
+      { stage: "visible", dependency_environment: dependencyReport(), verifier_backend: backendReport(), oracle_assurance: oracleAssuranceReport() }
+    );
   }
   const priRoot = mkdtempSync3(join16(tmpdir3(), "tw-verify-pri-"));
   const priDir = join16(priRoot, "t");
@@ -11070,8 +11104,11 @@ function runVerify(opts) {
     ));
   } catch (e) {
     cleanup([visRoot, priRoot]);
-    out2(`verify: could not materialize (${e instanceof Error ? e.message : String(e)}) \u2014 failing closed`);
-    return 2;
+    return cannotVerify(
+      "MATERIALIZATION_FAILED",
+      `could not materialize pristine copy (${e instanceof Error ? e.message : String(e)})`,
+      { stage: "pristine", verifier_backend: backendReport(), dependency_environment: dependencyReport(), oracle_assurance: oracleAssuranceReport() }
+    );
   }
   const overlayBefore = overlayDigest(priDir, restored);
   const pristine = runStage(priDir);
@@ -11080,6 +11117,7 @@ function runVerify(opts) {
     const exhausted = pristine.failure === "resource";
     if (opts.json) {
       out2(JSON.stringify({
+        schema_version: MACHINE_SCHEMA_VERSION,
         verdict: "CANNOT_VERIFY",
         reason: exhausted ? "VERIFIER_RESOURCE_EXHAUSTED" : "VERIFIER_BACKEND_RUNTIME_FAILURE",
         stage: "pristine",
@@ -11108,13 +11146,14 @@ function runVerify(opts) {
   const depsMoved = !dependencyAfterPristine.ok && !opts.allowDepDrift;
   cleanup([visRoot, priRoot]);
   if (overlayMoved || treeMoved || depsMoved) {
-    out2(
-      "verify: " + (overlayMoved ? "a restored file in the pristine copy changed while the pristine suite was running" : treeMoved ? "the working tree changed while the pristine suite was running" : "the frozen dependency environment changed while the pristine suite was running") + " \u2014"
-    );
-    out2("the verdict would describe something other than what ran. Failing closed, not open.");
-    out2("(A suite that rewrites its own snapshots or test files in place will trip this; run it in");
-    out2("whatever mode your runner calls CI, so verification observes rather than updates.)");
-    return 2;
+    const reason = overlayMoved ? "PRISTINE_INTEGRITY_CHANGED" : treeMoved ? "WORKTREE_CHANGED" : "DEPENDENCY_DRIFT";
+    const detail = overlayMoved ? "a restored file in the pristine copy changed while the pristine suite was running" : treeMoved ? "the working tree changed while the pristine suite was running" : dependencyAfterPristine.reason ?? "the frozen dependency environment changed while the pristine suite was running";
+    return cannotVerify(reason, detail, {
+      stage: "pristine",
+      verifier_backend: backendReport(),
+      dependency_environment: dependencyReport(),
+      oracle_assurance: oracleAssuranceReport()
+    });
   }
   let verdict2;
   let code2;
@@ -11136,6 +11175,7 @@ function runVerify(opts) {
   if (opts.json) {
     out2(
       JSON.stringify({
+        schema_version: MACHINE_SCHEMA_VERSION,
         verdict: verdict2,
         base,
         command: cmd,
@@ -11299,8 +11339,9 @@ 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 [resultFile, budgetRaw, machineRaw, command, ...args] = process.argv.slice(1);
 const budgetMs = budgetRaw === '' ? null : Number(budgetRaw);
+const machineMode = machineRaw === '1';
 let child;
 let timedOut = false;
 let finished = false;
@@ -11326,7 +11367,9 @@ function killTree(pid) {
 
 try {
   child = spawn(command, args, {
-    stdio: 'inherit',
+    // Machine mode owns stdout for the final envelope document. Preserve agent
+    // diagnostics by routing both child streams to the parent's stderr.
+    stdio: machineMode ? ['inherit', 2, 2] : 'inherit',
     detached: process.platform !== 'win32',
   });
 } catch (e) {
@@ -11363,8 +11406,9 @@ child.once('exit', (code, signal) => finish(code, signal));
 var LINUX_SUBREAPER_SUPERVISOR = String.raw`
 import ctypes, json, os, signal, subprocess, sys, time
 
-result_file, agent_env_file, agent_cwd, budget_raw, test_mode, command, *args = sys.argv[1:]
+result_file, agent_env_file, agent_cwd, budget_raw, test_mode, machine_raw, command, *args = sys.argv[1:]
 budget = None if budget_raw == "" else float(budget_raw)
+machine_mode = machine_raw == "1"
 libc = ctypes.CDLL(None, use_errno=True)
 PR_SET_DUMPABLE = 4
 PR_SET_CHILD_SUBREAPER = 36
@@ -11482,6 +11526,10 @@ try:
         cwd=agent_cwd,
         env=agent_env,
         start_new_session=True,
+        # In machine mode stdout is reserved for TamperWard's one final JSON
+        # document. Agent stdout is retained as diagnostics on stderr.
+        stdout=sys.stderr if machine_mode else None,
+        stderr=None,
     )
 except Exception as exc:
     # No candidate process exists, so the lifecycle domain is trivially empty.
@@ -11511,7 +11559,7 @@ write_result({
 })
 raise SystemExit(0)
 `;
-function runAgentSupervised(argv2, cwd, budgetSecs, linuxPythonCandidates, lifecycleTestMode) {
+function runAgentSupervised(argv2, cwd, budgetSecs, linuxPythonCandidates, lifecycleTestMode, machineMode = false) {
   const stateDir = mkdtempSync4(join17(tmpdir4(), "tw-agent-supervisor-"));
   const resultFile = join17(stateDir, "result.json");
   const agentEnvFile = join17(stateDir, "agent-env.json");
@@ -11544,6 +11592,7 @@ function runAgentSupervised(argv2, cwd, budgetSecs, linuxPythonCandidates, lifec
         cwd,
         budgetSecs === void 0 ? "" : String(budgetSecs),
         lifecycleTestMode ?? "",
+        machineMode ? "1" : "0",
         ...argv2
       ];
       supervisorCwd = "/";
@@ -11555,6 +11604,7 @@ function runAgentSupervised(argv2, cwd, budgetSecs, linuxPythonCandidates, lifec
         AGENT_SUPERVISOR,
         resultFile,
         budgetSecs === void 0 ? "" : String(budgetSecs * 1e3),
+        machineMode ? "1" : "0",
         ...argv2
       ];
     }
@@ -11674,8 +11724,7 @@ function stopObserverProcess(observer) {
     }
     const deadline = Date.now() + 2e3;
     while (Date.now() < deadline) {
-      const health = watcherTelemetry(observer.log);
-      if (health.health?.state === "stopped" || !pidAlive2(pid)) break;
+      if (!pidAlive2(pid)) break;
       waitMs(25);
     }
     if (pidAlive2(pid)) {
@@ -11688,22 +11737,22 @@ function stopObserverProcess(observer) {
   observer.finished = true;
   return beforeStop;
 }
-function observerSummary(observer, telemetry) {
+function observerSummary(observer, telemetry, write = out) {
   const h = telemetry.health;
   const counts = h ? `${h.event_count} event(s), ${h.dropped_events} dropped, ${h.error_count} error(s)` : "no valid health record";
   const reason = telemetry.reason ? `; ${telemetry.reason}` : "";
-  out(
+  write(
     `tamperward run \u2014 transient observer: ${telemetry.state} (advisory; ${counts}; log ${observer.log}${reason})`
   );
 }
-function collectObserverFindings(observer, telemetry, cwd, base, head, policy) {
-  observerSummary(observer, telemetry);
+function collectObserverFindings(observer, telemetry, cwd, base, head, policy, write = out) {
+  observerSummary(observer, telemetry, write);
   const strict = process.env.TAMPERWARD_TRANSIENT === "block";
   const drained = drainEvents(observer.log, 0);
   const { events } = drained;
   if (!drained.complete) {
     const issue = drained.issue ?? "read-stalled";
-    out(
+    write(
       `tamperward run \u2014 transient observer: telemetry was not fully classified (${issue}; ${drained.bytesRead}/${MAX_EVENT_SWEEP_BYTES} bytes read). ` + (strict ? "Strict transient policy fails closed." : "Observer telemetry remains advisory, so this degrades evidence but does not independently fail the envelope.")
     );
     if (strict) return { blocking: true };
@@ -11719,7 +11768,7 @@ function collectObserverFindings(observer, telemetry, cwd, base, head, policy) {
       changes.filter((change) => change.kind === "file").map((change) => change.path)
     );
   } catch (e) {
-    out(
+    write(
       `tamperward run \u2014 transient observer: recorded ${events.length} event(s), but could not classify them against the final diff (${e instanceof Error ? e.message : String(e)}).` + (strict ? " Strict transient policy fails closed." : "")
     );
     return { blocking: strict };
@@ -11730,16 +11779,16 @@ function collectObserverFindings(observer, telemetry, cwd, base, head, policy) {
   };
   const findings = transientFindings(events, persistent, policy, finalHash);
   for (const finding of findings) {
-    out(
+    write(
       `[observer] ${finding.severity === "block" ? "BLOCK" : "warn"} ${finding.rule}${finding.file ? " " + finding.file : ""}: ${finding.message}`
     );
   }
   return { blocking: findings.some((finding) => finding.severity === "block") };
 }
-function finishObserverAdvisory(observer) {
+function finishObserverAdvisory(observer, write = out) {
   if (!observer || observer.finished) return;
   const telemetry = stopObserverProcess(observer);
-  observerSummary(observer, telemetry);
+  observerSummary(observer, telemetry, write);
 }
 function git3(args, cwd) {
   return execFileSync9("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
@@ -11798,6 +11847,8 @@ function survivorsHoldingTree(cwd, spawnedAfterTicks) {
 }
 function runEnvelope(opts) {
   const cwd = resolve7(opts.cwd ?? process.cwd());
+  const say = opts.json ? (_s) => {
+  } : out;
   if (!opts.argv.length) {
     err("tamperward run: no agent command given (usage: tamperward run [options] -- <command...>)");
     return 2;
@@ -11848,8 +11899,8 @@ function runEnvelope(opts) {
     return 2;
   }
   const verifierBackend = prepareVerifierBackend(frozenPolicy.verify);
-  out(`tamperward run \u2014 trusted base ${base.slice(0, 10)}; agent exit is untrusted.`);
-  out(`tamperward run \u2014 verifier backend: ${verifierBackendSummary(verifierBackend)}`);
+  say(`tamperward run \u2014 trusted base ${base.slice(0, 10)}; agent exit is untrusted.`);
+  say(`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.`);
@@ -11865,7 +11916,7 @@ function runEnvelope(opts) {
   }
   const dependencyEnvironment = verifierBackend.kind === "local" ? discoverDependencyEnvironment(cwd, frozenCmd) : null;
   if (dependencyEnvironment) {
-    out(`tamperward run \u2014 dependency environment: ${dependencyEnvironmentSummary(dependencyEnvironment)}`);
+    say(`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.`);
@@ -11873,11 +11924,11 @@ function runEnvelope(opts) {
       return 2;
     }
   } else {
-    out(`tamperward run \u2014 dependency environment: verifier-owned by ${verifierBackend.image ?? "isolated image"}`);
+    say(`tamperward run \u2014 dependency environment: verifier-owned by ${verifierBackend.image ?? "isolated image"}`);
   }
   const observer = opts.observeTransients ? startSupervisedObserver(cwd, base, opts.observerEntry) : null;
   if (!observer) {
-    out("tamperward run \u2014 transient observer: disabled (advisory; pass --observe-transients to enable)");
+    say("tamperward run \u2014 transient observer: disabled (advisory; pass --observe-transients to enable)");
   }
   const rewritesBefore = objectRewriteState(cwd);
   const spawnTicks = nowTicks();
@@ -11886,16 +11937,38 @@ function runEnvelope(opts) {
     cwd,
     opts.agentBudget,
     opts.linuxPythonCandidates,
-    opts.lifecycleTestMode
+    opts.lifecycleTestMode,
+    opts.json === true
   );
   const agentExit = agentRun.exit;
   const agentTimedOut = agentRun.timedOut;
+  const emitRunJson = (verdict3, exitCode2, extra = {}, complete = false) => {
+    if (!opts.json) return;
+    out(JSON.stringify(machineOutput({
+      verdict: verdict3,
+      exit_code: exitCode2,
+      complete,
+      base,
+      agent: {
+        exit_code: agentExit,
+        timed_out: agentTimedOut,
+        lifecycle_owned: agentRun.lifecycleOwned,
+        ...opts.agentBudget !== void 0 ? { budget_secs: opts.agentBudget } : {}
+      },
+      verifier_backend: verifierBackendReport(verifierBackend),
+      dependency_environment: dependencyEnvironment ? dependencyEnvironmentReport(dependencyEnvironment) : { status: "verifier-owned", roots: [], image: verifierBackend.image },
+      ...extra
+    })));
+  };
   if (agentRun.failure && !agentTimedOut) {
     err(`tamperward run: agent runtime failed to start/report cleanly (${agentRun.failure}).`);
   }
-  if (process.platform === "linux" && !agentRun.lifecycleOwned) {
-    err("tamperward run: the Linux agent lifecycle boundary was not established/drained \u2014 failing closed before adjudication.");
-    finishObserverAdvisory(observer);
+  if (!agentRun.lifecycleOwned) {
+    err("tamperward run: the agent lifecycle boundary was not established/drained \u2014 failing closed before adjudication.");
+    finishObserverAdvisory(observer, say);
+    emitRunJson("CANNOT_ADJUDICATE", 2, {
+      reason: "AGENT_LIFECYCLE_NOT_OWNED"
+    });
     return 2;
   }
   if (agentTimedOut) {
@@ -11908,9 +11981,10 @@ function runEnvelope(opts) {
     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.");
-    out(`
+    say(`
 tamperward run \u2014 agent exit ${agentExit}; OBJECT_REWRITE \u2192 ENFORCEMENT_FAILED`);
-    finishObserverAdvisory(observer);
+    finishObserverAdvisory(observer, say);
+    emitRunJson("OBJECT_REWRITE", 1);
     return 1;
   }
   const head = git3(["rev-parse", "HEAD"], cwd).trim();
@@ -11918,36 +11992,41 @@ tamperward run \u2014 agent exit ${agentExit}; OBJECT_REWRITE \u2192 ENFORCEMENT
   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.");
-    out(`
+    say(`
 tamperward run \u2014 agent exit ${agentExit}; HISTORY_REWRITE \u2192 ENFORCEMENT_FAILED`);
-    finishObserverAdvisory(observer);
+    finishObserverAdvisory(observer, say);
+    emitRunJson("HISTORY_REWRITE", 1, { head });
     return 1;
   }
   const protectedIgnored = (rel) => isProtected(rel, frozenPolicy);
   const fpBefore = treeFingerprint(cwd, protectedIgnored);
   let diffCode = 0;
   if (head !== base) {
-    out(`
+    say(`
 [envelope] policy check over committed changes (${base.slice(0, 10)}...${head.slice(0, 10)}):`);
-    diffCode = runCheck({ diff: `${base}...${head}`, cwd, policyOverride: frozenPolicy });
+    diffCode = runCheck({ diff: `${base}...${head}`, cwd, policyOverride: frozenPolicy, silent: opts.json });
   }
-  out("\n[envelope] policy check over the working tree (frozen policy, untracked included, no local ledger):");
-  const workCode = runCheck({ worktree: true, cwd, policyOverride: frozenPolicy, includeUntracked: true, ciLayer: true });
+  say("\n[envelope] policy check over the working tree (frozen policy, untracked included, no local ledger):");
+  const workCode = runCheck({ worktree: true, cwd, policyOverride: frozenPolicy, includeUntracked: true, ciLayer: true, silent: opts.json });
   const dependencyBeforeVerificationAttestation = dependencyEnvironment ? attestDependencyEnvironment(cwd, dependencyEnvironment) : void 0;
   const dependencyBeforeVerification = dependencyBeforeVerificationAttestation?.check ?? { ok: true };
   if (!dependencyBeforeVerification.ok) {
     err("tamperward run: the frozen dependency environment changed before verification began \u2014");
     err(`${dependencyBeforeVerification.reason ?? "dependency identity changed"}.`);
     if (!opts.allowDepDrift) {
-      out(`
+      say(`
 tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEMENT_FAILED`);
-      finishObserverAdvisory(observer);
+      finishObserverAdvisory(observer, say);
+      emitRunJson("DEPENDENCY_DRIFT", 1, {
+        head,
+        checks: { diff: diffCode, worktree: workCode }
+      });
       return 1;
     }
     err("(--allow-dep-drift: proceeding anyway, on the operator's judgement.)");
   }
   let verifierFinalDependencyAttestation;
-  out("\n[envelope] pristine verification against the trusted base:");
+  say("\n[envelope] pristine verification against the trusted base:");
   const verifyCode = runVerify({
     cwd,
     base,
@@ -11962,7 +12041,8 @@ tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEME
       }
     } : {},
     allowDepDrift: opts.allowDepDrift,
-    verifierBackend
+    verifierBackend,
+    silent: opts.json
   });
   if (opts.settle && opts.settle > 0) {
     waitForSettleSync(opts.settle);
@@ -11975,7 +12055,7 @@ tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEME
   const dependencyAfter = dependencyEnvironment ? checkDependencyEnvironment(cwd, dependencyEnvironment) : { ok: true };
   if (dependencyEnvironment && process.env.TAMPERWARD_DIAGNOSTICS === "1") {
     const metrics = dependencyEnvironmentDiagnostics(dependencyEnvironment);
-    out(
+    say(
       `tamperward run \u2014 dependency attestation diagnostics: full_snapshots=${metrics.fullSnapshots} reused_snapshots=${metrics.reusedSnapshots} total_ms=${Number(metrics.totalMs.toFixed(3))} verifier_final_attestation=${verifierFinalDependencyAttestation ? "yes" : "no"} run_lifecycle_owned=${agentRun.lifecycleOwned ? "yes" : "no"} entry_reuse=${canReuseAdjacentDependencyAttestation(agentRun.lifecycleOwned) ? "yes" : "no"}`
     );
   }
@@ -12003,7 +12083,8 @@ tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEME
       cwd,
       base,
       head,
-      frozenPolicy
+      frozenPolicy,
+      say
     );
     observerBlocked = observed.blocking;
   }
@@ -12012,10 +12093,25 @@ tamperward run \u2014 agent exit ${agentExit}; DEPENDENCY_DRIFT \u2192 ENFORCEME
   const blocked = diffCode === 1 || workCode === 1 || verifyCode === 1 || notQuiescent || observerBlocked;
   const enforcement = cannot ? 2 : blocked ? 1 : 0;
   const verdict2 = enforcement === 2 ? "CANNOT_ADJUDICATE (fail closed)" : rewrote ? "OBJECT_REWRITE \u2014 the base the checks read is not the base we anchored to" : depsDrifted ? "DEPENDENCY_DRIFT \u2014 the suite runner changed under the envelope" : notQuiescent ? "NOT_QUIESCENT \u2014 the tree moved, or something still holds it" : observerBlocked ? "TRANSIENT_OBSERVER_BLOCK \u2014 observed temporal weakening under strict transient policy" : enforcement === 1 ? "ENFORCEMENT_FAILED \u2014 the tree the runtime released does not stand" : agentTimedOut ? "AGENT_TIMEOUT \u2014 runtime budget expired; post-timeout enforcement clean" : agentExit !== 0 ? `agent exited ${agentExit} (enforcement clean)` : "GREEN MEANS GREEN";
+  const machineVerdict = enforcement === 2 ? "CANNOT_ADJUDICATE" : rewrote ? "OBJECT_REWRITE" : depsDrifted ? "DEPENDENCY_DRIFT" : notQuiescent ? "NOT_QUIESCENT" : observerBlocked ? "TRANSIENT_OBSERVER_BLOCK" : enforcement === 1 ? "ENFORCEMENT_FAILED" : agentTimedOut ? "AGENT_TIMEOUT" : agentExit !== 0 ? "AGENT_FAILED" : "VERIFIED";
   const agentSummary = agentTimedOut ? `AGENT_TIMEOUT (${opts.agentBudget}s; exit 124)` : `agent exit ${agentExit}`;
-  out(`
+  const exitCode = enforcement !== 0 ? enforcement : agentTimedOut ? 124 : agentExit;
+  if (opts.json) {
+    const cannotReason = enforcement !== 2 ? null : verifyCode === 2 ? "VERIFY_CANNOT_VERIFY" : diffCode === 2 ? "CHECK_DIFF_UNJUDGEABLE" : "CHECK_WORKTREE_UNJUDGEABLE";
+    emitRunJson(machineVerdict, exitCode, {
+      head,
+      checks: { diff: diffCode, worktree: workCode, verify: verifyCode },
+      observer: {
+        enabled: Boolean(opts.observeTransients),
+        blocking: observerBlocked
+      },
+      ...cannotReason ? { reason: cannotReason } : {}
+    }, true);
+  } else {
+    say(`
 tamperward run \u2014 ${agentSummary}; checks diff=${diffCode} worktree=${workCode} verify=${verifyCode} \u2192 ${verdict2}`);
-  return enforcement !== 0 ? enforcement : agentTimedOut ? 124 : agentExit;
+  }
+  return exitCode;
 }
 function parseRun(args) {
   const o = { argv: [] };
@@ -12027,6 +12123,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 === "--json") o.json = true;
     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]);
@@ -12073,14 +12170,14 @@ function lifecyclePlatformCheck(platform = process.platform, linuxPython = platf
 var VERIFY_COMMAND = /\btamperward(?:@\S+)?\s+verify\b/;
 function err2(message, opts, id = "doctor", checks = []) {
   if (opts?.json) {
-    const report2 = {
+    const report2 = machineOutput({
       command: "doctor",
       authoritative: false,
       checks: [
         ...checks.filter((check2) => check2.id !== id),
         { id, state: "BROKEN", detail: message }
       ]
-    };
+    });
     process.stdout.write(JSON.stringify(report2) + "\n");
   } else {
     process.stderr.write(`tamperward doctor: ${message}
@@ -12293,7 +12390,7 @@ function observerCheck(cwd) {
 function emitReport(opts, checks) {
   const authoritative = !checks.some((x) => x.state === "BROKEN");
   if (opts.json) {
-    const report2 = { command: "doctor", authoritative, checks };
+    const report2 = machineOutput({ command: "doctor", authoritative, checks });
     process.stdout.write(JSON.stringify(report2) + "\n");
     return;
   }
@@ -13149,7 +13246,7 @@ function validateCliArgs(cmd, args) {
     const prefix = args.slice(0, delimiter3);
     const command = args.slice(delimiter3 + 1);
     const parsed = validateFlatArgs(prefix, {
-      flags: ["--allow-dirty", "--allow-dep-drift", "--observe-transients"],
+      flags: ["--allow-dirty", "--allow-dep-drift", "--observe-transients", "--json"],
       values: {
         "--base": "string",
         "--cmd": "string",
@@ -13250,7 +13347,8 @@ Formats:
   github  GitHub Actions view: one inline annotation per finding (so it shows up
           on the line in "Files changed") plus a job-summary table on the run
           page, alongside the same text output in the log.
-  json    the findings verbatim, plus a summary count.
+  json    versioned machine-readable output. Top-level schema_version identifies
+          the public JSON-schema major; published schemas live under schemas/.
   auto    github when GITHUB_ACTIONS=true, otherwise text.
   tamperward hook claude                    PreToolUse gate (reads hook JSON on stdin)
   tamperward sweep claude                   Stop sweep (re-scan the turn's working tree)
@@ -13279,11 +13377,13 @@ Formats:
              [--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).
-             [--observe-transients]          --observe-transients starts a session-
+             [--observe-transients] [--json] --observe-transients starts a session-
                                             scoped observer before the agent and
                                             reports temporal evidence/health after it.
                                             --agent-budget bounds the agent runtime
                                             itself and still adjudicates after timeout.
+                                            --json emits one final versioned run verdict
+                                            document on stdout after agent adjudication.
                                             Exit: agent's
                                             code when clean; 124 on clean AGENT_TIMEOUT;
                                             1 on any blocking finding/masked failure;