tamperward 2.20.6 → 2.21.0

package/README.md

@@ -368,13 +368,29 @@ Full assumptions and residual risks: [SPEC.md](./SPEC.md),
 ## Quick start
 
 ```bash
-npx tamperward init
+npx tamperward onboard
 ```
 
 Requires Node.js 20.19 or later. JavaScript and TypeScript are the fully
 supported detector surface; the other documented ecosystems get file-level and
 pattern-based protection.
 
+`onboard` (2.21.0) is the guided first run: it previews the installation with the
+same planner as `init --dry-run`, explains each enforcement point, asks before writing
+anything, runs the canonical `init`, offers the detected suite command for your
+explicit acceptance (it is never written without one), runs and explains the first
+`verify`, offers a safe demonstration of a weakening move on a disposable worktree that
+leaves your tree byte-for-byte as it was, checks the GitHub controls with
+`doctor --github` (or prints them), and ends with a `READY` / `READY WITH WARNINGS` /
+`BROKEN` / `INCOMPLETE` posture taken from `doctor`. Non-interactive stdin refuses
+rather than hangs; `--yes --verify-command "<cmd>"` is the scripted form.
+
+The deterministic primitive underneath is unchanged:
+
+```bash
+npx tamperward init
+```
+
 One idempotent command wires the policy, the agent hooks, the pre-commit hook, a
 CI workflow that runs both the diff-time check and pristine verification, and a
 `CODEOWNERS` requirement on the paths that decide whether the gate runs at all.
@@ -566,6 +582,7 @@ option can never be reinterpreted as the 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` |
+| `onboard` | `--cwd <dir>` · `--base <rev>` · `--repo <owner/repo>` · `--branch <name>` · `--skip-demo` / `--demo` (mutually exclusive) · `--no-github` · `--yes` (scripted: no prompts; the demo runs only with `--demo`) · `--verify-command "<suite command>"` (the only way a scripted run configures `verify.command`) |
 | `watch` | `--dir <dir>` · `--log <file>` — a daemon; it runs until signalled |
 | `hook claude` / `sweep claude` | none — the Claude Code payload arrives on stdin |
 
@@ -581,6 +598,7 @@ option can never be reinterpreted as the agent command.
 | `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 | — |
+| `onboard` | posture `READY` or `READY WITH WARNINGS` (from `doctor`) | posture `BROKEN` or `INCOMPLETE`, including a declined write or an unconfigured verifier | refused (not a git repository, non-interactive stdin without `--yes`, a dirty tree the operator would not continue on) or aborted at a prompt | — |
 | no or unknown command | help printed (no command) | — | unknown command, help printed | — |
 
 ### Environment variables

package/dist/cli/index.js

@@ -2202,8 +2202,8 @@ function numericOf(e) {
   }
   return void 0;
 }
-function metricsOf(expr, resolve10) {
-  const obj = resolve10(expr);
+function metricsOf(expr, resolve11) {
+  const obj = resolve11(expr);
   if (!ts4.isObjectLiteralExpression(obj)) return void 0;
   const out2 = { values: {}, opaque: false };
   let any = false;
@@ -2217,7 +2217,7 @@ function metricsOf(expr, resolve10) {
     const k = keyName(p.name);
     if (k === null || !isMetric(k)) continue;
     any = true;
-    const n = numericOf(resolve10(p.initializer));
+    const n = numericOf(resolve11(p.initializer));
     if (n === void 0) out2.opaque = true;
     else out2.values[k] = n;
   }
@@ -2263,17 +2263,17 @@ function parseThresholds(src) {
   const res = { paths: /* @__PURE__ */ new Map(), present: false, opaque: false };
   try {
     const sf = sourceOf(src);
-    const resolve10 = resolverFor(sf);
+    const resolve11 = resolverFor(sf);
     const visit = (node) => {
       if (ts4.isPropertyAssignment(node)) {
         const key2 = keyName(node.name);
         if (key2 === "coverageThreshold" || key2 === "thresholds" && underKey(node, "coverage")) {
           res.present = true;
-          const init = resolve10(node.initializer);
+          const init = resolve11(node.initializer);
           if (!ts4.isObjectLiteralExpression(init)) {
             res.opaque = true;
           } else {
-            const flat = metricsOf(init, resolve10);
+            const flat = metricsOf(init, resolve11);
             if (flat) res.global = merge(res.global, flat);
             for (const p of init.properties) {
               if (ts4.isSpreadAssignment(p)) {
@@ -2287,7 +2287,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, resolve10);
+              const m = metricsOf(p.initializer, resolve11);
               if (!m) continue;
               if (k === "global") res.global = merge(res.global, m);
               else res.paths.set(norm(k), m);
@@ -2320,18 +2320,18 @@ function parseLists(src) {
   const res = { collectFrom: null, collectKey: "collectCoverageFrom", ignore: [], opaqueCollect: false, opaqueIgnore: false };
   try {
     const sf = sourceOf(src);
-    const resolve10 = resolverFor(sf);
+    const resolve11 = resolverFor(sf);
     const visit = (node) => {
       if (ts4.isPropertyAssignment(node)) {
         const k = keyName(node.name);
         const vitestCoverage = ownerKey(node) === "coverage";
         if (k === "collectCoverageFrom" || k === "include" && vitestCoverage) {
-          const { items, opaque } = literals(resolve10(node.initializer));
+          const { items, opaque } = literals(resolve11(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(resolve10(node.initializer));
+          const { items, opaque } = literals(resolve11(node.initializer));
           res.ignore.push(...items);
           if (opaque) res.opaqueIgnore = true;
         }
@@ -7030,7 +7030,7 @@ function evaluate(changes, policy, detectors = allDetectors, view, ctx) {
       process.stderr.write(`tamperward: detector "${d.id}" errored: ${String(e)}
 `);
       if (view === "staged" || view === "worktree" || view === "range") {
-        const failed = {
+        const failed2 = {
           rule: "detector-error",
           severity: "block",
           message: `Detector "${d.id}" failed to run; the verdict is incomplete.`,
@@ -7038,7 +7038,7 @@ function evaluate(changes, policy, detectors = allDetectors, view, ctx) {
           remediation: "A rule that cannot run is not a rule that passed. Fix the input or the detector; do not read this as clean.",
           signoff: { required: true, command: `tamperward allow detector-error --reason "..."` }
         };
-        out2.push(failed);
+        out2.push(failed2);
       }
     }
   }
@@ -11211,6 +11211,7 @@ function runVerify(opts) {
   const out2 = opts.silent ? (_s) => {
   } : (s) => void process.stdout.write(s + "\n");
   const cannotVerify = (reason, detail, extra = {}) => {
+    opts.onVerdict?.({ verdict: "CANNOT_VERIFY", reason, ...detail ? { detail } : {} });
     if (opts.json) {
       out2(JSON.stringify({
         schema_version: MACHINE_SCHEMA_VERSION,
@@ -11256,6 +11257,7 @@ function runVerify(opts) {
   const verifierBackend = opts.verifierBackend ?? prepareVerifierBackend(policy.verify);
   const backendReport = () => verifierBackendReport(verifierBackend);
   if (!verifierBackend.available) {
+    opts.onVerdict?.({ verdict: "CANNOT_VERIFY", reason: "VERIFIER_BACKEND_UNAVAILABLE", ...verifierBackend.reason ? { detail: verifierBackend.reason } : {} });
     if (opts.json) {
       out2(JSON.stringify({
         schema_version: MACHINE_SCHEMA_VERSION,
@@ -11272,6 +11274,7 @@ function runVerify(opts) {
   }
   const isolated = verifierBackend.kind === "container";
   if (!isolated && !localVerifierShell(process.platform, cmd)) {
+    opts.onVerdict?.({ verdict: "CANNOT_VERIFY", reason: "LOCAL_VERIFIER_UNSUPPORTED_PLATFORM", detail: `checkpointed-local verifier is unsupported on ${process.platform}` });
     if (opts.json) {
       out2(JSON.stringify({
         schema_version: MACHINE_SCHEMA_VERSION,
@@ -11295,6 +11298,7 @@ function runVerify(opts) {
     image: verifierBackend.image
   };
   if (dependencyEnvironment?.status === "unattestable" && !opts.allowDepDrift) {
+    opts.onVerdict?.({ verdict: "CANNOT_VERIFY", reason: "DEPENDENCY_ENVIRONMENT_UNATTESTABLE", ...dependencyEnvironment.reason ? { detail: dependencyEnvironment.reason } : {} });
     if (opts.json) {
       out2(JSON.stringify({
         schema_version: MACHINE_SCHEMA_VERSION,
@@ -11355,6 +11359,7 @@ function runVerify(opts) {
   if (visible.failure === "backend" || visible.failure === "resource") {
     cleanup([visRoot]);
     const exhausted = visible.failure === "resource";
+    opts.onVerdict?.({ verdict: "CANNOT_VERIFY", reason: exhausted ? "VERIFIER_RESOURCE_EXHAUSTED" : "VERIFIER_BACKEND_RUNTIME_FAILURE", ...visible.reason ? { detail: visible.reason } : {} });
     if (opts.json) {
       out2(JSON.stringify({
         schema_version: MACHINE_SCHEMA_VERSION,
@@ -11421,6 +11426,7 @@ function runVerify(opts) {
   if (pristine.failure === "backend" || pristine.failure === "resource") {
     cleanup([visRoot, priRoot]);
     const exhausted = pristine.failure === "resource";
+    opts.onVerdict?.({ verdict: "CANNOT_VERIFY", reason: exhausted ? "VERIFIER_RESOURCE_EXHAUSTED" : "VERIFIER_BACKEND_RUNTIME_FAILURE", ...pristine.reason ? { detail: pristine.reason } : {} });
     if (opts.json) {
       out2(JSON.stringify({
         schema_version: MACHINE_SCHEMA_VERSION,
@@ -11476,6 +11482,7 @@ function runVerify(opts) {
     verdict2 = "SUITE_RED";
     code2 = 1;
   }
+  opts.onVerdict?.({ verdict: verdict2 });
   const signedOff = verdict2 === "MASKED_FAILURE" ? oobToken("verify", oobFromEnv(), oobHeadFromEnv()) : null;
   if (signedOff) code2 = 0;
   if (opts.json) {
@@ -12482,22 +12489,17 @@ 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 = 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}
-`);
-  }
-  return 2;
+function failed(message, id = "doctor", checks = []) {
+  return {
+    code: 2,
+    authoritative: false,
+    checks: [
+      ...checks.filter((check2) => check2.id !== id),
+      { id, state: "BROKEN", detail: message }
+    ],
+    failure: { id, message },
+    summary: []
+  };
 }
 function policyFor(opts, cwd) {
   if (!opts.base) return loadPolicy(cwd);
@@ -12701,8 +12703,7 @@ function observerCheck(cwd) {
     detail: `unavailable${observer.reason ? ": " + observer.reason : ""}; optional/advisory, and zero events are not evidence of no transient activity`
   };
 }
-function emitReport(opts, checks) {
-  const authoritative = !checks.some((x) => x.state === "BROKEN");
+function emitReport(opts, checks, authoritative) {
   if (opts.json) {
     const report2 = machineOutput({ command: "doctor", authoritative, checks });
     process.stdout.write(JSON.stringify(report2) + "\n");
@@ -12894,22 +12895,20 @@ function verifyJobs(doc) {
   }
   return found;
 }
-function runDoctor(opts = {}) {
+function diagnose(opts = {}) {
   const cwd = resolve8(opts.cwd ?? process.cwd());
   let policy;
   try {
     policy = policyFor(opts, cwd);
   } catch (e) {
-    return err2(
+    return failed(
       e instanceof PolicyError || e instanceof Error ? e.message : String(e),
-      opts,
       "policy"
     );
   }
   let postureWorkflows = opts.workflow ? [opts.workflow] : void 0;
-  const fail = (id, message) => err2(
+  const fail = (id, message) => failed(
     message,
-    opts,
     id,
     collectLocalPosture(cwd, policy, postureWorkflows, Boolean(opts.workflow))
   );
@@ -13037,19 +13036,38 @@ function runDoctor(opts = {}) {
     });
   }
   checks.push(observerCheck(cwd));
-  if (!opts.json) {
-    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.
-`
+  const summary = [
+    `tamperward doctor: CI verifier envelope OK \u2014 ${verifyJobCount} verify job(s), trusted budget ${policy.verify.budget}s/stage, requires >=${requiredMinutes}m outer timeout.`
+  ];
+  if (github) {
+    summary.push(
+      "tamperward doctor: GitHub repository authority OK \u2014 " + github.repo + "#" + github.branch + " requires tamperward, Code Owner review, and stale-review dismissal on new pushes."
     );
-    if (github) {
-      process.stdout.write(
-        "tamperward doctor: GitHub repository authority OK \u2014 " + github.repo + "#" + github.branch + " requires tamperward, Code Owner review, and stale-review dismissal on new pushes.\n"
-      );
+  }
+  return {
+    code: 0,
+    authoritative: !checks.some((x) => x.state === "BROKEN"),
+    checks,
+    summary,
+    ...github ? { github: { repo: github.repo, branch: github.branch } } : {}
+  };
+}
+function runDoctor(opts = {}) {
+  const outcome = diagnose(opts);
+  if (outcome.failure) {
+    if (opts.json) {
+      emitReport(opts, outcome.checks, false);
+    } else {
+      process.stderr.write(`tamperward doctor: ${outcome.failure.message}
+`);
     }
+    return outcome.code;
   }
-  emitReport(opts, checks);
-  return 0;
+  if (!opts.json) {
+    for (const line of outcome.summary) process.stdout.write(line + "\n");
+  }
+  emitReport(opts, outcome.checks, outcome.authoritative);
+  return outcome.code;
 }
 
 // src/cli/trace-verify.ts
@@ -13430,6 +13448,507 @@ function parseTraceVerify(args) {
   return out2;
 }
 
+// src/cli/onboard.ts
+import { execFileSync as execFileSync12 } from "node:child_process";
+import { randomBytes as randomBytes2 } from "node:crypto";
+import { lstatSync as lstatSync6, mkdtempSync as mkdtempSync6, readFileSync as readFileSync19, realpathSync as realpathSync8, renameSync as renameSync2, rmSync as rmSync7, writeFileSync as writeFileSync10 } from "node:fs";
+import { tmpdir as tmpdir6 } from "node:os";
+import { join as join20, resolve as resolve10, sep as sep4 } from "node:path";
+import { createInterface } from "node:readline";
+import { parseDocument } from "yaml";
+function readlineAsker(input, output) {
+  const rl = createInterface({ input, output });
+  let closed = false;
+  let pending = null;
+  rl.on("close", () => {
+    closed = true;
+    const resolve11 = pending;
+    pending = null;
+    resolve11?.(null);
+  });
+  rl.on("SIGINT", () => rl.close());
+  const ask = (question) => new Promise((resolvePromise) => {
+    if (closed) {
+      resolvePromise(null);
+      return;
+    }
+    pending = resolvePromise;
+    rl.question(question, (answer) => {
+      pending = null;
+      resolvePromise(answer);
+    });
+  });
+  ask.close = () => {
+    if (!closed) rl.close();
+  };
+  return ask;
+}
+var Aborted = class extends Error {
+};
+var STEPS = [
+  "Preflight",
+  "Preview the installation",
+  "Initialize",
+  "Configure verification",
+  "First verification",
+  "Safe demonstration",
+  "GitHub repository authority",
+  "Posture",
+  "Next steps"
+];
+var MANUAL_CONTROLS = [
+  "In the branch-protection or ruleset settings of the protected branch, configure ALL THREE:",
+  "  1. require the `tamperward` status check;",
+  '  2. enable "Require review from Code Owners";',
+  '  3. enable "Dismiss stale pull request approvals when new commits are pushed".',
+  "Until all three are enforced the generated CI gate is advisory: a pull request runs the",
+  "workflow from its own head and a required check is matched by job name, so it could keep",
+  "the job called `tamperward`, replace the gate with `true`, and report green."
+];
+var JS_TEST_PATH = /(?:^|\/)(?:[^/]+\.(?:test|spec)\.[cm]?[jt]sx?|__tests__\/[^/]+\.[cm]?[jt]sx?)$/;
+var JS_TEST_BLOCK = /^(\s*)(it|test|describe)(\s*\()/m;
+function git5(cwd, args) {
+  try {
+    return execFileSync12("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return null;
+  }
+}
+function explainVerdict(v, code2) {
+  const verdict2 = v?.verdict ?? (code2 === 0 ? "VERIFIED" : code2 === 1 ? "SUITE_RED" : "CANNOT_VERIFY");
+  switch (verdict2) {
+    case "VERIFIED":
+      return [
+        "VERIFIED: your suite passes, and still passes with every protected test, snapshot and",
+        "config file restored from the base. Nothing was masked. Exit 0."
+      ];
+    case "SUITE_RED":
+      return [
+        "SUITE_RED: your suite fails as it is. That is not a TamperWard finding \u2014 fix the code",
+        "(or the suite) first; verify exits 1 until the visible run is green."
+      ];
+    case "MASKED_FAILURE":
+      return [
+        "MASKED_FAILURE: your suite passes as it is, but FAILS once the protected files are restored",
+        "from the base. Something weakened the checks; the code does not pass the original suite.",
+        "Exit 1. In CI only a reviewer label (`tamperward:allow:verify@<head-sha>`) clears it."
+      ];
+    default:
+      return [
+        `CANNOT VERIFY${v?.reason ? ` (${v.reason})` : ""}: TamperWard could not verify this repository and fails closed`,
+        "(exit 2) rather than reporting success. Nothing above is a verdict about your code.",
+        ...v?.detail ? [`  ${v.detail}`] : []
+      ];
+  }
+}
+function atomicReplaceFile(path, content, mode) {
+  const tmp = `${path}.${process.pid}.${randomBytes2(8).toString("hex")}.tmp`;
+  try {
+    writeFileSync10(tmp, content, { encoding: "utf8", flag: "wx", mode });
+    renameSync2(tmp, path);
+  } finally {
+    rmSync7(tmp, { force: true });
+  }
+}
+function writeVerifyCommand(cwd, command) {
+  const path = join20(cwd, POLICY_FILE);
+  const st = lstatSync6(path, { throwIfNoEntry: false });
+  if (st && (!st.isFile() || st.isSymbolicLink())) {
+    return `${POLICY_FILE} is not a regular file; refusing to follow or replace a symlink or special file`;
+  }
+  const mode = st ? st.mode & 511 : 420;
+  const original = st ? readFileSync19(path, "utf8") : null;
+  let next;
+  try {
+    const doc = parseDocument(original && original.trim() ? original : "version: 1\n");
+    if (doc.errors.length) return `${POLICY_FILE} is not valid YAML: ${doc.errors[0].message}`;
+    doc.setIn(["verify", "command"], command);
+    if (!doc.hasIn(["verify", "budget"])) doc.setIn(["verify", "budget"], 300);
+    next = doc.toString();
+  } catch (e) {
+    return `${POLICY_FILE} could not be updated: ${errorMessage(e)}`;
+  }
+  atomicReplaceFile(path, next, mode);
+  try {
+    const loaded = loadPolicy(cwd);
+    if (loaded.verify?.command !== command) throw new Error("verify.command did not round-trip");
+    return null;
+  } catch (e) {
+    if (original === null) rmSync7(path, { force: true });
+    else atomicReplaceFile(path, original, mode);
+    return `the updated ${POLICY_FILE} does not load (${errorMessage(e)}); restored the previous file`;
+  }
+}
+async function runOnboard(opts, io = {}) {
+  const cwd = resolve10(opts.cwd ?? process.cwd());
+  const out2 = io.out ?? ((line) => void process.stdout.write(line + "\n"));
+  const err2 = (line) => void process.stderr.write(line + "\n");
+  const platform = io.platform ?? process.platform;
+  const runners = {
+    init: runInit,
+    verify: runVerify,
+    doctor: diagnose,
+    check: runCheck,
+    ...io.runners
+  };
+  const interactive = io.interactive ?? (Boolean(process.stdin.isTTY) && !process.env.CI && !process.env.GITHUB_ACTIONS);
+  const scripted = Boolean(opts.yes);
+  if (!interactive && !scripted) {
+    err2("tamperward onboard: stdin is not interactive (or a CI environment was detected), so the guided");
+    err2("setup cannot ask questions. Re-run with --yes for the scripted mode (add --verify-command");
+    err2('"<suite command>" to configure verification; a detected command is never written unscripted),');
+    err2("or run the deterministic primitive directly: tamperward init.");
+    return 2;
+  }
+  if (!isGitRepo(cwd)) {
+    err2(`tamperward onboard: ${cwd} is not inside a git repository \u2014 run \`git init\` first; every enforcement point is git-anchored`);
+    return 2;
+  }
+  const prompt = { asker: null };
+  const rawAsk = io.ask ?? ((q) => (prompt.asker ??= readlineAsker(process.stdin, process.stdout))(q));
+  const ask = async (question) => {
+    const answer = await rawAsk(question);
+    if (answer === null) throw new Aborted();
+    return answer.trim();
+  };
+  const confirm = async (question, fallback, scriptedAnswer) => {
+    if (scripted) return scriptedAnswer;
+    const a = (await ask(`${question} ${fallback ? "[Y/n]" : "[y/N]"} `)).toLowerCase();
+    if (a === "") return fallback;
+    return a === "y" || a === "yes";
+  };
+  let step = 0;
+  const header = (n) => {
+    step = n;
+    out2("");
+    out2(`== ${n}/${STEPS.length} ${STEPS[n - 1]} ==`);
+  };
+  const wrote = [];
+  let verifyCommand;
+  let verifyResult = null;
+  let githubChecked = false;
+  let repo = null;
+  let declined = false;
+  let doctorOutcome = null;
+  try {
+    header(1);
+    out2(`TamperWard ${TW_VERSION} on Node ${process.versions.node} (${platform}/${process.arch}), repository ${cwd}`);
+    const lifecycle = lifecyclePlatformCheck(platform);
+    out2(`platform: [${lifecycle.state}] ${lifecycle.detail}`);
+    const localVerifySupported = localVerifierShell(platform, "true") !== null;
+    if (!localVerifySupported) {
+      out2("platform: checkpointed-local verify is unsupported here; only a digest-pinned container verifier");
+      out2("  (verify.backend: container) can verify on this platform, exactly as the support contract states.");
+    }
+    const head = git5(cwd, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])?.trim() ?? null;
+    if (!head) {
+      out2("history: no commit yet. Verification and the demonstration need a committed base; the wiring can still be written.");
+    }
+    const status = git5(cwd, ["status", "--porcelain", "--untracked-files=all"]) ?? "";
+    const dirty = status.split("\n").filter(Boolean).map((line) => line.slice(3).split(" -> ").at(-1) ?? "");
+    const owned = new Set(planInit(cwd).map((a) => a.path));
+    const foreign = dirty.filter((p) => !owned.has(p));
+    if (dirty.length && foreign.length === 0) {
+      out2(`working tree: ${dirty.length} uncommitted path(s), all written by init \u2014 commit them so the gate travels with the repository.`);
+    } else if (dirty.length) {
+      out2(`working tree is not clean: ${dirty.length} changed or untracked path(s). Onboarding never stashes,`);
+      out2("resets or edits your changes, but a clean tree makes the first verification easier to read:");
+      out2("commit or stash your work first for the cleanest result.");
+      if (!await confirm("Continue with a dirty working tree?", false, true)) {
+        out2("Stopped before writing anything. Commit or stash your work, then re-run: tamperward onboard");
+        return 2;
+      }
+    } else {
+      out2("working tree: clean");
+    }
+    header(2);
+    out2("This is the plan `tamperward init` would apply (the same planner as `init --dry-run`):");
+    out2("");
+    runners.init({ cwd, dryRun: true });
+    out2("");
+    out2("What each item is for:");
+    out2(`  policy      \u2014 ${POLICY_FILE} holds your overrides; the baseline rules apply even without it.`);
+    out2("  agent hooks \u2014 Claude Code PreToolUse deny + Stop sweep: the steering layer, judged in the loop.");
+    out2("  pre-commit  \u2014 the same engine over the staged diff, so a shortcut cannot be committed quietly.");
+    out2("  CI          \u2014 the authority for the protected branch: check --diff over the PR range plus");
+    out2("                pristine verify; cleared only by a reviewer label bound to the head SHA.");
+    out2("  CODEOWNERS  \u2014 a human requirement on the paths that decide whether the gate runs at all.");
+    const plan = planInit(cwd);
+    const pending = plan.filter((a) => a.apply).length;
+    const errors = plan.filter((a) => a.status === "error").length;
+    if (pending === 0) {
+      out2("");
+      out2(errors ? "Nothing to write, but item(s) above need your attention." : "Everything is already wired \u2014 nothing to write.");
+    } else {
+      out2("");
+      out2("init never overwrites a file you wrote: it creates what is absent and merges what is shared.");
+      if (!await confirm(`Write these ${pending} change(s) now?`, false, true)) {
+        declined = true;
+        out2("Declined: nothing was written. Re-run `tamperward onboard` when ready, or apply the plan");
+        out2("yourself with `tamperward init` (`--dry-run` prints it again).");
+      }
+    }
+    if (!declined && pending > 0) {
+      header(3);
+      const code2 = runners.init({ cwd });
+      wrote.push(...plan.filter((a) => a.apply).map((a) => a.path));
+      if (code2 !== 0) out2("init reported item(s) that need your attention (above); onboarding continues so you can see the rest.");
+    }
+    if (!declined) {
+      header(4);
+      let configured;
+      try {
+        configured = loadPolicy(cwd).verify?.command?.trim() || void 0;
+      } catch (e) {
+        out2(`${POLICY_FILE} does not load (${errorMessage(e)}); fix it, then re-run. verify.command was not configured.`);
+      }
+      if (configured) {
+        out2(`verification configured \u2014 ${configured}`);
+        verifyCommand = configured;
+      } else {
+        out2("The verifier command is part of the trust anchor: `verify` re-runs it against a pristine copy of");
+        out2("your suite, and CI fails closed without it. TamperWard never chooses it for you.");
+        const candidates = verifierCandidates(cwd);
+        let chosen;
+        if (scripted) {
+          if (opts.verifyCommand?.trim()) {
+            chosen = opts.verifyCommand.trim();
+          } else {
+            out2(candidates.length ? `Detected candidate(s): ${candidates.join(", ")}.` : "No suite command was detected.");
+            out2('Scripted mode: verify.command was not written. Pass --verify-command "<suite command>" to set it explicitly.');
+          }
+        } else if (candidates.length === 1) {
+          out2(`Detected one high-confidence suite command: ${candidates[0]}`);
+          if (await confirm(`Use \`${candidates[0]}\` as verify.command?`, false, false)) chosen = candidates[0];
+          else chosen = await ask("Enter the suite command to trust (empty to skip): ") || void 0;
+        } else if (candidates.length > 1) {
+          out2("Several suite commands were detected; choose the one that defines merge authority:");
+          candidates.forEach((c, i) => out2(`  ${i + 1}. ${c}`));
+          const a = await ask(`Choose 1-${candidates.length} (${candidates.join(" / ")}), type a command, or press Enter to skip: `);
+          const n = Number(a);
+          chosen = a === "" ? void 0 : Number.isInteger(n) && n >= 1 && n <= candidates.length ? candidates[n - 1] : a;
+        } else {
+          out2("No suite command was detected (no test script, pytest/tox config, Cargo or Go module root).");
+          chosen = await ask("Enter the suite command to trust (empty to skip): ") || void 0;
+        }
+        if (chosen) {
+          const problem = writeVerifyCommand(cwd, chosen);
+          if (problem) {
+            out2(`verify.command was not written: ${problem}`);
+          } else {
+            out2(`Wrote verify.command: ${chosen} (budget 300s) to ${POLICY_FILE}. Commit it: with a --base, verify reads`);
+            out2("the policy from that commit, so an uncommitted command is invisible to CI.");
+            verifyCommand = chosen;
+            wrote.push(POLICY_FILE);
+          }
+        } else {
+          out2("verify.command was not configured. CI will fail closed (exit 2) until it is; add it to");
+          out2(`${POLICY_FILE} under verify: and re-run \`tamperward doctor\`.`);
+        }
+      }
+    }
+    if (!declined) {
+      header(5);
+      out2("`verify` runs your suite twice: as-is (visible), and with every protected test/snapshot/config");
+      out2("file restored from the trusted base (pristine). The pair is what no diff rule can fake.");
+      if (!verifyCommand) {
+        out2("Skipped: no verify.command. Standalone `tamperward verify` would report CANNOT_VERIFY");
+        out2("(exit 2) here \u2014 it fails closed rather than pretending to verify.");
+      } else if (!localVerifySupported) {
+        out2(`Skipped: checkpointed-local verify is unsupported on ${platform}; \`tamperward verify\` fails closed`);
+        out2("(exit 2) before running anything. Configure a digest-pinned container verifier for this platform.");
+      } else if (!head) {
+        out2("Skipped: no commit to anchor the pristine copy to. Commit, then run: tamperward verify");
+      } else if (await confirm(`Run the first verification now (${verifyCommand}, twice)?`, true, true)) {
+        let summary = null;
+        const verifyOpts = { cwd, onVerdict: (v) => {
+          summary = v;
+        } };
+        if (opts.base) verifyOpts.base = opts.base;
+        const code2 = runners.verify(verifyOpts);
+        verifyResult = { code: code2, summary };
+        out2("");
+        for (const line of explainVerdict(summary, code2)) out2(line);
+        out2(`(verify exited ${code2}; onboarding reports it and changes nothing about it.)`);
+      } else {
+        out2(`Skipped. Run it any time: tamperward verify${opts.base ? ` --base ${opts.base}` : ""}`);
+      }
+    }
+    if (!declined && !opts.skipDemo) {
+      header(6);
+      out2("Optional: see a finding without risking anything. TamperWard creates a detached temporary");
+      out2("worktree of HEAD, adds `.skip` to one test block THERE, runs `check --worktree` on it, then");
+      out2("removes the worktree. Your working tree is not touched; its fingerprint is shown before and after.");
+      const wanted = scripted ? Boolean(opts.demo) : opts.demo ? true : await confirm("Run the demonstration?", false, false);
+      if (!wanted) {
+        out2("Demo skipped.");
+      } else if (!head) {
+        out2("Demo skipped: no commit to build disposable state from.");
+      } else {
+        runDemo(cwd, head, runners, out2);
+      }
+    }
+    header(7);
+    out2("Local wiring steers the agent and gates commits; only the repository can make CI binding.");
+    repo = opts.repo ?? inferGitHubRepo(cwd);
+    const doctorCommand = `tamperward doctor --github --repo ${repo ?? "OWNER/REPO"} --branch ${opts.branch ?? "<default-branch>"}`;
+    if (opts.noGithub) {
+      out2("--no-github: the GitHub API is not consulted, so nothing below is reported as enforced.");
+      for (const line of MANUAL_CONTROLS) out2(line);
+      out2(`Then verify it with: ${doctorCommand}`);
+    } else if (!repo) {
+      out2("No GitHub repository could be determined (no github.com origin; pass --repo OWNER/REPO).");
+      for (const line of MANUAL_CONTROLS) out2(line);
+      out2(`Then verify it with: ${doctorCommand}`);
+    } else {
+      out2(`Repository: ${repo}${opts.branch ? `, branch ${opts.branch}` : ""}.`);
+      githubChecked = await confirm(
+        "Check the live GitHub controls now with `doctor --github`? (reads the GitHub API; set GH_TOKEN/GITHUB_TOKEN if needed)",
+        true,
+        true
+      );
+      if (!githubChecked) {
+        for (const line of MANUAL_CONTROLS) out2(line);
+        out2(`Then verify it with: ${doctorCommand}`);
+      }
+    }
+    header(8);
+    const doctorOpts = { cwd };
+    if (githubChecked && repo) {
+      doctorOpts.github = true;
+      doctorOpts.repo = repo;
+      if (opts.branch) doctorOpts.branch = opts.branch;
+    }
+    doctorOutcome = runners.doctor(doctorOpts);
+    for (const line of doctorOutcome.summary) out2(line);
+    if (doctorOutcome.failure) out2(`tamperward doctor: ${doctorOutcome.failure.message}`);
+    for (const check2 of doctorOutcome.checks) renderCheck(check2, out2);
+    const posture = postureOf(doctorOutcome);
+    const warnings = doctorOutcome.checks.filter((c) => c.state === "WARN").length;
+    const broken = doctorOutcome.checks.filter((c) => c.state === "BROKEN");
+    out2("");
+    out2(
+      `POSTURE: ${posture}` + (posture === "READY WITH WARNINGS" ? ` \u2014 ${warnings} warning(s) above` : "") + (posture === "BROKEN" ? ` \u2014 ${broken.map((c) => c.id).join(", ")}` : "") + (posture === "INCOMPLETE" && doctorOutcome.failure ? ` \u2014 doctor could not certify: ${doctorOutcome.failure.id}` : "")
+    );
+    if (doctorOutcome.github) {
+      out2(`GitHub repository authority: ENFORCED \u2014 doctor --github verified ${doctorOutcome.github.repo}#${doctorOutcome.github.branch}`);
+      out2("  requires the tamperward check, Code Owner review, and stale-approval dismissal.");
+    } else {
+      out2("GitHub repository authority: NOT VERIFIED \u2014 locally configured only. Until doctor --github");
+      out2(`  confirms the three controls, CI is advisory. Run: ${doctorCommand}`);
+      if (githubChecked && doctorOutcome.failure?.id === "github-authority") {
+        for (const line of MANUAL_CONTROLS) out2(line);
+      }
+    }
+    if (declined) out2("Nothing was written this run; the posture above describes the repository as it was.");
+    if (verifyResult) out2(`First verification: ${verifyResult.summary?.verdict ?? `exit ${verifyResult.code}`}.`);
+    header(9);
+    out2("Day to day:");
+    out2("  tamperward check --worktree              the stop-sweep view of everything changed since HEAD");
+    out2(`  tamperward verify --base ${opts.base ?? "<base>"}${opts.base ? "" : "          "}pristine re-execution against a base the agent cannot rewrite`);
+    out2(`  tamperward run --base ${opts.base ?? "<base>"} -- <agent...>  the enforcement envelope (Linux; fails closed elsewhere)`);
+    out2(`  ${doctorCommand}`);
+    out2("When the final verification matters most \u2014 a release, a merge into the protected branch \u2014 prefer");
+    out2("the digest-pinned container verifier (verify.backend: container, image: <ref>@sha256:<digest>):");
+    out2("it owns the runtime and dependencies, mounts the tree read-only and disables the network, so the");
+    out2("candidate cannot reach the verifier from the same host. `run` deliberately does not offer it.");
+    if (wrote.length) out2(`Commit what onboarding wrote (${[...new Set(wrote)].join(", ")}) so the gate travels with the repository.`);
+    return posture === "READY" || posture === "READY WITH WARNINGS" ? 0 : 1;
+  } catch (e) {
+    if (e instanceof Aborted) {
+      out2("");
+      out2(`tamperward onboard: aborted during step ${step} (${STEPS[step - 1]}).`);
+      out2(
+        wrote.length ? `Written so far: ${[...new Set(wrote)].join(", ")} \u2014 all through init, all idempotent; nothing is half-applied.` : "Nothing was written."
+      );
+      out2("Re-run `tamperward onboard` to continue from the same place, or `tamperward doctor` to see the current posture.");
+      return 2;
+    }
+    throw e;
+  } finally {
+    prompt.asker?.close();
+  }
+}
+function renderCheck(check2, out2) {
+  if (check2.id === "observer") out2(`tamperward doctor: transient observer: ${check2.detail}`);
+  else out2(`tamperward doctor: [${check2.state}] ${check2.id} \u2014 ${check2.detail}`);
+}
+function postureOf(outcome) {
+  if (outcome.failure) return "INCOMPLETE";
+  if (outcome.checks.some((c) => c.state === "BROKEN")) return "BROKEN";
+  if (outcome.checks.some((c) => c.state === "WARN")) return "READY WITH WARNINGS";
+  return "READY";
+}
+function runDemo(cwd, head, runners, out2) {
+  const files = (git5(cwd, ["ls-tree", "-r", "-z", head]) ?? "").split("\0").filter(Boolean).flatMap((row) => {
+    const tab = row.indexOf("	");
+    if (tab < 0) return [];
+    const mode = row.slice(0, tab).split(" ")[0];
+    const path = row.slice(tab + 1);
+    return (mode === "100644" || mode === "100755") && JS_TEST_PATH.test(path) ? [path] : [];
+  });
+  let target = null;
+  for (const path of files) {
+    const before2 = git5(cwd, ["show", `${head}:${path}`]);
+    if (before2 === null || !JS_TEST_BLOCK.test(before2)) continue;
+    target = { path, before: before2, after: before2.replace(JS_TEST_BLOCK, "$1$2.skip$3") };
+    break;
+  }
+  if (!target) {
+    out2("Demo skipped: no JavaScript test block (it/test/describe) at HEAD to demonstrate on.");
+    return;
+  }
+  const before = treeFingerprint(cwd);
+  out2(`working tree fingerprint before: ${before.slice(0, 16)}`);
+  const wt = mkdtempSync6(join20(tmpdir6(), "tw-onboard-demo-"));
+  try {
+    if (git5(cwd, ["worktree", "add", "--detach", wt, head]) === null) {
+      out2("Demo skipped: could not create a temporary worktree (git worktree add failed).");
+      return;
+    }
+    const targetPath = join20(wt, target.path);
+    const targetStat = lstatSync6(targetPath, { throwIfNoEntry: false });
+    if (!targetStat || !targetStat.isFile() || targetStat.isSymbolicLink()) {
+      out2("Demo skipped: the selected test is not a regular file in the disposable worktree.");
+      return;
+    }
+    let worktreeRoot;
+    let realTarget;
+    try {
+      worktreeRoot = realpathSync8(wt);
+      realTarget = realpathSync8(targetPath);
+    } catch {
+      out2("Demo skipped: the selected test could not be resolved safely inside the disposable worktree.");
+      return;
+    }
+    const prefix = worktreeRoot.endsWith(sep4) ? worktreeRoot : worktreeRoot + sep4;
+    if (!realTarget.startsWith(prefix)) {
+      out2("Demo skipped: the selected test resolves outside the disposable worktree.");
+      return;
+    }
+    out2(`disposable worktree: ${wt}`);
+    out2(`weakening move: ${target.path} \u2014 the first test block becomes .skip (only in the disposable copy)`);
+    atomicReplaceFile(targetPath, target.after, targetStat.mode & 511);
+    out2("");
+    out2(`$ tamperward check --worktree   (in ${wt})`);
+    const code2 = runners.check({ cwd: wt, worktree: true });
+    out2("");
+    out2(`check exited ${code2}: ${code2 === 1 ? "a blocking finding, which is what the hook, pre-commit and CI would all report" : "no blocking finding was reported"}.`);
+  } finally {
+    git5(cwd, ["worktree", "remove", "--force", wt]);
+    git5(cwd, ["worktree", "prune"]);
+    rmSync7(wt, { recursive: true, force: true });
+  }
+  const after = treeFingerprint(cwd);
+  out2(`working tree fingerprint after:  ${after.slice(0, 16)}`);
+  if (after === before) {
+    out2("Identical: your working tree was restored byte-for-byte (it was never edited; the disposable worktree is gone).");
+  } else {
+    out2("WARNING: the fingerprint moved. The demo never wrote into your working tree, so something else");
+    out2("changed it while the demo ran; inspect with `git status`.");
+  }
+}
+
 // src/cli/main.ts
 function parseAllow(args) {
   const o = {};
@@ -13461,6 +13980,22 @@ function parseInit(args) {
   }
   return o;
 }
+function parseOnboard(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 === "--repo") o.repo = args[++i];
+    else if (a === "--branch") o.branch = args[++i];
+    else if (a === "--verify-command") o.verifyCommand = args[++i];
+    else if (a === "--skip-demo") o.skipDemo = true;
+    else if (a === "--demo") o.demo = true;
+    else if (a === "--no-github") o.noGithub = true;
+    else if (a === "--yes") o.yes = true;
+  }
+  return o;
+}
 function parseDoctor(args) {
   const o = {};
   for (let i = 0; i < args.length; i++) {
@@ -13614,6 +14149,21 @@ function validateCliArgs(cmd, args) {
       }
     }).error;
   }
+  if (cmd === "onboard") {
+    const parsed = validateFlatArgs(args, {
+      flags: ["--yes", "--skip-demo", "--demo", "--no-github"],
+      values: {
+        "--cwd": "string",
+        "--base": "string",
+        "--repo": "string",
+        "--branch": "string",
+        "--verify-command": "string"
+      }
+    });
+    if (parsed.error) return parsed.error;
+    if (parsed.seen.has("--demo") && parsed.seen.has("--skip-demo")) return "--demo cannot be combined with --skip-demo";
+    return void 0;
+  }
   if (cmd === "verify") {
     return validateFlatArgs(args, {
       flags: ["--json", "--keep", "--require-ancestor"],
@@ -13704,6 +14254,21 @@ Formats:
                                             2 when it cannot adjudicate (fails closed)
   tamperward allow <rule> --reason "..."    record a human sign-off (local audit ledger)
              [--file F] [--cwd D]
+  tamperward onboard [--yes] [--cwd D]      guided first-run setup: preflight, the
+             [--base R] [--repo O/R]        init plan with a confirmation before any
+             [--branch B] [--verify-command C] write, canonical init, explicit verifier
+             [--skip-demo | --demo]         acceptance (a detected suite command is
+             [--no-github]                  never written without it), the first
+                                            verify explained, an optional demo on a
+                                            disposable worktree, GitHub authority via
+                                            doctor --github or the manual controls,
+                                            and a READY / READY WITH WARNINGS /
+                                            BROKEN / INCOMPLETE posture from doctor.
+                                            Non-interactive stdin refuses unless
+                                            --yes scripts it (then --verify-command
+                                            is the only way to configure verify).
+                                            Exit: 0 READY[ WITH WARNINGS], 1
+                                            BROKEN/INCOMPLETE, 2 refused or aborted
   tamperward init [--dry-run]               wire the policy file plus every
              [--force-workflow] [--cwd D]   enforcement point: Claude Code hooks,
                                             pre-commit, CI. Idempotent; never
@@ -13757,6 +14322,8 @@ function main(argv2) {
       return runInit(parseInit(rest));
     case "doctor":
       return runDoctor(parseDoctor(rest));
+    case "onboard":
+      return runOnboard(parseOnboard(rest));
     case "watch":
       return runWatch(rest);
     case "verify":
@@ -13783,17 +14350,25 @@ function main(argv2) {
   }
 }
 function guardedMain(argv2, stderr = process.stderr) {
-  try {
-    return main(argv2);
-  } catch (e) {
+  const failClosed2 = (e) => {
     const first = (e instanceof Error ? e.message : String(e)).split("\n").map((l) => l.trim()).find(Boolean) ?? "";
     stderr.write(`tamperward: ${first || "unexpected failure"}
 `);
     return 2;
+  };
+  try {
+    const result = main(argv2);
+    return typeof result === "number" ? result : result.catch(failClosed2);
+  } catch (e) {
+    return failClosed2(e);
   }
 }
 
 // src/cli/index.ts
 var argv = process.argv.slice(2);
+var exit = (code2) => {
+  if (code2 >= 0) process.exit(code2);
+};
 var code = guardedMain(argv);
-if (code >= 0) process.exit(code);
+if (typeof code === "number") exit(code);
+else void code.then(exit);

package/package.json

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