dw-sdlc 0.15.2 → 0.16.1

package/README.md

@@ -48,7 +48,7 @@ its `roots` to `maxProseLines` lines of prose, 3 by default.
 `dw-sdlc pr ship [<n>] [-R owner/name]` reads one pull request through an authenticated `gh` and
 answers the one Action it needs next, as a line or, with `--json`, one document. The exit code says
 whose turn it is: 0 done, 10 the agent's, 20 wait, 30 the dev's, 2 it cannot run. The script
-performs its own Actions: it updates a branch behind its base, marks the head reviewed when the
+performs its own Actions: it updates a branch GitHub reports `BEHIND`, marks the head reviewed when the
 Review depth is `off`, marks a draft ready once nothing else holds it back, and squash merges a pull
 request that is green, reviewed and opened by the `gh` account, when the merge is its own. `--dry-run` performs nothing: it answers the first Action the
 script would perform as the dev's. It never deletes a branch; a merged pull request answers with

package/dist/cli.js

@@ -5,6 +5,7 @@ import * as check from "./commands/check.js";
 import * as config from "./commands/config.js";
 import * as doctor from "./commands/doctor.js";
 import * as gate from "./commands/gate.js";
+import * as leadStart from "./commands/lead-start.js";
 import * as prReviewed from "./commands/pr-reviewed.js";
 import * as prShip from "./commands/pr-ship.js";
 import * as primitives from "./commands/primitives.js";
@@ -31,7 +32,8 @@ const COMMANDS = new Map([
     ["sweep", sweep],
     ["worker start", workerStart],
     ["worker ls", workerLs],
-    ["worker report", workerReport]
+    ["worker report", workerReport],
+    ["lead start", leadStart]
 ]);
 function usage() {
     const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;

package/dist/commands/lead-start.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "start the next session as a Lead in a herdr terminal of its own";
+export declare function run(argv: string[]): Promise<number>;

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;

package/dist/recap-next.js

@@ -0,0 +1,105 @@
+// The candidates for the session after this one, as `dw-sdlc recap` reads them: the open issues an agent may
+// start, from one GraphQL request that also asks which issues the branch's pull request closes.
+import { isObject, parseObject } from "./json-text.js";
+import { CannotRun, gh, said } from "./pr/read.js";
+/** The label that marks an issue as ready for an agent to start. */
+export const READY_LABEL = "ready-for-agent";
+/** How many open issues the one read holds, oldest first, and how many issues the pull request closes. */
+const ISSUES_READ = 100;
+const CLOSING_READ = 25;
+const QUERY = `query Backlog($owner: String!, $name: String!, $number: Int!, $closing: Boolean!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) @include(if: $closing) { closingIssuesReferences(first: ${CLOSING_READ}) { nodes { number } } }
+    issues(first: ${ISSUES_READ}, states: OPEN, labels: ["${READY_LABEL}"], orderBy: { field: CREATED_AT, direction: ASC }) {
+      nodes { number title url assignees { totalCount } issueDependenciesSummary { blockedBy } parent { number } }
+    }
+  }
+}`;
+const REMEDY = "check gh auth status and the network, then call again";
+function malformed(field) {
+    return new CannotRun(`the backlog reply does not parse: ${field}`, "gh answered a shape dw-sdlc does not read; report it with the output of gh --version");
+}
+function nodesOf(value, field) {
+    if (!isObject(value) || !Array.isArray(value.nodes)) {
+        throw malformed(field);
+    }
+    return value.nodes;
+}
+function numberOf(value, field) {
+    if (!isObject(value) || typeof value.number !== "number") {
+        throw malformed(field);
+    }
+    return value.number;
+}
+/** An issue node as a candidate, or null when it has an assignee or an open blocker. */
+function candidateOf(node) {
+    if (!isObject(node) || typeof node.title !== "string" || typeof node.url !== "string") {
+        throw malformed("issues.nodes");
+    }
+    const { assignees, issueDependenciesSummary: dependencies, parent } = node;
+    if (!isObject(assignees) || typeof assignees.totalCount !== "number") {
+        throw malformed("issues.nodes.assignees");
+    }
+    if (!isObject(dependencies) || typeof dependencies.blockedBy !== "number") {
+        throw malformed("issues.nodes.issueDependenciesSummary");
+    }
+    if (assignees.totalCount > 0 || dependencies.blockedBy > 0) {
+        return null;
+    }
+    const number = numberOf(node, "issues.nodes.number");
+    return { number, title: node.title, url: node.url, parent: parent === null ? null : numberOf(parent, "parent") };
+}
+function repositoryOf(stdout) {
+    const data = parseObject(stdout)?.data;
+    const repository = isObject(data) ? data.repository : undefined;
+    if (!isObject(repository)) {
+        throw malformed("data.repository");
+    }
+    return repository;
+}
+/**
+ * The open issues labelled ready-for-agent with no assignee and no open blocker, read from `repo`, or from the
+ * repository gh resolves when it is null. The open sub-issues of an issue pull request `pr` closes come
+ * first, then the rest, each part in issue order; the issues it closes are never candidates.
+ */
+function nextCandidates(pr) {
+    const [owner, name] = pr === null ? ["{owner}", "{repo}"] : pr.repo.split("/");
+    const reply = gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${QUERY}`,
+        "-F",
+        `owner=${owner ?? ""}`,
+        "-F",
+        `name=${name ?? ""}`,
+        "-F",
+        `number=${pr?.number ?? 0}`,
+        "-F",
+        `closing=${pr !== null}`
+    ]);
+    if (reply.status !== 0) {
+        throw new CannotRun(`gh could not read the backlog: ${said(reply.stderr)}`, REMEDY);
+    }
+    const repository = repositoryOf(reply.stdout);
+    const closes = new Set(pr === null
+        ? []
+        : nodesOf(isObject(repository.pullRequest) ? repository.pullRequest.closingIssuesReferences : undefined, "pullRequest").map((node) => numberOf(node, "closingIssuesReferences.nodes")));
+    const candidates = nodesOf(repository.issues, "issues")
+        .map(candidateOf)
+        .filter((candidate) => candidate !== null && !closes.has(candidate.number))
+        .toSorted((one, other) => one.number - other.number);
+    const underClosed = (candidate) => candidate.parent !== null && closes.has(candidate.parent);
+    return [...candidates.filter(underClosed), ...candidates.filter((candidate) => !underClosed(candidate))];
+}
+export function readNext(pr) {
+    try {
+        return { candidates: nextCandidates(pr) };
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            return { unread: error.message };
+        }
+        throw error;
+    }
+}

package/dist/worker/launch.d.ts

@@ -0,0 +1,31 @@
+/** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
+export declare const NAME: RegExp;
+/** The most seconds a start looks for the new tab in the window, beside the read-back. */
+export declare const TAB_WAIT = 10;
+/** The id of the herdr space the terminal `id` sits in, if it sits in one. */
+export declare function spaceOf(id: string): string | undefined;
+export type Launch = {
+    name: string;
+    /** The `role` label of the new terminal. */
+    role: "worker" | "lead";
+    /** The herdr space of the caller, which the new terminal joins; none leaves the tab alone. */
+    space: string | undefined;
+    /** The folder it starts in. */
+    cwd: string;
+    /** The program and its arguments, its first message last. */
+    argv: string[];
+    /** The most seconds the read-back waits. */
+    wait: number;
+};
+export type Launched = {
+    address: string;
+    tab: "none" | "renamed" | "kept";
+    reason: string | undefined;
+};
+/**
+ * Runs `hc run` once for `launch`, outliving its caller, then names the tab and reads the terminal back side
+ * by side. It never sends the first message again; `reason` says why the session did not take it.
+ */
+export declare function launch(command: string, { name, role, space, cwd, argv, wait }: Launch): Promise<Launched>;
+/** The line that says a started session did not take its first message, and how to recover. */
+export declare function undelivered(command: string, name: string, address: string, reason: string, message: string): string;

package/dist/worker/launch.js

@@ -0,0 +1,100 @@
+// What `worker start` and `lead start` share: a session started in a herdr terminal of its own beside the
+// caller, its tab named, and the terminal read back until the session shows it took its first message.
+import { setTimeout as sleep } from "node:timers/promises";
+import { isObject } from "../json-text.js";
+import { describe, hcObject, Refusal } from "./herdr.js";
+import { nameTab } from "./tabs.js";
+/** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
+export const NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+/** The most seconds a start looks for the new tab in the window, beside the read-back. */
+export const TAB_WAIT = 10;
+/** What a session 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;
+/** The status a session reports, if it has reported one. */
+function reportedStatus(terminal) {
+    const { status } = terminal;
+    return isObject(status) && typeof status.state === "string" ? status.state : undefined;
+}
+/** Why the session, called `who`, can no longer take its first message, or undefined while it still may. */
+function failure(terminal, who) {
+    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 ${who} reports its status as error` : undefined;
+}
+/** Reads the terminal until the session shows work, for up to `wait` seconds; why it did not, or undefined once it did. */
+async function delivery(address, wait, who) {
+    const deadline = Date.now() + wait * 1000;
+    for (;;) {
+        let terminal;
+        try {
+            terminal = hcObject(["get", address, "--json"]);
+        }
+        catch (error) {
+            if (!(error instanceof Refusal)) {
+                throw error;
+            }
+            // The session is running by now, so a failed read is a message not confirmed, never a start that did not happen.
+            return `the terminal could not be read back: ${describe(error)}`;
+        }
+        const failed = failure(terminal, who);
+        if (failed !== undefined) {
+            return failed;
+        }
+        if (WORKING.has(reportedStatus(terminal) ?? "")) {
+            return undefined;
+        }
+        if (Date.now() >= deadline) {
+            return `the ${who} showed no sign of work within ${wait} s`;
+        }
+        await sleep(POLL_MS);
+    }
+}
+/** The id of the herdr space the terminal `id` sits in, if it sits in one. */
+export function spaceOf(id) {
+    const { labels } = hcObject(["get", id, "--json"]);
+    const space = isObject(labels) ? labels["herdr.space"] : undefined;
+    return typeof space === "string" ? space : undefined;
+}
+/**
+ * Runs `hc run` once for `launch`, outliving its caller, then names the tab and reads the terminal back side
+ * by side. It never sends the first message again; `reason` says why the session did not take it.
+ */
+export async function launch(command, { name, role, space, cwd, argv, wait }) {
+    const { address } = hcObject([
+        "run",
+        "--bg",
+        "--json",
+        "--name",
+        name,
+        "--label",
+        `role=${role}`,
+        ...(space === undefined ? [] : ["--label", `herdr.space=${space}`]),
+        "--outlive-parent",
+        "--cwd",
+        cwd,
+        "--",
+        ...argv
+    ]);
+    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 session to start.
+    const naming = space === undefined ? Promise.resolve("none") : nameTab(address, name, Math.min(TAB_WAIT, wait));
+    const [named, reason] = await Promise.all([naming, delivery(address, wait, role === "lead" ? "Lead" : "Worker")]);
+    if (typeof named === "object") {
+        process.stderr.write(`dw-sdlc ${command}: warning: ${named.kept}\n`);
+    }
+    return { address, tab: typeof named === "object" ? "kept" : named, reason };
+}
+/** The line that says a started session did not take its first message, and how to recover. */
+export function undelivered(command, name, address, reason, message) {
+    return (`dw-sdlc ${command}: ${name} (${address}) started but its first message was not delivered: ${reason} — ` +
+        `run hc read ${address} to see why; do not send the ${message} again before you have read it\n`);
+}

package/dist/worker/origin.js

@@ -27,7 +27,8 @@ export function freshenOrigin(root, baseBranch) {
     const branch = defaultBranch(root, baseBranch);
     const args = ["-C", root, "fetch", "--quiet", "origin", ...(branch === undefined ? [] : [branch])];
     const fetched = `git fetch origin${branch === undefined ? "" : ` ${branch}`}`;
-    const stale = (why) => new Refusal(`${fetched} failed, so the Worker would begin from a stale base: ${why}`, "check the network and the access to origin, then start the Worker again");
+    const stale = (why) => new Refusal(`${fetched} failed, so the Worker would begin from a stale base: ${why}`, "check the network and the access to origin; when origin/HEAD names a branch the remote no longer has, " +
+        "run `git remote set-head origin --auto`; then start the Worker again");
     let result;
     try {
         result = exec("git", args, { env: repositoryFreeEnv(), limitMs: SLOW_LIMIT_MS });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.15.2",
+  "version": "0.16.1",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {