dw-sdlc 0.13.0 → 0.15.0

package/dist/landed.js

@@ -1,7 +1,7 @@
 // Whether a local branch is Landed: its work is on the base, as the guard's `guard_landed`
 // (plugins/sdlc/hooks/lib-git.sh) judges it. The guard keeps its own bash version; docs/adr/0015 says why there
 // are two, and the shared table of scenarios, plugins/sdlc/test/landed-scenarios.ts, holds them to one meaning.
-import { spawnSync } from "node:child_process";
+import { exec, SLOW_LIMIT_MS } from "./exec.js";
 import { repositoryFreeEnv } from "./git-env.js";
 /** The base commits read, newest first: a branch that forked further back is kept rather than read for seconds. */
 const SCAN = 5000;
@@ -9,18 +9,17 @@ const SCAN = 5000;
 function localEnv() {
     return { ...repositoryFreeEnv(), GIT_NO_LAZY_FETCH: "1" };
 }
-function git(root, args, input) {
-    const result = spawnSync("git", ["-C", root, ...args], {
-        encoding: "utf8",
+function git(root, args, input, limitMs) {
+    const result = exec("git", ["-C", root, ...args], {
         env: localEnv(),
-        input,
-        maxBuffer: 64 * 1024 * 1024
+        ...(input === undefined ? {} : { input }),
+        ...(limitMs === undefined ? {} : { limitMs })
     });
     return { status: result.status ?? 1, stdout: result.stdout ?? "" };
 }
 /** What `git <args>` prints, or undefined when it exits non-zero. */
-function answer(root, args, input) {
-    const ran = git(root, args, input);
+function answer(root, args, input, limitMs) {
+    const ran = git(root, args, input, limitMs);
     return ran.status === 0 ? ran.stdout.trim() : undefined;
 }
 /** The patch-id of the whole diff from `from` to `to`; undefined for an empty diff or one git could not finish. */
@@ -44,10 +43,9 @@ function baseHoldsPatch(root, range, patch) {
             "git patch-id --verbatim"
         ].join(" | ")
     ].join("; ");
-    const result = spawnSync("bash", ["-c", pipeline, "bash", root, String(SCAN), range], {
-        encoding: "utf8",
+    const result = exec("bash", ["-c", pipeline, "bash", root, String(SCAN), range], {
         env: localEnv(),
-        maxBuffer: 64 * 1024 * 1024
+        limitMs: SLOW_LIMIT_MS
     });
     if (result.status !== 0) {
         return false;
@@ -77,7 +75,7 @@ export function isCommitLanded(root, baseRef, tip) {
         return false;
     }
     const range = `${fork}..${baseRef}`;
-    const trees = answer(root, ["log", "--format=%T", `--max-count=${SCAN}`, range]) ?? "";
+    const trees = answer(root, ["log", "--format=%T", `--max-count=${SCAN}`, range], undefined, SLOW_LIMIT_MS) ?? "";
     if (trees.split("\n").includes(tree)) {
         return true;
     }

package/dist/pr/decide.d.ts

@@ -3,7 +3,7 @@ import { type PrState, REVIEW } from "./state.ts";
 export { REVIEW };
 export type Status = "act" | "wait" | "park" | "done";
 export type Actor = "script" | "agent" | "dev";
-export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "review-limit" | "mark-reviewed" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-author" | "awaiting-approval" | "ready-to-merge" | "merge";
+export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "review-limit" | "mark-reviewed" | "unverified" | "ci-stuck" | "awaiting-reply" | "awaiting-review" | "mark-ready" | "awaiting-author" | "awaiting-approval" | "partial-read" | "ready-to-merge" | "merge";
 /** The Actions the script performs itself, each one gh command. */
 export type ScriptAction = "update-branch" | "mark-ready" | "mark-reviewed" | "merge";
 /**

package/dist/pr/decide.js

@@ -46,6 +46,20 @@ function failure({ name, link, log }) {
 function threads(pr, lastByViewer) {
     return pr.unresolvedThreads.filter((thread) => thread.lastByViewer === lastByViewer);
 }
+/**
+ * Whether the decision is changes requested and every reviewer asking for them has been answered by a
+ * push. One review still unanswered, or none in the reply to judge, keeps the agent's turn.
+ */
+function reviewAnswered({ reviewDecision, changeRequests }) {
+    return (reviewDecision === "CHANGES_REQUESTED" &&
+        changeRequests.length > 0 &&
+        changeRequests.every(({ answered }) => answered));
+}
+/** The names, `a`, `a and b` or `a, b and c`. */
+function namesOf(names) {
+    const last = names.at(-1);
+    return names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${last}`;
+}
 function listed({ id, path, line, author, body }) {
     return { id, path, line, author, body };
 }
@@ -200,7 +214,7 @@ const ROWS = [
         })
     },
     {
-        when: (pr) => pr.reviewDecision === "CHANGES_REQUESTED",
+        when: (pr) => pr.reviewDecision === "CHANGES_REQUESTED" && !reviewAnswered(pr),
         answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
     },
     {
@@ -273,6 +287,17 @@ const ROWS = [
             details: { threads: threads(pr, true).map(listed) }
         })
     },
+    {
+        // After awaiting-reply, so the pull request's own Review and CI run first and the reviewer gets a
+        // verified fix. Only the reviewer can act: their review stands until they review again or dismiss it.
+        when: reviewAnswered,
+        answer: (pr) => ({
+            status: "park",
+            action: "awaiting-review",
+            actor: "dev",
+            reason: `changes requested by ${namesOf(pr.changeRequests.map(({ reviewer }) => reviewer))}, answered by a push: the next review is the reviewer's`
+        })
+    },
     {
         when: (pr) => pr.draft && pr.viewerDidAuthor,
         answer: () => ({ status: "act", action: "mark-ready", actor: "script", reason: "still a draft" })
@@ -295,6 +320,17 @@ const ROWS = [
             reason: "an approving review is required"
         })
     },
+    {
+        // A failure or an open thread past what the read holds shows in no row above.
+        when: (pr) => pr.cutOff.length > 0,
+        answer: (pr, _, policy) => ({
+            status: "park",
+            action: "partial-read",
+            actor: "dev",
+            reason: `the read holds only ${pr.cutOff.join(" and ")}: the merge is the dev's`,
+            command: devCommand(pr, "merge", policy)
+        })
+    },
     {
         when: (pr) => !pr.viewerDidAuthor,
         answer: (pr, _, policy) => readyToMerge(pr, policy, "another author's pull request: the merge is the dev's"),

package/dist/pr/read.js

@@ -1,7 +1,7 @@
 // The read the pr commands and recap make: gh as a child process, its auth, the pull request a command names,
 // its state from one GraphQL request with the compares that tell whether its head carries an earlier Review
 // and that size its changes, and beside them the default branch and the clock the decision reads.
-import { spawnSync } from "node:child_process";
+import { exec, TimedOut } from "../exec.js";
 import { behindOf, changedOf, changesOf, compareArgs, sameChanges } from "./delta.js";
 import { awaitsReview, parseDefaultBranch, parsePr, parseView, QUERY, ReplyError } from "./state.js";
 /** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
@@ -42,8 +42,20 @@ function authProblem(stderr) {
     const marked = stderr.split("\n").find((line) => line.trimStart().startsWith("X "));
     return marked === undefined ? firstLine(stderr) : marked.trim().slice(2);
 }
+/** `gh args` as a child process; past its limit it stops the command as any other failed read does. */
+function reachGh(args) {
+    try {
+        return exec("gh", args);
+    }
+    catch (error) {
+        if (error instanceof TimedOut) {
+            throw new CannotRun(error.message, REMEDIES.read);
+        }
+        throw error;
+    }
+}
 export function gh(args) {
-    const result = spawnSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    const result = reachGh(args);
     if (result.error !== undefined) {
         if ("code" in result.error && result.error.code === "ENOENT") {
             throw new CannotRun("gh is not on PATH", REMEDIES.missing);

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 baseRefName baseRefOid\n      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { 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) { 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 baseRefName baseRefOid\n      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\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;
@@ -33,6 +33,11 @@ export type Thread = {
 declare const STATES: readonly ["OPEN", "CLOSED", "MERGED"];
 declare const MERGEABLE: readonly ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
 declare const REVIEW_DECISIONS: readonly ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"];
+/** A reviewer whose latest review requests changes, and whether a push has answered it. */
+export type ChangeRequest = {
+    reviewer: string;
+    answered: boolean;
+};
 export type PrState = {
     url: string;
     repo: string;
@@ -57,6 +62,10 @@ export type PrState = {
     checks: CiCheck[];
     /** The threads neither resolved nor outdated. */
     unresolvedThreads: Thread[];
+    /** Each reviewer's latest review that requests changes, in the order GitHub lists them. */
+    changeRequests: ChangeRequest[];
+    /** What the read holds of each list with more after it, as `the first 50 checks`; empty when it holds all. */
+    cutOff: string[];
     /** The oids of the pull request's last 100 commits, oldest first, the head last. */
     commits: string[];
     /**

package/dist/pr/state.js

@@ -12,16 +12,20 @@ export const MARK_STATE = "failure";
 export 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 const ACCEPTED = "accepted by the dev, findings open";
+/** How many checks and review threads the one read holds; each list's `pageInfo` says when more follow. */
+const CHECKS_READ = 50;
+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 baseRefName baseRefOid
       baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }
-      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
+      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }
+      reviewThreads(first: ${THREADS_READ}) { pageInfo { hasNextPage } nodes { id isResolved isOutdated path line
         comments(first: 1) { nodes { author { login } body } }
         latest: comments(last: 1) { nodes { viewerDidAuthor } } } }
       commits(last: 1) { nodes { commit { committedDate statusCheckRollup {
-        contexts(first: 50) { nodes {
+        contexts(first: ${CHECKS_READ}) { pageInfo { hasNextPage } nodes {
           ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
           ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
       history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: "${REVIEW}") { state description } } } } }
@@ -131,6 +135,10 @@ function nodes(node, key) {
     }
     return value.map((item, index) => object(item, `${at}[${index}]`));
 }
+/** Whether a connection has more nodes after the ones the reply holds. */
+function hasMore(node, key) {
+    return boolean(child(child(node, key), "pageInfo"), "hasNextPage");
+}
 /** The first object of a connection's `nodes`; an empty connection does not parse. */
 function firstNode(node, key) {
     const [first] = nodes(node, key);
@@ -246,6 +254,27 @@ function lastReadOf(history, head) {
     }
     return { commit: last.oid, clean: last.read === "clean", mergesOnly: mergesOnlyAfter(index) };
 }
+/**
+ * Whether a non-merge commit follows `commit` in the history, oldest first, as `lastReadOf` judges a read
+ * mark. A commit outside the history, after a force-push or past the last 100, is not answered.
+ */
+function answeredAfter(history, commit) {
+    const index = history.findIndex(({ oid }) => oid === commit);
+    return index >= 0 && history.slice(index + 1).some(({ merge }) => !merge);
+}
+/** The reviewers whose latest review requests changes, each judged against the history. */
+function changeRequestsOf(pr, history) {
+    return nodes(pr, "latestReviews")
+        .filter((review) => string(review, "state") === "CHANGES_REQUESTED")
+        .map((review) => {
+        const author = childOrNull(review, "author");
+        const commit = childOrNull(review, "commit");
+        return {
+            reviewer: author === null ? "ghost" : string(author, "login"),
+            answered: answeredAfter(history, commit === null ? null : string(commit, "oid"))
+        };
+    });
+}
 function readMarksOf(history) {
     const success = history.findLastIndex(({ posted }) => posted === "clean" || posted === "off");
     const count = history.slice(success + 1).filter(({ posted }) => posted === "findings").length;
@@ -293,6 +322,11 @@ export function parsePr(reply, repo) {
         unresolvedThreads: nodes(pr, "reviewThreads")
             .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
             .map(threadOf),
+        changeRequests: changeRequestsOf(pr, history),
+        cutOff: [
+            ...(rollup !== null && hasMore(rollup, "contexts") ? [`the first ${CHECKS_READ} checks`] : []),
+            ...(hasMore(pr, "reviewThreads") ? [`the first ${THREADS_READ} threads`] : [])
+        ],
         commits: history.map(({ oid }) => oid),
         lastRead: lastReadOf(history, head),
         marks: readMarksOf(history)

package/dist/setup-rules.js

@@ -1,7 +1,7 @@
 // The permission rules the setup writes: the lease exception and the irreversible set for the user
 // file, and a repository's deny backstop for a machine without jq.
-import { spawnSync } from "node:child_process";
 import { DEFAULT_GUARDRAILS, matchesEnvGlob, resolveConfig } from "./agentic-config.js";
+import { exec } from "./exec.js";
 /** The auto-mode exception that lets a lease push through the classifier's default force-push block. */
 export const LEASE_RULE = "Force push with --force-with-lease or --force-if-includes to a branch that is not master, main or production: allowed. The guardrails plugin's hook refuses a bare --force, -f or +refspec and any force to a protected branch, so the lease form is the safe one and needs no prompt.";
 /** The irreversible set for the user file; `git stash clear` also in the rtk form a permission rule sees once rtk rewrites it. */
@@ -57,7 +57,7 @@ const GH_DENY = ["gh repo delete", "gh repo delete *"];
 export const RETIRED_DENY = ["Bash(git branch -D *)", "Bash(rtk git branch -D *)"];
 const ENV_NAME = /^\.env(\..+)?$|^\.envrc$/;
 function git(root, args) {
-    const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
+    const result = exec("git", ["-C", root, ...args]);
     return result.status === 0 ? result.stdout.trim() : undefined;
 }
 function listedIn(globs, file) {

package/dist/sweep-terminals.d.ts

@@ -0,0 +1,89 @@
+import { type Worker } from "./worker/herdr.ts";
+import { type LockVerdict } from "./worktree-lock.ts";
+/** A live terminal of another session, or the sweeping one's own, with the place herdr shows it at. */
+type Seen = {
+    address: string;
+    name: string;
+    folder: string;
+    place: string;
+};
+/** A Worker with the pid of the program `hc get` reports in its terminal, which a Claude Code lock names. */
+export type Located = Worker & {
+    pid: number | undefined;
+};
+export type Terminals = {
+    own: Seen | undefined;
+    workers: Located[];
+    others: Seen[];
+};
+/** What holds a worktree: the terminal of this session, another session's, or a Worker of this one. */
+export type Holder = {
+    role: "own";
+    terminal: Seen;
+} | {
+    role: "other";
+    terminal: Seen;
+} | {
+    role: "worker";
+    worker: Located;
+};
+/** The terminal to stop and remove, or only to remove once it has finished. */
+export type TerminalPlan = {
+    kind: "terminal";
+    name: string;
+    reason: string;
+    stop: boolean;
+    tree?: string;
+};
+/** The address of the terminal the Sweep runs in, or undefined outside herdr. */
+export declare function sweepingTerminal(): string | undefined;
+/**
+ * Reads herdr for the sweeping terminal `own`: its Workers, finished ones included, and the other live
+ * terminals. An `hc` that fails stops the Sweep, since a terminal it cannot see must not count as absent.
+ */
+export declare function readTerminals(own: string): Terminals;
+/** A Worker whose terminal is live but whose folder is gone, with no worktree of `roots` around it, could commit nothing more. */
+export declare function workerWithoutFolder({ workers }: Terminals, roots: string[]): Worker[];
+/** The terminals in the folder of each of `trees`; the main checkout `main` takes those not in a linked one. */
+export declare function holdersOf({ own, workers, others }: Terminals, main: string, trees: string[]): Map<string, Holder[]>;
+/** How the Sweep says a Worker that is working, blocked or yet to report is, or undefined for one that is done. */
+export declare function atWork({ status }: Worker): string | undefined;
+/** What the terminals in a worktree keep it for, or null when only Workers at the end of their turn are in it. */
+export declare function whyHeld(holders: Holder[]): {
+    reason: string;
+    command: string | null;
+} | null;
+/** The terminals of the Workers done in a worktree that goes, to stop and remove with it. */
+export declare function stopsOf(holders: Holder[], tree: string): TerminalPlan[];
+/** Stops, if `item` asks, and removes its terminal; the words of the `hc` that refused, or undefined when it is gone. */
+export declare function removeTerminal(item: {
+    name: string;
+    stop?: boolean;
+}): string | undefined;
+/** A Worker the Sweep keeps, with why. */
+export type KeptWorker = {
+    name: string;
+    reason: string;
+};
+/** The Workers no worktree of this Sweep decides: a finished one is removed, one whose folder is gone goes under the status rule. */
+export declare function outsideWorktrees(terminals: Terminals, roots: string[]): {
+    remove: TerminalPlan[];
+    keep: KeptWorker[];
+};
+/** The command that stops or removes the terminal of a planned terminal by hand. */
+export declare function byHand(item: {
+    name: string;
+    stop?: boolean;
+}): string;
+/** The Worker in `holders` whose program is the process a live lock names, when it may be stopped. */
+export declare function lockHolder(pid: number, holders: Holder[]): Located | undefined;
+/** The lock of the worktree at `path` read again once its Worker is stopped, given the program a moment to end. */
+export declare function lockAfterStop(root: string, path: string): LockVerdict;
+type KeptTerminal = {
+    name: string;
+    reason: string;
+    command: string | null;
+};
+/** The terminals in a worktree that stays which the Sweep lists as kept: Workers, and another session's terminals. */
+export declare function keptIn(holders: Holder[], tree: string): KeptTerminal[];
+export {};

package/dist/sweep-terminals.js

@@ -0,0 +1,262 @@
+// What a Sweep does with herdr terminals: it stops and removes only a Worker of its own whose turn has ended,
+// in a worktree that goes in the same Sweep or is already gone. docs/adr/0015 sets the bounds.
+import { existsSync, realpathSync } from "node:fs";
+import { isObject, parseObject } from "./json-text.js";
+import { shellLine } from "./pr/decide.js";
+import { CannotRun } from "./pr/read.js";
+import { worktreesOf } from "./sweep-trees.js";
+import { call, hcObject, isLive, Refusal, said, workersOf } from "./worker/herdr.js";
+import { lockVerdict } from "./worktree-lock.js";
+/** Statuses of a Worker that is not at the end of its turn, with how the Sweep says it. */
+const AT_WORK = {
+    working: "working",
+    blocked: "blocked, waiting for the dev",
+    unknown: "yet to report"
+};
+/** The address of the terminal the Sweep runs in, or undefined outside herdr. */
+export function sweepingTerminal() {
+    const id = process.env.HC_TERMINAL_ID;
+    return id === undefined || id === "" ? undefined : id;
+}
+function word(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/**
+ * Each live terminal with the folder it works in, `hc get`'s foreground. An `hc get` that fails stops the
+ * Sweep, since a terminal in a folder it cannot see must not count as absent; one gone since the listing is dropped.
+ */
+function foldersOf(list) {
+    return list.flatMap((worker) => {
+        if (!isLive(worker)) {
+            return [{ ...worker, pid: undefined }];
+        }
+        const got = call("hc", ["get", worker.address, "--json"]);
+        if (got.status === 3) {
+            return [];
+        }
+        const parsed = got.status === 0 ? parseObject(got.stdout) : undefined;
+        if (parsed === undefined) {
+            throw new Refusal(`hc get ${worker.address} failed: ${got.status === 0 ? "its reply is no JSON object" : said(got)}`);
+        }
+        const { cwd, pid } = isObject(parsed.foreground) ? parsed.foreground : { cwd: undefined, pid: undefined };
+        const there = typeof cwd === "string" && cwd !== "" ? { ...worker, folder: cwd } : worker;
+        return [{ ...there, pid: typeof pid === "number" ? pid : undefined }];
+    });
+}
+/** The live terminals `hc ls` lists, each with the folder it works in. */
+function liveTerminals() {
+    const { terminals } = hcObject(["ls", "--json"]);
+    if (!Array.isArray(terminals)) {
+        throw new Refusal("hc ls answered no list of terminals", "check hc --version");
+    }
+    const places = new Map();
+    const listed = terminals.flatMap((entry) => {
+        const address = isObject(entry) ? word(entry.address) : undefined;
+        if (!isObject(entry) || address === undefined || typeof entry.cwd !== "string") {
+            throw new Refusal("hc ls answered a terminal without an address or a folder", "check hc --version");
+        }
+        places.set(address, word(entry.where));
+        const name = word(entry.name) ?? address;
+        return [{ name, address, state: "live", status: word(entry.status) ?? "unknown", folder: entry.cwd }];
+    });
+    return foldersOf(listed).map(({ name, address, folder }) => ({
+        name,
+        address,
+        folder,
+        place: places.get(address) ?? folder
+    }));
+}
+/**
+ * Reads herdr for the sweeping terminal `own`: its Workers, finished ones included, and the other live
+ * terminals. An `hc` that fails stops the Sweep, since a terminal it cannot see must not count as absent.
+ */
+export function readTerminals(own) {
+    try {
+        const workers = foldersOf(workersOf(own, true));
+        const live = liveTerminals();
+        const addresses = new Set(workers.map(({ address }) => address));
+        return {
+            own: live.find(({ address }) => address === own),
+            workers,
+            others: live.filter(({ address }) => address !== own && !addresses.has(address))
+        };
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            throw new CannotRun(error.message, error.remedy ?? "check hc, then call again");
+        }
+        throw error;
+    }
+}
+function canonical(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function isInside(folder, root) {
+    return folder === root || folder.startsWith(root.endsWith("/") ? root : `${root}/`);
+}
+/** The deepest of `roots` whose folder holds `folder`, or undefined. */
+function treeOf(folder, roots) {
+    const real = canonical(folder);
+    const holding = roots.filter((root) => isInside(folder, root) || isInside(real, canonical(root)));
+    return holding.toSorted((a, b) => b.length - a.length)[0];
+}
+/** A Worker whose terminal is live but whose folder is gone, with no worktree of `roots` around it, could commit nothing more. */
+export function workerWithoutFolder({ workers }, roots) {
+    const standing = roots.filter((root) => existsSync(root));
+    return workers.filter((worker) => isLive(worker) && !existsSync(worker.folder) && treeOf(worker.folder, standing) === undefined);
+}
+/** The terminals in the folder of each of `trees`; the main checkout `main` takes those not in a linked one. */
+export function holdersOf({ own, workers, others }, main, trees) {
+    const held = new Map();
+    const standing = [main, ...trees].filter((root) => existsSync(root));
+    const place = (folder, holder) => {
+        const tree = treeOf(folder, standing);
+        if (tree !== undefined && tree !== main) {
+            held.set(tree, [...(held.get(tree) ?? []), holder]);
+        }
+    };
+    if (own !== undefined) {
+        place(own.folder, { role: "own", terminal: own });
+    }
+    for (const terminal of others) {
+        place(terminal.folder, { role: "other", terminal });
+    }
+    for (const worker of workers) {
+        if (isLive(worker)) {
+            place(worker.folder, { role: "worker", worker });
+        }
+    }
+    return held;
+}
+/** How the Sweep says a Worker that is working, blocked or yet to report is, or undefined for one that is done. */
+export function atWork({ status }) {
+    return AT_WORK[status];
+}
+/** What the terminals in a worktree keep it for, or null when only Workers at the end of their turn are in it. */
+export function whyHeld(holders) {
+    const reasons = [];
+    const kills = [];
+    for (const holder of holders) {
+        if (holder.role === "own") {
+            reasons.push(`the terminal this Sweep runs in, ${holder.terminal.address}, is in it`);
+        }
+        else if (holder.role === "other") {
+            const { address, place } = holder.terminal;
+            reasons.push(`another session's terminal ${address} is in it, at ${place}`);
+            kills.push(shellLine(["hc", "kill", address]));
+        }
+        else {
+            const at = atWork(holder.worker);
+            if (at !== undefined) {
+                reasons.push(`its Worker ${holder.worker.name} (${holder.worker.address}) is ${at}`);
+            }
+        }
+    }
+    return reasons.length === 0
+        ? null
+        : { reason: reasons.join("; "), command: kills.length === 0 ? null : kills.join(" && ") };
+}
+/** The terminals of the Workers done in a worktree that goes, to stop and remove with it. */
+export function stopsOf(holders, tree) {
+    return holders.flatMap((holder) => holder.role === "worker"
+        ? [
+            {
+                kind: "terminal",
+                name: holder.worker.address,
+                reason: `Worker ${holder.worker.name} is ${holder.worker.status}: stopped, then removed with its worktree`,
+                stop: true,
+                tree
+            }
+        ]
+        : []);
+}
+/** Stops, if `item` asks, and removes its terminal; the words of the `hc` that refused, or undefined when it is gone. */
+export function removeTerminal(item) {
+    try {
+        if (item.stop === true) {
+            const killed = call("hc", ["kill", item.name]);
+            // 11: the terminal finished between the read and the stop.
+            if (killed.status !== 0 && killed.status !== 11) {
+                return `hc kill ${item.name} failed: ${said(killed)}`;
+            }
+        }
+        const removed = call("hc", ["rm", item.name]);
+        // 3: the terminal is gone already.
+        return removed.status === 0 || removed.status === 3 ? undefined : `hc rm ${item.name} failed: ${said(removed)}`;
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            return error.message;
+        }
+        throw error;
+    }
+}
+/** The Workers no worktree of this Sweep decides: a finished one is removed, one whose folder is gone goes under the status rule. */
+export function outsideWorktrees(terminals, roots) {
+    const remove = [];
+    const keep = [];
+    for (const worker of terminals.workers.filter((one) => !isLive(one))) {
+        remove.push({ kind: "terminal", name: worker.address, reason: `Worker ${worker.name} is finished`, stop: false });
+    }
+    for (const worker of workerWithoutFolder(terminals, roots)) {
+        const at = atWork(worker);
+        if (at === undefined) {
+            const reason = `Worker ${worker.name} is ${worker.status} and its folder ${worker.folder} is gone: stopped, then removed`;
+            remove.push({ kind: "terminal", name: worker.address, reason, stop: true });
+        }
+        else {
+            keep.push({ name: worker.address, reason: `Worker ${worker.name} is ${at}, its folder ${worker.folder} is gone` });
+        }
+    }
+    return { remove, keep };
+}
+/** The command that stops or removes the terminal of a planned terminal by hand. */
+export function byHand(item) {
+    return item.stop === true
+        ? `${shellLine(["hc", "kill", item.name])}; ${shellLine(["hc", "rm", item.name])}`
+        : shellLine(["hc", "rm", item.name]);
+}
+/** The Worker in `holders` whose program is the process a live lock names, when it may be stopped. */
+export function lockHolder(pid, holders) {
+    for (const holder of holders) {
+        if (holder.role === "worker" && holder.worker.pid === pid && atWork(holder.worker) === undefined) {
+            return holder.worker;
+        }
+    }
+    return undefined;
+}
+/** The lock of the worktree at `path` read again once its Worker is stopped, given the program a moment to end. */
+export function lockAfterStop(root, path) {
+    let verdict = { state: "none" };
+    for (let attempt = 0; attempt < 15; attempt++) {
+        verdict = lockVerdict(path, worktreesOf(root).find((tree) => tree.path === path)?.lock);
+        if (verdict.state !== "stays") {
+            return verdict;
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    }
+    return verdict;
+}
+/** The terminals in a worktree that stays which the Sweep lists as kept: Workers, and another session's terminals. */
+export function keptIn(holders, tree) {
+    return holders.flatMap((holder) => {
+        if (holder.role === "other") {
+            const { address, place } = holder.terminal;
+            const reason = `another session's terminal, in the worktree at ${tree}, at ${place}`;
+            return [{ name: address, reason, command: shellLine(["hc", "kill", address]) }];
+        }
+        if (holder.role === "worker") {
+            const { name, address, status } = holder.worker;
+            const at = atWork(holder.worker);
+            return [
+                { name: address, reason: `Worker ${name} is ${at ?? `${status}, but its worktree stays`}`, command: null }
+            ];
+        }
+        return [];
+    });
+}

package/dist/sweep-trees.d.ts

@@ -0,0 +1,17 @@
+/** `git <args>` at `root`, or a stop naming its problem. */
+export declare function must(root: string, args: string[]): string;
+export type Tree = {
+    path: string;
+    head: string;
+    branch: string | undefined;
+    lock: string | undefined;
+    prunable: boolean;
+};
+/** Every worktree of the repository, the main checkout first. */
+export declare function worktreesOf(root: string): Tree[];
+/** The files `git status` lists in the worktree at `path`, ignored ones aside, or why it cannot be read. */
+export declare function dirtyFiles(path: string): string[] | {
+    error: string;
+};
+/** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
+export declare function pausedOperation(path: string): string | undefined;