@brainervirus/workit-core 7.4.0 → 7.5.0

package/src/fanout-landed.ts

@@ -0,0 +1,313 @@
+// Has a fanout slice landed? Shared by `fanout status` and `fanout check`, so
+// a landed slice is done for both and its dependents stop waiting.
+//
+// With the forge, the slice branch's PR reads merged. A squash merge never
+// makes the branch an ancestor of the trunk, so this is the only reliable
+// signal; it holds while the branch has nothing newer than the merged head.
+// Without the forge (offline, no gh/glab, no PR yet), git decides:
+// - on_trunk: the branch tip is on the trunk and its reflog proves commits of
+//   its own (a commit, cherry-pick or rebase made on it, inside start..head);
+//   a branch only fast-forwarded to a newer trunk or parent has none;
+// - squash_patch: the branch's change has the same patch-id as one trunk
+//   commit (a squash merge that applied without the trunk touching the same
+//   lines). Anything else reads as not landed.
+// A merged PR whose branch is gone counts only when the ledger links that
+// branch to this slice (a worktree row, or a row recorded on its merged
+// head), so a reused branch name from older work is not taken for this slice.
+// A landing whose changed paths read on the trunk exactly as before it (a
+// revert) is not landed; the note says so.
+// The forge is asked through a breaker: after the first unavailable answer
+// (gh/glab missing, not logged in, timed out) it is not asked again in the
+// same run, and git decides the rest.
+import { spawnSync } from "node:child_process";
+import { GIT_TIMEOUTS, hasCommit, mergeBase, patchId } from "./git/rev";
+import type { ResolvedForge } from "./forge/resolve";
+import type { ForgeResult, PrRef } from "./forge/types";
+import { gitRun, type Slice } from "./fanout";
+
+export type LandedHow = "pr_merged" | "on_trunk" | "squash_patch";
+
+export type SliceLanding = {
+  landed: boolean;
+  how: LandedHow | null;
+  /** The slice's PR when the forge was asked and has one (open, closed or merged). */
+  pr: PrRef | null;
+  /** The merged head: a stacked child's diff base once the branch is gone. */
+  landedHead: string | null;
+  /** Why the forge could not answer for this slice; null when it did or was not asked. */
+  forgeError: string | null;
+  note: string | null;
+};
+
+export type LandingContext = {
+  cwd: string;
+  /** The trunk ref (e.g. refs/remotes/origin/main). */
+  trunk: string;
+  forge: ResolvedForge | null;
+  /** Trunk patch-ids per fork point, filled lazily. */
+  cache?: Map<string, Set<string>>;
+};
+
+export type ForgeBreaker = {
+  /** The forge whose calls stop after the first unavailable answer; null when there is none. */
+  forge: ResolvedForge | null;
+  /** Why it went down during this run, else null. */
+  down: () => string | null;
+};
+
+/**
+ * Wrap the forge so a missing, logged-out or hanging gh/glab costs one call
+ * per run, not one timeout per slice: after the first `unavailable` answer
+ * every later call fails at once with the same error.
+ */
+export function forgeBreaker(resolved: ResolvedForge | null): ForgeBreaker {
+  if (!resolved) return { forge: null, down: () => null };
+  let tripped: string | null = null;
+  const guard =
+    <A extends unknown[], T>(call: (...args: A) => ForgeResult<T>) =>
+    (...args: A): ForgeResult<T> => {
+      if (tripped) return { ok: false, code: "unavailable", error: tripped };
+      const result = call(...args);
+      if (!result.ok && result.code === "unavailable") tripped = result.error;
+      return result;
+    };
+  const inner = resolved.forge;
+  const forge = Object.create(inner) as typeof inner;
+  forge.findPr = guard(inner.findPr.bind(inner));
+  forge.prStatus = guard(inner.prStatus.bind(inner));
+  return { forge: { ...resolved, forge }, down: () => tripped };
+}
+
+const isAncestor = (cwd: string, a: string, b: string): boolean =>
+  gitRun(cwd, ["merge-base", "--is-ancestor", a, b]).ok;
+
+/** Where a local branch began (its oldest reflog entry), or null. */
+export function branchCreatedAt(cwd: string, branch: string): string | null {
+  if (!branch || branch.startsWith("-")) return null;
+  const log = gitRun(cwd, ["log", "-g", "--format=%H", `refs/heads/${branch}`, "--"]);
+  if (!log.ok) return null;
+  return log.stdout.trim().split("\n").findLast(Boolean) ?? null;
+}
+
+/**
+ * Does the branch's reflog show a commit made on it inside `start..head`?
+ * A commit, cherry-pick or rebased pick counts; a fast-forward, reset or
+ * branch creation does not, and neither does a rebase that only moved it.
+ */
+export function hasOwnCommits(
+  cwd: string,
+  branch: string,
+  start: string | null,
+  head: string,
+): boolean {
+  if (!branch || branch.startsWith("-")) return false;
+  const log = gitRun(cwd, ["log", "-g", "--format=%H%x00%gs", `refs/heads/${branch}`, "--"]);
+  if (!log.ok) return false;
+  for (const line of log.stdout.split("\n")) {
+    const [sha, subject = ""] = line.split("\0");
+    if (!sha) continue;
+    const made =
+      /^(?:commit(?: \((?:initial|amend)\))?|cherry-pick|rebase(?: -i)? \(pick\)):/u.test(subject);
+    const onto = /^rebase(?: -i)? \(finish\): \S+ onto ([0-9a-f]+)/u.exec(subject)?.[1];
+    if (!made && !(onto && !sha.startsWith(onto) && !onto.startsWith(sha))) continue;
+    if (sha !== head && !isAncestor(cwd, sha, head)) continue;
+    if (start && (sha === start || isAncestor(cwd, sha, start))) continue;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * The landing was undone: every path the change touched reads on the trunk
+ * exactly as before it (`git revert`, or a manual undo).
+ */
+function reverted(cwd: string, trunk: string, landedHead: string, start: string | null): boolean {
+  const fork = mergeBase(cwd, landedHead, trunk);
+  if (fork && fork !== landedHead) return unchangedSince(cwd, fork, landedHead, trunk);
+  // On the trunk already (merge or fast-forward): compare with where it began.
+  const before =
+    start && start !== landedHead && isAncestor(cwd, start, landedHead)
+      ? start
+      : gitRun(cwd, ["rev-parse", "--verify", "-q", `${landedHead}^1`]).stdout.trim();
+  return before ? unchangedSince(cwd, before, landedHead, trunk) : false;
+}
+
+function unchangedSince(cwd: string, before: string, after: string, trunk: string): boolean {
+  const paths = gitRun(cwd, ["diff", "--name-only", "--no-renames", "-z", before, after]);
+  const files = paths.ok ? paths.stdout.split("\0").filter(Boolean) : [];
+  if (files.length === 0) return false;
+  return gitRun(cwd, ["diff", "--quiet", before, trunk, "--", ...files]).ok;
+}
+
+const TRUNK_SCAN = 500;
+
+/** Stable patch-ids of the trunk's own commits since `fork` (same pinned diff options as patchId). */
+function trunkPatchIds(ctx: LandingContext, fork: string): Set<string> {
+  const cache = (ctx.cache ??= new Map());
+  const known = cache.get(fork);
+  if (known) return known;
+  const ids = new Set<string>();
+  const log = gitRun(ctx.cwd, [
+    "log",
+    "--no-merges",
+    `--max-count=${TRUNK_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}..${ctx.trunk}`,
+    "--",
+  ]);
+  if (log.ok && log.stdout.trim()) {
+    const run = spawnSync("git", ["patch-id", "--stable"], {
+      cwd: ctx.cwd,
+      input: log.stdout,
+      encoding: "utf8",
+      timeout: GIT_TIMEOUTS.local,
+      windowsHide: true,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    for (const line of (run.stdout ?? "").split("\n")) {
+      const id = line.trim().split(/\s+/u)[0];
+      if (id) ids.add(id);
+    }
+  }
+  cache.set(fork, ids);
+  return ids;
+}
+
+/** The ledger links `branch` to this slice: a worktree row, or a row recorded on `head`. */
+function linked(
+  rows: readonly Record<string, unknown>[],
+  input: Pick<LandingInput, "fanout" | "since">,
+  slice: Pick<Slice, "id" | "branch">,
+  head: string | null,
+): boolean {
+  // Only rows from this run of the fanout: a plan of the same name made
+  // earlier must not lend its merged PRs to this one.
+  const since = input.since ? Date.parse(input.since) : Number.NaN;
+  return rows.some(
+    (row) =>
+      (Number.isNaN(since) || Date.parse(String(row.at)) >= since) &&
+      ((row.type === "fanout.worktree.created" &&
+        row.fanout === input.fanout &&
+        row.slice === slice.id) ||
+        (head !== null && row.branch === slice.branch && row.head === head)),
+  );
+}
+
+export type LandingInput = {
+  /** The branch tip; null when the branch is gone. */
+  head: string | null;
+  /** The commit it began at when known (reflog or the worktree ledger row). */
+  createdFrom: string | null;
+  /** Its dependency branch's tip (or merged head) for a stacked slice. */
+  parentHead: string | null;
+  fanout: string;
+  /** When this fanout plan was first made (FanoutFile.createdAt): older rows do not link. */
+  since: string | null;
+  rows: readonly Record<string, unknown>[];
+};
+
+/** Has `slice` landed on the trunk? */
+export function detectLanding(
+  ctx: LandingContext,
+  slice: Pick<Slice, "id" | "branch">,
+  input: LandingInput,
+): SliceLanding {
+  const out: SliceLanding = {
+    landed: false,
+    how: null,
+    pr: null,
+    landedHead: null,
+    forgeError: null,
+    note: null,
+  };
+  const landed = (how: LandedHow, landedHead: string): SliceLanding => {
+    if (
+      !hasCommit(ctx.cwd, landedHead) ||
+      !reverted(ctx.cwd, ctx.trunk, landedHead, input.createdFrom)
+    )
+      return { ...out, landed: true, how, landedHead };
+    return {
+      ...out,
+      note: `landed (${how}${out.pr ? ` #${out.pr.number}` : ""}), then reverted on the trunk: its paths read as before it`,
+    };
+  };
+  const { head } = input;
+  if (ctx.forge) {
+    const found = ctx.forge.forge.findPr(slice.branch, {
+      owner: ctx.forge.headRepo.split("/")[0] ?? null,
+      projectId: ctx.forge.headProjectId,
+      sha: head,
+    });
+    if (!found.ok) out.forgeError = found.error;
+    else if (found.data) {
+      out.pr = found.data;
+      if (found.data.state === "merged") {
+        const merged = found.data.headSha;
+        const label = `#${found.data.number}`;
+        if (!head) {
+          if (!linked(input.rows, input, slice, merged)) {
+            out.pr = null;
+            out.note = `${slice.branch} is gone; merged ${label} is not linked to this slice in the ledger (an older branch of the same name?)`;
+            return out;
+          }
+          return merged ? landed("pr_merged", merged) : { ...out, landed: true, how: "pr_merged" };
+        }
+        if (!merged || head === merged || isAncestor(ctx.cwd, head, merged))
+          return landed("pr_merged", merged ?? head);
+        out.note = isAncestor(ctx.cwd, merged, head)
+          ? `${label} merged at ${merged.slice(0, 12)}; ${slice.branch} is ahead of it with newer commits`
+          : `${label} merged at ${merged.slice(0, 12)}; ${slice.branch} has diverged from it (rewritten after the merge)`;
+        return out;
+      }
+    }
+  }
+  if (!head) return out;
+  const fork = mergeBase(ctx.cwd, head, ctx.trunk);
+  if (fork === head) {
+    // On the trunk: landed only when commits were made on the branch itself.
+    return hasOwnCommits(ctx.cwd, slice.branch, input.createdFrom, head)
+      ? landed("on_trunk", head)
+      : out;
+  }
+  if (!fork) return out;
+  const trunkIds = trunkPatchIds(ctx, fork);
+  if (trunkIds.size === 0) return out;
+  const froms = [fork];
+  if (input.parentHead && input.parentHead !== head && isAncestor(ctx.cwd, input.parentHead, head))
+    froms.push(input.parentHead);
+  for (const from of froms) {
+    const id = patchId(ctx.cwd, from, head);
+    if (id && trunkIds.has(id)) return landed("squash_patch", head);
+  }
+  return out;
+}
+
+/** The commit a slice branch began at: its reflog, else `fanout worktree create`'s ledger row. */
+export function sliceStart(
+  cwd: string,
+  rows: readonly Record<string, unknown>[],
+  fanout: string,
+  slice: Pick<Slice, "id" | "branch">,
+): string | null {
+  const reflog = branchCreatedAt(cwd, slice.branch);
+  if (reflog) return reflog;
+  const row = rows.findLast(
+    (candidate) =>
+      candidate.type === "fanout.worktree.created" &&
+      candidate.fanout === fanout &&
+      candidate.slice === slice.id &&
+      typeof candidate.baseSha === "string",
+  );
+  return (row?.baseSha as string | undefined) ?? null;
+}

package/src/fanout-status.ts

@@ -0,0 +1,321 @@
+// `workit fanout status` (G3): one dashboard row per slice, derived from side
+// effects only (git, the forge, the ledger), never from what a worker said.
+//
+// Per slice: whether its branch exists and its head, the age of its last
+// commit, its PR and CI state (when the forge answers), the ledger verdict on
+// that head, and whether it landed (fanout-landed.ts, squash merges
+// included). A slice is STUCK when it started, has not landed, has no
+// accepted verdict, and nothing moved for longer than the threshold: no new
+// commit or branch update, no ledger row for its branch or slice. The
+// threshold is --stuck-after, else the slice's TIMEBOX when it reads as a
+// duration, else 30 minutes.
+//
+// Landable: not landed, an accepted verdict on the current head and, when the
+// forge answered, an open PR whose checks pass. The suggested landing order
+// walks the plan's order (dependencies first), skips landed slices and keeps
+// a slice only once each dependency has landed or comes earlier in the order.
+// Without the forge (offline, no gh/glab) the rest still works and says so.
+import { parseDuration } from "./duration";
+import { checksState, gatingChecks, missingRequired, type ChecksState } from "./forge/report";
+import type { ResolvedForge } from "./forge/resolve";
+import { checkVerdicts, readLedger, type ReadRow, type VerdictBasis } from "./ledger";
+import { sliceLandings } from "./fanout-check";
+import { forgeBreaker } from "./fanout-landed";
+import {
+  branchRef,
+  fanoutFail,
+  gitRun,
+  landingOrder,
+  trunkRef,
+  type FanoutFile,
+  type FanoutResult,
+  type Slice,
+} from "./fanout";
+import type { LandedHow } from "./fanout-landed";
+
+export const DEFAULT_STUCK_MS = 30 * 60_000;
+
+export type SliceState = "landed" | "ready" | "stuck" | "active" | "waiting" | "not_started";
+
+export type SliceStatusRow = {
+  id: string;
+  branch: string;
+  base: string;
+  worktree: string;
+  dependsOn: string[];
+  branchExists: boolean;
+  head: string | null;
+  lastCommitAt: string | null;
+  /** Newest side effect: commit, branch update (reflog) or ledger row. */
+  lastActivityAt: string | null;
+  idleMinutes: number | null;
+  stuckAfterMinutes: number;
+  pr: { number: number; url: string; state: string } | null;
+  /** passing | failing | pending | none, or unknown without the forge or a PR. */
+  ci: ChecksState | "unknown";
+  verdict: { accepted: boolean; basis: VerdictBasis; review: string };
+  landed: { how: LandedHow; pr: number | null } | null;
+  stuck: boolean;
+  /** Dependencies that have not landed. */
+  waitsFor: string[];
+  state: SliceState;
+  /** Why it is not landable yet. */
+  reasons: string[];
+  notes: string[];
+};
+
+export type StatusOutcome = {
+  name: string;
+  trunk: string;
+  trunkRef: string | null;
+  forge: { available: boolean; error: string | null };
+  slices: SliceStatusRow[];
+  /** Landable slices in the order to land them. */
+  landingOrder: string[];
+  /** Not started; every dependency landed (or, stacked, its parent has an accepted verdict). */
+  spawnable: string[];
+  stuck: string[];
+  next: string;
+  notes: string[];
+};
+
+export type StatusOptions = {
+  forge: ResolvedForge | null;
+  /** Why the forge is not available (shown in notes). */
+  forgeError?: string | null;
+  stuckAfterMs?: number | null;
+  now?: Date;
+};
+
+/** A TIMEBOX such as `45 minutes`, `2h` or `1h30m`, in ms; null without a unit or otherwise. */
+export function timeboxMs(text: string | null): number | null {
+  if (!text || /^\s*\d+(?:\.\d+)?\s*$/u.test(text)) return null;
+  const ms = parseDuration(text);
+  return ms && ms > 0 ? ms : null;
+}
+
+const isoOf = (seconds: string): string | null => {
+  const value = Number(seconds.trim());
+  return Number.isFinite(value) && value > 0 ? new Date(value * 1000).toISOString() : null;
+};
+
+const newest = (...values: Array<string | null | undefined>): string | null =>
+  values
+    .filter((value): value is string => Boolean(value) && !Number.isNaN(Date.parse(value ?? "")))
+    .reduce<string | null>(
+      (best, value) => (best === null || Date.parse(value) > Date.parse(best) ? value : best),
+      null,
+    );
+
+function activity(cwd: string, plan: FanoutFile, slice: Slice, rows: readonly ReadRow[]) {
+  const head = branchRef(cwd, slice.branch);
+  const commit = head ? isoOf(gitRun(cwd, ["log", "-1", "--format=%ct", head, "--"]).stdout) : null;
+  // `refs/heads/<b>@{<unix time>}`: when the local branch last moved.
+  const moved = /@\{(\d+)\}/u.exec(
+    gitRun(cwd, [
+      "log",
+      "-g",
+      "-1",
+      "--date=unix",
+      "--format=%gd",
+      `refs/heads/${slice.branch}`,
+      "--",
+    ]).stdout,
+  );
+  const reflog = moved ? isoOf(moved[1]) : null;
+  const ledger = rows
+    .filter(
+      (row) => row.branch === slice.branch || (row.fanout === plan.name && row.slice === slice.id),
+    )
+    .map((row) => row.at);
+  return {
+    head,
+    commit,
+    last: newest(commit, reflog, ...ledger),
+    worktreeCreated: rows.some(
+      (row) =>
+        row.type === "fanout.worktree.created" &&
+        row.fanout === plan.name &&
+        row.slice === slice.id,
+    ),
+  };
+}
+
+export function fanoutStatus(
+  cwd: string,
+  plan: FanoutFile,
+  options: StatusOptions,
+): FanoutResult<StatusOutcome> {
+  const now = options.now ?? new Date();
+  const breaker = forgeBreaker(options.forge);
+  const forge = breaker.forge;
+  const trunk = trunkRef(cwd, plan.trunk);
+  if (!trunk)
+    return fanoutFail(
+      "unavailable",
+      `trunk ${plan.trunk} does not resolve here`,
+      `git fetch origin ${plan.trunk}`,
+    );
+  const ledger = readLedger(cwd);
+  const rows: readonly ReadRow[] = ledger.ok ? ledger.value.rows : [];
+  const notes: string[] = [];
+  if (!ledger.ok) notes.push(`ledger unreadable (${ledger.error}); verdicts read as missing`);
+  if (!forge)
+    notes.push(
+      `forge unavailable${options.forgeError ? ` (${options.forgeError})` : ""}: PR and CI not shown; landed detection uses git only, so a squash merge may be missed`,
+    );
+
+  const tips = new Map(plan.slices.map((slice) => [slice.id, branchRef(cwd, slice.branch)]));
+  const landings = sliceLandings(cwd, plan, trunk, tips, rows, forge);
+  const byId = new Map(plan.slices.map((slice) => [slice.id, slice]));
+  const order = landingOrder(plan.slices);
+  const out = new Map<string, SliceStatusRow>();
+
+  for (const id of order) {
+    const slice = byId.get(id) as Slice;
+    const landing = landings.get(id);
+    const seen = activity(cwd, plan, slice, rows);
+    const threshold = options.stuckAfterMs ?? timeboxMs(slice.timebox) ?? DEFAULT_STUCK_MS;
+    const idle = seen.last ? Math.max(0, now.getTime() - Date.parse(seen.last)) : null;
+    const verdict = seen.head ? checkVerdicts(cwd, slice.branch, rows) : null;
+    const row: SliceStatusRow = {
+      id,
+      branch: slice.branch,
+      base: slice.base,
+      worktree: slice.worktree,
+      dependsOn: slice.dependsOn,
+      branchExists: seen.head !== null,
+      head: seen.head,
+      lastCommitAt: seen.commit,
+      lastActivityAt: seen.last,
+      idleMinutes: idle === null ? null : Math.floor(idle / 60_000),
+      stuckAfterMinutes: Math.round(threshold / 60_000),
+      pr: landing?.pr
+        ? { number: landing.pr.number, url: landing.pr.url, state: landing.pr.state }
+        : null,
+      ci: "unknown",
+      verdict: {
+        accepted: verdict?.accepted.accepted ?? false,
+        basis: verdict?.current.basis ?? "none",
+        review: verdict?.review ?? "unreviewed",
+      },
+      landed:
+        landing?.landed && landing.how
+          ? { how: landing.how, pr: landing.pr?.number ?? null }
+          : null,
+      stuck: false,
+      waitsFor: [],
+      state: "not_started",
+      reasons: [],
+      notes: [
+        ...(landing?.note ? [landing.note] : []),
+        ...(landing?.forgeError ? [`forge: ${landing.forgeError}`] : []),
+      ],
+    };
+    const answered = forge !== null && !landing?.forgeError;
+    if (answered && landing?.pr && landing.pr.state === "open" && !row.landed) {
+      const status = forge.forge.prStatus(landing.pr.number);
+      if (status.ok)
+        row.ci = checksState(gatingChecks(status.data).checks, missingRequired(status.data));
+      else row.notes.push(`forge: ${status.error}`);
+    }
+    row.waitsFor = slice.dependsOn.filter((dep) => !out.get(dep)?.landed);
+    out.set(id, row);
+    if (row.landed) {
+      row.state = "landed";
+      continue;
+    }
+    const started = row.branchExists || seen.worktreeCreated;
+    if (!row.branchExists) row.reasons.push("no branch yet");
+    if (!row.verdict.accepted)
+      row.reasons.push(
+        `verdict ${row.verdict.basis === "none" ? "missing" : row.verdict.basis} on the current head`,
+      );
+    if (answered && row.branchExists) {
+      if (!row.pr) row.reasons.push("no PR");
+      else if (row.pr.state !== "open") row.reasons.push(`PR ${row.pr.state}`);
+      else if (row.ci === "failing" || row.ci === "pending") row.reasons.push(`CI ${row.ci}`);
+    }
+    row.stuck = started && !row.verdict.accepted && idle !== null && idle > threshold;
+    if (row.stuck) row.reasons.push(`no activity for ${row.idleMinutes} min`);
+  }
+
+  // Landing order: landable slices whose dependencies landed or land earlier.
+  const suggested: string[] = [];
+  for (const id of order) {
+    const row = out.get(id) as SliceStatusRow;
+    if (row.landed || row.reasons.length) continue;
+    if (row.waitsFor.every((dep) => suggested.includes(dep))) suggested.push(id);
+  }
+  const spawnable: string[] = [];
+  for (const id of order) {
+    const row = out.get(id) as SliceStatusRow;
+    if (row.landed) continue;
+    const parent = plan.slices.find((other) => other.branch === row.base);
+    if (suggested.includes(id)) row.state = "ready";
+    else if (row.stuck) row.state = "stuck";
+    // Work on a branch is in progress even while its dependency has not landed.
+    else if (row.branchExists) row.state = "active";
+    else if (
+      row.waitsFor.length === 0 ||
+      (parent &&
+        row.waitsFor.length === 1 &&
+        row.waitsFor[0] === parent.id &&
+        out.get(parent.id)?.verdict.accepted)
+    ) {
+      const created = rows.some(
+        (candidate) =>
+          candidate.type === "fanout.worktree.created" &&
+          candidate.fanout === plan.name &&
+          candidate.slice === id,
+      );
+      row.state = created ? "active" : "not_started";
+      if (!created) spawnable.push(id);
+    } else row.state = "waiting";
+    if (row.waitsFor.length && !suggested.includes(id))
+      row.reasons.push(`waits for ${row.waitsFor.join(", ")}`);
+  }
+  const stuck = order.filter((id) => out.get(id)?.stuck);
+  const down = breaker.down();
+  if (down)
+    notes.push(
+      `forge went down during this run (${down}): later slices show no PR or CI, and git alone decided whether they landed`,
+    );
+  const online = forge !== null && !down;
+  // Verified, but the forge has no PR for them yet.
+  const noPr = order.filter((id) => {
+    const row = out.get(id) as SliceStatusRow;
+    return !row.landed && row.reasons.length === 1 && row.reasons[0] === "no PR";
+  });
+  const next = stuck.length
+    ? `replace ${stuck.join(", ")}: stop the worker, then workit fanout worktree release ${stuck[0]} (records git status first) and respawn it in MODE: resume`
+    : suggested.length
+      ? online
+        ? `land in this order: ${suggested.join(", ")} (workit fanout check first; workit pr merge each)`
+        : `land in this order: ${suggested.join(", ")} once each has a PR (offline: PRs unchecked; open a missing one with workit git push && workit pr create --fill, then workit fanout status online)`
+      : noPr.length
+        ? `open PRs for ${noPr.join(", ")}: workit git push && workit pr create --fill on each branch`
+        : spawnable.length
+          ? `spawn ${spawnable.join(", ")} (workit fanout worktree create <slice> on hosts without native worktrees)`
+          : order.every((id) => out.get(id)?.landed)
+            ? "every slice has landed"
+            : "wait for workers, then workit fanout status again";
+  return {
+    ok: true,
+    data: {
+      name: plan.name,
+      trunk: plan.trunk,
+      trunkRef: trunk,
+      forge: {
+        available: online,
+        error: online ? null : (down ?? options.forgeError ?? null),
+      },
+      slices: order.map((id) => out.get(id) as SliceStatusRow),
+      landingOrder: suggested,
+      spawnable,
+      stuck,
+      next,
+      notes,
+    },
+  };
+}