@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/autopilot-publish.mjs

@@ -0,0 +1,1625 @@
+#!/usr/bin/env node
+/**
+ * @file autopilot-publish.mjs  -  the runner's publish step: the one place an
+ * unattended run's work leaves the machine.
+ *
+ * Under MULTI_AGENT_UNATTENDED=1 a run commits and then leaves a PR request
+ * (pr-request.mjs write) instead of pushing; agent-guard blocks every outward
+ * write it could make itself. After the run's session ends the autopilot
+ * runner calls publish(), which treats everything the run wrote - the request,
+ * the state, the gate ledger, the worktree and its git config - as a claim to
+ * check, not an instruction:
+ *
+ *   1. The request, the state and the test log are read as bounded regular
+ *      files (lib/regular-file.mjs): a FIFO, a device or an oversized file is
+ *      refused, never read. The request is read once and validated in process
+ *      (pr-request.mjs validatePrRequest) on those same bytes.
+ *   2. The repository comes from the runner's own config (the queue item's
+ *      `nameWithOwner`), never from the request. A request naming another
+ *      repository is refused, not redirected. The base is the configured
+ *      `baseBranch`, else the remote's default branch, or one listed in
+ *      `allowedBases`; any other base is refused.
+ *   3. The worktree belongs to that repository, sits on the requested branch,
+ *      which is the branch the run recorded in its state, has no uncommitted
+ *      change to a tracked file, and the branch is not protected (main,
+ *      master, develop, release/*, the configured base).
+ *   4. Everything that touches the network runs from a fresh bare staging
+ *      repository with a git config the runner writes (no system config, a
+ *      global config holding only the operator's credential helpers, hooks
+ *      off). The branch is fetched into it from the worktree; the base is
+ *      fetched into it from the resolved remote. The worktree's own config
+ *      never sees a URL, a proxy or a credential.
+ *   5. The branch is strictly ahead of the base. A branch that already exists
+ *      on the remote is refused unless this run pushed it and its tip is an
+ *      ancestor of the run's HEAD.
+ *   6. The deterministic gates: the gate ledger for every commit's parent, the
+ *      test log it names (a missing log is a refusal), the pre-commit-check.sh
+ *      detectors over each of the branch's commits, and the outbound gate on the title
+ *      and body. The ledger is written by the run and so is only a consistency
+ *      check; the evidence is step 7.
+ *   7. Independent verification: the stack adapter's build and test commands,
+ *      resolved from the base commit's manifests (a range that changes the
+ *      commands, the package scripts they run or the package manager is
+ *      refused), run here in the worktree with every token-shaped variable
+ *      removed from the environment and a bounded timeout, then
+ *      evidence-gate.mjs --stack and test-summary.mjs on that fresh output. A
+ *      failure, zero tests, or a stack with no commands (unless
+ *      `verify.allowUnverifiedStack`) refuses. The operator's credential
+ *      settings are snapshotted before this step and the push uses the
+ *      snapshot; a user git config that changed while it ran refuses.
+ *
+ *      This step executes code the run wrote, as the runner's user. Removing
+ *      variables keeps tokens out of its environment, not out of its reach:
+ *      it can read Keychain items the user's own tools read without a prompt,
+ *      run `gh auth token`, and read the user's files. Only running the runner
+ *      as a separate, non-admin macOS user that holds nothing else bounds that
+ *      (multi-agent-refs/features/unattended-security.md).
+ *   8. Push from the staging repository with a URL resolved from the config
+ *      (`pushUrl`) or `gh repo view`: no force, explicit refspec
+ *      HEAD:refs/heads/<branch>.
+ *   9. GitHub: `gh pr create --draft` with the body in a file. Bitbucket has no
+ *      draft PR, so the branch is pushed, a summary is written beside the
+ *      request, and the outcome is `pushed-awaiting-pr`. Any other host is
+ *      refused.
+ *
+ * Every spawn that writes outward runs with MULTI_AGENT_UNATTENDED and
+ * MULTI_AGENT_SESSION_ID removed from its environment: the runner is not the
+ * agent, and these are processes it starts, not tool calls a hook inspects.
+ * GIT_TERMINAL_PROMPT=0 makes a missing credential a failure instead of a
+ * prompt nobody answers.
+ *
+ * A refusal at any step writes nothing outward, parks the run through
+ * gate-ledger.mjs park (`verificationFailed.gate` = `publish/<gate>`) and
+ * records the verdict at prVerdictPath (mode 0600). Findings name a rule and a
+ * file, never a matched value.
+ *
+ * Usage (a person re-running a parked publish after fixing its cause):
+ *   autopilot-publish.mjs --session <uuid> --state <agent-state.json> --repo <owner/name>
+ *
+ * Output: the verdict as JSON on stdout. Exit: 0 published, 1 refused or
+ * failed, 2 usage, 3 nothing to publish.
+ *
+ * @module pipeline/scripts/autopilot-publish
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { scan } from "../lib/outbound-gate.mjs";
+import { prRequestPath, prRequestsDir, prVerdictPath } from "../lib/pr-request-location.mjs";
+import { readRegularFile, readRegularJson } from "../lib/regular-file.mjs";
+import { OUTCOME } from "./_autopilot-outcomes.mjs";
+import { commandFor, getAdapter, loadAdapters, resolveStack } from "./_stack-adapter.mjs";
+import { checkCommit, park, updateState } from "./gate-ledger.mjs";
+import { LOCKFILES } from "./package-manager.mjs";
+import { PROTECTED_BRANCHES, validatePrRequest } from "./pr-request.mjs";
+import { summarize } from "./test-summary.mjs";
+
+const HERE = import.meta.dirname;
+const PRE_COMMIT = join(HERE, "pre-commit-check.sh");
+const EVIDENCE_GATE = join(HERE, "evidence-gate.mjs");
+const PHASE_COMMIT = 4;
+const GIT_TIMEOUT_MS = 60 * 1000;
+const NET_TIMEOUT_MS = 5 * 60 * 1000;
+// A valid request is at most a 256-character title and a 65536-character body.
+const REQUEST_MAX_BYTES = 1024 * 1024;
+const STATE_MAX_BYTES = 16 * 1024 * 1024;
+const LOG_MAX_BYTES = 64 * 1024 * 1024;
+const VERIFY_TIMEOUT_SEC = 30 * 60;
+export const SUMMARY_SUFFIX = ".summary.md";
+export const HOSTS = ["github", "bitbucket"];
+
+/** The environment of every outward spawn: not the agent's, never prompting. */
+export function outwardEnv(env = process.env) {
+  const out = { ...env, GIT_TERMINAL_PROMPT: "0" };
+  for (const k of [
+    "MULTI_AGENT_UNATTENDED",
+    "MULTI_AGENT_SESSION_ID",
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_INDEX_FILE",
+    "GIT_CONFIG_PARAMETERS",
+    "GIT_CONFIG_COUNT",
+  ]) {
+    delete out[k];
+  }
+  return out;
+}
+
+const SECRET_NAME = /(?:^|_)(?:TOKEN|KEY|SECRET|PASSWORD|PASSWD|CREDENTIALS?)$/i;
+const SECRET_NAMES = new Set([
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "SSH_AUTH_SOCK",
+  "GIT_ASKPASS",
+  "SSH_ASKPASS",
+]);
+
+/**
+ * The environment the run's own build and tests execute in: no token-shaped
+ * variable, no ssh agent socket and no askpass helper. This narrows what the
+ * process is handed; it does not take away what the runner's user can reach.
+ * The code still runs as that user, so a Keychain item readable without a
+ * prompt, `gh auth token` and every file the user can read stay available to
+ * it. A separate macOS user for the runner is what bounds that.
+ */
+export function verifyEnv(env = process.env) {
+  const out = outwardEnv(env);
+  for (const k of Object.keys(out)) {
+    if (SECRET_NAMES.has(k) || SECRET_NAME.test(k)) delete out[k];
+  }
+  return out;
+}
+
+/**
+ * May the run's work land on this branch? Never a long-lived branch, and never
+ * a base the config names for the repository (`baseBranch`, `allowedBases`).
+ *
+ * @param {string} branch
+ * @param {{baseBranch?: string, allowedBases?: string[]}} repoCfg
+ */
+export function protectedBranch(branch, repoCfg = {}) {
+  if (PROTECTED_BRANCHES.includes(branch)) return true;
+  if (branch === "release" || branch.startsWith("release/")) return true;
+  if (Array.isArray(repoCfg.allowedBases) && repoCfg.allowedBases.includes(branch)) return true;
+  return Boolean(repoCfg.baseBranch) && branch === repoCfg.baseBranch;
+}
+
+function realOr(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function git(wt, args, env, timeout = GIT_TIMEOUT_MS) {
+  return spawnSync("git", ["-C", wt, ...args], {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout,
+  });
+}
+
+function gitOut(wt, args, env) {
+  const r = git(wt, args, env);
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+function writePrivate(path, text) {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, text, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+}
+
+class Refusal extends Error {
+  constructor(gate, reason, extra = {}) {
+    super(reason);
+    this.gate = gate;
+    this.extra = extra;
+  }
+}
+
+/** First line of a process's stderr, bounded, for a verdict a person reads. */
+function why(r) {
+  const text = `${r.stderr || ""}${r.error ? ` ${r.error.message}` : ""}`.trim();
+  return text.split("\n").filter(Boolean).slice(-3).join(" | ").slice(0, 400) || `exit ${r.status}`;
+}
+
+/**
+ * The staging repository's global git config: the operator's credential
+ * settings (`credential.*` from the system and global scopes, read outside
+ * any repository), and nothing else. No URL rewrite, proxy, TLS switch, extra
+ * header, ssh command or include reaches the push, from the worktree or from
+ * anywhere else.
+ *
+ * @returns {string} gitconfig text
+ */
+export function credentialConfig(env = process.env) {
+  const base = outwardEnv(env);
+  const cwd = tmpdir();
+  const r = spawnSync(
+    "git",
+    ["config", "--null", "--show-scope", "--get-regexp", "^credential\\."],
+    {
+      cwd,
+      encoding: "utf8",
+      env: base,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: GIT_TIMEOUT_MS,
+    },
+  );
+  const dir = mkdtempSync(join(tmpdir(), "ap-cred-"));
+  const file = join(dir, "gitconfig");
+  try {
+    writeFileSync(file, "", { mode: 0o600 });
+    const fields = r.status === 0 ? r.stdout.split("\0") : [];
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+      const scope = fields[i];
+      const rec = fields[i + 1];
+      if (!["system", "global", "unknown"].includes(scope)) continue;
+      const nl = rec.indexOf("\n");
+      const key = nl === -1 ? rec : rec.slice(0, nl);
+      const value = nl === -1 ? "" : rec.slice(nl + 1);
+      if (!/^credential\./i.test(key)) continue;
+      spawnSync("git", ["config", "--file", file, "--add", key, value], {
+        cwd,
+        env: base,
+        stdio: "ignore",
+        timeout: GIT_TIMEOUT_MS,
+      });
+    }
+    return readRegularFile(file);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The user-level git config files a credential helper can be named in, by
+ * path, with a digest of each (absent is recorded as absent). Compared before
+ * and after the run's build and tests: a change means code the run shipped
+ * edited the operator's git config, and nothing is pushed with it.
+ *
+ * @returns {Record<string, string>}
+ */
+export function gitConfigFingerprint(env = process.env) {
+  const home = env.HOME || "";
+  const xdg = env.XDG_CONFIG_HOME ? env.XDG_CONFIG_HOME : join(home, ".config");
+  const paths = new Set([join(home, ".gitconfig"), join(xdg, "git", "config")]);
+  if (env.GIT_CONFIG_GLOBAL) paths.add(env.GIT_CONFIG_GLOBAL);
+  const out = {};
+  for (const p of paths) {
+    let digest;
+    try {
+      digest = `${realOr(p)}:${createHash("sha256")
+        .update(readRegularFile(p, { maxBytes: STATE_MAX_BYTES }))
+        .digest("hex")}`;
+    } catch (err) {
+      digest = err?.code === "missing" ? "absent" : `unreadable:${err?.code || "error"}`;
+    }
+    out[p] = digest;
+  }
+  return out;
+}
+
+const HOST_WALK_MAX = 20000;
+
+/**
+ * A digest per file of what the next run executes or is configured by: the
+ * installed pipeline (~/.claude/scripts, ~/.claude/lib), the Claude Code
+ * settings, the unattended profile, and the per-user launch agents. Taken
+ * before and after the run's build and tests; any difference is a refusal.
+ *
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {Record<string,string>}
+ */
+export function hostFingerprint(env = process.env) {
+  const home = env.HOME || "";
+  const out = {};
+  const digest = (p) => {
+    try {
+      const st = lstatSync(p);
+      if (st.isSymbolicLink()) return `link:${readlinkSync(p)}`;
+      if (!st.isFile()) return `type:${st.mode & 0o170000}`;
+      return createHash("sha256")
+        .update(readFileSync(p))
+        .update(`:${st.mode & 0o7777}`)
+        .digest("hex");
+    } catch (err) {
+      return err?.code === "ENOENT" ? "absent" : `unreadable:${err?.code || "error"}`;
+    }
+  };
+  let seen = 0;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      out[dir] = err?.code === "ENOENT" ? "absent" : `unreadable:${err?.code || "error"}`;
+      return;
+    }
+    out[dir] = `dir:${entries
+      .map((e) => e.name)
+      .sort()
+      .join("/")}`;
+    for (const e of entries) {
+      if (++seen > HOST_WALK_MAX) {
+        out[`${dir}/...`] = "too-many-entries";
+        return;
+      }
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else out[p] = digest(p);
+    }
+  };
+  const claude = join(home, ".claude");
+  for (const d of [
+    join(claude, "scripts"),
+    join(claude, "lib"),
+    join(home, "Library", "LaunchAgents"),
+  ])
+    walk(d);
+  for (const f of ["settings.json", "settings.local.json", "multi-agent-unattended.settings.json"])
+    out[join(claude, f)] = digest(join(claude, f));
+  return out;
+}
+
+/**
+ * A fresh bare repository to push from, with a config the runner wrote. Every
+ * git process in it runs with GIT_CONFIG_NOSYSTEM, GIT_CONFIG_GLOBAL pointing
+ * at the credential config snapshot (credentialConfig()), hooks off and no
+ * terminal prompt.
+ */
+function stagingRepo(env, credText = credentialConfig(env)) {
+  const dir = mkdtempSync(join(tmpdir(), "ap-stage-"));
+  chmodSync(dir, 0o700);
+  const cfg = join(dir, "gitconfig");
+  writeFileSync(cfg, credText, { mode: 0o600 });
+  const bare = join(dir, "stage.git");
+  const stageEnv = {
+    ...outwardEnv(env),
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_GLOBAL: cfg,
+    GIT_TERMINAL_PROMPT: "0",
+  };
+  const r = spawnSync("git", ["init", "--bare", "--quiet", "--template=", bare], {
+    cwd: dir,
+    encoding: "utf8",
+    env: stageEnv,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: GIT_TIMEOUT_MS,
+  });
+  const cleanup = () => rmSync(dir, { recursive: true, force: true });
+  if (r.status !== 0) {
+    cleanup();
+    throw new Refusal("push", `cannot create the staging repository: ${why(r)}`);
+  }
+  const run = (args, timeout = GIT_TIMEOUT_MS) =>
+    git(bare, ["-c", "core.hooksPath=/dev/null", ...args], stageEnv, timeout);
+  const out = (args) => {
+    const x = run(args);
+    return x.status === 0 ? x.stdout.trim() : null;
+  };
+  return { bare, run, out, cleanup };
+}
+
+/**
+ * The worktree is still on `branch` at `headSha` with no change to a tracked
+ * file: the tree that is verified is the tree that is pushed.
+ */
+function assertUnmoved(wt, branch, headSha, env, gate) {
+  const at = gitOut(wt, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}^{commit}`], env);
+  const head = gitOut(wt, ["rev-parse", "--verify", "HEAD^{commit}"], env);
+  if (at !== headSha || head !== headSha) {
+    throw new Refusal(gate, `${branch} is no longer at ${headSha.slice(0, 12)} in the worktree`);
+  }
+  const dirty = git(
+    wt,
+    ["-c", "core.fsmonitor=false", "status", "--porcelain", "--untracked-files=no"],
+    env,
+  );
+  if (dirty.status !== 0 || dirty.stdout.trim()) {
+    throw new Refusal(
+      gate,
+      "the worktree has uncommitted changes to tracked files; the tree verified would not be the tree pushed",
+    );
+  }
+}
+
+/** The host a configured repository publishes to. */
+export function resolveHost(repoCfg) {
+  const host = repoCfg.host ?? "github";
+  return HOSTS.includes(host) ? host : null;
+}
+
+function resolvePushUrl(repo, repoCfg, host, env) {
+  if (typeof repoCfg.pushUrl === "string" && repoCfg.pushUrl.trim()) {
+    const url = repoCfg.pushUrl.trim();
+    if (outboundFindings({ pushUrl: url }).length) {
+      throw new Refusal(
+        "remote",
+        "pushUrl carries credentials; the credential helper supplies them",
+      );
+    }
+    return url;
+  }
+  if (host !== "github") {
+    throw new Refusal("remote", `${host} needs pushUrl in the runner's config for ${repo}`);
+  }
+  const r = spawnSync(
+    env.MA_AP_GH_BIN || "gh",
+    ["repo", "view", repo, "--json", "url", "--jq", ".url"],
+    {
+      encoding: "utf8",
+      env: outwardEnv(env),
+      cwd: tmpdir(),
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: NET_TIMEOUT_MS,
+    },
+  );
+  const url = r.status === 0 ? r.stdout.trim().split("\n").pop() : "";
+  if (!url) throw new Refusal("remote", `gh repo view ${repo} gave no URL: ${why(r)}`);
+  return url;
+}
+
+/**
+ * The branch, copied from the worktree into the staging repository. The fetch
+ * runs in the staging repository, so only its config decides where it reads
+ * from; the worktree is the local path it names.
+ */
+function stageBranch(stage, wt, branch, headSha) {
+  const r = stage.run([
+    "fetch",
+    "--no-tags",
+    "--quiet",
+    wt,
+    `+refs/heads/${branch}:refs/heads/${branch}`,
+  ]);
+  if (r.status !== 0) throw new Refusal("branch", `cannot stage ${branch}: ${why(r)}`);
+  const staged = stage.out(["rev-parse", "--verify", `refs/heads/${branch}^{commit}`]);
+  if (staged !== headSha) {
+    throw new Refusal("branch", `${branch} moved while it was staged`);
+  }
+}
+
+/** The branch the remote's HEAD names, or null when it names none. */
+function remoteDefaultBranch(stage, url) {
+  const r = stage.run(["ls-remote", "--symref", url, "HEAD"], NET_TIMEOUT_MS);
+  if (r.status !== 0) throw new Refusal("base", `cannot read the remote's HEAD: ${why(r)}`);
+  const lines = r.stdout.split("\n");
+  const sym = lines.map((l) => /^ref: refs\/heads\/(\S+)\tHEAD$/.exec(l)?.[1]).find(Boolean);
+  if (!sym) return null;
+  return lines.some((l) => l.endsWith("\tHEAD") && !l.startsWith("ref: ")) ? sym : null;
+}
+
+/**
+ * The base a request may target: the configured `baseBranch`, else the
+ * remote's default branch, plus any branch the config lists in
+ * `allowedBases`. Anything else is refused, so a run cannot aim its PR at a
+ * release or deployment branch the operator did not choose.
+ */
+function checkBase(stage, url, base, repoCfg) {
+  const allowed = Array.isArray(repoCfg.allowedBases)
+    ? repoCfg.allowedBases.filter((b) => typeof b === "string" && b)
+    : [];
+  if (allowed.includes(base)) return;
+  if (repoCfg.baseBranch) {
+    if (base === repoCfg.baseBranch) return;
+    throw new Refusal(
+      "base",
+      `the request targets ${base}; the config's base is ${repoCfg.baseBranch}`,
+    );
+  }
+  const def = remoteDefaultBranch(stage, url);
+  if (!def) {
+    throw new Refusal(
+      "base",
+      "no baseBranch is configured and the remote names no default branch; set baseBranch",
+    );
+  }
+  if (base !== def) {
+    throw new Refusal(
+      "base",
+      `the request targets ${base}; the remote's default branch is ${def} (allowedBases lists other permitted bases)`,
+    );
+  }
+}
+
+/** The base the PR would target, as the remote has it now. */
+function fetchBase(stage, url, base) {
+  const r = stage.run(
+    ["fetch", "--no-tags", "--quiet", url, `+refs/heads/${base}:refs/publish/base`],
+    NET_TIMEOUT_MS,
+  );
+  if (r.status !== 0)
+    throw new Refusal("base", `cannot fetch ${base} from the configured remote: ${why(r)}`);
+  const sha = stage.out(["rev-parse", "--verify", "refs/publish/base^{commit}"]);
+  if (!sha) throw new Refusal("base", `fetched ${base} but it does not name a commit`);
+  return sha;
+}
+
+/**
+ * A branch already on the remote is taken over only when this run pushed it
+ * (its previous verdict for this session says so) and its tip is an ancestor
+ * of the run's HEAD, so the push is a fast-forward of the run's own work.
+ */
+function checkRemoteBranch(stage, url, branch, headSha, prior) {
+  const r = stage.run(["ls-remote", "--heads", url, `refs/heads/${branch}`], NET_TIMEOUT_MS);
+  if (r.status !== 0) throw new Refusal("remote", `cannot list ${branch} on the remote: ${why(r)}`);
+  const line = r.stdout.split("\n").find((l) => l.endsWith(`\trefs/heads/${branch}`));
+  if (!line) return;
+  const tip = line.split("\t")[0];
+  const f = stage.run(
+    ["fetch", "--no-tags", "--quiet", url, `+refs/heads/${branch}:refs/publish/remote`],
+    NET_TIMEOUT_MS,
+  );
+  if (f.status !== 0) throw new Refusal("remote", `cannot fetch ${branch}: ${why(f)}`);
+  if (stage.run(["merge-base", "--is-ancestor", tip, headSha]).status !== 0) {
+    throw new Refusal(
+      "remote-branch",
+      `${branch} exists on the remote at ${tip.slice(0, 12)}, which is not an ancestor of the run's HEAD`,
+    );
+  }
+  const ours = prior && prior.pushed === true && prior.branch === branch;
+  if (!ours) {
+    throw new Refusal(
+      "remote-branch",
+      `${branch} already exists on the remote and this run did not push it`,
+    );
+  }
+}
+
+/** Gate ledger: the commit hook's requirement, re-checked for every commit in the range. */
+function checkLedger(state, commits, wt, env) {
+  for (const c of commits) {
+    const parent = gitOut(wt, ["rev-parse", "--verify", `${c}^1`], env);
+    if (!parent)
+      throw new Refusal("gate-ledger", `commit ${c.slice(0, 12)} has no parent to check`);
+    const r = checkCommit(state, parent);
+    if (!r.ok) {
+      const parts = [
+        ...r.missing.map((g) => `missing ${g}`),
+        ...r.failing.map((e) => `failing ${e.gate}`),
+      ];
+      throw new Refusal(
+        "gate-ledger",
+        `commit ${c.slice(0, 12)} is not backed by the ledger for ${parent.slice(0, 12)}: ${parts.join(", ")}`,
+      );
+    }
+  }
+}
+
+/** The run's test log, as the latest test-summary ledger entry names it. */
+function testLogOf(state) {
+  const entries = (Array.isArray(state?.gates) ? state.gates : []).filter(
+    (e) => e && e.gate === "test-summary",
+  );
+  const last = entries.at(-1);
+  const src = last?.detail?.source;
+  return typeof src === "string" && src && src !== "stdin"
+    ? { path: src, parser: last.detail.parser || null }
+    : null;
+}
+
+/**
+ * The log the ledger's test-summary entry names, read as a bounded regular
+ * file inside the worktree or the run's own directory. No log is a refusal:
+ * a ledger without one has nothing to be consistent with.
+ */
+function checkTestLog(state, wt, statePath) {
+  const log = testLogOf(state);
+  if (!log) {
+    throw new Refusal("test-log", "the gate ledger names no test log for the run's tests");
+  }
+  const path = isAbsolute(log.path) ? log.path : join(wt, log.path);
+  let text;
+  try {
+    text = readRegularFile(path, { maxBytes: LOG_MAX_BYTES, within: [wt, dirname(statePath)] });
+  } catch (err) {
+    throw new Refusal("test-log", `the test log the ledger names is refused: ${err.message}`);
+  }
+  let r;
+  try {
+    r = summarize(text, { parsers: log.parser ? [log.parser] : undefined, source: path });
+  } catch {
+    r = summarize(text, { source: path });
+  }
+  if (r.status === "failed" || r.status === "no-tests") {
+    throw new Refusal(
+      "test-summary",
+      `the test log says ${r.status} (executed ${r.executed ?? "?"}, failed ${r.failed ?? "?"})`,
+    );
+  }
+  return r.status;
+}
+
+function checkSecrets(wt, range, env) {
+  if (!existsSync(PRE_COMMIT))
+    throw new Refusal("secret-scan", "pre-commit-check.sh is not installed beside this script");
+  const r = spawnSync("bash", [PRE_COMMIT, "--scan-range", range], {
+    cwd: wt,
+    encoding: "utf8",
+    env: verifyEnv(env),
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: GIT_TIMEOUT_MS * 5,
+  });
+  if (r.status === 0) return;
+  const blocked = (r.stderr || "")
+    .split("\n")
+    .filter((l) => l.startsWith("BLOCKED:"))
+    .slice(0, 5)
+    .join(" | ");
+  throw new Refusal(
+    "secret-scan",
+    blocked || `pre-commit-check.sh --scan-range exited ${r.status}`,
+  );
+}
+
+const RUN_MARKER = "MA_AP_VERIFY_RUN";
+
+/**
+ * Processes carrying this run's marker in their environment. A child that
+ * calls setsid or double-forks leaves the process group, but it inherits the
+ * environment unless it clears it, and `ps -E` prints it. macOS only, like the
+ * rest of the pipeline.
+ */
+function markedPids(marker) {
+  const needle = `${RUN_MARKER}=${marker}`;
+  const pids = [];
+  const r = spawnSync("ps", ["-axwwE", "-o", "pid=,command="], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: GIT_TIMEOUT_MS,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  for (const line of (r.stdout || "").split("\n")) {
+    const m = /^\s*(\d+)\s/.exec(line);
+    if (m && line.split(/\s/).includes(needle)) pids.push(Number(m[1]));
+  }
+  return pids;
+}
+
+function killMarked(marker) {
+  for (let round = 0; round < 3; round++) {
+    const pids = markedPids(marker).filter((p) => p !== process.pid);
+    if (!pids.length) return;
+    for (const pid of pids) {
+      try {
+        process.kill(-pid, "SIGKILL");
+      } catch {
+        // Not a group leader.
+      }
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+}
+
+/**
+ * Run one command in its own process group, output to a file, and kill the
+ * whole group at the deadline and again when it exits. Every process started
+ * for the command carries a per-run marker in its environment, and any process
+ * still carrying it is killed too, so a child that left the group with setsid
+ * or a double fork does not outlive verification. A process that also clears
+ * its environment is out of reach of this check; the run's own code executes
+ * as this user, and that is the limit named in unattended-security.md.
+ *
+ * @returns {Promise<{status: number|null, signal: string|null, timedOut: boolean, error?: Error}>}
+ */
+function runBounded(command, { cwd, env, logPath, timeoutMs }) {
+  return new Promise((resolve) => {
+    const fd = openSync(logPath, "w", 0o600);
+    const marker = randomBytes(12).toString("hex");
+    let child;
+    try {
+      child = spawn("bash", ["-c", command], {
+        cwd,
+        env: { ...env, [RUN_MARKER]: marker },
+        stdio: ["ignore", fd, fd],
+        detached: true,
+      });
+    } catch (error) {
+      closeSync(fd);
+      resolve({ status: null, signal: null, timedOut: false, error });
+      return;
+    }
+    const killGroup = () => {
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {
+        // The group is already gone.
+      }
+      killMarked(marker);
+    };
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup();
+    }, timeoutMs);
+    const done = (result) => {
+      clearTimeout(timer);
+      killGroup();
+      closeSync(fd);
+      resolve({ ...result, timedOut });
+    };
+    child.on("error", (error) => done({ status: null, signal: null, error }));
+    child.on("exit", (status, signal) => done({ status, signal }));
+  });
+}
+
+const VERIFY_KINDS = ["build", "test"];
+const PINNED_SCRIPTS = VERIFY_KINDS.flatMap((k) => [`pre${k}`, k, `post${k}`]);
+// Files that change how a build or test command runs without changing the
+// command line: the package manager's config (script-shell, registry), the
+// test runner's config and plugins, and the Gradle wrapper and settings. A
+// range that adds or edits one, at any depth, chooses how it is verified.
+const PINNED_CONFIG = new Set([
+  ".npmrc",
+  ".yarnrc",
+  ".yarnrc.yml",
+  "pytest.ini",
+  "conftest.py",
+  "tox.ini",
+  "gradle.properties",
+  "gradle-wrapper.properties",
+  "settings.gradle",
+  "settings.gradle.kts",
+]);
+const MANIFEST_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * What decides the verification commands in one directory: the command lines
+ * the stack adapter resolves, the package scripts they run (with their pre and
+ * post hooks) and the declared package manager.
+ */
+function verificationPins(dir, stack, doc, wt) {
+  const commands = {};
+  for (const kind of VERIFY_KINDS) {
+    commands[kind] = commandFor(stack, kind, { dir, doc, vars: { worktreePath: wt } }).command;
+  }
+  let pkg = null;
+  if (existsSync(join(dir, "package.json"))) {
+    try {
+      pkg = readRegularJson(join(dir, "package.json"), null, { maxBytes: MANIFEST_MAX_BYTES });
+    } catch (err) {
+      throw new Refusal("verify-scripts", `package.json is refused unread: ${err.message}`);
+    }
+  }
+  const declared = pkg && typeof pkg.scripts === "object" && pkg.scripts ? pkg.scripts : {};
+  const scripts = {};
+  for (const name of PINNED_SCRIPTS) {
+    if (Object.hasOwn(declared, name)) scripts[name] = declared[name];
+  }
+  return { commands, scripts, packageManager: pkg?.packageManager ?? null };
+}
+
+/**
+ * The files command resolution reads, copied out of the base commit into a
+ * private directory, so the base's declaration is read and nothing the range
+ * wrote.
+ */
+function materializeBaseManifests(wt, baseSha, doc, dir, env) {
+  const names = new Set(["package.json", ...LOCKFILES.map(([file]) => file)]);
+  for (const a of Object.values(doc.adapters)) {
+    for (const set of a.commands || []) for (const n of set.when || []) names.add(n);
+  }
+  for (const name of names) {
+    const r = spawnSync("git", ["-C", wt, "cat-file", "blob", `${baseSha}:${name}`], {
+      env,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: GIT_TIMEOUT_MS,
+      maxBuffer: MANIFEST_MAX_BYTES,
+    });
+    if (r.status === 0) writeFileSync(join(dir, name), r.stdout, { mode: 0o600 });
+    else if (r.error?.code === "ENOBUFS") writeFileSync(join(dir, name), "", { mode: 0o600 });
+  }
+}
+
+/** The [tool:pytest] section of a setup.cfg, or "" when it has none. */
+export function pytestSection(text) {
+  const m = /^\[tool:pytest\][^\n]*\n([\s\S]*?)(?=^\[|(?![\s\S]))/m.exec(String(text || ""));
+  return m ? m[1].trim() : "";
+}
+
+/**
+ * The PINNED_CONFIG files the range adds, edits or removes, at any depth, and
+ * a setup.cfg whose [tool:pytest] section changed.
+ */
+function changedConfig(wt, baseSha, env) {
+  const r = git(
+    wt,
+    ["-c", "core.quotePath=false", "diff", "--name-only", "-z", baseSha, "HEAD"],
+    env,
+  );
+  if (r.status !== 0) return ["the range's changed files (git diff refused)"];
+  const out = [];
+  for (const name of r.stdout.split("\0").filter(Boolean)) {
+    const base = name.split("/").pop();
+    if (PINNED_CONFIG.has(base)) out.push(name);
+    else if (base === "setup.cfg") {
+      const at = (ref) =>
+        spawnSync("git", ["-C", wt, "cat-file", "blob", `${ref}:${name}`], {
+          env,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: GIT_TIMEOUT_MS,
+          maxBuffer: MANIFEST_MAX_BYTES,
+        }).stdout;
+      if (pytestSection(at(baseSha)) !== pytestSection(at("HEAD")))
+        out.push(`${name} [tool:pytest]`);
+    }
+  }
+  return out;
+}
+
+/**
+ * The verification commands, pinned to the base commit. The commands come from
+ * the base's manifests; a range that changes a command line, a package script
+ * the commands run, its pre/post hook, the declared package manager, or a
+ * repository executable a command line starts with is refused, because the run
+ * would otherwise choose how it is verified.
+ *
+ * @returns {{kind: string, command: string}[]}
+ */
+function pinnedCommands(wt, baseSha, stack, doc, headPins, env) {
+  const dir = mkdtempSync(join(tmpdir(), "ap-base-"));
+  chmodSync(dir, 0o700);
+  try {
+    materializeBaseManifests(wt, baseSha, doc, dir, env);
+    let basePins;
+    try {
+      basePins = verificationPins(dir, stack, doc, wt);
+    } catch (err) {
+      if (err instanceof Refusal) throw err;
+      throw new Refusal(
+        "verify-scripts",
+        `the base commit declares no ${stack} build and test command (${err.message}); the range would define its own verification`,
+      );
+    }
+    const changed = [];
+    for (const kind of VERIFY_KINDS) {
+      if (basePins.commands[kind] !== headPins.commands[kind]) changed.push(`${kind} command`);
+    }
+    for (const name of PINNED_SCRIPTS) {
+      if (basePins.scripts[name] !== headPins.scripts[name]) changed.push(`${name} script`);
+    }
+    if (basePins.packageManager !== headPins.packageManager) changed.push("packageManager");
+    for (const kind of VERIFY_KINDS) {
+      const exe = /^\.\/([^\s;&|<>]+)/.exec(basePins.commands[kind])?.[1];
+      if (!exe) continue;
+      const d = git(wt, ["diff", "--quiet", baseSha, "HEAD", "--", exe], env);
+      if (d.status !== 0) changed.push(`./${exe}`);
+    }
+    changed.push(...changedConfig(wt, baseSha, env));
+    if (changed.length) {
+      throw new Refusal(
+        "verify-scripts",
+        `the range changes what verification runs (${[...new Set(changed)].join(", ")}); verification uses the base commit's declaration`,
+      );
+    }
+    return VERIFY_KINDS.map((kind) => ({ kind, command: basePins.commands[kind] }));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// Dependency directories a clean checkout does not have and the stack's build
+// needs: the run's copies are linked in. What the run put there is outside
+// what this step can vouch for; unattended-security.md states it.
+const DEPENDENCY_DIRS = ["node_modules", "Pods", ".venv"];
+
+/**
+ * A detached, clean checkout of `headSha` in a private directory: nothing
+ * untracked from the run's worktree (a .npmrc, a conftest.py, a config that
+ * shadows a committed one) reaches the build or the tests. Hooks are off for
+ * the checkout. The dependency directories the run installed are linked in.
+ *
+ * @returns {{dir: string, remove: () => void}}
+ */
+function cleanCheckout(wt, headSha, env) {
+  const parent = mkdtempSync(join(tmpdir(), "ap-checkout-"));
+  chmodSync(parent, 0o700);
+  const dir = join(parent, "checkout");
+  const remove = () => {
+    git(wt, ["worktree", "remove", "--force", dir], env);
+    git(wt, ["worktree", "prune"], env);
+    rmSync(parent, { recursive: true, force: true });
+  };
+  const r = git(
+    wt,
+    ["-c", "core.hooksPath=/dev/null", "worktree", "add", "--detach", "--quiet", dir, headSha],
+    env,
+  );
+  if (r.status !== 0) {
+    remove();
+    throw new Refusal(
+      "verify-checkout",
+      `a clean checkout of ${headSha.slice(0, 12)} failed: ${why(r)}`,
+    );
+  }
+  for (const name of DEPENDENCY_DIRS) {
+    const src = join(wt, name);
+    if (existsSync(src) && !existsSync(join(dir, name))) symlinkSync(src, join(dir, name));
+  }
+  return { dir, remove };
+}
+
+/**
+ * Build and test a clean checkout of the run's commit with the stack adapter's
+ * own commands, pinned to the base commit's manifests, then judge the fresh
+ * output with evidence-gate.mjs --stack and test-summary.mjs. The run's ledger
+ * is not consulted here. A build or test that rewrites a tracked file of the
+ * checkout is refused: what was tested would not be what is pushed.
+ *
+ * @returns {Promise<{stack: string, verified: boolean, tests?: object, reason?: string}>}
+ */
+async function verifyIndependently(wt, headSha, baseSha, config, env) {
+  const co = cleanCheckout(wt, headSha, verifyEnv(env));
+  try {
+    const result = await verifyCheckout(co.dir, baseSha, config, env);
+    const dirty = git(
+      co.dir,
+      ["-c", "core.fsmonitor=false", "status", "--porcelain", "--untracked-files=no"],
+      verifyEnv(env),
+    );
+    if (dirty.status !== 0 || dirty.stdout.trim()) {
+      throw new Refusal(
+        "verify-test",
+        "the build or tests rewrote tracked files; the tree verified would not be the tree pushed",
+      );
+    }
+    return result;
+  } finally {
+    co.remove();
+  }
+}
+
+async function verifyCheckout(wt, baseSha, config, env) {
+  let doc;
+  let stack;
+  try {
+    doc = loadAdapters();
+    stack = resolveStack(wt, { doc }).primary;
+  } catch (err) {
+    throw new Refusal("verify-stack", `the stack adapters cannot be read: ${err.message}`);
+  }
+  const allowUnverified = config?.verify?.allowUnverifiedStack === true;
+  let headPins;
+  try {
+    headPins = verificationPins(wt, stack, doc, wt);
+  } catch (err) {
+    if (err instanceof Refusal) throw err;
+    if (allowUnverified) return { stack, verified: false, reason: err.message };
+    throw new Refusal(
+      "verify-stack",
+      `stack ${stack} has no build and test command to verify with (${err.message}); verify.allowUnverifiedStack publishes it unverified`,
+    );
+  }
+  const commands = Object.fromEntries(
+    pinnedCommands(wt, baseSha, stack, doc, headPins, verifyEnv(env)).map((c) => [c.kind, c]),
+  );
+  if (!existsSync(EVIDENCE_GATE)) {
+    throw new Refusal("verify-build", "evidence-gate.mjs is not installed beside this script");
+  }
+  const sec =
+    Number(config?.verify?.timeoutSec) > 0 ? Number(config.verify.timeoutSec) : VERIFY_TIMEOUT_SEC;
+  const dir = mkdtempSync(join(tmpdir(), "ap-verify-"));
+  chmodSync(dir, 0o700);
+  const runEnv = verifyEnv(env);
+  try {
+    let tests = null;
+    for (const kind of ["build", "test"]) {
+      const gate = `verify-${kind}`;
+      const logPath = join(dir, `${kind}.log`);
+      const r = await runBounded(commands[kind].command, {
+        cwd: wt,
+        env: runEnv,
+        logPath,
+        timeoutMs: sec * 1000,
+      });
+      if (r.timedOut) throw new Refusal(gate, `the ${kind} command did not finish in ${sec}s`);
+      if (r.error) throw new Refusal(gate, `the ${kind} command did not start: ${r.error.message}`);
+      if (r.status !== 0) {
+        throw new Refusal(gate, `the ${kind} command exited ${r.status ?? r.signal}`);
+      }
+      const ev = spawnSync(
+        process.execPath,
+        [
+          EVIDENCE_GATE,
+          "--claim",
+          kind,
+          "--status",
+          "passed",
+          "--evidence",
+          logPath,
+          "--stack",
+          stack,
+        ],
+        {
+          cwd: dir,
+          encoding: "utf8",
+          env: runEnv,
+          stdio: ["ignore", "pipe", "pipe"],
+          timeout: GIT_TIMEOUT_MS,
+        },
+      );
+      if (ev.status !== 0) {
+        let reason = why(ev);
+        try {
+          reason = JSON.parse(ev.stdout).reason || reason;
+        } catch {
+          // The gate's stderr already says why.
+        }
+        throw new Refusal(gate, `evidence-gate refused the ${kind} output: ${reason}`);
+      }
+      if (kind === "test") {
+        const adapter = getAdapter(stack, { doc });
+        const s = summarize(readRegularFile(logPath, { maxBytes: LOG_MAX_BYTES }), {
+          parsers: adapter.testSummary?.parsers,
+          source: logPath,
+        });
+        if (s.status === "failed" || s.status === "no-tests") {
+          throw new Refusal(
+            gate,
+            `the test run says ${s.status} (executed ${s.executed ?? "?"}, failed ${s.failed ?? "?"})`,
+          );
+        }
+        tests = { status: s.status, executed: s.executed, failed: s.failed };
+      }
+    }
+    return { stack, verified: true, tests };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Certain outbound-gate findings in any of the texts, by name.
+ *
+ * @param {Record<string,string>} texts
+ */
+export function outboundFindings(texts) {
+  const out = [];
+  for (const [field, text] of Object.entries(texts)) {
+    if (typeof text !== "string") continue;
+    for (const f of scan(text)) if (f.certain) out.push(`${field}:${f.line} ${f.rule}`);
+  }
+  return out;
+}
+
+/** The request, read once as a bounded regular file and validated on those bytes. */
+function readRequest(reqPath) {
+  let req;
+  try {
+    req = JSON.parse(readRegularFile(reqPath, { maxBytes: REQUEST_MAX_BYTES }));
+  } catch (err) {
+    throw new Refusal("pr-request", `the request is refused unread: ${err.message}`, { exit: 1 });
+  }
+  const { errors, secrets } = validatePrRequest(req);
+  if (secrets.length || errors.length) {
+    const detail = [...errors, ...secrets.map((s) => `${s.field}:${s.line} ${s.rule}`)].join("; ");
+    throw new Refusal("pr-request", `the request is invalid: ${detail}`, {
+      exit: secrets.length ? 7 : 1,
+    });
+  }
+  return req;
+}
+
+function push(stage, url, branch) {
+  const r = stage.run(
+    [
+      "-c",
+      "push.recurseSubmodules=no",
+      "push",
+      "--no-verify",
+      "--porcelain",
+      url,
+      `refs/heads/${branch}:refs/heads/${branch}`,
+    ],
+    NET_TIMEOUT_MS,
+  );
+  if (r.status !== 0) throw new Refusal("push", `git push refused: ${why(r)}`);
+}
+
+function openDraftPr(req, repo, env) {
+  const dir = mkdtempSync(join(tmpdir(), "ap-publish-"));
+  chmodSync(dir, 0o700);
+  try {
+    const bodyFile = join(dir, "body.md");
+    writeFileSync(bodyFile, req.body, { mode: 0o600 });
+    const r = spawnSync(
+      env.MA_AP_GH_BIN || "gh",
+      [
+        "pr",
+        "create",
+        "--draft",
+        "--repo",
+        repo,
+        "--base",
+        req.base,
+        "--head",
+        req.branch,
+        "--title",
+        req.title,
+        "--body-file",
+        bodyFile,
+      ],
+      {
+        cwd: dir,
+        encoding: "utf8",
+        env: outwardEnv(env),
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: NET_TIMEOUT_MS,
+      },
+    );
+    const url = (r.stdout || "").match(/https?:\/\/\S+\/pull\/\d+/g)?.pop() || null;
+    if (r.status !== 0 || !url) {
+      throw new Refusal("pr-create", `gh pr create did not open a PR: ${why(r)}`, { pushed: true });
+    }
+    return { url, number: Number(url.match(/\/pull\/(\d+)/)[1]) };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function summaryText(req, repo, url, sha) {
+  return [
+    `# Branch pushed, PR not opened`,
+    "",
+    `The autopilot runner verified and pushed this branch. The host has no draft`,
+    `pull request, so a person opens the PR from it.`,
+    "",
+    `- Repository: ${repo}`,
+    `- Branch: ${req.branch}`,
+    `- Base: ${req.base}`,
+    `- Head: ${sha}`,
+    `- Remote: ${url.replace(/\/\/[^/@]*@/, "//")}`,
+    "",
+    `## Title`,
+    "",
+    req.title,
+    "",
+    `## Body`,
+    "",
+    req.body,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Verify and publish one run's PR request.
+ *
+ * @param {{sessionId: string, statePath: string|null, item: {repo: string, source?: string, id?: string},
+ *          config: object, env?: Record<string,string|undefined>}} args
+ * @returns {Promise<{outcome: string|null, reason?: string, gate?: string, prUrl?: string,
+ *          summaryPath?: string, request?: object}>} outcome null: nothing to publish
+ */
+export async function publish({ sessionId, statePath, item, config, env = process.env }) {
+  let reqPath;
+  try {
+    reqPath = prRequestPath(sessionId, env);
+  } catch {
+    return { outcome: null, reason: "no session id" };
+  }
+  if (!existsSync(reqPath)) return { outcome: null, reason: "no PR request" };
+  if (!statePath || !existsSync(statePath)) {
+    return { outcome: null, reason: "no run state to publish from" };
+  }
+
+  const verdictPath = prVerdictPath(sessionId, env);
+  const repo = item?.repo;
+  const base = { at: new Date().toISOString(), sessionId, repo };
+  // What this session's previous publish recorded. The verdict lives under the
+  // autopilot root, which an unattended run cannot write.
+  const prior = readRegularJson(verdictPath, null);
+  const priorPushed = prior?.pushed === true;
+  let req = null;
+  let pushed = false;
+  let stateReadable = false;
+  let stage = null;
+  try {
+    let state;
+    try {
+      state = JSON.parse(readRegularFile(statePath, { maxBytes: STATE_MAX_BYTES }));
+    } catch (err) {
+      throw new Refusal("state", `the run's state is refused unread: ${err.message}`);
+    }
+    if (!state || typeof state !== "object" || Array.isArray(state)) {
+      throw new Refusal("state", "the run's state is not a JSON object");
+    }
+    stateReadable = true;
+    if ((state.currentPhase ?? 0) < PHASE_COMMIT) {
+      return {
+        outcome: null,
+        reason: `the run stopped at phase ${state.currentPhase ?? 0}, before the commit hand-off`,
+      };
+    }
+    // A run whose own gate rejected its work is not published. A publish that
+    // was refused before may be re-run once its cause is fixed.
+    const vf = state.verificationFailed;
+    if (vf && !String(vf.gate || "").startsWith("publish/")) {
+      return { outcome: null, reason: "the run's own verification failed" };
+    }
+    if (state.pr?.url || state.publish?.outcome) {
+      return { outcome: null, reason: "already published" };
+    }
+
+    req = readRequest(reqPath);
+
+    const repoCfg = (config?.repos || []).find((r) => r && r.nameWithOwner === repo);
+    if (!repo || !repoCfg)
+      throw new Refusal("repo", `${repo || "(no repo)"} is not in the runner's config`);
+    if (req.repo !== repo) {
+      throw new Refusal("repo", `the request names ${req.repo}; this item belongs to ${repo}`);
+    }
+    const host = resolveHost(repoCfg);
+    if (!host)
+      throw new Refusal(
+        "host",
+        `host ${JSON.stringify(repoCfg.host)} is not one of ${HOSTS.join(", ")}`,
+      );
+
+    const localEnv = verifyEnv(env);
+    const wt = typeof state.worktreePath === "string" ? state.worktreePath : null;
+    if (!wt || !existsSync(wt)) throw new Refusal("worktree", "the run's worktree is not on disk");
+    const common = (d) => {
+      const c = gitOut(d, ["rev-parse", "--path-format=absolute", "--git-common-dir"], localEnv);
+      return c ? realOr(c) : null;
+    };
+    const wtCommon = common(wt);
+    if (!wtCommon || !repoCfg.localPath || wtCommon !== common(repoCfg.localPath)) {
+      throw new Refusal(
+        "worktree",
+        `the worktree is not a checkout of ${repoCfg.localPath || repo}`,
+      );
+    }
+
+    if (protectedBranch(req.branch, repoCfg)) {
+      throw new Refusal(
+        "branch",
+        `${req.branch} is protected; the run's work belongs on its own branch`,
+      );
+    }
+    if (typeof state.branch !== "string" || state.branch !== req.branch) {
+      throw new Refusal(
+        "branch",
+        `the request names ${req.branch}; the run recorded ${state.branch ?? "no branch"}`,
+      );
+    }
+    const branchSha = gitOut(
+      wt,
+      ["rev-parse", "--verify", "--quiet", `refs/heads/${req.branch}^{commit}`],
+      localEnv,
+    );
+    if (!branchSha)
+      throw new Refusal("branch", `branch ${req.branch} does not exist in the worktree`);
+    const headSha = gitOut(wt, ["rev-parse", "--verify", "HEAD^{commit}"], localEnv);
+    if (headSha !== branchSha) throw new Refusal("branch", `the worktree is not on ${req.branch}`);
+    assertUnmoved(wt, req.branch, headSha, localEnv, "worktree");
+
+    const url = resolvePushUrl(repo, repoCfg, host, env);
+    stage = stagingRepo(env);
+    checkBase(stage, url, req.base, repoCfg);
+    stageBranch(stage, wt, req.branch, headSha);
+    const baseSha = fetchBase(stage, url, req.base);
+    const commits = (stage.out(["rev-list", "--reverse", `${baseSha}..${headSha}`]) || "")
+      .split("\n")
+      .filter(Boolean);
+    if (!commits.length) throw new Refusal("branch", `${req.branch} is not ahead of ${req.base}`);
+    checkRemoteBranch(stage, url, req.branch, headSha, prior);
+    const mergeBase = stage.out(["merge-base", baseSha, headSha]);
+    if (!mergeBase) throw new Refusal("branch", `${req.branch} shares no history with ${req.base}`);
+
+    checkLedger(state, commits, wt, localEnv);
+    checkTestLog(state, wt, statePath);
+    checkSecrets(wt, `${mergeBase}..${headSha}`, env);
+    const leaks = outboundFindings({ title: req.title, body: req.body });
+    if (leaks.length) throw new Refusal("outbound-gate", `the PR text carries ${leaks.join(", ")}`);
+    stage.cleanup();
+    stage = null;
+
+    // The run's own code executes next, as this user. The operator's
+    // credential settings are read now, before it runs, and the push uses that
+    // snapshot. Afterwards the user-level git config must be byte-for-byte
+    // what it was: a build or test that rewrote it is refused, not pushed with.
+    const credText = credentialConfig(env);
+    const fingerprint = gitConfigFingerprint(env);
+    const hostBefore = hostFingerprint(env);
+    const verified = await verifyIndependently(wt, headSha, mergeBase, config, env);
+    assertUnmoved(wt, req.branch, headSha, localEnv, "verify-test");
+    const hostAfter = hostFingerprint(env);
+    const hostEdited = Object.keys({ ...hostBefore, ...hostAfter }).filter(
+      (p) => hostBefore[p] !== hostAfter[p],
+    );
+    if (hostEdited.length) {
+      throw new Refusal(
+        "verify-host",
+        `the build or tests changed the host while they ran (${hostEdited.slice(0, 5).join(", ")}${hostEdited.length > 5 ? ", ..." : ""}); nothing is pushed`,
+      );
+    }
+    const after = gitConfigFingerprint(env);
+    const edited = Object.keys({ ...fingerprint, ...after }).filter(
+      (p) => fingerprint[p] !== after[p],
+    );
+    if (edited.length || credentialConfig(env) !== credText) {
+      throw new Refusal(
+        "verify-credentials",
+        `the git config changed while the run's build and tests ran${edited.length ? ` (${edited.join(", ")})` : ""}; nothing is pushed with it`,
+      );
+    }
+
+    stage = stagingRepo(env, credText);
+    stageBranch(stage, wt, req.branch, headSha);
+    push(stage, url, req.branch);
+    pushed = true;
+
+    if (host === "bitbucket") {
+      const summaryPath = join(prRequestsDir(env), `${sessionId}${SUMMARY_SUFFIX}`);
+      const text = summaryText(req, repo, url, headSha);
+      writePrivate(summaryPath, text);
+      const publishRec = {
+        outcome: OUTCOME.PUSHED_AWAITING_PR,
+        at: base.at,
+        host,
+        branch: req.branch,
+        base: req.base,
+        sha: headSha,
+      };
+      await updateState(statePath, (s) => ({ ...s, publish: publishRec }));
+      writePrivate(
+        verdictPath,
+        `${JSON.stringify({ ...base, ...publishRec, pushed: true, verified, summaryPath }, null, 2)}\n`,
+      );
+      return { outcome: OUTCOME.PUSHED_AWAITING_PR, summaryPath, request: req };
+    }
+
+    const pr = openDraftPr(req, repo, env);
+    await updateState(statePath, (s) => ({
+      ...s,
+      pr: { url: pr.url, number: pr.number, draft: true },
+    }));
+    writePrivate(
+      verdictPath,
+      `${JSON.stringify({ ...base, outcome: OUTCOME.PR_OPENED, host, branch: req.branch, sha: headSha, pushed: true, verified, url: pr.url }, null, 2)}\n`,
+    );
+    return { outcome: OUTCOME.PR_OPENED, prUrl: pr.url, request: req };
+  } catch (err) {
+    const gate = err instanceof Refusal ? err.gate : "internal";
+    const reason = err instanceof Refusal ? err.message : `unexpected: ${err?.message || err}`;
+    const branch = req?.branch ?? prior?.branch ?? null;
+    writePrivate(
+      verdictPath,
+      `${JSON.stringify(
+        {
+          ...base,
+          outcome: OUTCOME.VERIFICATION_FAILED,
+          gate,
+          error: reason,
+          pushed: pushed || Boolean(err?.extra?.pushed) || (priorPushed && prior.branch === branch),
+          branch,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    if (stateReadable) {
+      try {
+        await park(statePath, {
+          outcome: OUTCOME.VERIFICATION_FAILED,
+          gate: `publish/${gate}`,
+          reason,
+        });
+      } catch {
+        // The verdict file already says why; a state that cannot be written
+        // still ends the attempt as verification-failed below.
+      }
+    }
+    return { outcome: OUTCOME.VERIFICATION_FAILED, gate, reason };
+  } finally {
+    stage?.cleanup();
+  }
+}
+
+/**
+ * Run one outward script for a channel, after the outbound gate. The text goes
+ * to the script as a 0600 body file in a private temp dir, never on argv, and
+ * the script runs with MULTI_AGENT_UNATTENDED unset. Pushes one result.
+ */
+function scriptRunner(results, env) {
+  return (channel, script, args, text) => {
+    if (text !== undefined) {
+      const leaks = outboundFindings({ [channel]: text });
+      if (leaks.length) {
+        results.push({ channel, status: "refused", reason: `outbound gate: ${leaks.join(", ")}` });
+        return;
+      }
+    }
+    if (!existsSync(script)) {
+      results.push({ channel, status: "failed", reason: `${script} is not installed` });
+      return;
+    }
+    const dir = mkdtempSync(join(tmpdir(), "ap-report-"));
+    try {
+      const full = [...args];
+      if (text !== undefined) {
+        const f = join(dir, "body.md");
+        writeFileSync(f, text, { mode: 0o600 });
+        full.push("--body-file", f);
+      }
+      const r = spawnSync("bash", [script, ...full], {
+        cwd: dir,
+        encoding: "utf8",
+        env: outwardEnv(env),
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: NET_TIMEOUT_MS,
+      });
+      results.push(
+        r.status === 0
+          ? { channel, status: "posted" }
+          : { channel, status: "failed", reason: why(r) },
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+}
+
+/**
+ * What the runner posts after a PR opened, and nothing before. Each piece is
+ * off unless the config turns it on:
+ *
+ *   reportChannels + channels.mode "configured": `jira` posts one comment with
+ *     the PR link and the PR text through jira-publish.sh. `pr` is the draft PR
+ *     itself. `confluence` and `wiki` need a page composed by a session with
+ *     publish rights, which an unattended run does not get, so they are
+ *     reported as skipped.
+ *   reportIssueUpdates: update-issue-progress.sh for a GitHub issue the run
+ *     recorded, and a PR-link Jira comment when no channel comment went out.
+ *
+ * Every text passes the outbound gate here before a script sees it, and every
+ * script runs with MULTI_AGENT_UNATTENDED unset (each script's own gate runs
+ * again inside it).
+ *
+ * @returns {{channel: string, status: "posted"|"skipped"|"refused"|"failed", reason?: string}[]}
+ */
+export function reportAfterPublish({
+  prUrl,
+  request,
+  item,
+  state,
+  config,
+  env = process.env,
+  scripts = {},
+}) {
+  const results = [];
+  if (!prUrl) return results;
+  const jiraKey =
+    (typeof state?.jiraId === "string" && state.jiraId) ||
+    (item?.source === "jira" ? item.id : null);
+  const jiraScript = scripts.jiraPublish || join(HERE, "..", "lib", "jira-publish.sh");
+  const progressScript = scripts.issueProgress || join(HERE, "update-issue-progress.sh");
+
+  const runScript = scriptRunner(results, env);
+
+  let jiraPosted = false;
+  const ch = config?.channels || {};
+  if (config?.reportChannels === true && ch.mode === "configured") {
+    for (const target of Array.isArray(ch.targets) ? ch.targets : []) {
+      if (target === "pr") {
+        results.push({ channel: "pr", status: "posted", reason: "the draft PR is the report" });
+      } else if (target === "jira") {
+        if (!jiraKey) {
+          results.push({
+            channel: "jira",
+            status: "skipped",
+            reason: "no Jira issue linked to this run",
+          });
+          continue;
+        }
+        runScript(
+          "jira",
+          jiraScript,
+          ["--issue", jiraKey],
+          `Draft PR opened: ${prUrl}\n\n${request?.title || ""}\n\n${request?.body || ""}`,
+        );
+        jiraPosted = results.at(-1).status === "posted";
+      } else {
+        results.push({
+          channel: target,
+          status: "skipped",
+          reason: `${target} needs a page composed with publish rights; not posted unattended`,
+        });
+      }
+    }
+  }
+  if (config?.reportIssueUpdates === true) {
+    if (state?.githubIssue?.number && state?.taskId) {
+      runScript("issue-progress", progressScript, [String(state.taskId)]);
+    }
+    if (jiraKey && !jiraPosted) {
+      runScript("jira-pr-link", jiraScript, ["--issue", jiraKey], `Draft PR opened: ${prUrl}\n`);
+    }
+  }
+  return results;
+}
+
+/**
+ * The daily digest, through the same channels and the same gate as the post-PR
+ * report. Sent only with `reportChannels: true` and `channels.mode:
+ * "configured"`; the caller decides whether the digest runs at all
+ * (`digest.enabled`). `jira` posts one comment on `digest.jiraIssue`, a
+ * standing issue the operator chose, because a digest belongs to no single
+ * item. `pr` has no PR to be, and `confluence` and `wiki` need a page composed
+ * with publish rights, so all three are reported as skipped.
+ *
+ * @returns {{channel: string, status: "posted"|"skipped"|"refused"|"failed", reason?: string}[]}
+ */
+export function reportDigest({ text, config, env = process.env, scripts = {} }) {
+  const results = [];
+  const ch = config?.channels || {};
+  if (config?.reportChannels !== true || ch.mode !== "configured") return results;
+  const runScript = scriptRunner(results, env);
+  const jiraScript = scripts.jiraPublish || join(HERE, "..", "lib", "jira-publish.sh");
+  const issue = typeof config?.digest?.jiraIssue === "string" ? config.digest.jiraIssue.trim() : "";
+  for (const target of Array.isArray(ch.targets) ? ch.targets : []) {
+    if (target === "jira") {
+      if (!issue) {
+        results.push({ channel: "jira", status: "skipped", reason: "digest.jiraIssue is not set" });
+        continue;
+      }
+      runScript("jira", jiraScript, ["--issue", issue], text);
+    } else if (target === "pr") {
+      results.push({ channel: "pr", status: "skipped", reason: "a digest has no PR" });
+    } else {
+      results.push({
+        channel: target,
+        status: "skipped",
+        reason: `${target} needs a page composed with publish rights; not posted unattended`,
+      });
+    }
+  }
+  return results;
+}
+
+function arg(argv, name) {
+  const i = argv.indexOf(name);
+  return i === -1 ? undefined : argv[i + 1];
+}
+
+async function main(argv) {
+  const sessionId = arg(argv, "--session");
+  const statePath = arg(argv, "--state");
+  const repo = arg(argv, "--repo");
+  if (!sessionId || !statePath || !repo) {
+    process.stderr.write(
+      "usage: autopilot-publish.mjs --session <uuid> --state <agent-state.json> --repo <owner/name>\n",
+    );
+    return 2;
+  }
+  const root =
+    process.env.MA_AUTOPILOT_ROOT || join(process.env.HOME || "", ".claude", "autopilot");
+  const config = readRegularJson(join(root, "config.json"), null);
+  if (!config) {
+    process.stderr.write(`autopilot-publish: no config at ${join(root, "config.json")}\n`);
+    return 2;
+  }
+  const r = await publish({ sessionId, statePath, item: { repo }, config });
+  process.stdout.write(
+    `${JSON.stringify({ outcome: r.outcome, gate: r.gate, reason: r.reason, prUrl: r.prUrl })}\n`,
+  );
+  if (r.outcome === null) return 3;
+  return r.outcome === OUTCOME.VERIFICATION_FAILED ? 1 : 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}