@workit-dev/core 0.0.1 → 1.0.0

package/src/stack.ts

@@ -0,0 +1,2570 @@
+// `workit stack` (D7, design §2.1 S12): plain base-branch chains on GitHub and
+// GitLab, no Graphite and no `gh stack`/git-spice dependency.
+//
+// Truth is git ancestry plus the forge's PR bases. The stack file
+// `<store>/stacks/<name>.json` (D13: under the git common dir, so it is shared
+// by every worktree and survives worktree removal) is a reconstructible
+// cache of the order and of what each branch was last built on:
+//   {v:1, name, trunk, forge, repo, branches:[{branch, parent, pr, lastHead,
+//    lastParentHead, patchId, merged}], updatedAt}
+// `lastParentHead` is the parent tip a branch was last rebased onto, so a
+// restack is `git rebase --onto <new parent tip> <lastParentHead> <branch>`.
+//
+// One writer per stack: every command that writes the file or touches the
+// branches holds `<store>/stacks/<name>.json.lock` (a held lock answers
+// `busy`; a lock left by a dead process is reclaimed).
+//
+// sync: after a parent merged (squash merges rewrite history, so a child must
+// be rebased, design §0 #9) every remaining branch is restacked in order,
+// pushed with a lease through the S11 push, and its PR retargeted. A rebase
+// conflict stops with the rebase left in progress and the unblock command;
+// unprocessed branches keep their recorded state. Each restack appends an
+// observed `stack.restacked` row; when the change relative to its parent is
+// identical (patch-id and exact diff hash), S13 carries the verdict through
+// it. CI is never carried: it runs again on the new head.
+//
+// land: first a pre-flight (#739) judges every PR the run would land (open,
+// based on trunk or its parent, READY (S10), verdict-accepted (S13), the
+// merge grant, its author, the `--allow-failing` waiver on its head); any
+// refusal stops the land with nothing merged and names every refused PR. Then
+// it merges from the root, one at a time through the S11 `pr merge` gates
+// (merge grant, head-SHA guard). After each merge the rest is restacked and
+// retargeted and the next PR's CI is awaited before it is judged again; what
+// only shows then (a head that moved, a forge race) stops the run there, and
+// the outcome lists what landed. Descendants are never armed for auto-merge.
+//
+// Optional adapters (`gh stack`, git-spice) can later implement `StackAdapter`
+// and replace the built-in restack/retarget; nothing else depends on how the
+// chain is rewritten.
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { requireGrant, type GrantDecision } from "./autonomy";
+import { pushTarget } from "./core/remotes";
+import { isProtectedTarget } from "./core/branch";
+import { classifyLockOwner, localLockHost, processStartOf } from "./core/store-lock";
+import { baseTarget, forgeLogin, mergePullRequest, otherAuthor, type Sleep } from "./forge/pr-ops";
+import {
+  buildStatusDoc,
+  mergeGateForge,
+  pollDelay,
+  waitVerdict,
+  type CheckWaiver,
+  type WaivedCheck,
+  type ChecksState,
+  type NextAction,
+  type PrStatusDoc,
+} from "./forge/report";
+import type { ResolvedForge } from "./forge/resolve";
+import type { ForgeResult, MergeMethod, PrState } from "./forge/types";
+import { executePush, pushPreflight, recordedRemoteTip, type PushPlan } from "./git/ops";
+import {
+  currentBranch,
+  fetchRefs,
+  GIT_TIMEOUTS,
+  hasCommit,
+  mergeBase,
+  patchId,
+  pushRemoteName,
+  remoteRefTip,
+  resolveRef,
+  sameOwnChange,
+} from "./git/rev";
+import {
+  appendObserved,
+  diffHash,
+  rangeKeys,
+  readLedger,
+  storeRoot,
+  type LedgerActor,
+  type ReadRow,
+  type VerdictBasis,
+} from "./ledger";
+import type { LaneNeed, ReviewLane } from "./core/policy/lane";
+import { prLaneGate } from "./core/policy/pr-lane";
+import { checkVerdictsCovered, type StackCover } from "./verdict-cover";
+
+export const STACK_VERSION = 1;
+
+export type StackEntry = {
+  branch: string;
+  /** The branch this one is built on (the trunk for the root). */
+  parent: string;
+  pr: number | null;
+  /** The branch tip when the stack last processed it. */
+  lastHead: string | null;
+  /** The parent tip it was last rebased onto (the `--onto` upstream for the next restack). */
+  lastParentHead: string | null;
+  /** patch-id of lastParentHead...lastHead. */
+  patchId: string | null;
+  /** Set once its PR merged (or its tip reached the trunk); skipped afterwards. */
+  merged: { pr: number | null; mergeSha: string | null; at: string } | null;
+  /**
+   * A restack begun but not yet verified and pushed: the change as it was
+   * (`from..tip`) and the base it is moving onto. Survives a conflict or a
+   * content_changed stop, so the next sync compares against the original.
+   */
+  pendingRestack?: { from: string; tip: string; onto: string } | null;
+};
+
+export type StackFile = {
+  v: number;
+  name: string;
+  trunk: string;
+  forge: "github" | "gitlab" | null;
+  repo: string | null;
+  branches: StackEntry[];
+  updatedAt: string;
+};
+
+export type StackError = {
+  ok: false;
+  code: "blocked" | "failed" | "unavailable" | "not_found" | "busy" | "invalid_input";
+  error: string;
+  unblock?: string;
+  data?: Record<string, unknown>;
+};
+export type StackResult<T> = { ok: true; data: T } | StackError;
+
+const stackFail = (
+  code: StackError["code"],
+  error: string,
+  unblock?: string,
+  data?: Record<string, unknown>,
+): StackError => ({
+  ok: false,
+  code,
+  error,
+  ...(unblock ? { unblock } : {}),
+  ...(data ? { data } : {}),
+});
+
+const fromForge = (result: Extract<ForgeResult<unknown>, { ok: false }>): StackError =>
+  stackFail(result.code, result.error, result.unblock);
+
+/**
+ * Test and adapter seams. `pushPlan` decides where a branch is pushed (the
+ * S11 preflight by default); `adapter` is where an optional `gh stack` /
+ * git-spice adapter would plug in later. Only the built-in one ships.
+ */
+export type StackAdapter = {
+  name: string;
+  /** Rebase `branch` from `from` onto `onto`; the built-in one runs git rebase --onto. */
+  restack(cwd: string, input: { branch: string; onto: string; from: string }): RestackOutcome;
+};
+
+export const stackDeps: {
+  pushPlan: (cwd: string, branch: string) => ForgeResult<PushPlan>;
+  adapter: StackAdapter;
+  /** Bound on one restack (hooks such as post-rewrite run inside it). */
+  rebaseTimeoutMs: number;
+} = {
+  pushPlan: (cwd, branch) => pushPreflight(cwd, { branch }),
+  adapter: { name: "git", restack: (cwd, input) => gitRestack(cwd, input) },
+  rebaseTimeoutMs: Number(process.env.WORKIT_STACK_REBASE_TIMEOUT_MS) || 10 * 60_000,
+};
+
+// ---------------------------------------------------------------------------
+// git plumbing
+
+type GitRun = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+};
+
+const gitRun = (cwd: string, args: string[], timeoutMs: number = GIT_TIMEOUTS.local): GitRun => {
+  const run = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: "0",
+      GIT_EDITOR: "true",
+      GIT_SEQUENCE_EDITOR: "true",
+      LC_ALL: "C",
+      LANGUAGE: "C",
+    },
+  });
+  const failure: NodeJS.ErrnoException | undefined = run.error;
+  return {
+    ok: run.status === 0,
+    stdout: run.stdout ?? "",
+    stderr: run.error ? String(run.error.message) : (run.stderr ?? ""),
+    timedOut: failure?.code === "ETIMEDOUT",
+  };
+};
+
+const safeRef = (value: string): boolean => value.length > 0 && !value.startsWith("-");
+
+const isAncestor = (cwd: string, ancestor: string, descendant: string): boolean =>
+  safeRef(ancestor) &&
+  safeRef(descendant) &&
+  gitRun(cwd, ["merge-base", "--is-ancestor", ancestor, descendant]).ok;
+
+const branchTip = (cwd: string, branch: string): string | null =>
+  resolveRef(cwd, `refs/heads/${branch}`);
+
+/**
+ * The worktree that has `branch` checked out, if any, including one where a
+ * rebase of it is stopped (HEAD is detached then; the branch is named in
+ * rebase-merge/head-name).
+ */
+function worktreeOf(cwd: string, branch: string): string | null {
+  const list = gitRun(cwd, ["worktree", "list", "--porcelain"]);
+  if (!list.ok) return null;
+  let current: string | null = null;
+  for (const line of list.stdout.split("\n")) {
+    if (line.startsWith("worktree ")) current = line.slice("worktree ".length);
+    else if (line === `branch refs/heads/${branch}` && current) return current;
+    else if (line === "detached" && current && rebasingBranch(current) === `refs/heads/${branch}`)
+      return current;
+  }
+  return null;
+}
+
+function rebasingBranch(dir: string): string | null {
+  for (const name of ["rebase-merge/head-name", "rebase-apply/head-name"]) {
+    const found = gitRun(dir, ["rev-parse", "--path-format=absolute", "--git-path", name]);
+    if (!found.ok) continue;
+    try {
+      return fs.readFileSync(found.stdout.trim(), "utf8").trim();
+    } catch {
+      // not this one
+    }
+  }
+  return null;
+}
+
+/** A rebase (or am) stopped in this worktree. */
+function rebaseInProgress(dir: string): boolean {
+  for (const name of ["rebase-merge", "rebase-apply"]) {
+    const found = gitRun(dir, ["rev-parse", "--path-format=absolute", "--git-path", name]);
+    if (found.ok && fs.existsSync(found.stdout.trim())) return true;
+  }
+  return false;
+}
+
+const trackedDirt = (dir: string): boolean => {
+  const status = gitRun(dir, ["status", "--porcelain", "--untracked-files=no"]);
+  return !status.ok || status.stdout.trim() !== "";
+};
+
+export type RestackOutcome =
+  | { ok: true; head: string }
+  | {
+      ok: false;
+      conflict: boolean;
+      timedOut?: boolean;
+      worktree: string;
+      error: string;
+    };
+
+/** Where sync checks out branches nobody has checked out (never the user's checkout). */
+const scratchDir = (cwd: string): string | null => {
+  const dir = stacksDir(cwd);
+  return dir.ok ? path.join(dir.data, "worktrees") : null;
+};
+
+/**
+ * `git rebase --onto <onto> <from>` with the branch checked out: in the
+ * worktree that already has it, else in a temporary worktree under the store
+ * root (`git worktree add`), so the user's own checkout never moves. Never
+ * autostashes and never updates other refs (`rebase.updateRefs` would move
+ * sibling stack branches). A temporary worktree is removed on success and
+ * kept on a conflict, so the rebase can be continued there.
+ */
+function gitRestack(
+  cwd: string,
+  input: { branch: string; onto: string; from: string },
+): RestackOutcome {
+  const owner = worktreeOf(cwd, input.branch);
+  let dir = owner;
+  if (!dir) {
+    const scratch = scratchDir(cwd);
+    if (!scratch)
+      return {
+        ok: false,
+        conflict: false,
+        worktree: cwd,
+        error: "no store root",
+      };
+    fs.mkdirSync(scratch, { recursive: true });
+    dir = path.join(
+      scratch,
+      `${input.branch.replace(/[^A-Za-z0-9._-]+/gu, "_").slice(0, 40)}-${randomBytes(4).toString("hex")}`,
+    );
+    const added = gitRun(cwd, ["worktree", "add", "-q", dir, input.branch], GIT_TIMEOUTS.worktree);
+    if (!added.ok)
+      return {
+        ok: false,
+        conflict: false,
+        worktree: cwd,
+        error: firstLine(added),
+      };
+  }
+  const run = gitRun(
+    dir,
+    [
+      "-c",
+      "rebase.autoStash=false",
+      "-c",
+      "rebase.updateRefs=false",
+      "rebase",
+      "--no-autosquash",
+      "--onto",
+      input.onto,
+      input.from,
+    ],
+    stackDeps.rebaseTimeoutMs,
+  );
+  if (!run.ok) {
+    // Killed at the bound: the rebase stopped mid-way, which is not a conflict.
+    if (run.timedOut)
+      return {
+        ok: false,
+        conflict: false,
+        timedOut: true,
+        worktree: dir,
+        error: `git rebase did not finish within ${stackDeps.rebaseTimeoutMs} ms`,
+      };
+    if (rebaseInProgress(dir))
+      return {
+        ok: false,
+        conflict: true,
+        worktree: dir,
+        error: firstLine(run),
+      };
+    if (!owner) gitRun(cwd, ["worktree", "remove", "--force", dir]);
+    return { ok: false, conflict: false, worktree: dir, error: firstLine(run) };
+  }
+  if (!owner) gitRun(cwd, ["worktree", "remove", "--force", dir]);
+  const head = branchTip(cwd, input.branch);
+  return head
+    ? { ok: true, head }
+    : {
+        ok: false,
+        conflict: false,
+        worktree: dir,
+        error: `${input.branch} vanished`,
+      };
+}
+
+/** Remove temporary sync worktrees that are clean and not mid-rebase. */
+function pruneScratch(cwd: string): void {
+  const scratch = scratchDir(cwd);
+  if (!scratch || !fs.existsSync(scratch)) return;
+  for (const name of fs.readdirSync(scratch)) {
+    const dir = path.join(scratch, name);
+    if (!rebaseInProgress(dir) && !trackedDirt(dir))
+      gitRun(cwd, ["worktree", "remove", "--force", dir]);
+  }
+  gitRun(cwd, ["worktree", "prune"]);
+}
+
+const firstLine = (run: GitRun): string =>
+  (`${run.stderr}\n${run.stdout}`.split("\n").find((line) => line.trim()) ?? "git failed")
+    .trim()
+    .slice(0, 300);
+
+// ---------------------------------------------------------------------------
+// store
+
+/**
+ * Portable file name for a stack: a readable slug plus a hash of the exact
+ * name, so names differing only in case or in characters Windows rejects
+ * never collide, and no file is ever a reserved device name (CON, NUL, …).
+ */
+export const stackFileName = (name: string): string =>
+  `${name
+    .replace(/[^A-Za-z0-9._-]+/gu, "_")
+    .replace(/^[._]+/u, "")
+    .slice(0, 48)
+    .toLowerCase()}-${createHash("sha256").update(name).digest("hex").slice(0, 12)}.json`;
+
+const fileFor = stackFileName;
+
+/** A stack name must be printable and short. */
+const validName = (name: string): boolean => {
+  if (name.length === 0 || name.length > 200) return false;
+  for (let index = 0; index < name.length; index += 1) {
+    const code = name.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return false;
+  }
+  return true;
+};
+
+export function stacksDir(cwd: string): StackResult<string> {
+  const root = storeRoot(cwd);
+  if (!root.ok) return stackFail(root.code, root.error, root.unblock);
+  return { ok: true, data: path.join(root.value.root, "stacks") };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+const str = (value: unknown): string | null => (typeof value === "string" && value ? value : null);
+
+/** Tolerant read (D17): unknown keys are ignored, required keys are checked. */
+function parseStack(raw: unknown): StackFile | null {
+  if (!isRecord(raw) || !Array.isArray(raw.branches)) return null;
+  const name = str(raw.name);
+  const trunk = str(raw.trunk);
+  if (!name || !trunk) return null;
+  const branches: StackEntry[] = [];
+  for (const item of raw.branches) {
+    if (!isRecord(item)) return null;
+    const branch = str(item.branch);
+    if (!branch) return null;
+    const merged = isRecord(item.merged)
+      ? {
+          pr: typeof item.merged.pr === "number" ? item.merged.pr : null,
+          mergeSha: str(item.merged.mergeSha),
+          at: str(item.merged.at) ?? "",
+        }
+      : null;
+    branches.push({
+      branch,
+      parent: str(item.parent) ?? trunk,
+      pr: typeof item.pr === "number" ? item.pr : null,
+      lastHead: str(item.lastHead),
+      lastParentHead: str(item.lastParentHead),
+      patchId: str(item.patchId),
+      merged,
+      ...(isRecord(item.pendingRestack) &&
+      str(item.pendingRestack.from) &&
+      str(item.pendingRestack.tip) &&
+      str(item.pendingRestack.onto)
+        ? {
+            pendingRestack: {
+              from: str(item.pendingRestack.from) as string,
+              tip: str(item.pendingRestack.tip) as string,
+              onto: str(item.pendingRestack.onto) as string,
+            },
+          }
+        : {}),
+    });
+  }
+  return {
+    v: typeof raw.v === "number" ? raw.v : STACK_VERSION,
+    name,
+    trunk,
+    forge: raw.forge === "github" || raw.forge === "gitlab" ? raw.forge : null,
+    repo: str(raw.repo),
+    branches,
+    updatedAt: str(raw.updatedAt) ?? "",
+  };
+}
+
+export function readStack(cwd: string, name: string): StackResult<StackFile | null> {
+  const dir = stacksDir(cwd);
+  if (!dir.ok) return dir;
+  const file = path.join(dir.data, fileFor(name));
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { ok: true, data: null };
+    return stackFail("unavailable", `cannot read ${file}: ${(error as Error).message}`);
+  }
+  let parsed: StackFile | null = null;
+  try {
+    parsed = parseStack(JSON.parse(text));
+  } catch {
+    parsed = null;
+  }
+  return parsed
+    ? { ok: true, data: parsed }
+    : stackFail(
+        "failed",
+        `stack file ${file} is not a valid stack`,
+        `workit stack plan --name ${name} <branch…>  # rebuild it`,
+      );
+}
+
+/** Atomic write (temp file + rename) so a reader never sees half a stack. */
+export function writeStack(
+  cwd: string,
+  stack: StackFile,
+  now: Date = new Date(),
+): StackResult<void> {
+  const dir = stacksDir(cwd);
+  if (!dir.ok) return dir;
+  const file = path.join(dir.data, fileFor(stack.name));
+  const temp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.mkdirSync(dir.data, { recursive: true });
+    stack.updatedAt = now.toISOString();
+    fs.writeFileSync(temp, `${JSON.stringify(stack, null, 2)}\n`);
+    fs.renameSync(temp, file);
+    return { ok: true, data: undefined };
+  } catch (error) {
+    fs.rmSync(temp, { force: true });
+    return stackFail("unavailable", `cannot write ${file}: ${(error as Error).message}`);
+  }
+}
+
+/** Every stack in the store, sorted by name (unreadable files are skipped). */
+export function listStacks(cwd: string): StackResult<StackFile[]> {
+  const dir = stacksDir(cwd);
+  if (!dir.ok) return dir;
+  let names: string[] = [];
+  try {
+    names = fs.readdirSync(dir.data).filter((name) => name.endsWith(".json"));
+  } catch {
+    return { ok: true, data: [] };
+  }
+  const out: StackFile[] = [];
+  for (const name of names) {
+    let parsed: StackFile | null = null;
+    try {
+      parsed = parseStack(JSON.parse(fs.readFileSync(path.join(dir.data, name), "utf8")));
+    } catch {
+      parsed = null;
+    }
+    // Only files at the name's own path count (a renamed copy is ignored).
+    if (parsed && fileFor(parsed.name) === name) out.push(parsed);
+  }
+  return {
+    ok: true,
+    data: out.toSorted((a, b) => a.name.localeCompare(b.name)),
+  };
+}
+
+/** The stack `name`, else the one holding the current branch, else the only one. */
+export function selectStack(cwd: string, name: string | null): StackResult<StackFile> {
+  if (name !== null && !validName(name))
+    return stackFail("invalid_input", "a stack name must be 1-200 printable characters");
+  if (name) {
+    const read = readStack(cwd, name);
+    if (!read.ok) return read;
+    return read.data
+      ? { ok: true, data: read.data }
+      : stackFail(
+          "not_found",
+          `no stack named ${name}`,
+          `workit stack plan --name ${name} <branch…>`,
+        );
+  }
+  const all = listStacks(cwd);
+  if (!all.ok) return all;
+  const branch = currentBranch(cwd);
+  const holding = all.data.filter((stack) =>
+    stack.branches.some((entry) => entry.branch === branch),
+  );
+  if (holding.length === 1) return { ok: true, data: holding[0] };
+  if (holding.length === 0 && all.data.length === 1) return { ok: true, data: all.data[0] };
+  return stackFail(
+    "not_found",
+    holding.length > 1 || all.data.length > 1
+      ? `several stacks match; pick one (${(holding.length > 1 ? holding : all.data).map((stack) => stack.name).join(", ")})`
+      : "no stack is planned here",
+    holding.length > 1 || all.data.length > 1
+      ? "pass --name <stack>"
+      : "workit stack plan [<branch>…]  # from the current branch chain by default",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// single writer
+
+const LOCK_WAIT_MS = 2_000;
+/** The holder touches its owner file this often while it works (land waits for CI). */
+const HEARTBEAT_MS = 20_000;
+/** A lock whose owner has not touched it for this long is stale, whoever holds it. */
+const HEARTBEAT_STALE_MS = 2 * 60_000;
+/** A lock directory without a readable owner is debris after this (a holder writes it at once). */
+const OWNERLESS_STALE_MS = 30_000;
+
+const OWNER = "owner";
+
+type LockOwner = {
+  pid: number;
+  processStart: string | null;
+  host: string;
+  nonce: string;
+};
+
+const readOwner = (lock: string): { raw: string | null; age: number | null } => {
+  let raw: string | null = null;
+  try {
+    raw = fs.readFileSync(path.join(lock, OWNER), "utf8");
+  } catch {
+    raw = null;
+  }
+  let age: number | null = null;
+  for (const target of [path.join(lock, OWNER), lock])
+    try {
+      age = Date.now() - fs.statSync(target).mtimeMs;
+      break;
+    } catch {
+      // next
+    }
+  return { raw, age };
+};
+
+/**
+ * Is the lock's holder gone? Same machine (host + pid namespace + boot, the
+ * S1 store-lock identity): the pid is dead or reused. Any holder whose
+ * heartbeat is older than HEARTBEAT_STALE_MS. A lock with no readable owner
+ * once it is OWNERLESS_STALE_MS old.
+ */
+export function stackLockStale(raw: string | null, age: number | null): boolean {
+  let payload: unknown = null;
+  try {
+    payload = raw ? JSON.parse(raw) : null;
+  } catch {
+    payload = null;
+  }
+  if (payload === null) return age !== null && age > OWNERLESS_STALE_MS;
+  const owner = classifyLockOwner(payload, age);
+  // A verifiably live holder on this machine is never stale, however old its
+  // heartbeat (a long synchronous rebase cannot heartbeat).
+  if (owner.state === "live") return false;
+  if (owner.state === "stale") return true;
+  // Another host or pid namespace: only its heartbeat can tell.
+  return age !== null && age > HEARTBEAT_STALE_MS;
+}
+
+/** Touch the held stack lock's owner file (called between git/forge steps). */
+let activeBeat: (() => void) | null = null;
+export const touchStackLock = (): void => activeBeat?.();
+
+function takeLock(lock: string): LockOwner | null {
+  try {
+    fs.mkdirSync(lock);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return null;
+    throw error;
+  }
+  const owner: LockOwner = {
+    pid: process.pid,
+    processStart: processStartOf(process.pid),
+    host: localLockHost(),
+    nonce: randomBytes(8).toString("hex"),
+  };
+  fs.writeFileSync(path.join(lock, OWNER), JSON.stringify(owner));
+  return owner;
+}
+
+/** Move a stale lock aside, only if it still holds what was judged stale. */
+function reapLock(lock: string, observed: string | null): boolean {
+  const tomb = `${lock}.reap-${randomBytes(6).toString("hex")}`;
+  try {
+    fs.renameSync(lock, tomb);
+  } catch {
+    return false;
+  }
+  if (readOwner(tomb).raw === observed) {
+    fs.rmSync(tomb, { recursive: true, force: true });
+    return true;
+  }
+  try {
+    fs.renameSync(tomb, lock);
+  } catch {
+    fs.rmSync(tomb, { recursive: true, force: true });
+  }
+  return false;
+}
+
+function releaseLock(lock: string, owner: LockOwner): void {
+  const { raw } = readOwner(lock);
+  if (raw !== JSON.stringify(owner)) return;
+  const tomb = `${lock}.release-${randomBytes(6).toString("hex")}`;
+  try {
+    fs.renameSync(lock, tomb);
+    fs.rmSync(tomb, { recursive: true, force: true });
+  } catch {
+    // someone reaped it
+  }
+}
+
+/**
+ * Hold the stack's lock for `fn`. A lock held by a live process answers
+ * `busy` after LOCK_WAIT_MS (retryable). The holder heartbeats while it works,
+ * so a lock left by a dead process, a crashed host or an aborted mkdir is
+ * reclaimed (see stackLockStale) without ever stealing a working holder's.
+ */
+export async function withStackLock<T>(
+  cwd: string,
+  name: string,
+  fn: () => Promise<StackResult<T>>,
+  waitMs: number = LOCK_WAIT_MS,
+): Promise<StackResult<T>> {
+  const dir = stacksDir(cwd);
+  if (!dir.ok) return dir;
+  if (!validName(name))
+    return stackFail("invalid_input", "a stack name must be 1-200 printable characters");
+  const lock = path.join(dir.data, `${fileFor(name)}.lock`);
+  try {
+    fs.mkdirSync(dir.data, { recursive: true });
+  } catch (error) {
+    return stackFail("unavailable", `cannot create ${dir.data}: ${(error as Error).message}`);
+  }
+  const deadline = Date.now() + waitMs;
+  let owner: LockOwner | null = null;
+  for (;;) {
+    owner = takeLock(lock);
+    if (owner) break;
+    const seen = readOwner(lock);
+    if (stackLockStale(seen.raw, seen.age) && reapLock(lock, seen.raw)) continue;
+    if (Date.now() >= deadline) {
+      let holder: Partial<LockOwner> = {};
+      try {
+        holder = seen.raw ? (JSON.parse(seen.raw) as LockOwner) : {};
+      } catch {
+        holder = {};
+      }
+      return stackFail(
+        "busy",
+        `stack ${name} is busy: another workit stack command${holder.pid ? ` (pid ${holder.pid} on ${holder.host ?? "?"})` : ""} holds ${lock}`,
+        "retry when it finishes; a lock whose holder stopped heartbeating is reclaimed automatically",
+        { lock, pid: holder.pid ?? null, host: holder.host ?? null },
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  const held = owner;
+  const touch = () => {
+    try {
+      const now = new Date();
+      fs.utimesSync(path.join(lock, OWNER), now, now);
+    } catch {
+      // lost the lock; the release below is a no-op then
+    }
+  };
+  const beat = setInterval(touch, HEARTBEAT_MS);
+  beat.unref?.();
+  const previous = activeBeat;
+  activeBeat = touch;
+  try {
+    return await fn();
+  } finally {
+    activeBeat = previous;
+    clearInterval(beat);
+    releaseLock(lock, held);
+  }
+}
+
+/**
+ * Hold the stack's lock for a synchronous `fn` without waiting: a live holder
+ * answers `busy` at once; a stale lock is reclaimed first.
+ */
+export function withStackLockSync<T>(
+  cwd: string,
+  name: string,
+  fn: () => StackResult<T>,
+): StackResult<T> {
+  const dir = stacksDir(cwd);
+  if (!dir.ok) return dir;
+  if (!validName(name))
+    return stackFail("invalid_input", "a stack name must be 1-200 printable characters");
+  const lock = path.join(dir.data, `${fileFor(name)}.lock`);
+  try {
+    fs.mkdirSync(dir.data, { recursive: true });
+  } catch (error) {
+    return stackFail("unavailable", `cannot create ${dir.data}: ${(error as Error).message}`);
+  }
+  let owner = takeLock(lock);
+  if (!owner) {
+    const seen = readOwner(lock);
+    if (stackLockStale(seen.raw, seen.age) && reapLock(lock, seen.raw)) owner = takeLock(lock);
+  }
+  if (!owner)
+    return stackFail(
+      "busy",
+      `stack ${name} is busy: another workit stack command holds ${lock}`,
+      "retry when it finishes",
+      { lock },
+    );
+  try {
+    return fn();
+  } finally {
+    releaseLock(lock, owner);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// plan
+
+export type PlanInput = {
+  name: string | null;
+  trunk: string;
+  /** Bottom (closest to trunk) first; empty: derive from the current branch. */
+  branches: string[];
+};
+
+export type PlanOutcome = {
+  stack: StackFile;
+  created: boolean;
+  /** Per branch: built on its parent's tip, and the PR base the forge reports. */
+  checks: Array<{
+    branch: string;
+    parent: string;
+    onParent: boolean;
+    pr: number | null;
+    prBase: string | null;
+    baseMatches: boolean | null;
+  }>;
+  notes: string[];
+};
+
+const remoteFor = (cwd: string, resolved: ResolvedForge | null, trunk: string): string =>
+  resolved?.baseRemote ?? pushRemoteName(cwd, trunk) ?? "origin";
+
+/** The trunk tip: the remote-tracking ref when present, else the local branch. */
+const trunkTip = (cwd: string, remote: string, trunk: string): string | null =>
+  resolveRef(cwd, `refs/remotes/${remote}/${trunk}`) ?? branchTip(cwd, trunk);
+
+/**
+ * The current branch and the local branches it is stacked on: every local
+ * branch (not the trunk) whose tip is a proper ancestor of HEAD and not
+ * already on the trunk, ordered bottom-up.
+ */
+function deriveChain(cwd: string, trunk: string, base: string): StackResult<string[]> {
+  const branch = currentBranch(cwd);
+  if (!branch || branch === trunk)
+    return stackFail(
+      "invalid_input",
+      branch ? `you are on the trunk ${trunk}` : "HEAD is detached",
+      "switch to the top branch of the stack, or name the branches: workit stack plan <bottom> … <top>",
+    );
+  const refs = gitRun(cwd, [
+    "for-each-ref",
+    "--format=%(refname:short) %(objectname)",
+    "refs/heads",
+  ]);
+  const head = branchTip(cwd, branch);
+  if (!refs.ok || !head) return stackFail("failed", "cannot list local branches");
+  const below: Array<{ branch: string; depth: number }> = [];
+  for (const line of refs.stdout.split("\n")) {
+    const [name, sha] = line.trim().split(" ");
+    if (!name || !sha || name === branch || name === trunk) continue;
+    if (sha === head || isAncestor(cwd, sha, base) || !isAncestor(cwd, sha, head)) continue;
+    const count = gitRun(cwd, ["rev-list", "--count", `${base}..${sha}`]);
+    below.push({ branch: name, depth: Number(count.stdout.trim()) || 0 });
+  }
+  // Branches sharing one tip are ambiguous; keep the order stable by name.
+  below.sort((a, b) => a.depth - b.depth || a.branch.localeCompare(b.branch));
+  return { ok: true, data: [...below.map((entry) => entry.branch), branch] };
+}
+
+export function planStack(
+  cwd: string,
+  resolved: ResolvedForge | null,
+  input: PlanInput,
+  existing: StackFile | null,
+): StackResult<PlanOutcome> {
+  const remote = remoteFor(cwd, resolved, input.trunk);
+  const notes: string[] = [];
+  const trunkSha = trunkTip(cwd, remote, input.trunk);
+  if (!trunkSha)
+    return stackFail(
+      "not_found",
+      `trunk ${input.trunk} is not available locally`,
+      `git fetch ${remote} ${input.trunk}  # or pass --trunk <branch>`,
+    );
+  let branches = input.branches;
+  if (branches.length === 0) {
+    if (existing) branches = existing.branches.map((entry) => entry.branch);
+    else {
+      const derived = deriveChain(cwd, input.trunk, trunkSha);
+      if (!derived.ok) return derived;
+      branches = derived.data;
+    }
+  }
+  if (new Set(branches).size !== branches.length)
+    return stackFail("invalid_input", "a branch is listed twice");
+  if (branches.includes(input.trunk))
+    return stackFail("invalid_input", `the trunk ${input.trunk} cannot be in the stack`);
+  for (const branch of branches)
+    if (!safeRef(branch) || !branchTip(cwd, branch))
+      return stackFail(
+        "not_found",
+        `branch ${branch} does not exist locally`,
+        `git switch ${branch}  # or git branch ${branch} ${remote}/${branch}`,
+      );
+
+  const previous = new Map((existing?.branches ?? []).map((entry) => [entry.branch, entry]));
+  const entries: StackEntry[] = [];
+  const checks: PlanOutcome["checks"] = [];
+  let parent = input.trunk;
+  let parentSha = trunkSha;
+  for (const branch of branches) {
+    const tip = branchTip(cwd, branch) as string;
+    const before = previous.get(branch);
+    // A recorded merge is re-checked, never trusted: the PR must read merged,
+    // or (no PR) the branch must have its own commits and be on the trunk.
+    if (before?.merged) {
+      let still = false;
+      if (before.pr && resolved) {
+        const status = resolved.forge.prStatus(before.pr);
+        still = status.ok && status.data.state === "merged";
+      } else
+        still =
+          hasOwnCommits(cwd, tip, before.lastParentHead) &&
+          (isAncestor(cwd, tip, trunkSha) ||
+            squashedOnTrunk(cwd, before.lastParentHead as string, tip, trunkSha));
+      if (still) {
+        entries.push(before);
+        continue;
+      }
+      notes.push(`${branch} was recorded as merged but is not; it is back in the stack`);
+    }
+    const onParent = isAncestor(cwd, parentSha, tip);
+    let builtOn = parentSha;
+    if (!onParent) {
+      if (before?.lastParentHead && isAncestor(cwd, before.lastParentHead, tip))
+        // What it was last built on still is in its history: keep it, so sync
+        // replays only this branch's own commits.
+        builtOn = before.lastParentHead;
+      else {
+        const old =
+          oldParentVersion(cwd, parent, parentSha, tip) ?? oldParentLookalike(cwd, parentSha, tip);
+        if (old)
+          return stackFail(
+            "blocked",
+            `parent_rewritten: ${branch} is built on an older version of ${parent} (${old.slice(0, 12)}); replaying it from the merge base would bring the old ${parent} commits back`,
+            `git rebase --onto ${parent} ${old} ${branch}  # moves only ${branch}'s own commits; then workit stack plan`,
+            { branch, parent, oldParentTip: old },
+          );
+        builtOn = mergeBase(cwd, parentSha, tip) ?? parentSha;
+        notes.push(
+          `${branch} is not on ${parent} and has no recorded base; sync will replay every commit since their merge base ${builtOn.slice(0, 12)}`,
+        );
+      }
+    }
+    let pr = before?.pr ?? null;
+    let prBase: string | null = null;
+    if (resolved) {
+      const found = resolved.forge.findPr(branch, {
+        owner: resolved.headRepo.split("/")[0] ?? null,
+        projectId: resolved.headProjectId,
+        sha: tip,
+      });
+      if (found.ok && found.data && found.data.state === "open") {
+        pr = found.data.number;
+        const status = resolved.forge.prStatus(pr);
+        if (status.ok) prBase = status.data.base;
+      } else if (!found.ok) notes.push(`${branch}: PR lookup failed (${found.error})`);
+    }
+    entries.push({
+      ...(before?.pendingRestack ? { pendingRestack: before.pendingRestack } : {}),
+      branch,
+      parent,
+      pr,
+      lastHead: tip,
+      lastParentHead: builtOn,
+      patchId: patchId(cwd, builtOn, tip),
+      merged: null,
+    });
+    checks.push({
+      branch,
+      parent,
+      onParent,
+      pr,
+      prBase,
+      baseMatches: prBase === null ? null : prBase === parent,
+    });
+    if (!onParent) notes.push(`${branch} is not on ${parent}; workit stack sync rebases it`);
+    if (prBase !== null && prBase !== parent)
+      notes.push(
+        `${branch}: PR base is ${prBase}, the stack says ${parent}; workit stack sync retargets it`,
+      );
+    parent = branch;
+    parentSha = tip;
+  }
+  if (!resolved) notes.push("forge not resolved: PR numbers were not looked up");
+  const name = input.name ?? existing?.name ?? branches[0];
+  return {
+    ok: true,
+    data: {
+      stack: {
+        v: STACK_VERSION,
+        name,
+        trunk: input.trunk,
+        forge: resolved?.forge.kind ?? existing?.forge ?? null,
+        repo: resolved?.forge.repo ?? existing?.repo ?? null,
+        branches: entries,
+        updatedAt: "",
+      },
+      created: existing === null,
+      checks,
+      notes,
+    },
+  };
+}
+
+/**
+ * Record (or refresh) stack `name` as `branches`, bottom first, without the
+ * forge: `fanout worktree create` calls it when a slice starts on its parent
+ * slice's branch, so `stack sync` can later replay only the child's commits.
+ */
+export function recordStack(
+  cwd: string,
+  input: { name: string; trunk: string; branches: string[] },
+): StackResult<{ stack: StackFile; created: boolean }> {
+  return withStackLockSync(cwd, input.name, () => {
+    const existing = readStack(cwd, input.name);
+    if (!existing.ok) return existing;
+    const planned = planStack(
+      cwd,
+      null,
+      { name: input.name, trunk: input.trunk, branches: input.branches },
+      existing.data,
+    );
+    if (!planned.ok) return planned;
+    const written = writeStack(cwd, planned.data.stack);
+    if (!written.ok) return written;
+    return { ok: true, data: { stack: planned.data.stack, created: planned.data.created } };
+  });
+}
+
+/** `tip` has commits of its own beyond `base` (an empty branch is not "merged"). */
+function hasOwnCommits(cwd: string, tip: string, base: string | null): boolean {
+  if (!base) return false;
+  return tip !== base && !isAncestor(cwd, tip, base);
+}
+
+/**
+ * An earlier tip of `parent` (from its reflog) that `child` is built on but
+ * the current parent no longer contains: the parent was rewritten (amend,
+ * rebase) under the child.
+ */
+function oldParentVersion(
+  cwd: string,
+  parent: string,
+  parentSha: string,
+  child: string,
+): string | null {
+  if (!safeRef(parent)) return null;
+  const log = gitRun(cwd, ["reflog", "show", "--format=%H", `refs/heads/${parent}`, "--"]);
+  if (!log.ok) return null;
+  for (const sha of log.stdout.split("\n").map((line) => line.trim())) {
+    if (!sha || sha === parentSha) continue;
+    if (isAncestor(cwd, sha, child) && !isAncestor(cwd, sha, parentSha)) return sha;
+  }
+  return null;
+}
+
+type CommitKey = { sha: string; subject: string; patch: string | null };
+
+/** Non-merge commits of `range`, oldest first, with their stable patch-ids. */
+function commitKeys(cwd: string, range: string): CommitKey[] {
+  const log = gitRun(cwd, ["log", "--reverse", "--no-merges", "--format=%H%x00%s", range]);
+  if (!log.ok) return [];
+  const patches = new Map<string, string>();
+  const diff = gitRun(cwd, ["log", "--no-merges", "-p", "--format=commit %H", range]);
+  if (diff.ok && diff.stdout.trim()) {
+    const ids = spawnSync("git", ["patch-id", "--stable"], {
+      cwd,
+      input: diff.stdout,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    for (const line of (ids.stdout ?? "").split("\n")) {
+      const [patch, sha] = line.trim().split(/\s+/u);
+      if (patch && sha) patches.set(sha, patch);
+    }
+  }
+  return log.stdout
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, subject = ""] = line.split("\0");
+      return { sha, subject, patch: patches.get(sha) ?? null };
+    });
+}
+
+/**
+ * Without a reflog (expired, fresh clone): commits of `child` since its merge
+ * base with the parent that look like the parent's own (same patch-id or same
+ * subject as a commit the parent now has instead). The newest such commit is
+ * where the old parent version ended.
+ */
+function oldParentLookalike(cwd: string, parentSha: string, child: string): string | null {
+  const base = mergeBase(cwd, parentSha, child);
+  if (!base) return null;
+  const parentCommits = commitKeys(cwd, `${base}..${parentSha}`);
+  if (parentCommits.length === 0) return null;
+  const patches = new Set(parentCommits.map((commit) => commit.patch).filter(Boolean));
+  const subjects = new Set(parentCommits.map((commit) => commit.subject).filter(Boolean));
+  let last: string | null = null;
+  for (const commit of commitKeys(cwd, `${base}..${child}`))
+    if ((commit.patch && patches.has(commit.patch)) || subjects.has(commit.subject))
+      last = commit.sha;
+  return last;
+}
+
+// ---------------------------------------------------------------------------
+// status
+
+export type StackVerdict = "READY" | "WAITING" | "ADVANCE" | "COMPLETE";
+
+export type StopReason =
+  | "no_pr"
+  | "pr_mismatch"
+  | "pr_closed"
+  | "base_not_trunk"
+  | "not_ready"
+  | "no_verdict"
+  | "needs_verdict"
+  | "failed_verdict"
+  | "grant_required"
+  | "max_reached"
+  | "merge_refused"
+  | "waiver_refused"
+  | "head_unverified";
+
+export type BranchStatus = {
+  branch: string;
+  parent: string;
+  pr: number | null;
+  merged: boolean;
+  head: string | null;
+  /** The parent's (or trunk's) tip is in this branch's history. */
+  onParent: boolean | null;
+  prState: PrState | null;
+  prBase: string | null;
+  baseMatches: boolean | null;
+  next: NextAction | null;
+  checks: ChecksState | null;
+  blockers: string[];
+  /**
+   * `accepted`: an accepted independent verdict; `satisfied`: what the land
+   * gate reads, the verdict the PR's review lane asks for (an accepted
+   * independent one outside `verification: proportional`).
+   */
+  verdict: {
+    accepted: boolean;
+    satisfied: boolean;
+    basis: VerdictBasis;
+    reasons: string[];
+    verdictId: string | null;
+    lane: ReviewLane | null;
+    need: LaneNeed;
+    /** The verdict higher in the stack that covers this branch, when it has none of its own. */
+    cover: StackCover | null;
+  };
+};
+
+export type Qualification =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: StopReason;
+      detail: string;
+      unblock: string;
+      ready: boolean;
+    };
+
+export type StatusOutcome = {
+  name: string;
+  trunk: string;
+  verdict: StackVerdict;
+  reason: string | null;
+  next: string | null;
+  branches: BranchStatus[];
+};
+
+type Ctx = {
+  cwd: string;
+  resolved: ResolvedForge;
+  actor: LedgerActor;
+  sleep: Sleep;
+};
+
+const noun = (resolved: ResolvedForge, pr: number): string =>
+  `${resolved.forge.kind === "github" ? "PR #" : "MR !"}${pr}`;
+
+function statusDoc(ctx: Ctx, pr: number): ForgeResult<PrStatusDoc> {
+  const status = ctx.resolved.forge.prStatus(pr);
+  if (!status.ok) return status;
+  return buildStatusDoc(ctx.cwd, ctx.resolved, status.data, {
+    logLines: 0,
+    behind: false,
+  });
+}
+
+/**
+ * The recorded PR number must still be this branch's PR from our head
+ * repository: the forge reports this branch as its head, and looking the
+ * branch up (owner/project matched, as `pr create` does) finds this number.
+ */
+function prBinding(ctx: Pick<Ctx, "resolved">, entry: StackEntry, doc: PrStatusDoc): string | null {
+  const label = noun(ctx.resolved, entry.pr as number);
+  if (doc.head.branch !== entry.branch)
+    return `${label} is for ${doc.head.branch}, not ${entry.branch}`;
+  const found = ctx.resolved.forge.findPr(entry.branch, {
+    owner: ctx.resolved.headRepo.split("/")[0] ?? null,
+    projectId: ctx.resolved.headProjectId,
+    sha: null,
+  });
+  if (!found.ok) return `cannot confirm ${label} belongs to ${entry.branch}: ${found.error}`;
+  if (found.data?.number !== entry.pr)
+    return `${entry.branch} from ${ctx.resolved.headRepo} is ${found.data ? noun(ctx.resolved, found.data.number) : "without a PR"}, not ${label}`;
+  return null;
+}
+
+/** The stack was planned against this forge repository. */
+export function repoMismatch(ctx: Pick<Ctx, "resolved">, stack: StackFile): StackError | null {
+  const { kind, repo } = ctx.resolved.forge;
+  if ((stack.repo && stack.repo !== repo) || (stack.forge && stack.forge !== kind))
+    return stackFail(
+      "blocked",
+      `repo_mismatch: stack ${stack.name} was planned on ${stack.forge ?? "?"} ${stack.repo ?? "?"}, but this checkout resolves to ${kind} ${repo}`,
+      `workit stack plan --name ${stack.name} <branch…>  # re-plan it here, or run from the right checkout`,
+      {
+        planned: { forge: stack.forge, repo: stack.repo },
+        resolved: { forge: kind, repo },
+      },
+    );
+  return null;
+}
+
+const verdictOf = (
+  cwd: string,
+  branch: string,
+  rows: readonly ReadRow[],
+  doc: PrStatusDoc | null,
+): BranchStatus["verdict"] => {
+  // A lower branch may be covered by the verdict at the top of the stack (#334).
+  const check = checkVerdictsCovered(cwd, branch, rows);
+  // Without a PR there is no base to diff against: the gate stays independent.
+  const gate = doc ? prLaneGate(cwd, check, { branch, base: doc.base, head: doc.head.sha }) : null;
+  return {
+    accepted: check.accepted.accepted,
+    satisfied: gate ? gate.satisfied : check.accepted.accepted,
+    basis: check.current.basis,
+    reasons: check.accepted.reasons,
+    verdictId: gate
+      ? gate.verdictId
+      : typeof check.accepted.verdict?.id === "string" && check.accepted.accepted
+        ? check.accepted.verdict.id
+        : null,
+    lane: gate?.lane.lane ?? null,
+    need: gate?.need ?? "non-author",
+    cover: check.cover,
+  };
+};
+
+/**
+ * Does the root-most open PR qualify to land? Order: a PR exists and is
+ * open, it targets the trunk, the forge says READY, an accepted verdict
+ * covers the head (unless `bypass`: `--unverified` under `merge: true`), and
+ * the grant allows merging. `ready` says everything but the grant holds
+ * ("verified, ready").
+ */
+export function qualify(
+  ctx: Pick<Ctx, "cwd" | "resolved">,
+  stack: StackFile,
+  entry: StackEntry,
+  doc: PrStatusDoc | null,
+  verdict: BranchStatus["verdict"],
+  grant: GrantDecision,
+  /** Why the PR number no longer belongs to this branch (null: it does). */
+  binding: string | null = null,
+  /** `stack land --unverified`: skip the verdict where the grant allows it. */
+  bypass = false,
+): Qualification {
+  const label = entry.pr ? noun(ctx.resolved, entry.pr) : entry.branch;
+  const stop = (reason: StopReason, detail: string, unblock: string, ready = false) => ({
+    ok: false as const,
+    reason,
+    detail,
+    unblock,
+    ready,
+  });
+  if (!entry.pr || !doc)
+    return stop(
+      "no_pr",
+      `${entry.branch} has no open PR`,
+      `git switch ${entry.branch} && workit pr create --fill --base ${entry.parent}  # then workit stack plan`,
+    );
+  if (binding)
+    return stop(
+      "pr_mismatch",
+      binding,
+      `workit stack plan --name ${stack.name}  # re-resolve the PRs`,
+    );
+  if (doc.state !== "open")
+    return stop(
+      "pr_closed",
+      `${label} is ${doc.state}`,
+      "reopen it, or drop the branch from the stack: workit stack plan <branches…>",
+    );
+  if (doc.base !== stack.trunk)
+    return stop(
+      "base_not_trunk",
+      `${label} targets ${doc.base}, not ${stack.trunk}`,
+      "workit stack sync",
+    );
+  if (doc.next !== "READY")
+    return stop(
+      "not_ready",
+      `${label} is ${doc.next}${doc.blockers.length ? ` (${doc.blockers.join(", ")})` : ""}`,
+      doc.next === "WAITING_CI"
+        ? `workit ci wait --pr ${entry.pr}`
+        : doc.blockers.includes("mergeability_unknown")
+          ? `the forge is still computing mergeability; wait a minute, then workit stack land again (workit pr status --pr ${entry.pr} shows when it settles)`
+          : `workit pr status --pr ${entry.pr}`,
+    );
+  const allowUnverified = grant.allowed && grant.allowUnverified;
+  // The bypass covers a missing verdict, never a rejection.
+  if (bypass && allowUnverified && verdict.reasons.includes("failing_verdict"))
+    return stop(
+      "failed_verdict",
+      `${label} has a current independent failed verdict for ${doc.head.sha.slice(0, 12)}; --unverified never lands over a rejection`,
+      "a new independent verdict on the head supersedes it",
+    );
+  if (!(bypass && allowUnverified) && !verdict.satisfied) {
+    const bypassHint = allowUnverified
+      ? `; or, only if the user asks to land unverified: workit stack land --unverified --reason "<why>"`
+      : "";
+    return stop(
+      verdict.reasons.includes("no_verdict") ? "no_verdict" : "needs_verdict",
+      verdict.need === "self"
+        ? `${label} has no verdict for ${doc.head.sha.slice(0, 12)} (lane self: the author's own --self verdict is enough; ${verdict.reasons.join(", ") || "none"})`
+        : `${label} has no accepted independent verdict for ${doc.head.sha.slice(0, 12)}${verdict.lane && verdict.lane !== "none" ? ` (lane ${verdict.lane})` : ""} (${verdict.reasons.join(", ") || "none"})`,
+      verdict.need === "self"
+        ? `after an observed passing \`workit check test\`, the author runs: workit ledger verdict tests-verified --self --how "<what you ran>" --branch ${entry.branch}${bypassHint}`
+        : `an independent session verifies ${entry.branch} and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${entry.branch}${bypassHint}`,
+    );
+  }
+  if (!grant.allowed)
+    return stop(
+      "grant_required",
+      `${label} is verified and ready, but ${grant.error}`,
+      grant.unblock,
+      true,
+    );
+  return { ok: true };
+}
+
+export function stackStatus(ctx: Ctx, stack: StackFile): StackResult<StatusOutcome> {
+  const mismatch = repoMismatch(ctx, stack);
+  if (mismatch) return mismatch;
+  const ledger = readLedger(ctx.cwd, { integrity: true });
+  if (!ledger.ok) return stackFail(ledger.code, ledger.error, ledger.unblock);
+  const remote = remoteFor(ctx.cwd, ctx.resolved, stack.trunk);
+  const trunkSha = trunkTip(ctx.cwd, remote, stack.trunk);
+  const grant = requireGrant(ctx.cwd, "merge", { target: baseTarget(ctx.resolved) });
+  const branches: BranchStatus[] = [];
+  let verdict: StackVerdict | null = null;
+  let reason: string | null = null;
+  let next: string | null = null;
+  let parentName = stack.trunk;
+  let parentSha = trunkSha;
+  let mergedSeen = false;
+  for (const entry of stack.branches) {
+    let doc: PrStatusDoc | null = null;
+    if (entry.pr) {
+      const read = statusDoc(ctx, entry.pr);
+      if (!read.ok) return fromForge(read);
+      doc = read.data;
+    }
+    const merged = entry.merged !== null || doc?.state === "merged";
+    const head = branchTip(ctx.cwd, entry.branch);
+    const row: BranchStatus = {
+      branch: entry.branch,
+      parent: parentName,
+      pr: entry.pr,
+      merged,
+      head,
+      onParent: merged || !head || !parentSha ? null : isAncestor(ctx.cwd, parentSha, head),
+      prState: doc?.state ?? null,
+      prBase: doc?.base ?? null,
+      baseMatches: doc && !merged ? doc.base === parentName : null,
+      next: doc?.next ?? null,
+      checks: doc?.checks.state ?? null,
+      blockers: doc?.blockers ?? [],
+      verdict: merged
+        ? {
+            accepted: true,
+            satisfied: true,
+            basis: "none",
+            reasons: [],
+            verdictId: null,
+            lane: null,
+            need: "non-author",
+            cover: null,
+          }
+        : verdictOf(ctx.cwd, entry.branch, ledger.value.rows, doc),
+    };
+    branches.push(row);
+    if (merged) {
+      mergedSeen = true;
+      continue;
+    }
+    if (verdict === null) {
+      // The root-most open branch decides the stack's verdict.
+      const stale = row.onParent === false || row.baseMatches === false;
+      if (mergedSeen && stale) {
+        verdict = "ADVANCE";
+        reason = "a parent merged; the rest is not restacked or retargeted yet";
+        next = "workit stack sync";
+      } else {
+        const q = qualify(
+          ctx,
+          stack,
+          entry,
+          doc,
+          row.verdict,
+          grant,
+          doc ? prBinding(ctx, entry, doc) : null,
+        );
+        if (q.ok) {
+          verdict = "READY";
+          next = "workit stack land";
+        } else {
+          verdict = "WAITING";
+          reason = `${q.reason}: ${q.detail}`;
+          next = q.unblock;
+        }
+      }
+    }
+    parentName = entry.branch;
+    parentSha = head;
+  }
+  return {
+    ok: true,
+    data: {
+      name: stack.name,
+      trunk: stack.trunk,
+      verdict: verdict ?? "COMPLETE",
+      reason,
+      next,
+      branches,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// sync
+
+export type SyncOptions = {
+  /** Push and retarget (false: only rebase locally). */
+  publish: boolean;
+  dryRun: boolean;
+  /** Process only the first N unmerged branches (land moves just the new root). */
+  limit?: number;
+  /** Branches whose changed restack may be pushed anyway; never used by land. */
+  force?: ReadonlySet<string>;
+};
+
+export type SyncStep = {
+  branch: string;
+  pr: number | null;
+  parent: string;
+  /** null: already on its parent. */
+  restack: {
+    from: string;
+    onto: string;
+    head: string | null;
+    carried: boolean | null;
+  } | null;
+  push: { pushed: boolean; forced: boolean; sha: string } | null;
+  retarget: { from: string; to: string } | null;
+};
+
+export type SyncOutcome = {
+  name: string;
+  dryRun: boolean;
+  merged: Array<{ branch: string; pr: number | null }>;
+  steps: SyncStep[];
+};
+
+type SyncState = {
+  /** PR status docs read during this run, by PR number. */
+  docs: Map<number, PrStatusDoc>;
+};
+
+/** Mark branches whose PR merged (or whose tip is on the trunk) as merged. */
+function detectMerged(
+  ctx: Ctx | null,
+  cwd: string,
+  stack: StackFile,
+  trunkSha: string,
+  state: SyncState,
+): StackResult<Array<{ branch: string; pr: number | null }>> {
+  const newly: Array<{ branch: string; pr: number | null }> = [];
+  for (const entry of stack.branches) {
+    if (entry.merged) continue;
+    let merged = false;
+    if (entry.pr && ctx) {
+      const read = statusDoc(ctx, entry.pr);
+      if (!read.ok) return fromForge(read);
+      if (read.data.head.branch !== entry.branch)
+        return stackFail(
+          "blocked",
+          `pr_mismatch: ${noun(ctx.resolved, entry.pr)} is for ${read.data.head.branch}, not ${entry.branch}`,
+          `workit stack plan --name ${stack.name}  # re-resolve the PRs`,
+          { branch: entry.branch, pr: entry.pr },
+        );
+      state.docs.set(entry.pr, read.data);
+      merged = read.data.state === "merged";
+    } else {
+      // Without a PR only git can tell: the tip is on the trunk, or its own
+      // change is one trunk commit (a squash merge). A branch with no commits
+      // of its own is empty, not merged.
+      const tip = branchTip(cwd, entry.branch);
+      merged =
+        tip !== null &&
+        hasOwnCommits(cwd, tip, entry.lastParentHead) &&
+        (isAncestor(cwd, tip, trunkSha) ||
+          squashedOnTrunk(cwd, entry.lastParentHead as string, tip, trunkSha));
+    }
+    if (merged) {
+      entry.merged = {
+        pr: entry.pr,
+        mergeSha: null,
+        at: new Date().toISOString(),
+      };
+      newly.push({ branch: entry.branch, pr: entry.pr });
+    }
+  }
+  return { ok: true, data: newly };
+}
+
+/** Trunk commits scanned for a squash merge at most. */
+const SQUASH_SCAN = 500;
+
+/**
+ * Whether `base..tip` landed on the trunk as one squash commit: its patch-id
+ * equals one trunk commit's since they forked (the trunk not touching the
+ * same lines in between). Squash merges never make the tip an ancestor.
+ */
+function squashedOnTrunk(cwd: string, base: string, tip: string, trunkSha: string): boolean {
+  const own = patchId(cwd, base, tip);
+  const fork = mergeBase(cwd, tip, trunkSha);
+  if (!own || !fork || fork === trunkSha) return false;
+  const log = gitRun(cwd, [
+    "log",
+    "--no-merges",
+    `--max-count=${SQUASH_SCAN}`,
+    "-p",
+    "--format=commit %H",
+    "-U3",
+    "--diff-algorithm=myers",
+    "--indent-heuristic",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--no-renames",
+    "--full-index",
+    "--src-prefix=a/",
+    "--dst-prefix=b/",
+    `${fork}..${trunkSha}`,
+    "--",
+  ]);
+  if (!log.ok || !log.stdout.trim()) return false;
+  const ids = spawnSync("git", ["patch-id", "--stable"], {
+    cwd,
+    input: log.stdout,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUTS.local,
+    windowsHide: true,
+  });
+  if (ids.status !== 0) return false;
+  return ids.stdout.split("\n").some((line) => line.split(" ")[0] === own);
+}
+
+/**
+ * Push `branch` through the S11 push: the grant, the protected-branch check
+ * and the lease. A rewrite is forced only with a lease on the tip the stack
+ * last saw (or workit's own recorded push), and only when that tip is in the
+ * branch's history or reflog (S11 `--force-if-includes` semantics).
+ */
+function pushBranch(
+  cwd: string,
+  actor: LedgerActor,
+  branch: string,
+  priorTip: string | null,
+): StackResult<{ pushed: boolean; forced: boolean; sha: string }> {
+  const plan = stackDeps.pushPlan(cwd, branch);
+  if (!plan.ok) return fromForge(plan);
+  const remote = remoteRefTip(cwd, plan.data.rawUrl, `refs/heads/${branch}`);
+  if (!remote.ok) return stackFail(remote.code, remote.error);
+  if (remote.sha === plan.data.sha)
+    return {
+      ok: true,
+      data: { pushed: false, forced: false, sha: plan.data.sha },
+    };
+  const grant = requireGrant(cwd, "push", {
+    forge: !plan.data.local,
+    target: () => pushTarget(cwd, plan.data.remote),
+  });
+  if (!grant.allowed)
+    return stackFail("blocked", grant.error, grant.unblock, {
+      reason: grant.reason,
+    });
+  const force = remote.sha !== null && !isAncestor(cwd, remote.sha, plan.data.sha);
+  const expect = !force
+    ? null
+    : remote.sha === priorTip
+      ? priorTip
+      : (recordedRemoteTip(cwd, plan.data) ?? null);
+  const pushed = executePush(cwd, plan.data, {
+    forceWithLease: force,
+    expect,
+    actor,
+  });
+  if (!pushed.ok) return { ...fromForge(pushed), data: { branch } };
+  return {
+    ok: true,
+    data: {
+      pushed: pushed.data.pushed,
+      forced: pushed.data.forced,
+      sha: plan.data.sha,
+    },
+  };
+}
+
+/**
+ * Bring every unmerged branch onto its effective parent (the nearest unmerged
+ * branch below it, else the trunk), push it and retarget its PR, in order.
+ * Writes the stack file after every branch, so a stop leaves the processed
+ * branches recorded and the rest untouched.
+ */
+export function syncStack(
+  cwd: string,
+  ctx: Ctx | null,
+  stack: StackFile,
+  options: SyncOptions,
+  actor: LedgerActor,
+): StackResult<SyncOutcome> {
+  const remote = remoteFor(cwd, ctx?.resolved ?? null, stack.trunk);
+  let observedTrunk: string | null = null;
+  if (!options.dryRun && safeRef(stack.trunk)) {
+    const fetched = fetchRefs(cwd, remote, [
+      `+refs/heads/${stack.trunk}:refs/remotes/${remote}/${stack.trunk}`,
+    ]);
+    if (!fetched.ok)
+      return stackFail(fetched.code, fetched.error, `git fetch ${remote} ${stack.trunk}`);
+  } else if (safeRef(stack.trunk)) {
+    // Dry run: read the remote trunk without moving any ref (objects by id only).
+    const remoteTrunk = remoteRefTip(cwd, remote, `refs/heads/${stack.trunk}`);
+    if (remoteTrunk.ok && remoteTrunk.sha) {
+      if (!hasCommit(cwd, remoteTrunk.sha)) fetchRefs(cwd, remote, [remoteTrunk.sha]);
+      if (hasCommit(cwd, remoteTrunk.sha)) observedTrunk = remoteTrunk.sha;
+    }
+  }
+  const trunkSha = observedTrunk ?? trunkTip(cwd, remote, stack.trunk);
+  if (!trunkSha)
+    return stackFail(
+      "not_found",
+      `trunk ${stack.trunk} is not available`,
+      `git fetch ${remote} ${stack.trunk}`,
+    );
+  if (ctx) {
+    const mismatch = repoMismatch(ctx, stack);
+    if (mismatch) return mismatch;
+  }
+  const state: SyncState = { docs: new Map() };
+  const merged = detectMerged(ctx, cwd, stack, trunkSha, state);
+  if (!merged.ok) return merged;
+
+  const outcome: SyncOutcome = {
+    name: stack.name,
+    dryRun: options.dryRun,
+    merged: merged.data,
+    steps: [],
+  };
+  pruneScratch(cwd);
+
+  let parent = { name: stack.trunk, tip: trunkSha as string | null };
+  let processed = 0;
+  for (const entry of stack.branches) {
+    if (entry.merged) continue;
+    if (options.limit !== undefined && processed >= options.limit) break;
+    processed += 1;
+    touchStackLock();
+    const tip = branchTip(cwd, entry.branch);
+    if (!tip)
+      return stackFail(
+        "not_found",
+        `stack branch ${entry.branch} does not exist locally`,
+        `git branch ${entry.branch} ${remote}/${entry.branch}  # then workit stack sync`,
+        { progress: outcome },
+      );
+    const step: SyncStep = {
+      branch: entry.branch,
+      pr: entry.pr,
+      parent: parent.name,
+      restack: null,
+      push: null,
+      retarget: null,
+    };
+    let newTip: string | null = tip;
+    const parentTip = parent.tip;
+    if (parentTip === null) {
+      // Dry run: the parent would be rewritten first, so this one moves too.
+      step.restack = {
+        from: entry.lastParentHead ?? "?",
+        onto: `${parent.name} (restacked)`,
+        head: null,
+        carried: null,
+      };
+      newTip = null;
+    } else if (!isAncestor(cwd, parentTip, tip)) {
+      const pending = entry.pendingRestack ?? null;
+      const from =
+        pending && isAncestor(cwd, pending.onto, tip)
+          ? pending.onto
+          : entry.lastParentHead && isAncestor(cwd, entry.lastParentHead, tip)
+            ? entry.lastParentHead
+            : (mergeBase(cwd, entry.lastParentHead ?? parentTip, tip) ?? parentTip);
+      if (options.dryRun) {
+        step.restack = { from, onto: parentTip, head: null, carried: null };
+        newTip = null;
+      } else {
+        touchStackLock();
+        // A plain rebase linearizes merges and drops their resolutions.
+        const merges = gitRun(cwd, ["rev-list", "--merges", `${from}..${tip}`]);
+        if (!merges.ok || merges.stdout.trim())
+          return stackFail(
+            "blocked",
+            `merge_commits: ${entry.branch} has merge commits since ${from.slice(0, 12)}; restacking would drop what they resolved`,
+            `git rebase --rebase-merges --onto ${parentTip} ${from} ${entry.branch}  # check the result, then: workit stack sync`,
+            {
+              branch: entry.branch,
+              merges: merges.stdout.trim().split("\n").filter(Boolean),
+              progress: outcome,
+            },
+          );
+        const owner = worktreeOf(cwd, entry.branch);
+        if (owner && rebaseInProgress(owner))
+          return stackFail(
+            "blocked",
+            `a rebase is in progress in ${owner}`,
+            `git -C ${owner} rebase --continue  # or --abort; then workit stack --cwd ${owner} sync`,
+            { conflict: entry.branch, worktree: owner, progress: outcome },
+          );
+        if (owner && trackedDirt(owner))
+          return stackFail(
+            "blocked",
+            `dirty_worktree: ${owner} has ${entry.branch} checked out with uncommitted changes; restacking needs it clean`,
+            `commit or stash the changes in ${owner}, then workit stack sync`,
+            { branch: entry.branch, worktree: owner, progress: outcome },
+          );
+        // Record what is being moved before moving it: a conflict or a
+        // timeout leaves this in the stack file for the next sync to check.
+        entry.pendingRestack = pending
+          ? { ...pending, onto: parentTip }
+          : { from, tip, onto: parentTip };
+        const recorded = writeStack(cwd, stack);
+        if (!recorded.ok) return recorded;
+        const rebased = stackDeps.adapter.restack(cwd, {
+          branch: entry.branch,
+          onto: parentTip,
+          from,
+        });
+        touchStackLock();
+        if (!rebased.ok) {
+          outcome.steps.push(step);
+          if (rebased.timedOut)
+            return stackFail(
+              "failed",
+              `timed_out: restacking ${entry.branch} onto ${parent.name}: ${rebased.error}`,
+              `finish or abort the rebase in ${rebased.worktree} (git rebase --continue | --abort), then workit stack sync  # slow hooks: raise WORKIT_STACK_REBASE_TIMEOUT_MS`,
+              {
+                reason: "timed_out",
+                branch: entry.branch,
+                worktree: rebased.worktree,
+                progress: outcome,
+              },
+            );
+          return rebased.conflict
+            ? stackFail(
+                "blocked",
+                `conflict restacking ${entry.branch} onto ${parent.name}: ${rebased.error}`,
+                `resolve the conflicts in ${rebased.worktree}, git rebase --continue, then workit stack sync  # or git rebase --abort`,
+                {
+                  conflict: entry.branch,
+                  worktree: rebased.worktree,
+                  progress: outcome,
+                },
+              )
+            : stackFail(
+                "failed",
+                `restacking ${entry.branch} failed: ${rebased.error}`,
+                undefined,
+                {
+                  branch: entry.branch,
+                  progress: outcome,
+                },
+              );
+        }
+        newTip = rebased.head;
+        step.restack = { from, onto: parentTip, head: newTip, carried: null };
+      }
+    }
+    if (!options.dryRun && newTip) {
+      // Content safety: what was moved must arrive as the same change. The
+      // comparison is between the commits actually rebased (`from..tip`, as
+      // recorded before the rebase, even across a conflict) and the result
+      // on the new base: the exact diff, and no commit dropped as empty or
+      // already applied. Otherwise nothing is pushed and the record stays.
+      const check =
+        entry.pendingRestack && parentTip && isAncestor(cwd, parentTip, newTip)
+          ? entry.pendingRestack
+          : null;
+      let forced = false;
+      if (check && parentTip) {
+        const before = {
+          d: diffHash(cwd, check.from, check.tip),
+          commits: commitCount(cwd, check.from, check.tip),
+        };
+        const after = {
+          d: diffHash(cwd, parentTip, newTip),
+          commits: commitCount(cwd, parentTip, newTip),
+        };
+        const sameContent = before.d !== null && before.d === after.d;
+        const dropped = Math.max(0, before.commits - after.commits);
+        if (!sameContent || dropped > 0) {
+          if (!options.force?.has(entry.branch)) {
+            outcome.steps.push(step);
+            const written = writeStack(cwd, stack);
+            if (!written.ok) return written;
+            return stackFail(
+              "blocked",
+              `content_changed: ${entry.branch} on ${parent.name} is not the same change it was on ${check.from.slice(0, 12)}${dropped ? ` (${dropped} commit${dropped === 1 ? "" : "s"} dropped as empty or already applied)` : ""}; nothing was pushed`,
+              `inspect: git range-diff ${check.from}..${check.tip} ${parentTip}..${newTip}  # if intended: workit stack sync --force ${entry.branch}; to undo: git branch -f ${entry.branch} ${check.tip}`,
+              {
+                reason: "content_changed",
+                branch: entry.branch,
+                before: {
+                  base: check.from,
+                  head: check.tip,
+                  commits: before.commits,
+                  stat: shortStat(cwd, check.from, check.tip),
+                },
+                after: {
+                  base: parentTip,
+                  head: newTip,
+                  commits: after.commits,
+                  stat: shortStat(cwd, parentTip, newTip),
+                },
+                dropped,
+                progress: outcome,
+              },
+            );
+          }
+          forced = true;
+        }
+        entry.pendingRestack = null;
+      }
+      // Verdict carry (S13): the last verified head vs the new one, each
+      // against its own base. Equal only for the same patch and exact diff.
+      const moved =
+        entry.lastHead !== null &&
+        entry.lastHead !== newTip &&
+        entry.lastParentHead !== null &&
+        parentTip !== null &&
+        parentTip !== entry.lastParentHead;
+      if (moved && parentTip) {
+        const fromBase = entry.lastParentHead as string;
+        const fromHead = entry.lastHead as string;
+        const keysBefore = rangeKeys(cwd, fromBase, fromHead);
+        const keysAfter = rangeKeys(cwd, parentTip, newTip);
+        const before = { p: keysBefore.patchId, d: keysBefore.diffHash };
+        const after = { p: keysAfter.patchId, d: keysAfter.diffHash };
+        const equal =
+          before.d !== null &&
+          before.d === after.d &&
+          before.p !== null &&
+          before.p === after.p &&
+          sameOwnChange(cwd, {
+            from: fromHead,
+            to: newTip,
+            fromBase,
+            toBase: parentTip,
+          });
+        appendObserved(cwd, {
+          type: "stack.restacked",
+          actor,
+          stack: stack.name,
+          branch: entry.branch,
+          head: newTip,
+          fromHead,
+          fromBase,
+          toBase: parentTip,
+          patchId: after.p,
+          diffHash: after.d,
+          patchEqual: equal,
+          forced,
+        });
+        if (step.restack) step.restack.carried = equal;
+        else
+          step.restack = {
+            from: fromBase,
+            onto: parentTip,
+            head: newTip,
+            carried: equal,
+          };
+      }
+      if (options.publish) {
+        touchStackLock();
+        const pushed = pushBranch(cwd, actor, entry.branch, entry.lastHead ?? tip);
+        touchStackLock();
+        if (!pushed.ok) {
+          outcome.steps.push(step);
+          return { ...pushed, data: { ...pushed.data, progress: outcome } };
+        }
+        step.push = pushed.data;
+      }
+      entry.lastHead = newTip;
+      entry.lastParentHead = parentTip;
+      entry.patchId = parentTip ? patchId(cwd, parentTip, newTip) : null;
+    }
+    if (options.publish && ctx && entry.pr) {
+      const doc = state.docs.get(entry.pr);
+      if (doc && doc.state === "open" && doc.base !== parent.name) {
+        step.retarget = { from: doc.base, to: parent.name };
+        if (!options.dryRun) {
+          const grant = requireGrant(cwd, "pr", { target: baseTarget(ctx.resolved) });
+          if (!grant.allowed)
+            return stackFail("blocked", grant.error, grant.unblock, {
+              reason: grant.reason,
+              progress: outcome,
+            });
+          const updated = ctx.resolved.forge.updateBase(entry.pr, parent.name);
+          if (!updated.ok)
+            return {
+              ...fromForge(updated),
+              data: { branch: entry.branch, progress: outcome },
+            };
+          appendObserved(cwd, {
+            type: "pr.retargeted",
+            actor,
+            stack: stack.name,
+            branch: entry.branch,
+            head: newTip,
+            pr: entry.pr,
+            base: parent.name,
+            previousBase: doc.base,
+          });
+        }
+      }
+    }
+    entry.parent = parent.name;
+    outcome.steps.push(step);
+    if (!options.dryRun) {
+      const written = writeStack(cwd, stack);
+      if (!written.ok) return written;
+    }
+    parent = { name: entry.branch, tip: newTip };
+  }
+  if (!options.dryRun) {
+    const written = writeStack(cwd, stack);
+    if (!written.ok) return written;
+  }
+  return { ok: true, data: outcome };
+}
+
+export type PruneOutcome = {
+  /** Merged stack branches deleted locally (or that would be, on a dry run), with the tip to restore. */
+  deleted: Array<{ branch: string; sha: string }>;
+  /** Merged stack branches left in place, with why. */
+  kept: Array<{ branch: string; reason: string }>;
+};
+
+/**
+ * Delete the local branches of merged stack entries (#506). Only branches
+ * this stack recorded, never the trunk or a protected name, never one a
+ * worktree has checked out, only while the local tip is still the head the
+ * stack last recorded, and only when no commit can be lost: the tip is on
+ * the trunk, or is the head the PR merged at, or is contained in the
+ * branch's current remote tip. Each deletion names its sha (restore with
+ * `git branch <name> <sha>`) and is recorded in the ledger. Remote branches
+ * are left to the forge's delete-on-merge.
+ */
+export function pruneMergedBranches(
+  cwd: string,
+  ctx: Ctx | null,
+  stack: StackFile,
+  options: { dryRun: boolean; actor: LedgerActor },
+): PruneOutcome {
+  const outcome: PruneOutcome = { deleted: [], kept: [] };
+  const remote = remoteFor(cwd, ctx?.resolved ?? null, stack.trunk);
+  const trunkSha = trunkTip(cwd, remote, stack.trunk);
+  const keep = (branch: string, reason: string) => outcome.kept.push({ branch, reason });
+  for (const entry of stack.branches) {
+    if (!entry.merged || !safeRef(entry.branch) || entry.branch === stack.trunk) continue;
+    const tip = branchTip(cwd, entry.branch);
+    if (!tip) continue;
+    if (isProtectedTarget(cwd, entry.branch)) {
+      keep(entry.branch, "a protected branch under the workspace branch policy; never deleted");
+      continue;
+    }
+    if (entry.lastHead === null || tip !== entry.lastHead) {
+      keep(
+        entry.branch,
+        `its tip ${tip.slice(0, 12)} is not recorded by the stack (last ${entry.lastHead?.slice(0, 12) ?? "none"}); commits made after it merged stay`,
+      );
+      continue;
+    }
+    const owner = worktreeOf(cwd, entry.branch);
+    if (owner) {
+      keep(
+        entry.branch,
+        `checked out in ${owner}; switch it away, then git branch -D ${entry.branch}`,
+      );
+      continue;
+    }
+    const safe = safeToDelete(cwd, ctx, remote, trunkSha, entry, tip);
+    if (safe === null) {
+      keep(
+        entry.branch,
+        `${tip.slice(0, 12)} is not on ${stack.trunk}, not the head its PR merged at and not on ${remote}/${entry.branch}: deleting it could lose commits (push them, or delete it yourself)`,
+      );
+      continue;
+    }
+    if (!options.dryRun) {
+      const removed = gitRun(cwd, ["branch", "-D", "--", entry.branch]);
+      if (!removed.ok) {
+        keep(entry.branch, `git branch -D failed: ${removed.stderr.trim().split("\n")[0] ?? ""}`);
+        continue;
+      }
+      appendObserved(cwd, {
+        type: "stack.branch.deleted",
+        actor: options.actor,
+        stack: stack.name,
+        branch: entry.branch,
+        head: tip,
+        pr: entry.pr,
+        because: safe,
+      });
+    }
+    outcome.deleted.push({ branch: entry.branch, sha: tip });
+  }
+  return outcome;
+}
+
+/** Why deleting `branch` at `tip` loses nothing, or null when it might. */
+function safeToDelete(
+  cwd: string,
+  ctx: Ctx | null,
+  remote: string,
+  trunkSha: string | null,
+  entry: StackEntry,
+  tip: string,
+): "on_trunk" | "merged_head" | "on_remote" | null {
+  if (trunkSha && isAncestor(cwd, tip, trunkSha)) return "on_trunk";
+  if (ctx && entry.pr) {
+    const read = statusDoc(ctx, entry.pr);
+    if (read.ok && read.data.state === "merged" && read.data.head.sha === tip) return "merged_head";
+  }
+  const own = pushRemoteName(cwd, entry.branch) ?? remote;
+  const remoteTip = remoteRefTip(cwd, own, `refs/heads/${entry.branch}`);
+  if (remoteTip.ok && remoteTip.sha) {
+    if (!hasCommit(cwd, remoteTip.sha)) fetchRefs(cwd, own, [remoteTip.sha]);
+    if (hasCommit(cwd, remoteTip.sha) && isAncestor(cwd, tip, remoteTip.sha)) return "on_remote";
+  }
+  return null;
+}
+
+const commitCount = (cwd: string, base: string, head: string): number =>
+  Number(gitRun(cwd, ["rev-list", "--count", "--no-merges", `${base}..${head}`]).stdout.trim()) ||
+  0;
+
+const shortStat = (cwd: string, base: string, head: string): string =>
+  gitRun(cwd, ["diff", "--shortstat", `${base}...${head}`]).stdout.trim();
+
+// ---------------------------------------------------------------------------
+// land
+
+export type LandOptions = {
+  dryRun: boolean;
+  max: number | null;
+  method: MergeMethod;
+  /** Land without verdicts (`merge: true` only); each bypass is recorded. */
+  unverified?: { reason: string } | null;
+  /** Merge onto a red base (`--base-red-ok`); each merge records the reason. */
+  baseRedOk?: { reason: string } | null;
+  /** Merge PRs another author opened (`--others-pr`, as `pr merge`); each merge records the reason. */
+  othersPr?: { reason: string } | null;
+  /**
+   * Pass these failing optional checks (`--allow-failing`, as `pr merge`):
+   * never a required one; each PR it lets through records its own
+   * `merge.waived` rows.
+   */
+  allowFailing?: CheckWaiver | null;
+  /** How long to wait for CI on a PR that was just restacked. */
+  timeoutMs: number;
+  intervalMs: number;
+};
+
+export type LandStop = {
+  pr: number | null;
+  branch: string;
+  reason: StopReason;
+  detail: string;
+  unblock: string;
+  /** Everything but the merge grant holds: "verified, ready". */
+  ready: boolean;
+  /** The forge, not the PR, must move first (mergeability still UNKNOWN after the re-reads). */
+  babysit?: "wait-forge";
+};
+
+/**
+ * One PR in the pre-flight: `refused` is why it would not land (null: it
+ * passes); `waives` names the failing optional checks `--allow-failing`
+ * passes on its head.
+ */
+export type PreflightEntry = {
+  pr: number | null;
+  branch: string;
+  waives: string[];
+  refused: LandStop | null;
+};
+
+export type LandOutcome = {
+  name: string;
+  dryRun: boolean;
+  /**
+   * `unverified`: the ledger row of an `--unverified` bypass, else null;
+   * `waived`: the failing optional checks `--allow-failing` passed on this PR.
+   */
+  landed: Array<{
+    pr: number;
+    branch: string;
+    mergeSha: string | null;
+    unverified: string | null;
+    waived: WaivedCheck[];
+  }>;
+  /** Dry run: the PRs that qualify now, in order (later ones assume a clean restack). */
+  wouldLand: Array<{ pr: number; branch: string }>;
+  /**
+   * Every PR this run would land, judged before anything merges (#739), in
+   * order; any refusal stops the land with nothing merged. A dry run prints
+   * the same.
+   */
+  preflight: PreflightEntry[];
+  stoppedAt: LandStop | null;
+  retargeted: number[];
+  restacked: string[];
+  complete: boolean;
+};
+
+/** Poll the PR until its checks settle or the wait budget is spent (sleep-time based). */
+async function awaitChecks(
+  ctx: Ctx,
+  pr: number,
+  head: string,
+  options: LandOptions,
+): Promise<ForgeResult<PrStatusDoc>> {
+  let waited = 0;
+  for (let poll = 0; ; poll += 1) {
+    touchStackLock();
+    const doc = statusDoc(ctx, pr);
+    if (!doc.ok) return doc;
+    const verdict = waitVerdict(doc.data, { head, elapsedMs: waited });
+    if (verdict.state !== "waiting" || waited >= options.timeoutMs) return doc;
+    const delay = Math.min(
+      pollDelay(options.intervalMs, poll),
+      Math.max(1, options.timeoutMs - waited),
+    );
+    await ctx.sleep(delay);
+    waited += delay;
+  }
+}
+
+export async function landStack(
+  ctx: Ctx,
+  stack: StackFile,
+  options: LandOptions,
+): Promise<StackResult<LandOutcome>> {
+  const outcome: LandOutcome = {
+    name: stack.name,
+    dryRun: options.dryRun,
+    landed: [],
+    wouldLand: [],
+    preflight: [],
+    stoppedAt: null,
+    retargeted: [],
+    restacked: [],
+    complete: false,
+  };
+  const absorb = (sync: SyncOutcome) => {
+    for (const step of sync.steps) {
+      if (step.retarget && step.pr && !outcome.retargeted.includes(step.pr))
+        outcome.retargeted.push(step.pr);
+      if (step.restack?.head && !outcome.restacked.includes(step.branch))
+        outcome.restacked.push(step.branch);
+    }
+  };
+  // A stop after a merge names what already landed.
+  const failWith = (error: StackError): StackError => ({
+    ...error,
+    error: outcome.landed.length
+      ? `${error.error}; landed before the stop: ${outcome.landed.map((item) => `${noun(ctx.resolved, item.pr)} (${item.branch})`).join(", ")}`
+      : error.error,
+    data: { ...error.data, land: outcome },
+  });
+  const mismatch = repoMismatch(ctx, stack);
+  if (mismatch) return failWith(mismatch);
+  const bypass = options.unverified ?? null;
+  if (bypass) {
+    const grant = requireGrant(ctx.cwd, "merge", { target: baseTarget(ctx.resolved) });
+    if (!grant.allowed)
+      return failWith(
+        stackFail("blocked", grant.error, grant.unblock, {
+          reason: "grant_required",
+        }),
+      );
+    if (!grant.allowUnverified)
+      return failWith(
+        stackFail(
+          "blocked",
+          `unverified_refused: workspace ${grant.workspace ? `"${grant.workspace}"` : "(none)"} grants merge: "verified", which never lands without an accepted independent verdict`,
+          "a non-author session verifies each head (workit-review), then land without --unverified",
+          { reason: "unverified_refused" },
+        ),
+      );
+  }
+
+  // Catch up first: a parent merged elsewhere leaves the rest to restack.
+  if (!options.dryRun) {
+    const synced = syncStack(
+      ctx.cwd,
+      ctx,
+      stack,
+      { publish: true, dryRun: false, limit: 1 },
+      ctx.actor,
+    );
+    if (!synced.ok) return failWith(synced);
+    absorb(synced.data);
+  }
+  const ledgerRows = () => {
+    const ledger = readLedger(ctx.cwd, { integrity: true });
+    return ledger.ok ? ledger.value.rows : [];
+  };
+  let justRestacked = new Set(outcome.restacked);
+
+  // Judge every PR first: a refusal known now lands nothing (#739).
+  const pre = preflightLand(ctx, stack, options, justRestacked, ledgerRows());
+  if (!pre.ok) return failWith(pre);
+  outcome.preflight = pre.data.entries;
+  const refused = outcome.preflight.flatMap((entry) => (entry.refused ? [entry.refused] : []));
+  if (refused.length) {
+    outcome.stoppedAt = refused[0];
+    if (refused.some((stop) => stop.reason === "waiver_refused"))
+      return failWith(
+        stackFail(
+          "blocked",
+          `waiver_refused: nothing landed; the pre-flight refused ${refused.map((stop) => `${stop.pr ? noun(ctx.resolved, stop.pr) : stop.branch} (${stop.branch}) ${stop.detail}`).join("; ")}`,
+          refused.find((stop) => stop.reason === "waiver_refused")?.unblock,
+          { reason: "waiver_refused" },
+        ),
+      );
+    return { ok: true, data: outcome };
+  }
+  if (options.dryRun) {
+    outcome.wouldLand = outcome.preflight.map((entry) => ({
+      pr: entry.pr as number,
+      branch: entry.branch,
+    }));
+    outcome.stoppedAt = pre.data.cut;
+    outcome.complete = pre.data.cut === null;
+    return { ok: true, data: outcome };
+  }
+
+  // Merge bottom-up, re-judging each PR at its turn: what only the merge can
+  // show (a head that moved, a forge race) stops here, after the PRs below it.
+  for (;;) {
+    touchStackLock();
+    const entry = stack.branches.find((candidate) => !candidate.merged);
+    if (!entry) {
+      outcome.complete = true;
+      break;
+    }
+    if (options.max !== null && outcome.landed.length >= options.max) {
+      outcome.stoppedAt = maxReached(entry, options.max);
+      break;
+    }
+    // `pr merge`'s gate, one per PR: UNKNOWN mergeability is re-read with
+    // backoff, and an `--allow-failing` waiver passes the PR's failing
+    // optional checks, recorded only once the forge accepts its merge (a PR
+    // that stops records none). Sync keeps the raw forge: it lands nothing.
+    const gate = landGate(ctx, options);
+    const gated: Ctx = { ...ctx, resolved: { ...ctx.resolved, forge: gate } };
+    let doc: PrStatusDoc | null = null;
+    if (entry.pr) {
+      const head = branchTip(ctx.cwd, entry.branch);
+      const read =
+        justRestacked.has(entry.branch) && head
+          ? await awaitChecks(gated, entry.pr, head, options)
+          : statusDoc(gated, entry.pr);
+      if (!read.ok) return failWith(fromForge(read));
+      doc = read.data;
+    }
+    const grant = requireGrant(ctx.cwd, "merge", { target: baseTarget(ctx.resolved) });
+    const verdict = verdictOf(ctx.cwd, entry.branch, ledgerRows(), doc);
+    const q = qualify(
+      ctx,
+      stack,
+      entry,
+      doc,
+      verdict,
+      grant,
+      doc ? prBinding(ctx, entry, doc) : null,
+      bypass !== null,
+    );
+    if (!q.ok) {
+      outcome.stoppedAt = landStop(entry, q, doc);
+      break;
+    }
+    const pr = entry.pr as number;
+    const merged = await mergePullRequest(
+      ctx.cwd,
+      gated.resolved,
+      {
+        pr,
+        method: options.method,
+        deleteBranch: false,
+        actor: ctx.actor,
+        expect: { base: stack.trunk, branch: entry.branch },
+        ...(bypass && !verdict.satisfied ? { unverified: bypass } : {}),
+        ...(options.baseRedOk ? { baseRedOk: options.baseRedOk } : {}),
+        ...(options.othersPr ? { othersPr: options.othersPr } : {}),
+      },
+      ctx.sleep,
+    );
+    if (!merged.ok) {
+      outcome.stoppedAt = {
+        pr,
+        branch: entry.branch,
+        reason: "merge_refused",
+        detail: merged.error,
+        unblock: merged.unblock ?? `workit pr status --pr ${pr}`,
+        ready: false,
+      };
+      if (merged.code === "blocked" && "refusal" in merged && merged.refusal) break;
+      return failWith(stackFail(merged.code, merged.error, merged.unblock));
+    }
+    outcome.landed.push({
+      pr,
+      branch: entry.branch,
+      mergeSha: merged.data.mergeSha,
+      unverified: merged.data.unverified?.recorded ?? null,
+      waived: [...gate.waived],
+    });
+    entry.merged = {
+      pr,
+      mergeSha: merged.data.mergeSha,
+      at: new Date().toISOString(),
+    };
+    const written = writeStack(ctx.cwd, stack);
+    if (!written.ok) return failWith(written);
+    // Move the next PR onto the trunk: restack, lease push, retarget. The
+    // ones above it wait (restacking them now would only spend CI that the
+    // next merge restarts); `workit stack sync` moves them all.
+    const before = new Set(outcome.restacked);
+    const synced = syncStack(
+      ctx.cwd,
+      ctx,
+      stack,
+      { publish: true, dryRun: false, limit: 1 },
+      ctx.actor,
+    );
+    if (!synced.ok) return failWith(synced);
+    absorb(synced.data);
+    justRestacked = new Set(outcome.restacked.filter((branch) => !before.has(branch)));
+    for (const step of synced.data.steps) if (step.restack?.head) justRestacked.add(step.branch);
+  }
+  return { ok: true, data: outcome };
+}
+
+/**
+ * `pr merge`'s gate for one land read. The `--allow-failing` waiver applies
+ * per PR: a PR whose head does not run a named check is not refused for it.
+ */
+const landGate = (ctx: Ctx, options: LandOptions) =>
+  mergeGateForge(ctx.resolved.forge, ctx.cwd, {
+    waiver: options.allowFailing ?? null,
+    actor: ctx.actor,
+    perPr: true,
+  });
+
+const maxReached = (entry: StackEntry, max: number): LandStop => ({
+  pr: entry.pr,
+  branch: entry.branch,
+  reason: "max_reached",
+  detail: `--max ${max} reached`,
+  unblock: "workit stack land",
+  ready: false,
+});
+
+const landStop = (
+  entry: StackEntry,
+  q: Extract<Qualification, { ok: false }>,
+  doc: PrStatusDoc | null,
+): LandStop => ({
+  pr: entry.pr,
+  branch: entry.branch,
+  reason: q.reason,
+  detail: q.detail,
+  unblock: q.unblock,
+  ready: q.ready,
+  ...(q.reason === "not_ready" && doc?.babysit === "wait-forge"
+    ? { babysit: "wait-forge" as const }
+    : {}),
+});
+
+/** Blockers the land clears itself on a PR it restacks before judging it again. */
+const SETTLED_BY_RESTACK: ReadonlySet<string> = new Set(["checks_pending", "behind_base_required"]);
+
+/**
+ * The PR as it will stand at its turn. With a PR landing below it, its base
+ * is its parent until the land retargets it to the trunk; restacked (or about
+ * to be), its CI runs again and the land awaits it.
+ */
+function atItsTurn(
+  doc: PrStatusDoc,
+  stack: StackFile,
+  entry: StackEntry,
+  below: boolean,
+  restacked: boolean,
+): PrStatusDoc {
+  let view = doc;
+  if (below && (doc.base === entry.parent || doc.base === stack.trunk))
+    view = { ...view, base: stack.trunk };
+  if (
+    restacked &&
+    doc.next !== "READY" &&
+    doc.blockers.length > 0 &&
+    doc.blockers.every((blocker) => SETTLED_BY_RESTACK.has(blocker))
+  )
+    view = { ...view, next: "READY", blockers: [] };
+  return view;
+}
+
+/**
+ * `pr merge`'s others_pr gate, read before anything merges: the refusal for
+ * a PR whose author is not the forge login (or cannot be shown to be), else
+ * null. The login is read once.
+ */
+function othersPrGate(
+  resolved: ResolvedForge,
+): (pr: number) => { detail: string; unblock: string } | null {
+  let login: string | null | undefined;
+  return (pr) => {
+    const label = noun(resolved, pr);
+    if (login === undefined) login = forgeLogin(resolved);
+    const other = otherAuthor(resolved, pr, login);
+    if (other === null) return null;
+    if (!other.ok)
+      return {
+        detail: `identity_unknown: ${other.error}, so ${label} cannot be shown to be yours`,
+        unblock:
+          "fix: gh auth status / gh auth login (or glab auth login), then workit stack land again",
+      };
+    return {
+      detail: `others_pr: ${label} is by ${other.author}, not ${other.login} (the forge login); workit never merges another author's PR on its own`,
+      unblock: `only if the user asks you to land it: workit stack land --others-pr --reason "<why>"`,
+    };
+  };
+}
+
+/**
+ * The pre-flight (#739): every PR this run would land (each open one, or the
+ * first `--max`) is judged before anything merges, by the checks the merge
+ * loop runs: `qualify` (PR, base, READY after the mergeability re-read,
+ * verdict, grant), `pr merge`'s others_pr gate and the `--allow-failing`
+ * waiver per PR (a required check named is `waiver_refused`). A PR above the
+ * first is judged as it will stand at its turn (`atItsTurn`). A name no PR
+ * runs is `unknown_check`. `cut` is the `--max` stop.
+ */
+function preflightLand(
+  ctx: Ctx,
+  stack: StackFile,
+  options: LandOptions,
+  justRestacked: ReadonlySet<string>,
+  rows: readonly ReadRow[],
+): StackResult<{ entries: PreflightEntry[]; cut: LandStop | null }> {
+  const gate = landGate(ctx, options);
+  const gated: Ctx = { ...ctx, resolved: { ...ctx.resolved, forge: gate } };
+  const grant = requireGrant(ctx.cwd, "merge", { target: baseTarget(ctx.resolved) });
+  const others = options.othersPr ? null : othersPrGate(ctx.resolved);
+  const entries: PreflightEntry[] = [];
+  // A PR below this one lands first (or, in a dry run, merged elsewhere).
+  let below = false;
+  for (const entry of stack.branches) {
+    if (entry.merged) continue;
+    touchStackLock();
+    if (options.max !== null && entries.length >= options.max)
+      return {
+        ok: true,
+        data: { entries, cut: maxReached(entry, options.max) },
+      };
+    const judged = (refused: LandStop | null, waives: string[] = []) => {
+      entries.push({ pr: entry.pr, branch: entry.branch, waives, refused });
+      below = true;
+    };
+    let doc: PrStatusDoc | null = null;
+    if (entry.pr) {
+      const read = statusDoc(gated, entry.pr);
+      if (!read.ok && read.code === "blocked" && read.error.startsWith("waiver_refused:")) {
+        judged({
+          pr: entry.pr,
+          branch: entry.branch,
+          reason: "waiver_refused",
+          detail: read.error,
+          unblock: read.unblock ?? `workit pr status --pr ${entry.pr}`,
+          ready: false,
+        });
+        continue;
+      }
+      if (!read.ok) return fromForge(read);
+      doc = read.data;
+      if (options.dryRun && doc.state === "merged") {
+        // Merged elsewhere; the real run would restack past it.
+        below = true;
+        continue;
+      }
+    }
+    const q = qualify(
+      ctx,
+      stack,
+      entry,
+      doc && atItsTurn(doc, stack, entry, below, below || justRestacked.has(entry.branch)),
+      verdictOf(ctx.cwd, entry.branch, rows, doc),
+      grant,
+      doc ? prBinding(ctx, entry, doc) : null,
+      Boolean(options.unverified),
+    );
+    if (!q.ok) {
+      judged(landStop(entry, q, doc));
+      continue;
+    }
+    const pr = entry.pr as number;
+    const foreign = others?.(pr) ?? null;
+    judged(
+      foreign
+        ? {
+            pr,
+            branch: entry.branch,
+            reason: "merge_refused",
+            ...foreign,
+            ready: false,
+          }
+        : null,
+      gate.waives(pr),
+    );
+  }
+  const unknown = options.allowFailing?.checks.filter((name) => !gate.matched.has(name)) ?? [];
+  if (unknown.length)
+    return stackFail(
+      "invalid_input",
+      `unknown_check: --allow-failing ${unknown.map((name) => JSON.stringify(name)).join(", ")} matches no check on any PR this land would merge (${entries.map((entry) => (entry.pr ? noun(ctx.resolved, entry.pr) : entry.branch)).join(", ") || "none"})`,
+      "workit pr status --pr <n>  # copy the check name exactly",
+      { reason: "unknown_check" },
+    );
+  return { ok: true, data: { entries, cut: null } };
+}