dw-sdlc 0.15.2 → 0.17.0

package/dist/commands/lead-start.js

@@ -0,0 +1,135 @@
+// `dw-sdlc lead start`: starts the next session as a Lead in a herdr terminal of its own, beside the caller and
+// outliving it, on the command the config names for a Worker, without what makes it unsafe or isolated.
+import { parseArgs } from "node:util";
+import { mainCheckout, repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { describe, lead, refuse, Refusal, wholeNumber } from "../worker/herdr.js";
+import { launch, NAME, spaceOf, TAB_WAIT, undelivered } from "../worker/launch.js";
+export const summary = "start the next session as a Lead in a herdr terminal of its own";
+const USAGE = `Usage: dw-sdlc lead start --name <name> --prompt <first message> [--wait <seconds>] [--json]
+
+Starts a Lead in the background, the session after this one, and gives it the first message, such as
+/sdlc-delegate #326. It runs hc run with the name, the label role=lead, --outlive-parent and the main
+checkout as the folder, then worker.command of the config with the first message. It drops
+--dangerously-skip-permissions from the command, since a session never starts another that skips them, and
+any --worktree or -w with its name, since a Lead works in the main checkout. worker.command is split on
+whitespace, so it holds no quoted word. When the caller sits in a herdr space the Lead joins it, and its tab,
+which herdr numbers, takes the Lead's name: the window lists the tab a moment after hc run, so the command
+looks for it for up to ${TAB_WAIT} seconds, or --wait when shorter, while it reads the terminal back.
+
+It reads the terminal back for up to --wait seconds (default 30), until the Lead shows work: its status
+turns working, blocked or done. It fails when herdr reports the first message as unsent, the terminal has
+ended, the Lead reports an error, or the Lead is still idle or silent when the time is up. It never sends
+the first message again: read the terminal with hc read first.
+
+It refuses outside herdr ($HC_TERMINAL_ID unset) and in a linked worktree, where a Lead cannot start its
+Workers. The name is 1-32 of a-z, 0-9, - and _, such as lead-<issue>-<slug>.
+
+One line, or one JSON document with --json.
+
+Exit 0 started and delivered, 1 started but not delivered, 2 when it cannot run.`;
+const DEFAULT_WAIT = 30;
+/** What a session started by a session never carries: it would run with no permission check. */
+const UNSAFE = "--dangerously-skip-permissions";
+/** The flags that put a Claude Code session in a worktree of its own, each taking an optional name. */
+const WORKTREE = new Set(["--worktree", "-w"]);
+function parseCli(argv) {
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                name: { type: "string" },
+                prompt: { type: "string" },
+                wait: { type: "string" }
+            }
+        });
+        if (values.help === true) {
+            return "help";
+        }
+        const { name, prompt } = values;
+        if (name === undefined || !NAME.test(name)) {
+            return { error: `--name takes 1-32 of a-z, 0-9, - and _, not ${JSON.stringify(name ?? "")}` };
+        }
+        if (prompt === undefined || prompt.trim() === "") {
+            return { error: "give the Lead its first message: --prompt <first message>" };
+        }
+        const wait = wholeNumber("--wait", values.wait, DEFAULT_WAIT, 0);
+        if (typeof wait === "object") {
+            return wait;
+        }
+        return { name, prompt, wait, json: values.json === true };
+    }
+    catch (error) {
+        return { error: describe(error) };
+    }
+}
+/** `words` without the flag that skips permissions and without a worktree flag, its name with it when it has one. */
+function leadCommand(words) {
+    const kept = [];
+    for (let index = 0; index < words.length; index += 1) {
+        const word = words[index] ?? "";
+        if (word === UNSAFE || word.startsWith("--worktree=")) {
+            continue;
+        }
+        if (WORKTREE.has(word)) {
+            const next = words[index + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                index += 1;
+            }
+            continue;
+        }
+        kept.push(word);
+    }
+    return kept;
+}
+async function start(cli) {
+    const caller = lead();
+    const checkout = repositoryRoot(process.cwd());
+    const main = mainCheckout(checkout);
+    if (main !== undefined) {
+        throw new Refusal(`in a linked worktree, ${checkout}: a Lead works in the main checkout, and this session cannot start one there`, `run it from the main checkout, ${main}, or start the Lead there by hand`);
+    }
+    const command = leadCommand(resolveConfig(checkout).config.worker.command.split(/\s+/).filter(Boolean));
+    if (command.length === 0) {
+        throw new Refusal("worker.command holds no command", "set it in .ai/agentic.config.local.json, or remove the key");
+    }
+    const { address, tab, reason } = await launch("lead start", {
+        name: cli.name,
+        role: "lead",
+        space: spaceOf(caller),
+        cwd: checkout,
+        argv: [...command, cli.prompt],
+        wait: cli.wait
+    });
+    if (cli.json) {
+        const started = { name: cli.name, address, command: command.join(" "), cwd: checkout };
+        const document = { ...started, delivered: reason === undefined, ...(reason === undefined ? {} : { reason }), tab };
+        process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
+    }
+    if (reason !== undefined) {
+        process.stderr.write(undelivered("lead start", cli.name, address, reason, "first message"));
+        return 1;
+    }
+    if (!cli.json) {
+        process.stdout.write(`started ${cli.name} (${address}) in ${checkout}\n`);
+    }
+    return 0;
+}
+export async function run(argv) {
+    const cli = parseCli(argv);
+    if (cli === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc lead start: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        return await start(cli);
+    }
+    catch (error) {
+        return refuse("lead start", error);
+    }
+}

package/dist/commands/pr-ship.js

@@ -4,7 +4,7 @@
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig, REVIEW_DEPTHS } from "../agentic-config.js";
 import { decide, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
-import { CannotRun, carriesBase, gh, namedProblem, nameItRemedy, now, read, readAgain, readBranch, said, withBehind } from "../pr/read.js";
+import { CannotRun, carriesBase, gh, namedProblem, nameItRemedy, now, read, readAgain, readBranch, said } from "../pr/read.js";
 import { holds, renamedUpstream } from "../pr/upstream.js";
 export const summary = "decide the Action one pull request needs next, as a line or JSON";
 const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--review full|light|off] [--dry-run] [--json] [--verbose]
@@ -14,18 +14,17 @@ is omitted, and answers the Action it needs next: the status, the action, whose
 A branch pushed under another name has an upstream of that name. Where gh resolves no pull request
 for it, the script asks for the upstream's, and reads it only when its commits hold HEAD.
 The script performs its own Actions, each at most once and then reads again: it updates a branch
-behind its base, marks a draft ready once nothing else holds it back, and squash merges a pull
+GitHub reports BEHIND, marks a draft ready once nothing else holds it back, and squash merges a pull
 request ready to merge under pr.merge auto in .ai/agentic.config.json or with --merge for this call;
-under ask, the default, it parks with the merge command. A branch is behind when the compare of
-the base with the head shows the head lacks a commit of the base, or GitHub reports BEHIND, which
-it does only under a rule that a branch be up to date. A head without a ${REVIEW} success
-gets the Review depth --review names for this call, else pr.review: under full the agent reviews it
-with the command pr.reviewCommand names, /code-review by default; under light one sdlc-reviewer
-subagent reads the diff; under off the script posts the success itself, its description saying
-why. Under auto, the default, the script routes the depth from the changes the Review would read:
-lockfiles alone off; a file under .github/workflows/, more than 100 changed lines outside
-lockfiles, or a change it cannot size, more files than GitHub's compare lists or a file outside
-lockfiles with no patch, full; the rest light. After a push it names
+under ask, the default, it parks with the merge command. GitHub reports BEHIND only under a rule
+that a branch be up to date; a branch only behind its base merges as it is. A head without a
+${REVIEW} success gets the Review depth --review names for this call, else pr.review: under full
+the agent reviews it with the command pr.reviewCommand names, /code-review by default; under light
+one sdlc-reviewer subagent reads the diff; under off the script posts the success itself, its
+description saying why. Under auto, the default, the script routes the depth from the changes the
+Review would read: lockfiles alone off; a file under .github/workflows/, more than 100 changed
+lines outside lockfiles, or a change it cannot size, more files than GitHub's compare lists or a
+file outside lockfiles with no patch, full; the rest light. After a push it names
 the last commit a Review read under details.since, where the Review reads from and auto routes from:
 one with a ${REVIEW} success not posted under off, or the read mark pr reviewed --findings
 posts. It carries a success over a head whose only commits since are merges of the base, unless
@@ -171,7 +170,7 @@ function readTarget(cli, root, sized) {
 function ship(cli, root, policy) {
     // Only pr.review auto routes the depth from the changes, so only it reads them.
     const sized = policy.review.depth === "auto";
-    let pr = withBehind(readTarget(cli, root, sized));
+    let pr = readTarget(cli, root, sized);
     const performed = [];
     // The head each Action ran on.
     const postedOn = new Map();
@@ -205,7 +204,7 @@ function ship(cli, root, policy) {
         const record = { action, command, exit: status, ...(message === "" ? {} : { stderr: message }) };
         postedOn.set(action, before.head);
         try {
-            pr = withBehind(readAgain(pr, sized));
+            pr = readAgain(pr, sized);
             performed.push({ ...record, ok: TOOK[action](before, pr) });
         }
         catch (error) {

package/dist/commands/recap.d.ts

@@ -1,2 +1,2 @@
-export declare const summary = "the facts a Recap rests on and whether the session can be closed";
+export declare const summary = "the facts a Recap rests on, whether the session can be closed and what could come next";
 export declare function run(argv: string[]): number;

package/dist/commands/recap.js

@@ -7,9 +7,10 @@ import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.j
 import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
 import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
 import { holds, upstreamName } from "../pr/upstream.js";
+import { READY_LABEL, readNext } from "../recap-next.js";
 import { isLive, Refusal, workersOf, workingFolders } from "../worker/herdr.js";
 import { asked, git } from "../working-tree.js";
-export const summary = "the facts a Recap rests on and whether the session can be closed";
+export const summary = "the facts a Recap rests on, whether the session can be closed and what could come next";
 const USAGE = `Usage: dw-sdlc recap [--json]
 
 Reads the current branch, its uncommitted changes, the commits that reach no remote, its pull request
@@ -34,6 +35,12 @@ stand. A branch force-pushed since the last fetch can still read as holding it,
 A linked worktree is a reason beside the verdict, never against it: the session cannot remove the
 directory it runs in.
 
+Beside the verdict it lists the candidates for the next session: the open issues labelled
+${READY_LABEL} with no assignee and no open blocker, of the 100 opened first. The open sub-issues of an
+issue the branch's pull request closes come first, then the rest, each in issue order; an issue it closes
+is no candidate. Choosing one is the Recap's, never the command's. A backlog it cannot read lists none,
+with a warning, and leaves the verdict as it is.
+
 One line a fact, or one document with --json. Needs an authenticated gh and a remote it can read, and in
 herdr hc on PATH. A detached HEAD or a repository with no remote asks gh nothing, and the pull request
 fact says so; outside herdr the workers fact says so.
@@ -268,7 +275,17 @@ function workersLine(workers) {
     }
     return workers.length === 0 ? "none live" : `${workers.length} live: ${workersText(workers)}`;
 }
-function linesOf(local, { shipped, askedGh, workers }, line) {
+function nextLine(next) {
+    if (next === null) {
+        return "gh not asked";
+    }
+    if ("unread" in next) {
+        return `not read, ${next.unread}`;
+    }
+    const named = next.candidates.map(({ number, parent }) => `#${number}${parent === null ? "" : ` (sub-issue of #${parent})`}`);
+    return named.length === 0 ? "none" : named.join(", ");
+}
+function linesOf(local, { shipped, askedGh, workers, next }, line) {
     const none = askedGh ? "none" : "gh not asked";
     return [
         `branch: ${local.branch ?? "detached HEAD"}`,
@@ -277,6 +294,7 @@ function linesOf(local, { shipped, askedGh, workers }, line) {
         `pull request: ${shipped === null ? none : `${shipped.pr.url} ${lineOf(shipped.answer)}`}`,
         `worktree: ${local.worktree.linked ? `linked at ${local.worktree.path}` : "main checkout"}`,
         `workers: ${workersLine(workers)}`,
+        `next: ${nextLine(next)}`,
         line
     ].join("\n");
 }
@@ -316,14 +334,19 @@ function report(json) {
         ahead,
         orphaned: orphanedOf(root, read, shipped, held),
         askedGh: asksGh,
-        workers: liveWorkers()
+        workers: liveWorkers(),
+        next: asksGh ? readNext(shipped === null ? null : shipped.pr) : null
     };
+    if (facts.next !== null && "unread" in facts.next) {
+        process.stderr.write(`dw-sdlc recap: warning: the backlog was not read: ${facts.next.unread}\n`);
+    }
+    const next = facts.next !== null && "candidates" in facts.next ? facts.next.candidates : null;
     const close = closeOf(reasonsOf(local, facts));
     const pullRequest = shipped === null
         ? null
         : { url: shipped.pr.url, number: shipped.pr.number, state: shipped.pr.state, ...shipped.answer };
     const output = json
-        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, close }, null, 2)
+        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, close, next }, null, 2)
         : linesOf(local, facts, close.line);
     process.stdout.write(`${output}\n`);
     return close.verdict === "yes" ? 0 : 1;

package/dist/commands/worker-start.js

@@ -2,16 +2,12 @@
 // and effort the config names, and reads back whether the Worker took it.
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
 import { mainCheckout, repositoryRoot, resolveConfig, WORKER_EFFORTS } from "../agentic-config.js";
-import { isObject } from "../json-text.js";
-import { describe, hcObject, isLive, lead, refuse, Refusal, wholeNumber, workersOf } from "../worker/herdr.js";
+import { describe, isLive, lead, refuse, Refusal, wholeNumber, workersOf } from "../worker/herdr.js";
+import { launch, NAME, spaceOf, TAB_WAIT, undelivered } from "../worker/launch.js";
 import { freshenOrigin } from "../worker/origin.js";
-import { nameTab } from "../worker/tabs.js";
 export const summary = "start a Worker on a Brief in a herdr terminal";
-/** The most seconds the command looks for the Worker's tab in the window, beside the read-back. */
-const TAB_WAIT = 10;
 const USAGE = `Usage: dw-sdlc worker start --brief <file> --name <name> [--model <model>] [--effort <effort>]
                             [--max-workers <n>] [--wait <seconds>] [--json]
 
@@ -41,12 +37,6 @@ One line, or one JSON document with --json.
 Exit 0 started and delivered, 1 started but not delivered, 2 when it cannot run, a failed fetch included.`;
 const DEFAULT_MAX_WORKERS = 3;
 const DEFAULT_WAIT = 30;
-/** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
-const NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
-/** What a Worker reports once it has taken its first message. */
-const WORKING = new Set(["working", "blocked", "done"]);
-/** How long the read-back waits between two reads of the terminal. */
-const POLL_MS = 1000;
 function parseCli(argv) {
     try {
         const { values } = parseArgs({
@@ -106,56 +96,6 @@ function readBrief(file) {
     }
     return text;
 }
-/** The status a Worker reports, if it has reported one. */
-function reportedStatus(terminal) {
-    const { status } = terminal;
-    return isObject(status) && typeof status.state === "string" ? status.state : undefined;
-}
-/** Why the Worker can no longer take the Brief, or undefined while it still may. */
-function failure(terminal) {
-    const { first_message: first, state } = terminal;
-    if (isObject(first) && first.sent === false) {
-        return typeof first.reason === "string" ? first.reason : "herdr gave no reason";
-    }
-    if (state !== "live") {
-        return "the terminal has finished";
-    }
-    return reportedStatus(terminal) === "error" ? "the Worker reports its status as error" : undefined;
-}
-/** Reads the terminal until the Worker shows work, for up to `wait` seconds; why it did not, or undefined once it did. */
-async function delivery(address, wait) {
-    const deadline = Date.now() + wait * 1000;
-    for (;;) {
-        let terminal;
-        try {
-            terminal = hcObject(["get", address, "--json"]);
-        }
-        catch (error) {
-            if (!(error instanceof Refusal)) {
-                throw error;
-            }
-            // The Worker is running by now, so a failed read is a Brief not confirmed, never a start that did not happen.
-            return `the terminal could not be read back: ${describe(error)}`;
-        }
-        const failed = failure(terminal);
-        if (failed !== undefined) {
-            return failed;
-        }
-        if (WORKING.has(reportedStatus(terminal) ?? "")) {
-            return undefined;
-        }
-        if (Date.now() >= deadline) {
-            return `the Worker showed no sign of work within ${wait} s`;
-        }
-        await sleep(POLL_MS);
-    }
-}
-/** The id of the herdr space the Lead sits in, if it sits in one. */
-function spaceOf(leadId) {
-    const { labels } = hcObject(["get", leadId, "--json"]);
-    const space = isObject(labels) ? labels["herdr.space"] : undefined;
-    return typeof space === "string" ? space : undefined;
-}
 async function start(cli) {
     const brief = readBrief(cli.brief);
     const leadId = lead();
@@ -175,47 +115,21 @@ async function start(cli) {
     }
     // Before hc run, so a failed fetch starts no terminal.
     freshenOrigin(root, baseBranch);
-    const space = spaceOf(leadId);
-    const { address } = hcObject([
-        "run",
-        "--bg",
-        "--json",
-        "--name",
-        cli.name,
-        "--label",
-        "role=worker",
-        ...(space === undefined ? [] : ["--label", `herdr.space=${space}`]),
-        "--outlive-parent",
-        "--cwd",
-        root,
-        "--",
-        ...command,
-        "--worktree",
-        cli.name,
-        "--model",
-        model,
-        "--effort",
-        effort,
-        brief
-    ]);
-    if (typeof address !== "string") {
-        throw new Refusal("hc run answered no address for the terminal it started", "check hc ls before starting it again");
-    }
-    // Side by side, so the wait for the tab overlaps the wait for the Worker to start.
-    const naming = space === undefined ? Promise.resolve("none") : nameTab(address, cli.name, Math.min(TAB_WAIT, cli.wait));
-    const [named, reason] = await Promise.all([naming, delivery(address, cli.wait)]);
-    if (typeof named === "object") {
-        process.stderr.write(`dw-sdlc worker start: warning: ${named.kept}\n`);
-    }
+    const { address, tab, reason } = await launch("worker start", {
+        name: cli.name,
+        role: "worker",
+        space: spaceOf(leadId),
+        cwd: root,
+        argv: [...command, "--worktree", cli.name, "--model", model, "--effort", effort, brief],
+        wait: cli.wait
+    });
     if (cli.json) {
-        const tab = typeof named === "object" ? "kept" : named;
         const started = { name: cli.name, address, command: worker.command, model, effort, cwd: root };
         const document = { ...started, delivered: reason === undefined, ...(reason === undefined ? {} : { reason }), tab };
         process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
     }
     if (reason !== undefined) {
-        process.stderr.write(`dw-sdlc worker start: ${cli.name} (${address}) started but its first message was not delivered: ${reason} — ` +
-            `run hc read ${address} to see why; do not send the Brief again before you have read it\n`);
+        process.stderr.write(undelivered("worker start", cli.name, address, reason, "Brief"));
         return 1;
     }
     if (!cli.json) {

package/dist/pr/decide.js

@@ -157,7 +157,9 @@ const ROWS = [
             action: "done",
             actor: "dev",
             reason: pr.mergeCommit === null ? "merged" : `merged as ${pr.mergeCommit.slice(0, 7)}`,
-            ...(pr.branchStands ? { command: shellLine(["git", "push", "origin", "--delete", pr.branch]) } : {}),
+            ...(pr.branchStands && !pr.fromFork
+                ? { command: shellLine(["git", "push", "origin", "--delete", pr.branch]) }
+                : {}),
             ...(pr.mergeCommit === null ? {} : { details: { mergeCommit: pr.mergeCommit } })
         }),
         alone: true
@@ -189,8 +191,9 @@ const ROWS = [
         })
     },
     {
-        // GitHub reports BEHIND only under a rule that a branch be up to date; the compare tells it anywhere.
-        when: (pr) => pr.mergeStateStatus === "BEHIND" || (pr.behindBy ?? 0) > 0,
+        // GitHub reports BEHIND only under a rule that a branch be up to date. A branch only behind its base
+        // merges as it is: CI ran on its merge with the base as the base stood at that run.
+        when: (pr) => pr.mergeStateStatus === "BEHIND",
         answer: (pr) => ({ status: "act", action: "update-branch", actor: "script", reason: `behind ${pr.base}` })
     },
     {
@@ -249,8 +252,9 @@ const ROWS = [
         }
     },
     {
-        // A head whose every check was skipped has run nothing: a draft's are, until `ready` starts the run.
-        when: (pr) => ciOf(pr).length === 0 || (!pr.draft && ciOf(pr).every((check) => check.bucket === "skipping")),
+        // A head whose every check was skipped, or that has none, has run nothing. A draft's runs skip or
+        // never start until `ready` starts the run, so a draft is no case of it: `mark-ready` is its row.
+        when: (pr) => !pr.draft && (ciOf(pr).length === 0 || ciOf(pr).every((check) => check.bucket === "skipping")),
         answer: (pr, now, policy) => now - Math.max(Date.parse(pr.headCommittedAt), Date.parse(pr.readyAt ?? pr.headCommittedAt)) <=
             GRACE_SECONDS * 1000
             ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }

package/dist/pr/read.d.ts

@@ -43,8 +43,3 @@ export declare function readAgain(pr: PrState, sized: boolean): PrState;
 export declare function forgetCompares(): void;
 /** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
 export declare function carriesBase(before: PrState, after: PrState): boolean;
-/**
- * `pr` and how many commits of its base its head lacks, from the compare of the base with the head,
- * read only where the decision can reach the update: open, mergeable, not reported BEHIND already.
- */
-export declare function withBehind(pr: PrState): PrState;

package/dist/pr/read.js

@@ -187,17 +187,6 @@ export function carriesBase(before, after) {
     const reply = compared(after, before.baseOid, after.head, `the compare with ${before.baseOid.slice(0, 7)}`);
     return parseOrCannotRun(() => behindOf(reply)) === 0;
 }
-/**
- * `pr` and how many commits of its base its head lacks, from the compare of the base with the head,
- * read only where the decision can reach the update: open, mergeable, not reported BEHIND already.
- */
-export function withBehind(pr) {
-    if (pr.state !== "OPEN" || pr.mergeable !== "MERGEABLE" || pr.mergeStateStatus === "BEHIND") {
-        return pr;
-    }
-    const reply = compared(pr, pr.baseOid, pr.head, `the compare with ${pr.base}`);
-    return { ...pr, behindBy: parseOrCannotRun(() => behindOf(reply)) };
-}
 /** The own changes of `pr` at `commit`, from the compare with its base; null when it cannot show them whole. */
 function ownChanges(pr, commit) {
     const reply = compared(pr, pr.baseOid, commit, `the compare with ${commit.slice(0, 7)}`);
@@ -248,5 +237,5 @@ function query({ repo, number }, sized) {
         throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
     }
     const parsed = parseOrCannotRun(() => parsePr(reply.stdout, repo));
-    return withChanged(withCarried({ ...parsed, behindBy: null }), sized);
+    return withChanged(withCarried(parsed), sized);
 }

package/dist/pr/state.d.ts

@@ -10,7 +10,7 @@ export declare const MARK_STATE = "failure";
 export declare const READ_MARK = "read, findings open";
 /** How the description of the success the dev's `--accept` posts reads: the head, taken with its Findings open. */
 export declare const ACCEPTED = "accepted by the dev, findings open";
-export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName headRef { name } baseRefName\n      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { pageInfo { hasNextPage } nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName headRef { name } isCrossRepository baseRefName\n      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { pageInfo { hasNextPage } nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -56,6 +56,8 @@ export type PrState = {
     branch: string;
     /** Whether the head branch still stands on the remote: GitHub reports no `headRef` once it is gone. */
     branchStands: boolean;
+    /** Whether the pull request comes from a fork: its head branch lives on the fork, not on `origin`. */
+    fromFork: boolean;
     base: string;
     /**
      * The commit the base branch points at, read from the branch itself: GitHub's `baseRefOid` lags a
@@ -86,11 +88,6 @@ export type PrState = {
      * auto` to route on: `unsized` when the compare cannot list them all, null when not read.
      */
     changed: ChangedFile[] | "unsized" | null;
-    /**
-     * How many commits of the base the head lacks, from the compare of the base with the head; null when
-     * not read.
-     */
-    behindBy: number | null;
 };
 /**
  * A file a Review would read: its name, its name before a rename, and the lines it adds and removes,
@@ -147,5 +144,5 @@ export declare function parseView(reply: string): {
 /** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
 export declare function parseDefaultBranch(reply: string): string;
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
-export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed" | "behindBy">;
+export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed">;
 export {};

package/dist/pr/state.js

@@ -18,7 +18,7 @@ const THREADS_READ = 100;
 export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
-      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName headRef { name } baseRefName
+      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName headRef { name } isCrossRepository baseRefName
       baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }
       ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }
       latestReviews(first: 100) { nodes { state author { login } commit { oid } } }
@@ -319,6 +319,7 @@ export function parsePr(reply, repo) {
         readyAt: ready === undefined ? null : time(ready, "createdAt"),
         branch: string(pr, "headRefName"),
         branchStands: childOrNull(pr, "headRef") !== null,
+        fromFork: boolean(pr, "isCrossRepository"),
         base: string(pr, "baseRefName"),
         baseOid: baseRef === null ? string(pr, "baseRefOid") : string(child(baseRef, "target"), "oid"),
         mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),

package/dist/recap-next.d.ts

@@ -0,0 +1,19 @@
+/** The label that marks an issue as ready for an agent to start. */
+export declare const READY_LABEL = "ready-for-agent";
+/** An issue the next session may start; `parent` the issue it is a sub-issue of, null for none. */
+export type Candidate = {
+    number: number;
+    title: string;
+    url: string;
+    parent: number | null;
+};
+/** The candidates, or why the backlog could not be read: a Recap closes without them, so no failure stops it. */
+export type Next = {
+    candidates: Candidate[];
+} | {
+    unread: string;
+};
+export declare function readNext(pr: {
+    repo: string;
+    number: number;
+} | null): Next;