tamperward 2.12.0 → 2.13.1

package/README.md

@@ -254,13 +254,26 @@ 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.
 It never overwrites anything you wrote; `--dry-run` prints the plan.
 
-**`init` is not sufficient on its own, and it will tell you so.** In your
-branch-protection or ruleset settings you must require the check *and* enable
-"Require review from Code Owners". A `pull_request` workflow runs from the pull
-request's own head and a required check is matched by job name, so without that
-a PR can keep the job name, replace the gate with `true`, and present a green
-required check over a change the gate would have blocked. That is reproduced on
-this project's own CI, not a theoretical concern.
+**`init` is not sufficient on its own, and it will tell you so.** The protected
+branch needs all three repository-authority controls:
+
+1. require the **`tamperward`** status check;
+2. enable **Require review from Code Owners**; and
+3. enable **Dismiss stale pull request approvals when new commits are pushed**.
+
+The third control is load-bearing: an approval for an older gate-critical diff must
+not authorize a later push. GitHub's "require approval of the most recent reviewable
+push" can be useful in addition, but it is not equivalent here because that fresh
+approver is not necessarily the Code Owner for the gate path. A `pull_request`
+workflow runs from the pull request's own head and a required check is matched by job
+name, so without this human boundary a PR can keep the job name, replace the gate with
+`true`, and present a green required check over a change the gate would have blocked.
+That is reproduced on this project's own CI, not a theoretical concern.
+
+After configuring GitHub, verify the boundary with
+`tamperward doctor --github --repo OWNER/REPO --branch <default-branch>`.
+Public rulesets can be read anonymously; set `GH_TOKEN` or `GITHUB_TOKEN` when
+authentication is required.
 
 A real deployment needs a verify command configured — the generated CI verify step
 **fails closed (exit 2) without one** rather than passing quietly. In
@@ -323,9 +336,13 @@ from trusted CI, or after an externally isolated agent hands off the frozen cand
 
 ### CLI reference
 
-Every flag below is what the command's parser actually reads (`src/cli/index.ts`,
-`parseVerify`, `parseRun`). `check` reports an unknown flag on stderr; the other
-commands ignore what they do not know.
+Every flag below is what the command's parser actually reads (`src/cli/main.ts`,
+`parseVerify`, `parseRun`). Since **2.13.1**, user-supplied argv is validated before
+any command-specific parser or side effect runs: unknown options, missing values,
+invalid numeric budgets/timeouts, duplicate/conflicting `check` views, and unexpected
+positionals fail closed with exit 2 and one deterministic `tamperward: ...` diagnostic.
+`run` requires an explicit `--` before the wrapped command, so a typoed TamperWard
+option can never be reinterpreted as the agent command.
 
 | command | flags |
 | --- | --- |

package/dist/cli/index.js

@@ -308,8 +308,8 @@ function inspectOnce(abs2) {
   try {
     st = lstatSync(abs2);
   } catch (e) {
-    const code = errCode(e);
-    if (code === "ENOENT" || code === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
+    const code2 = errCode(e);
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
     return { kind: "unreadable", content: null, ...NO_META, detail: errText(e) };
   }
   if (st.isSymbolicLink() || !st.isFile()) return classify(abs2, st);
@@ -320,8 +320,8 @@ function inspectPath(abs2) {
   try {
     st = lstatSync(abs2);
   } catch (e) {
-    const code = errCode(e);
-    if (code === "ENOENT" || code === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
+    const code2 = errCode(e);
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
     return { kind: "unreadable", content: null, ...NO_META, detail: errText(e) };
   }
   return classify(abs2, st);
@@ -334,8 +334,8 @@ function inspectResolved(abs2) {
   try {
     real = realpathSync(abs2);
   } catch (e) {
-    const code = errCode(e);
-    if (code === "ENOENT" || code === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
+    const code2 = errCode(e);
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") return { kind: "absent", content: null, ...NO_META, detail: "" };
     return { kind: "unreadable", content: null, ...NO_META, detail: errText(e) };
   }
   return inspectPath(real);
@@ -2669,8 +2669,8 @@ var CODE_PROBES = ["src/index.ts", "src/index.js", "lib/index.js", "index.ts", "
 function sourceProbes(ctx) {
   const files = trackedFiles(ctx);
   if (!files) return CODE_PROBES;
-  const code = files.filter((f) => langOf(f) !== null);
-  return code.length ? code : CODE_PROBES;
+  const code2 = files.filter((f) => langOf(f) !== null);
+  return code2.length ? code2 : CODE_PROBES;
 }
 function triggerNarrowings(before, after, opts) {
   const out2 = [];
@@ -6535,8 +6535,8 @@ function terminalWidth(stream = process.stdout) {
   if (!c || c < 40) return 80;
   return Math.min(c, 100);
 }
-function paint(s, code, on) {
-  return on ? code + s + RESET : s;
+function paint(s, code2, on) {
+  return on ? code2 + s + RESET : s;
 }
 function wrap(text, width) {
   const out2 = [];
@@ -8221,12 +8221,13 @@ tamperward init: ${changed} change(s) applied. Commit them so the gate travels w
 `
   );
   w.write(
-    '\nONE STEP LEFT, AND IT IS NOT OPTIONAL. In your branch-protection or ruleset\nsettings for the default branch, require the tamperward check AND enable\n"Require review from Code Owners".\n\nUntil you do, the CI gate is advisory. A pull request runs the workflow from\nits OWN head, and a required check is matched by job name \u2014 so a pull request\ncan keep the job called `tamperward`, replace the gate with `true`, and present\na green required check over a change the gate would have blocked. That is\nreproduced, not theoretical. CODEOWNERS is what puts a human in front of it;\nbranch protection is what makes CODEOWNERS bind.\n'
+    '\nONE STEP LEFT, AND IT IS NOT OPTIONAL. In your branch-protection or ruleset\nsettings for the default branch, configure ALL THREE repository-authority controls:\n  1. require the tamperward check;\n  2. enable "Require review from Code Owners"; and\n  3. enable "Dismiss stale pull request approvals when new commits are pushed".\n\nThe freshness control is part of the security boundary: an approval for an older\ngate-critical diff must not authorize a later push. "Require approval of the most\nrecent reviewable push" can be useful in addition, but is not a substitute here\nbecause the fresh approver is not necessarily the Code Owner for the gate path.\n\nUntil all three are enforced, the CI gate is advisory. A pull request runs the\nworkflow from its OWN head, and a required check is matched by job name \u2014 so a\npull request can keep the job called `tamperward`, replace the gate with `true`,\nand present a green required check over a change the gate would have blocked.\nCODEOWNERS puts a human in front of gate-critical paths; branch protection or an\nactive ruleset makes that review fresh and binding. Verify with: tamperward doctor\n--github --repo OWNER/REPO --branch <default-branch>.\n'
   );
   return 0;
 }
 
 // src/cli/doctor.ts
+import { execFileSync as execFileSync7 } from "node:child_process";
 import { existsSync as existsSync10, readFileSync as readFileSync13, readdirSync as readdirSync3 } from "node:fs";
 import { join as join13, resolve as resolve4 } from "node:path";
 import { parse as parse3 } from "yaml";
@@ -8244,6 +8245,166 @@ function policyFor(opts, cwd) {
 function asMapping(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 }
+function evaluateGitHubProtection(snapshot2, requiredCheck = "tamperward") {
+  let hasRequiredCheck = false;
+  let hasCodeOwnerReview = false;
+  let dismissesStaleReviews = false;
+  if (Array.isArray(snapshot2.rules)) {
+    for (const raw of snapshot2.rules) {
+      const rule = asMapping(raw);
+      const params = asMapping(rule?.parameters);
+      if (!rule || !params) continue;
+      if (rule.type === "pull_request") {
+        if (params.require_code_owner_review === true) hasCodeOwnerReview = true;
+        if (params.dismiss_stale_reviews_on_push === true) dismissesStaleReviews = true;
+      }
+      if (rule.type === "required_status_checks") {
+        const checks = params.required_status_checks;
+        if (Array.isArray(checks)) {
+          hasRequiredCheck ||= checks.some((rawCheck) => {
+            const check2 = asMapping(rawCheck);
+            return check2?.context === requiredCheck;
+          });
+        }
+      }
+    }
+  }
+  const classic = asMapping(snapshot2.branchProtection);
+  const reviews = asMapping(classic?.required_pull_request_reviews);
+  if (reviews?.require_code_owner_reviews === true) hasCodeOwnerReview = true;
+  if (reviews?.dismiss_stale_reviews === true) dismissesStaleReviews = true;
+  const status = asMapping(classic?.required_status_checks);
+  if (status) {
+    const contexts = status.contexts;
+    if (Array.isArray(contexts)) {
+      hasRequiredCheck ||= contexts.some((x) => x === requiredCheck);
+    }
+    const checks = status.checks;
+    if (Array.isArray(checks)) {
+      hasRequiredCheck ||= checks.some((rawCheck) => {
+        const check2 = asMapping(rawCheck);
+        return check2?.context === requiredCheck;
+      });
+    }
+  }
+  const findings = [];
+  if (!hasRequiredCheck) findings.push("require the tamperward status check");
+  if (!hasCodeOwnerReview) findings.push("require Code Owner review");
+  if (!dismissesStaleReviews) findings.push("dismiss stale pull request approvals on new pushes");
+  return findings;
+}
+function gitText(cwd, args) {
+  try {
+    return execFileSync7("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function githubRepoFromRemote(remote) {
+  const m = remote.match(/github\.com(?::|\/)([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i);
+  return m ? m[1] + "/" + m[2].replace(/\.git$/i, "") : null;
+}
+function inferGitHubRepo(cwd) {
+  const envRepo = process.env.GITHUB_REPOSITORY;
+  if (envRepo && /^[^/\s]+\/[^/\s]+$/.test(envRepo)) return envRepo;
+  const remote = gitText(cwd, ["config", "--get", "remote.origin.url"]);
+  return remote ? githubRepoFromRemote(remote) : null;
+}
+var GITHUB_API_SCRIPT = [
+  "const endpoint = process.argv[1];",
+  "const token = process.env.TAMPERWARD_GITHUB_TOKEN || '';",
+  "const headers = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2026-03-10', 'User-Agent': 'tamperward-doctor' };",
+  "if (token) headers.Authorization = 'Bearer ' + token;",
+  "fetch('https://api.github.com/' + endpoint, { headers }).then(async (r) => {",
+  "  const body = await r.text();",
+  "  if (!r.ok) { process.stderr.write('HTTP ' + r.status + ': ' + body); process.exit(22); }",
+  "  process.stdout.write(body);",
+  "}).catch((e) => { process.stderr.write(String(e)); process.exit(23); });"
+].join("\n");
+function githubApiInvocation(endpoint, token) {
+  return {
+    executable: process.execPath,
+    args: ["-e", GITHUB_API_SCRIPT, endpoint],
+    env: {
+      TAMPERWARD_GITHUB_TOKEN: token,
+      LANG: "C",
+      LC_ALL: "C"
+    }
+  };
+}
+function githubApi(cwd, endpoint) {
+  const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN ?? "";
+  const invocation = githubApiInvocation(endpoint, token);
+  try {
+    const stdout = execFileSync7(
+      invocation.executable,
+      invocation.args,
+      {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: invocation.env,
+        timeout: 15e3
+      }
+    );
+    return JSON.parse(stdout);
+  } catch (e) {
+    const x = e;
+    const detail = x.stderr ? String(x.stderr).replace(/\s+/g, " ").trim() : x.message;
+    throw new Error(
+      "GitHub API " + endpoint + " failed: " + (detail || "unknown error")
+    );
+  }
+}
+function githubAuthority(opts, cwd) {
+  const repo = opts.repo ?? inferGitHubRepo(cwd);
+  if (!repo || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+    throw new Error(
+      "cannot determine GitHub repository; pass --repo OWNER/REPO or configure a github.com origin"
+    );
+  }
+  let branch = opts.branch ?? process.env.GITHUB_BASE_REF ?? "";
+  if (!branch) {
+    const meta2 = asMapping(githubApi(cwd, "repos/" + repo));
+    if (typeof meta2?.default_branch === "string") branch = meta2.default_branch;
+  }
+  if (!branch) throw new Error("cannot determine protected branch; pass --branch BRANCH");
+  let rules;
+  let rulesError = null;
+  try {
+    rules = githubApi(cwd, "repos/" + repo + "/rules/branches/" + encodeURIComponent(branch));
+  } catch (e) {
+    rulesError = e instanceof Error ? e : new Error(String(e));
+  }
+  let findings = evaluateGitHubProtection({ rules });
+  if (findings.length === 0) return { repo, branch, findings };
+  let branchProtection;
+  let classicError = null;
+  try {
+    branchProtection = githubApi(
+      cwd,
+      "repos/" + repo + "/branches/" + encodeURIComponent(branch) + "/protection"
+    );
+  } catch (e) {
+    classicError = e instanceof Error ? e : new Error(String(e));
+  }
+  findings = evaluateGitHubProtection({ rules, branchProtection });
+  if (findings.length > 0 && rules === void 0 && branchProtection === void 0) {
+    throw new Error(
+      "cannot inspect GitHub repository authority. Rules API: " + (rulesError?.message ?? "unavailable") + ". Classic branch protection API: " + (classicError?.message ?? "unavailable") + ". Authenticate gh with metadata read; classic-protection fallback may also need Administration read."
+    );
+  }
+  if (findings.length > 0 && branchProtection === void 0 && classicError) {
+    findings.push(
+      "classic branch protection could not be inspected; if it supplies a missing requirement, use GH_TOKEN/GITHUB_TOKEN with Administration read"
+    );
+  }
+  return { repo, branch, findings };
+}
 function verifyJobs(doc) {
   const root = asMapping(doc);
   const jobs = asMapping(root?.jobs);
@@ -8346,25 +8507,43 @@ function runDoctor(opts = {}) {
     const scope = opts.workflow ?? ".github/workflows/*.yml|*.yaml";
     return err(`${scope}: no job contains a tamperward verify step`);
   }
+  let github = null;
+  if (opts.github) {
+    try {
+      github = githubAuthority(opts, cwd);
+    } catch (e) {
+      return err(e instanceof Error ? e.message : String(e));
+    }
+    if (github.findings.length > 0) {
+      return err(
+        "GitHub repository authority for " + github.repo + "#" + github.branch + " is incomplete: " + github.findings.join("; ")
+      );
+    }
+  }
   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.
 `
   );
+  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 0;
 }
 
 // src/cli/verify.ts
-import { execFileSync as execFileSync8, spawnSync as spawnSync2 } from "node:child_process";
+import { execFileSync as execFileSync9, spawnSync as spawnSync2 } from "node:child_process";
 import { createHash as createHash10 } from "node:crypto";
 import { chmodSync as chmodSync2, cpSync, lstatSync as lstatSync4, mkdirSync as mkdirSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readlinkSync as readlinkSync3, rmSync as rmSync3, symlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { dirname as dirname7, isAbsolute as isAbsolute10, join as join16, relative as relative5, resolve as resolve7, sep as sep2 } from "node:path";
 
 // src/fingerprint.ts
-import { execFileSync as execFileSync7 } from "node:child_process";
+import { execFileSync as execFileSync8 } from "node:child_process";
 import { createHash as createHash7 } from "node:crypto";
 function treeFingerprint(cwd, keepIgnored) {
-  const listed = execFileSync7("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+  const listed = execFileSync8("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
     cwd,
     encoding: "utf8",
     maxBuffer: 1 << 28,
@@ -9138,8 +9317,8 @@ function runContainerStage(backend, dir, command, budgetSecs) {
     const secs = Math.round((Date.now() - t0) / 1e3);
     if (r.error) {
       cleanupContainer(backend, name);
-      const code = r.error.code;
-      return code === "ETIMEDOUT" ? { exit: null, secs, failure: "budget", reason: "verifier stage exceeded its budget" } : { exit: null, secs, failure: "backend", reason: `Docker client failed: ${r.error.message}` };
+      const code2 = r.error.code;
+      return code2 === "ETIMEDOUT" ? { exit: null, secs, failure: "budget", reason: "verifier stage exceeded its budget" } : { exit: null, secs, failure: "backend", reason: `Docker client failed: ${r.error.message}` };
     }
     if (r.status === null) {
       cleanupContainer(backend, name);
@@ -9271,7 +9450,7 @@ var VERIFICATION_SURFACE = [
   "**/*.runsettings"
 ];
 function git2(args, cwd) {
-  return execFileSync8("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
+  return execFileSync9("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
 }
 function resolveBase(base, cwd) {
   assertRev(base);
@@ -9467,7 +9646,7 @@ function overlayPristine(cwd, base, dest, policy, cmd, dependencyRoot) {
     if (e.type === "commit") {
       throw new Error(`the base's ${e.path} is a submodule; the pristine copy cannot reproduce it`);
     }
-    const content = execFileSync8("git", ["show", `${base}:${e.path}`], { cwd, maxBuffer: 1 << 28, env: trustedGitEnv() });
+    const content = execFileSync9("git", ["show", `${base}:${e.path}`], { cwd, maxBuffer: 1 << 28, env: trustedGitEnv() });
     const out2 = join16(dest, e.path);
     mkdirSync6(dirname7(out2), { recursive: true });
     rmSync3(out2, { force: true });
@@ -9763,22 +9942,22 @@ function runVerify(opts) {
     return 2;
   }
   let verdict2;
-  let code;
+  let code2;
   if (visible.exit === null || pristine.exit === null) {
     verdict2 = "BUDGET_EXCEEDED";
-    code = 2;
+    code2 = 2;
   } else if (visible.exit === 0 && pristine.exit === 0) {
     verdict2 = "VERIFIED";
-    code = 0;
+    code2 = 0;
   } else if (visible.exit === 0) {
     verdict2 = "MASKED_FAILURE";
-    code = 1;
+    code2 = 1;
   } else {
     verdict2 = "SUITE_RED";
-    code = 1;
+    code2 = 1;
   }
   const signedOff = verdict2 === "MASKED_FAILURE" ? oobToken("verify", oobFromEnv(), oobHeadFromEnv()) : null;
-  if (signedOff) code = 0;
+  if (signedOff) code2 = 0;
   if (opts.json) {
     out2(
       JSON.stringify({
@@ -9821,7 +10000,7 @@ function runVerify(opts) {
         `(${removedAdded} protected file(s) added since ${base.slice(0, 10)} were removed from the pristine run: the pristine tree carries exactly the base's protected surface.)`
       );
   }
-  return code;
+  return code2;
 }
 function parseVerify(args) {
   const o = {};
@@ -9856,7 +10035,7 @@ function parseVerify(args) {
 }
 
 // src/cli/run.ts
-import { execFileSync as execFileSync9, spawnSync as spawnSync3 } from "node:child_process";
+import { execFileSync as execFileSync10, spawnSync as spawnSync3 } from "node:child_process";
 import { mkdtempSync as mkdtempSync3, readdirSync as readdirSync5, readFileSync as readFileSync17, readlinkSync as readlinkSync4, realpathSync as realpathSync6, rmSync as rmSync4 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join17, resolve as resolve8 } from "node:path";
@@ -10079,7 +10258,7 @@ function runAgentWithBudget(argv2, cwd, budgetSecs) {
   }
 }
 function git3(args, cwd) {
-  return execFileSync9("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
+  return execFileSync10("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 28, env: trustedGitEnv() });
 }
 function nowTicks() {
   try {
@@ -10276,7 +10455,7 @@ tamperward run \u2014 agent exit ${agentExit}; HISTORY_REWRITE \u2192 ENFORCEMEN
   });
   if (opts.settle && opts.settle > 0) {
     try {
-      execFileSync9("sleep", [String(opts.settle)]);
+      execFileSync10("sleep", [String(opts.settle)]);
     } catch {
     }
   }
@@ -10372,6 +10551,9 @@ function parseDoctor(args) {
     if (a === "--cwd") o.cwd = args[++i];
     else if (a === "--base") o.base = args[++i];
     else if (a === "--workflow") o.workflow = args[++i];
+    else if (a === "--github") o.github = true;
+    else if (a === "--repo") o.repo = args[++i];
+    else if (a === "--branch") o.branch = args[++i];
   }
   return o;
 }
@@ -10385,17 +10567,148 @@ function parseCheck(args) {
     else if (a === "--format") {
       const v = args[++i];
       if (v !== void 0 && isFormat(v)) o.format = v;
-      else process.stderr.write(`tamperward: unknown --format "${v ?? ""}" (expected ${FORMATS.join(" | ")})
-`);
     } else if (a === "--diff") o.diff = args[++i];
     else if (a === "--cwd") o.cwd = args[++i];
-    else {
-      process.stderr.write(`tamperward: unknown flag "${a}"
-`);
-    }
   }
   return o;
 }
+function validateFlatArgs(args, grammar) {
+  const flags = new Set(grammar.flags ?? []);
+  const values = grammar.values ?? {};
+  const seen = /* @__PURE__ */ new Set();
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (flags.has(a) || Object.prototype.hasOwnProperty.call(values, a)) {
+      if (seen.has(a)) {
+        return { error: `option "${a}" specified more than once`, seen, positionals };
+      }
+      seen.add(a);
+      const rule = values[a];
+      if (!rule) continue;
+      const v = args[i + 1];
+      if (v === void 0 || v.startsWith("--")) {
+        return {
+          error: `${a} needs a value` + (v === void 0 ? "" : ` (got the flag "${v}")`),
+          seen,
+          positionals
+        };
+      }
+      i++;
+      if (rule === "positive") {
+        const n = Number(v);
+        if (!Number.isFinite(n) || n <= 0) {
+          return { error: `${a} needs a positive number (got "${v}")`, seen, positionals };
+        }
+      } else if (rule === "non-negative") {
+        const n = Number(v);
+        if (!Number.isFinite(n) || n < 0) {
+          return { error: `${a} needs a non-negative number (got "${v}")`, seen, positionals };
+        }
+      } else if (rule === "format" && !isFormat(v)) {
+        return {
+          error: `--format needs one of ${FORMATS.join(" | ")} (got "${v}")`,
+          seen,
+          positionals
+        };
+      }
+      continue;
+    }
+    if (a.startsWith("-")) {
+      return { error: `unknown option "${a}"`, seen, positionals };
+    }
+    if (grammar.positional === "one" && positionals.length === 0) {
+      positionals.push(a);
+      continue;
+    }
+    return { error: `unexpected argument "${a}"`, seen, positionals };
+  }
+  return { seen, positionals };
+}
+function validateCliArgs(cmd, args) {
+  if (cmd === "hook" || cmd === "sweep") {
+    if (args.length === 0) return `${cmd} requires an agent name`;
+    if (args.length > 1) return `unexpected argument "${args[1]}"`;
+    return void 0;
+  }
+  if (cmd === "run") {
+    const delimiter3 = args.indexOf("--");
+    if (delimiter3 < 0) return 'run requires an explicit "--" before the wrapped command';
+    const prefix = args.slice(0, delimiter3);
+    const command = args.slice(delimiter3 + 1);
+    const parsed = validateFlatArgs(prefix, {
+      flags: ["--allow-dirty", "--allow-dep-drift"],
+      values: {
+        "--base": "string",
+        "--cmd": "string",
+        "--budget": "positive",
+        "--agent-budget": "positive",
+        "--settle": "non-negative",
+        "--cwd": "string"
+      }
+    });
+    if (parsed.error) return parsed.error;
+    if (command.length === 0) return 'run requires a wrapped command after "--"';
+    return void 0;
+  }
+  if (cmd === "check") {
+    const parsed = validateFlatArgs(args, {
+      flags: ["--staged", "--worktree", "--json"],
+      values: { "--diff": "string", "--format": "format", "--cwd": "string" }
+    });
+    if (parsed.error) return parsed.error;
+    const views = ["--staged", "--worktree", "--diff"].filter((x) => parsed.seen.has(x));
+    if (views.length > 1) return "choose exactly one of --staged, --worktree, or --diff";
+    if (parsed.seen.has("--json") && parsed.seen.has("--format")) {
+      return "--json cannot be combined with --format";
+    }
+    return void 0;
+  }
+  if (cmd === "allow") {
+    const parsed = validateFlatArgs(args, {
+      values: { "--file": "string", "--reason": "string", "--cwd": "string" },
+      positional: "one"
+    });
+    if (parsed.error) return parsed.error;
+    if (parsed.positionals.length === 0) return "allow requires a rule";
+    return void 0;
+  }
+  if (cmd === "init") {
+    return validateFlatArgs(args, {
+      flags: ["--dry-run", "--force-workflow"],
+      values: { "--cwd": "string" }
+    }).error;
+  }
+  if (cmd === "doctor") {
+    return validateFlatArgs(args, {
+      flags: ["--github"],
+      values: {
+        "--cwd": "string",
+        "--base": "string",
+        "--workflow": "string",
+        "--repo": "string",
+        "--branch": "string"
+      }
+    }).error;
+  }
+  if (cmd === "verify") {
+    return validateFlatArgs(args, {
+      flags: ["--json", "--keep", "--require-ancestor"],
+      values: {
+        "--base": "string",
+        "--cmd": "string",
+        "--cwd": "string",
+        "--budget": "positive"
+      }
+    }).error;
+  }
+  if (cmd === "watch") {
+    return validateFlatArgs(args, {
+      values: { "--dir": "string", "--log": "string" }
+    }).error;
+  }
+  return void 0;
+}
 function printHelp() {
   process.stdout.write(`tamperward \u2014 the deterministic agent-integrity gate
 
@@ -10451,9 +10764,12 @@ Formats:
                                             did not write, or one you have edited.
   tamperward doctor [--base R]              validate the CI verifier's outer-time
              [--workflow F] [--cwd D]       envelope against the trusted policy.
-                                            Generated PR CI passes the base SHA so
-                                            candidate policy edits cannot choose
-                                            their own timing requirement.
+             [--github] [--repo O/R]        --github also validates repository
+             [--branch B]                   authority: required tamperward status,
+                                            Code Owner review, and stale-review
+                                            dismissal after new pushes. Public
+                                            rules can be read anonymously; set
+                                            GH_TOKEN/GITHUB_TOKEN when needed.
 
 Exit codes: 0 clean \xB7 1 a blocking finding (check), MASKED_FAILURE or SUITE_RED
             (verify), any blocking finding or masked failure (run) \xB7 2 cannot
@@ -10467,6 +10783,14 @@ Exit codes: 0 clean \xB7 1 a blocking finding (check), MASKED_FAILURE or SUITE_R
 }
 function main(argv2) {
   const [cmd, ...rest] = argv2;
+  if (cmd !== void 0 && cmd !== "-h" && cmd !== "--help") {
+    const invalid = validateCliArgs(cmd, rest);
+    if (invalid) {
+      process.stderr.write(`tamperward: ${invalid}
+`);
+      return 2;
+    }
+  }
   switch (cmd) {
     case "check":
       return runCheck(parseCheck(rest));
@@ -10480,6 +10804,8 @@ function main(argv2) {
       return runInit(parseInit(rest));
     case "doctor":
       return runDoctor(parseDoctor(rest));
+    case "watch":
+      return runWatch(rest);
     case "verify":
       return runVerify(parseVerify(rest));
     case "run":
@@ -10509,8 +10835,5 @@ function guardedMain(argv2, stderr = process.stderr) {
 
 // src/cli/index.ts
 var argv = process.argv.slice(2);
-if (argv[0] === "watch") {
-  runWatch(argv.slice(1));
-} else {
-  process.exit(guardedMain(argv));
-}
+var code = guardedMain(argv);
+if (code >= 0) process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "2.12.0",
+  "version": "2.13.1",
   "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",