dw-sdlc 0.13.0 → 0.14.0

package/dist/commands/sweep.js

@@ -2,13 +2,14 @@
 // docs/adr/0015 sets its bounds: it runs from the main checkout, never forces and never writes to a remote.
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
 import { repositoryFreeEnv } from "../git-env.js";
 import { isCommitLanded, isLanded } from "../landed.js";
 import { shellLine } from "../pr/decide.js";
 import { CannotRun } from "../pr/read.js";
+import { byHand, holdersOf, keptIn, lockAfterStop, lockHolder, outsideWorktrees, readTerminals, removeTerminal, stopsOf, sweepingTerminal, whyHeld } from "../sweep-terminals.js";
+import { dirtyFiles, must, pausedOperation, worktreesOf } from "../sweep-trees.js";
 import { asked, git } from "../working-tree.js";
 import { lockVerdict } from "../worktree-lock.js";
 export const summary = "removes Landed branches and clean worktrees whose work has landed, names what it keeps";
@@ -30,20 +31,24 @@ It keeps, and names with the reason and the command to run yourself:
 It never changes anything on a remote: the fetch only writes remote-tracking refs. A removal git refuses is
 kept with git's words, and the sweep goes on.
 
---dry-run removes nothing and answers the same items. One line an item, or one document with --json:
-  { dryRun, base, removed: [item], kept: [item] }, an item { kind, name, reason, command? }, kind branch, worktree
-  or lock (a lifted one), name its path, command the one the dev would run for a kept item.
+In herdr ($HC_TERMINAL_ID set) it reads, with hc, the Workers of this session, the terminals whose parent is
+this one, and every other live terminal. A Worker whose status is none of working, blocked or yet to report
+is stopped (hc kill) then removed (hc rm) when its worktree goes in the same Sweep or its folder is already
+gone; a worktree is judged whole first, so no Worker is stopped beside work it could still commit. A live
+Claude Code lock on that worktree that names the Worker's own program, the pid hc get reports, does not keep
+it: once the Worker is stopped the lock is read again and lifted only when it is stale then, else the
+worktree stays. A finished Worker of this session is removed. This session's own terminal and another
+session's are never stopped: a worktree one is in stays, named with the terminal's address and place and
+hc kill as the dev's command. Outside herdr no terminal is read, and the output says so. An hc that fails
+ends the Sweep with exit 2 before anything is removed.
+
+--dry-run removes and stops nothing and answers the same items. One line an item, or one document with --json:
+  { dryRun, terminalsRead, base, removed: [item], kept: [item] }, an item { kind, name, reason, command? },
+  kind branch, worktree, lock (a lifted one) or terminal, name its path or its address, command the one the
+  dev would run for a kept item.
 
 Exit 0 nothing is kept but the default, the base or a protected branch, 1 something else is, 2 when it
-cannot run: in a linked worktree, with no base to read, or when the fetch fails.`;
-/** `git <args>` at `root`, or a stop naming its problem. */
-function must(root, args) {
-    const result = git(root, args);
-    if ("error" in result) {
-        throw new CannotRun(result.error, "check the repository with git status");
-    }
-    return result.out;
-}
+cannot run: in a linked worktree, with no base to read, when the fetch fails or when hc fails in herdr.`;
 function forcedDelete(branch) {
     return shellLine(["git", "branch", "-D", branch]);
 }
@@ -89,68 +94,16 @@ function branchesOf(root) {
         .split("\n")
         .filter((name) => name !== "");
 }
-/** Every worktree of the repository, the main checkout first. */
-function worktreesOf(root) {
-    const trees = [];
-    let tree;
-    for (const line of must(root, ["worktree", "list", "--porcelain"]).split("\n")) {
-        if (line.startsWith("worktree ")) {
-            tree = { path: line.slice("worktree ".length), head: "", branch: undefined, lock: undefined, prunable: false };
-            trees.push(tree);
-        }
-        else if (tree !== undefined && line.startsWith("HEAD ")) {
-            tree.head = line.slice("HEAD ".length);
-        }
-        else if (tree !== undefined && line.startsWith("branch refs/heads/")) {
-            tree.branch = line.slice("branch refs/heads/".length);
-        }
-        else if (tree !== undefined && (line === "locked" || line.startsWith("locked "))) {
-            tree.lock = line.slice("locked".length).trim();
-        }
-        else if (tree !== undefined && (line === "prunable" || line.startsWith("prunable "))) {
-            tree.prunable = true;
-        }
-    }
-    return trees;
-}
-/** The files `git status` lists in the worktree at `path`, ignored ones aside, or why it cannot be read. */
-function dirtyFiles(path) {
-    const args = ["-C", path, "status", "--porcelain=v1", "-z", "--untracked-files=all"];
-    const result = spawnSync("git", args, { encoding: "utf8", env: repositoryFreeEnv(), maxBuffer: 64 * 1024 * 1024 });
-    if (result.status !== 0) {
-        const said = result.stderr.split("\n").find((line) => line.trim() !== "");
-        return { error: `git status: ${said?.trim() ?? `exited ${result.status ?? "on a signal"}`}` };
-    }
-    const files = [];
-    const entries = result.stdout.split("\0").filter((entry) => entry !== "");
-    for (let index = 0; index < entries.length; index++) {
-        const entry = entries[index] ?? "";
-        files.push(entry.slice(3));
-        if (entry.startsWith("R") || entry.startsWith("C")) {
-            index++;
-        }
-    }
-    return files;
-}
-const OPERATIONS = [
-    ["rebase-merge", "rebase"],
-    ["rebase-apply", "rebase or am"],
-    ["MERGE_HEAD", "merge"],
-    ["CHERRY_PICK_HEAD", "cherry-pick"],
-    ["REVERT_HEAD", "revert"],
-    ["BISECT_LOG", "bisect"]
-];
-/** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
-function pausedOperation(path) {
-    const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
-    return dir === undefined ? undefined : OPERATIONS.find(([file]) => existsSync(join(dir, file)))?.[1];
-}
 /** Why the worktree stays, with the dev's command when there is one, or null when its whole set passes. */
-function whyTreeStays(root, baseRef, tree, lock) {
+function whyTreeStays(root, baseRef, tree, lock, holders) {
     const { path } = tree;
     if (lock.state === "stays") {
         return lock;
     }
+    const held = whyHeld(holders);
+    if (held !== null) {
+        return held;
+    }
     if (tree.prunable || !existsSync(path)) {
         const prune = shellLine(["git", "worktree", "prune"]);
         return {
@@ -196,8 +149,8 @@ function stays(branch, { head, baseBranch, protectedBranches, held }) {
     const path = held.get(branch);
     return path === undefined ? null : { reason: `checked out in the worktree at ${path}`, command: null, dev: true };
 }
-/** Fetches origin, then sorts each linked worktree and local branch into what goes and what stays. */
-function judge(root) {
+/** Fetches origin, then sorts each linked worktree, local branch and Worker's terminal into what goes and what stays. */
+function judge(root, terminals) {
     fetchOrigin(root);
     const head = originHead(root);
     const base = baseOf(root, head);
@@ -206,9 +159,16 @@ function judge(root) {
     if (checkout === undefined) {
         throw new CannotRun("git lists no worktree", "check the repository with git worktree list");
     }
+    const holders = terminals === undefined
+        ? new Map()
+        : holdersOf(terminals, checkout.path, linked.map(({ path }) => path));
     const verdicts = linked.map((tree) => {
         const lock = lockVerdict(tree.path, tree.lock);
-        return { tree, lock, why: whyTreeStays(root, base.ref, tree, lock) };
+        const here = holders.get(tree.path) ?? [];
+        const pid = lock.state === "stays" ? lock.pid : undefined;
+        const workerLock = pid !== undefined && lockHolder(pid, here) !== undefined ? { pid } : undefined;
+        const why = whyTreeStays(root, base.ref, tree, workerLock === undefined ? lock : { state: "none" }, here);
+        return { tree, lock, here, why, workerLock };
     });
     const staying = verdicts.filter(({ why }) => why !== null).map(({ tree }) => tree);
     const held = new Map();
@@ -243,18 +203,28 @@ function judge(root) {
             kept.push({ kind: "branch", name, reason, command: forcedDelete(name), dev: true });
         }
     };
-    for (const { tree, lock, why } of verdicts) {
+    const outside = terminals === undefined
+        ? { remove: [], keep: [] }
+        : outsideWorktrees(terminals, [checkout.path, ...linked.map(({ path }) => path)]);
+    removed.push(...outside.remove);
+    for (const { name, reason } of outside.keep) {
+        kept.push({ kind: "terminal", name, reason, command: null, dev: true });
+    }
+    for (const { tree, lock, here, why, workerLock } of verdicts) {
         if (why !== null) {
             kept.push({ kind: "worktree", name: tree.path, ...why, dev: true });
+            kept.push(...keptIn(here, tree.path).map((item) => ({ kind: "terminal", ...item, dev: true })));
             continue;
         }
+        removed.push(...stopsOf(here, tree.path));
         const reason = `clean, its HEAD is Landed on ${baseName}`;
         removed.push({
             kind: "worktree",
             name: tree.path,
             reason,
             ...(tree.branch === undefined ? {} : { holds: tree.branch }),
-            ...(lock.state === "stale" ? { stale: lock } : {})
+            ...(lock.state === "stale" ? { stale: lock } : {}),
+            ...(workerLock === undefined ? {} : { workerLock })
         });
         if (tree.branch !== undefined) {
             judgeBranch(tree.branch);
@@ -264,7 +234,7 @@ function judge(root) {
     return { base: baseName, removed, kept };
 }
 /** Removes `item`; the item kept when git refuses it, with git's words, or undefined once it is gone. */
-function removal(root, item, heldBy) {
+function removal(root, item, heldBy, unstopped) {
     const refused = (reason, command) => ({
         kind: item.kind,
         name: item.name,
@@ -272,6 +242,16 @@ function removal(root, item, heldBy) {
         command,
         dev: true
     });
+    if (item.kind === "terminal") {
+        const failed = removeTerminal(item);
+        if (failed === undefined) {
+            return undefined;
+        }
+        if (item.tree !== undefined) {
+            unstopped.set(item.tree, `its Worker's terminal ${item.name} stays: ${failed}`);
+        }
+        return refused(failed, byHand(item));
+    }
     if (item.kind === "worktree") {
         const refusedWith = (reason, command) => {
             if (item.holds !== undefined) {
@@ -279,6 +259,20 @@ function removal(root, item, heldBy) {
             }
             return refused(reason, command);
         };
+        const unstoppable = unstopped.get(item.name);
+        if (unstoppable !== undefined) {
+            return refusedWith(unstoppable, null);
+        }
+        if (item.workerLock !== undefined) {
+            const now = lockAfterStop(root, item.name);
+            if (now.state === "stays") {
+                return refusedWith(`its Worker's terminal was stopped, but ${now.reason}`, now.command);
+            }
+            if (now.state === "stale") {
+                item.stale = now;
+            }
+            delete item.workerLock;
+        }
         if (item.stale !== undefined) {
             const lifted = git(root, ["worktree", "unlock", "--", item.name]);
             if ("error" in lifted) {
@@ -307,8 +301,9 @@ function apply({ base, removed, kept }, root) {
     const gone = [];
     const refused = [];
     const heldBy = new Map();
+    const unstopped = new Map();
     for (const item of removed) {
-        const stayed = removal(root, item, heldBy);
+        const stayed = removal(root, item, heldBy, unstopped);
         if (stayed === undefined) {
             gone.push(item);
         }
@@ -320,8 +315,12 @@ function apply({ base, removed, kept }, root) {
 }
 /** The removed items as the Sweep tells them: a stale lock lifted comes just before its worktree. */
 function shownOf(removed) {
-    return removed.flatMap(({ kind, name, reason, stale }) => {
+    return removed.flatMap(({ kind, name, reason, stale, workerLock }) => {
         const item = { kind, name, reason };
+        if (workerLock !== undefined) {
+            const why = `held by its Worker's program, pid ${workerLock.pid}: lifted once the stop leaves it stale`;
+            return [{ kind: "lock", name, reason: why }, item];
+        }
         return stale === undefined ? [item] : [{ kind: "lock", name, reason: stale.why }, item];
     });
 }
@@ -331,14 +330,15 @@ function verbOf(kind, dryRun) {
     }
     return dryRun ? "would remove" : "removed";
 }
-function linesOf({ dryRun, removed, kept }) {
+function linesOf({ dryRun, terminalsRead, removed, kept }) {
     const out = [
         ...removed.map(({ kind, name, reason }) => `${verbOf(kind, dryRun)} ${kind} ${name} — ${reason}`),
         ...kept.map(({ kind, name, reason, command }) => {
             return `kept ${kind} ${name} — ${reason}${command === null || command === undefined ? "" : `; to remove it yourself: ${command}`}`;
         })
     ];
-    return out.length === 0 ? "nothing to sweep" : out.join("\n");
+    const note = terminalsRead ? [] : ["terminals not read — outside herdr, $HC_TERMINAL_ID is not set"];
+    return [...(out.length === 0 ? ["nothing to sweep"] : out), ...note].join("\n");
 }
 function parseCli(argv) {
     try {
@@ -369,10 +369,13 @@ function sweep(json, dryRun) {
     if (main !== undefined) {
         throw new CannotRun(`${root} is a linked worktree`, `run it from the main checkout: ${shellLine(["cd", main])} && dw-sdlc sweep`);
     }
-    const judged = judge(root);
+    const own = sweepingTerminal();
+    const terminals = own === undefined ? undefined : readTerminals(own);
+    const judged = judge(root, terminals);
     const { base, removed, kept } = dryRun ? judged : apply(judged, root);
     const done = {
         dryRun,
+        terminalsRead: terminals !== undefined,
         base,
         removed: shownOf(removed),
         kept: kept.map(({ kind, name, reason, command }) => ({ kind, name, reason, command }))

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;

package/dist/sweep-trees.js

@@ -0,0 +1,72 @@
+// What a Sweep reads of a repository's linked worktrees: where each lies, what it has checked out, its lock,
+// the files that hold it and the operation paused in it.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { repositoryFreeEnv } from "./git-env.js";
+import { CannotRun } from "./pr/read.js";
+import { asked, git } from "./working-tree.js";
+/** `git <args>` at `root`, or a stop naming its problem. */
+export function must(root, args) {
+    const result = git(root, args);
+    if ("error" in result) {
+        throw new CannotRun(result.error, "check the repository with git status");
+    }
+    return result.out;
+}
+/** Every worktree of the repository, the main checkout first. */
+export function worktreesOf(root) {
+    const trees = [];
+    let tree;
+    for (const line of must(root, ["worktree", "list", "--porcelain"]).split("\n")) {
+        if (line.startsWith("worktree ")) {
+            tree = { path: line.slice("worktree ".length), head: "", branch: undefined, lock: undefined, prunable: false };
+            trees.push(tree);
+        }
+        else if (tree !== undefined && line.startsWith("HEAD ")) {
+            tree.head = line.slice("HEAD ".length);
+        }
+        else if (tree !== undefined && line.startsWith("branch refs/heads/")) {
+            tree.branch = line.slice("branch refs/heads/".length);
+        }
+        else if (tree !== undefined && (line === "locked" || line.startsWith("locked "))) {
+            tree.lock = line.slice("locked".length).trim();
+        }
+        else if (tree !== undefined && (line === "prunable" || line.startsWith("prunable "))) {
+            tree.prunable = true;
+        }
+    }
+    return trees;
+}
+/** The files `git status` lists in the worktree at `path`, ignored ones aside, or why it cannot be read. */
+export function dirtyFiles(path) {
+    const args = ["-C", path, "status", "--porcelain=v1", "-z", "--untracked-files=all"];
+    const result = spawnSync("git", args, { encoding: "utf8", env: repositoryFreeEnv(), maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0) {
+        const said = result.stderr.split("\n").find((line) => line.trim() !== "");
+        return { error: `git status: ${said?.trim() ?? `exited ${result.status ?? "on a signal"}`}` };
+    }
+    const files = [];
+    const entries = result.stdout.split("\0").filter((entry) => entry !== "");
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index] ?? "";
+        files.push(entry.slice(3));
+        if (entry.startsWith("R") || entry.startsWith("C")) {
+            index++;
+        }
+    }
+    return files;
+}
+const OPERATIONS = [
+    ["rebase-merge", "rebase"],
+    ["rebase-apply", "rebase or am"],
+    ["MERGE_HEAD", "merge"],
+    ["CHERRY_PICK_HEAD", "cherry-pick"],
+    ["REVERT_HEAD", "revert"],
+    ["BISECT_LOG", "bisect"]
+];
+/** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
+export function pausedOperation(path) {
+    const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
+    return dir === undefined ? undefined : OPERATIONS.find(([file]) => existsSync(join(dir, file)))?.[1];
+}

package/dist/worktree-lock.d.ts

@@ -4,12 +4,15 @@ export type StaleLock = {
     held: string;
     why: string;
 };
-export type LockVerdict = {
-    state: "none";
-} | StaleLock | {
+/** A lock that keeps the worktree; `pid` is the live process a Claude Code lock names. */
+export type LockStays = {
     state: "stays";
     reason: string;
     command: string | null;
+    pid?: number;
 };
+export type LockVerdict = {
+    state: "none";
+} | StaleLock | LockStays;
 /** What the lock of the worktree at `path`, held for `reason`, says about whether the Sweep may lift it. */
 export declare function lockVerdict(path: string, reason: string | undefined): LockVerdict;

package/dist/worktree-lock.js

@@ -58,6 +58,7 @@ export function lockVerdict(path, reason) {
     return {
         state: "stays",
         reason: `locked by a live Claude Code session: pid ${pid} is running (${reason})`,
-        command: null
+        command: null,
+        pid
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "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": {