tamperward 2.17.1 → 2.19.0

package/README.md

@@ -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
 ```
 
@@ -456,6 +482,50 @@ deliberately refuses `backend: container` before launching the agent because the
 would share the host identity that controls Docker. Use isolated `tamperward verify`
 from trusted CI, or after an externally isolated agent hands off the frozen candidate.
 
+### Machine-readable verdict API
+
+From **2.19.0**, the public JSON verdict surfaces are versioned independently of the
+npm package version. `check --json`, `verify --json`, `run --json`, and
+`doctor --json` include top-level `"schema_version": 1`. TamperWard publishes the
+corresponding JSON Schema Draft 2020-12 documents in the npm package and repository:
+
+- [`schemas/check-v1.schema.json`](./schemas/check-v1.schema.json)
+- [`schemas/verify-v1.schema.json`](./schemas/verify-v1.schema.json)
+- [`schemas/run-v1.schema.json`](./schemas/run-v1.schema.json)
+- [`schemas/doctor-v1.schema.json`](./schemas/doctor-v1.schema.json)
+
+Schema major **1** is deliberately additive: consumers should ignore fields they do not
+understand. Adding new evidence/diagnostic fields does not require a schema bump.
+Removing or renaming a required field, changing its type, or changing the meaning of a
+discriminator requires `schema_version: 2` and new `*-v2.schema.json` files; the v1
+files remain published for existing integrations.
+
+`run --json` owns stdout after the wrapped agent starts and emits one final envelope
+document, including post-agent early convictions such as `OBJECT_REWRITE`,
+`HISTORY_REWRITE`, `DEPENDENCY_DRIFT`, or lifecycle cannot-adjudicate. In this mode the
+agent's own stdout is routed to stderr (its stderr is unchanged), so stdout carries
+exactly one document however noisy the agent is. The document's `complete` field says
+whether the full post-agent adjudication ran: `true` documents carry `head`,
+`checks.{diff,worktree,verify}` and `observer`; early convictions and lifecycle refusals
+are `complete: false`. A `CANNOT_ADJUDICATE` document always names which layer could not
+judge in `reason` (`AGENT_LIFECYCLE_NOT_OWNED`, `VERIFY_CANNOT_VERIFY`,
+`CHECK_DIFF_UNJUDGEABLE`, `CHECK_WORKTREE_UNJUDGEABLE`). Argument, trusted-base, policy,
+dirty-start, and other **pre-agent/preflight** failures still fail closed on stderr at
+exit 2 because no agent adjudication occurred.
+
+`verify --json` never falls back to prose: every fail-closed exit before a verdict exists
+is a `CANNOT_VERIFY` document whose `reason` is one of the enumerated codes in the schema
+(`POLICY_ERROR`, `NO_SUITE_COMMAND`, `VERIFIER_BACKEND_UNAVAILABLE`, `WORKTREE_CHANGED`,
+`PRISTINE_INTEGRITY_CHANGED`, …) with a human `detail` beside it and, once a suite
+execution was in flight, the `stage` it happened in. The reason vocabularies for both
+`verify` and `run` are defined once in the source and asserted equal to the schema enums
+by the test suite, so a new code cannot ship without the contract.
+
+The JSON schemas describe **data shape**, not process status. Exit codes are a separate
+public protocol and are documented in the table immediately below. Consumers should
+validate both independently: schema validation answers “can I parse this verdict?”;
+the process exit answers “did the gate allow, block, time out, or fail to adjudicate?”
+
 ### CLI reference
 
 Every flag below is what the command's parser actually reads (`src/cli/main.ts`,
@@ -470,8 +540,9 @@ 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...>` |
+| `run` | `--base <rev>` · `--cmd <suite command>` · `--budget <seconds>` (per verifier suite) · `--agent-budget <seconds>` (optional wrapped-agent wall clock) · `--json` (one versioned final envelope document) · `--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>` |
 | `init` | `--cwd <dir>` · `--dry-run` · `--force-workflow` |
 | `watch` | `--dir <dir>` · `--log <file>` — a daemon; it runs until signalled |
@@ -483,6 +554,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 | — |
@@ -591,8 +663,11 @@ and the posts in [docs/blog/](./docs/blog/index.md).
 ## Stability
 
 The public surface is the CLI and its **exit codes**, the hook wire format, the
-`.tamperward.yml` schema, and the `--json` `Finding` shape. No `main`, no `exports` —
-it is a binary, not a library. The version answers one question: *can taking this
+`.tamperward.yml` schema, and the versioned `check` / `verify` / `run` / `doctor`
+machine-output schemas under `schemas/`. No `main`, no `exports` — it is a binary,
+not a library. The machine-output schema major is intentionally independent of the npm
+version: additive fields stay compatible within the major; breaking shape/semantic
+changes require a new schema major. The version answers one question: *can taking this
 upgrade turn a green build red without me changing anything?* **Patch never can** —
 bypass fixes and false-positive fixes ship as patches so they reach you automatically.
 Rule graduations (`warn` → `block`) are **opt-in**: they gate on the `version:` field in