dw-sdlc 0.21.0 → 0.21.1

package/dist/references-key.d.ts

@@ -15,7 +15,6 @@ export type KeyProblem = {
     path: string;
     message: string;
 };
-export declare function isObject(value: unknown): value is Record<string, unknown>;
 /** The References `value` declares, or the first problem in it, named by its path under the key. */
 export declare function parseReferences(value: unknown): {
     references: Reference[];

package/dist/references-key.js

@@ -3,6 +3,8 @@
 // and `test/references-key.test.ts` runs one case list through both. The first problem stops the parse.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { messageOf } from "./cannot-run.js";
+import { isObject } from "./json-text.js";
 /** The committed file the References are read from; no local layer adds to it. */
 export const REFERENCES_FILE = ".ai/references.json";
 /** The committed agentic config: a `references` key in it is refused, so the file stays the one list. */
@@ -30,9 +32,6 @@ function kind(value) {
     }
     return typeof value === "object" ? "an object" : `a ${typeof value}`;
 }
-export function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function nonEmpty(value, path) {
     if (typeof value !== "string") {
         throw new KeyError(path, `must be a string, not ${kind(value)}`);
@@ -153,7 +152,7 @@ function readObject(path, name) {
         value = JSON.parse(readFileSync(path, "utf8"));
     }
     catch (error) {
-        return { problem: `${name}: not JSON: ${error instanceof Error ? error.message : String(error)}` };
+        return { problem: `${name}: not JSON: ${messageOf(error)}` };
     }
     return isObject(value) ? { value } : { problem: `${name}: not a JSON object` };
 }

package/dist/run-command.d.ts

@@ -17,7 +17,10 @@ export type Ran = {
     tail: string[] | null;
 };
 export declare const TAIL_LINES = 50;
-/** Runs `body` with SIGINT and SIGTERM held, so a signal stops the command running and the Gate reports it. */
+/**
+ * Runs `body` with SIGINT and SIGTERM held, so a signal stops the command running and the Gate
+ * reports it, and SIGHUP passed on to the command.
+ */
 export declare function holdingSignals<T>(body: () => Promise<T>): Promise<T>;
 /** The signal that stopped the run, once one has: one the Gate got or one that ended a command. */
 export declare function stoppedBy(): NodeJS.Signals | undefined;

package/dist/run-command.js

@@ -1,39 +1,58 @@
-// How the Gate runs one command, a Step or a `gate.checks.run` script: through `sh -c` from the
-// repository root, stdin closed, its output captured or passed through, and what it answered; and
-// how SIGINT and SIGTERM stop the command running and every command after it.
+// How the Gate runs one command, a Step or a `gate.checks.run` script: `sh -c` from the repository
+// root in a process group of its own, stdin closed, output captured or passed through; and how SIGINT
+// and SIGTERM stop it, every process it started and every command after it.
 import { spawn } from "node:child_process";
 import { closeSync, fstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { signalGroup } from "./exec.js";
 export const TAIL_LINES = 50;
 /** What the shell answers for a command it cannot find, and for one it cannot execute. */
 const NOT_RUNNABLE = { 127: "was not found", 126: "could not be executed" };
 const STOPPING = ["SIGINT", "SIGTERM"];
-/** The command running, which a signal the Gate gets is passed on to. */
+/** The process group the running command leads, which a signal the Gate gets is passed on to. */
 let running;
 /** The first SIGINT or SIGTERM the Gate got; no command starts after it. */
 let received;
 /**
- * The SIGINT or SIGTERM that ended a command; no command starts after it either. Ctrl-C reaches the
- * command and the Gate together, and the command's exit can be seen before the Gate's own signal.
+ * The SIGINT or SIGTERM that ended a command; no command starts after it either. A signal sent to
+ * the command and the Gate together can show in the command's exit before the Gate's own handler runs.
  */
 let commandEndedBy;
 function release() {
     for (const signal of STOPPING) {
         process.off(signal, stop);
     }
+    process.off("SIGHUP", hangUp);
+}
+/** Sends `signal` to every process of the running command's group. */
+function signalCommand(signal) {
+    if (running !== undefined) {
+        signalGroup(running, signal);
+    }
 }
 function stop(signal) {
     if (received !== undefined) {
-        // A second signal ends the Gate at once, as it would with no handler: the command ignored the first.
+        // A second signal ends the Gate at once, as it would with no handler, and kills the command, which
+        // ignored the first.
+        signalCommand("SIGKILL");
         release();
         process.kill(process.pid, signal);
         return;
     }
     received = signal;
-    running?.kill(signal);
+    signalCommand(signal);
+}
+/** A hangup ends the Gate as with no handler, passed on first: a terminal's hangup misses the command's session. */
+function hangUp() {
+    signalCommand("SIGHUP");
+    release();
+    process.kill(process.pid, "SIGHUP");
 }
-/** Runs `body` with SIGINT and SIGTERM held, so a signal stops the command running and the Gate reports it. */
+/**
+ * Runs `body` with SIGINT and SIGTERM held, so a signal stops the command running and the Gate
+ * reports it, and SIGHUP passed on to the command.
+ */
 export async function holdingSignals(body) {
     running = undefined;
     received = undefined;
@@ -42,6 +61,7 @@ export async function holdingSignals(body) {
     for (const signal of STOPPING) {
         process.on(signal, stop);
     }
+    process.on("SIGHUP", hangUp);
     try {
         return await body();
     }
@@ -104,8 +124,9 @@ function run(command, root, stdio) {
             running = undefined;
             resolve({ ...answered, seconds: (performance.now() - started) / 1000 });
         };
-        const child = spawn(command, { shell: true, cwd: root, stdio });
-        running = child;
+        // A session of its own makes the command lead a process group, which every process it starts joins.
+        const child = spawn(command, { shell: true, cwd: root, stdio, detached: true });
+        running = child.pid;
         // A signal that cannot be delivered is an error too; only a child with no pid never started.
         child.on("error", (error) => {
             if (child.pid === undefined) {

package/dist/setup-gate.d.ts

@@ -1,11 +1,5 @@
 import type { NodePackageManager } from "./agentic-config.ts";
-/** A file's text after the setup and what writing it does, or why the setup leaves the file alone. */
-export type Change = {
-    text: string;
-    detail?: string;
-} | {
-    refusal: string;
-};
+import type { Change } from "./setup-writer.ts";
 /**
  * package.json with the package pinned exactly as a devDependency, in name order, where neither list
  * names it. A new dependency needs the owner's yes, so without `add` the file is refused.

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 { DEFAULT_GUARDRAILS, matchesEnvGlob, resolveConfig } from "./agentic-config.js";
-import { exec } from "./exec.js";
+import { asked } from "./git.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. */
@@ -56,10 +56,6 @@ 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 = exec("git", ["-C", root, ...args]);
-    return result.status === 0 ? result.stdout.trim() : undefined;
-}
 function listedIn(globs, file) {
     return globs.some((glob) => matchesEnvGlob(glob, file));
 }
@@ -67,7 +63,7 @@ function isEnvName(file) {
     return ENV_NAME.test(file.slice(file.lastIndexOf("/") + 1));
 }
 function gitFiles(root, ...flags) {
-    const listed = git(root, ["-c", "core.quotePath=false", "ls-files", ...flags, "--exclude-standard"]) ?? "";
+    const listed = asked(root, ["-c", "core.quotePath=false", "ls-files", ...flags, "--exclude-standard"]) ?? "";
     return listed.split("\n").filter((file) => file !== "");
 }
 /**

package/dist/setup-writer.d.ts

@@ -0,0 +1,32 @@
+/** `by hand` is an edit the setup names and leaves to the user; `skipped` is a file it has no reason to write. */
+export type Outcome = "wrote" | "unchanged" | "skipped" | "refused" | "by hand";
+export type Step = {
+    file: string;
+    outcome: Outcome;
+    detail?: string;
+};
+/** A file's text after the step and what writing it does, or why the step leaves the file alone. */
+export type Change = {
+    text: string;
+    detail?: string | undefined;
+} | {
+    refusal: string;
+};
+export declare class Writer {
+    readonly steps: Step[];
+    private readonly dryRun;
+    constructor(dryRun: boolean);
+    private record;
+    /**
+     * The file at `path`, recorded under `label`, as `change` leaves it, or as it leaves the text the file
+     * holds now: written when the text differs, unchanged when it does not, else refused.
+     */
+    apply(label: string, path: string, change: Change | ((current: string | undefined) => Change)): void;
+    /** The file at `path`, made by `make` when nothing sits there, a dangling symlink included; never replaced. */
+    create(label: string, path: string, make: (path: string) => void): void;
+    refuse(label: string, detail: string): void;
+    skip(label: string, detail: string): void;
+    byHand(label: string, detail: string): void;
+}
+/** One line a step: what it did, or would do under `dryRun`, the file, and why where it says. */
+export declare function stepLines(steps: Step[], dryRun: boolean): string[];

package/dist/setup-writer.js

@@ -0,0 +1,60 @@
+// How `dw-sdlc setup` and `dw-sdlc references setup` write a file: only when its text would change,
+// nothing under --dry-run, and one line a file saying what the step did or would do.
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export class Writer {
+    steps = [];
+    dryRun;
+    constructor(dryRun) {
+        this.dryRun = dryRun;
+    }
+    record(file, outcome, detail) {
+        this.steps.push(detail === undefined ? { file, outcome } : { file, outcome, detail });
+    }
+    /**
+     * The file at `path`, recorded under `label`, as `change` leaves it, or as it leaves the text the file
+     * holds now: written when the text differs, unchanged when it does not, else refused.
+     */
+    apply(label, path, change) {
+        const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
+        const next = typeof change === "function" ? change(current) : change;
+        if ("refusal" in next) {
+            this.record(label, "refused", next.refusal);
+            return;
+        }
+        if (next.text === current) {
+            this.record(label, "unchanged", undefined);
+            return;
+        }
+        if (!this.dryRun) {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, next.text);
+        }
+        this.record(label, "wrote", next.detail);
+    }
+    /** The file at `path`, made by `make` when nothing sits there, a dangling symlink included; never replaced. */
+    create(label, path, make) {
+        const absent = lstatSync(path, { throwIfNoEntry: false }) === undefined;
+        if (absent && !this.dryRun) {
+            mkdirSync(dirname(path), { recursive: true });
+            make(path);
+        }
+        this.record(label, absent ? "wrote" : "unchanged", undefined);
+    }
+    refuse(label, detail) {
+        this.record(label, "refused", detail);
+    }
+    skip(label, detail) {
+        this.record(label, "skipped", detail);
+    }
+    byHand(label, detail) {
+        this.record(label, "by hand", detail);
+    }
+}
+/** One line a step: what it did, or would do under `dryRun`, the file, and why where it says. */
+export function stepLines(steps, dryRun) {
+    return steps.map(({ file, outcome, detail }) => {
+        const verb = outcome === "wrote" && dryRun ? "would write" : outcome;
+        return `${verb.padEnd(11)} ${file}${detail === undefined ? "" : ` — ${detail}`}`;
+    });
+}

package/dist/shell-line.d.ts

@@ -0,0 +1,2 @@
+/** The words as one POSIX shell command line, each word that needs it single-quoted. */
+export declare function shellLine(words: string[]): string;

package/dist/shell-line.js

@@ -0,0 +1,5 @@
+// A command as the line a dev pastes into a POSIX shell: what an answer hands the dev to run.
+/** The words as one POSIX shell command line, each word that needs it single-quoted. */
+export function shellLine(words) {
+    return words.map((word) => (/^[\w./:=@%+,-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`)).join(" ");
+}

package/dist/sweep-removal.d.ts

@@ -0,0 +1,31 @@
+import type { StaleLock } from "./worktree-lock.ts";
+export type Item = {
+    kind: "branch" | "worktree" | "lock" | "terminal";
+    name: string;
+    reason: string;
+};
+export type Kept = Item & {
+    command: string | null;
+    dev: boolean;
+};
+/**
+ * An item to remove: `at` the commit it was judged at, a worktree's HEAD or a branch's tip; a worktree's
+ * `holds` branch, `stale` lock, `workerLock` its Worker's program holds; a terminal's `stop`, `tree`.
+ */
+export type Planned = Item & {
+    at?: string;
+    holds?: string;
+    stale?: StaleLock;
+    stop?: boolean;
+    tree?: string;
+    workerLock?: {
+        pid: number;
+    };
+};
+export type Judged = {
+    base: string;
+    removed: Planned[];
+    kept: Kept[];
+};
+/** Removes each item judged to go, in order; a worktree that stays keeps the branch it holds as well. */
+export declare function apply({ base, removed, kept }: Judged, root: string): Judged;

package/dist/sweep-removal.js

@@ -0,0 +1,133 @@
+// How a Sweep carries out what it judged: each item it plans to remove, removed in order, and the one git or
+// hc refuses, or that outlives its time limit, kept with why. docs/adr/0015 sets the bounds: it never forces.
+import { SLOW_LIMIT_MS, TimedOut } from "./exec.js";
+import { git } from "./git.js";
+import { byHand, lockAfterStop, takeDown } from "./sweep-terminals.js";
+import { forcedDelete, forcedRemoval, tipOf, unlockCommand, whyUnclean, worktreesOf } from "./sweep-trees.js";
+/** Why the worktree `item` stays after all, read again just before it goes: what changed since it was judged. */
+function whyChanged(root, item) {
+    const now = worktreesOf(root).find(({ path }) => path === item.name);
+    if (now === undefined) {
+        return { reason: "git no longer lists it", command: null };
+    }
+    if (now.head !== item.at) {
+        return { reason: `its HEAD moved to ${now.head.slice(0, 9)} since the Sweep judged it`, command: null };
+    }
+    if (now.branch !== item.holds) {
+        const on = now.branch === undefined ? "a detached HEAD" : `${now.branch} checked out`;
+        return { reason: `it has ${on} since the Sweep judged it`, command: null };
+    }
+    if (now.lock !== item.stale?.held) {
+        return { reason: "its lock changed since the Sweep judged it", command: null };
+    }
+    return whyUnclean(item.name, item.stale !== undefined);
+}
+/** The command that removes `item` by hand, for one the Sweep did not remove. */
+function byHandOf(item) {
+    if (item.kind === "terminal") {
+        return byHand(item);
+    }
+    return item.kind === "worktree" ? forcedRemoval(item.name, item.stale !== undefined) : forcedDelete(item.name);
+}
+/** Stops, if it asks, and removes the terminal of `item`; why it stays, in hc's words, or undefined once it is gone. */
+function removeTerminalOf(item, unstopped) {
+    const failed = takeDown(item);
+    if (failed === undefined) {
+        return undefined;
+    }
+    if (item.tree !== undefined) {
+        unstopped.set(item.tree, `its Worker's terminal ${item.name} stays: ${failed}`);
+    }
+    return { reason: failed, command: byHandOf(item) };
+}
+/** Removes the worktree of `item` once it still passes, its stale lock lifted just before; why it stays, or undefined. */
+function removeTree(root, item, unstopped) {
+    const unstoppable = unstopped.get(item.name);
+    if (unstoppable !== undefined) {
+        return { reason: unstoppable, command: null };
+    }
+    if (item.workerLock !== undefined) {
+        const now = lockAfterStop(root, item.name);
+        if (now.state === "stays") {
+            return { reason: `its Worker's terminal was stopped, but ${now.reason}`, command: now.command };
+        }
+        if (now.state === "stale") {
+            item.stale = now;
+        }
+        delete item.workerLock;
+    }
+    const changed = whyChanged(root, item);
+    if (changed !== null) {
+        return changed;
+    }
+    if (item.stale !== undefined) {
+        const lifted = git(root, ["worktree", "unlock", "--", item.name]);
+        if ("error" in lifted) {
+            return { reason: lifted.error, command: unlockCommand(item.name) };
+        }
+    }
+    let result;
+    try {
+        result = git(root, ["worktree", "remove", "--", item.name], { limitMs: SLOW_LIMIT_MS });
+    }
+    catch (error) {
+        if (!(error instanceof TimedOut)) {
+            throw error;
+        }
+        result = { error: error.message, said: error.message };
+    }
+    if (!("error" in result)) {
+        return undefined;
+    }
+    const relocked = item.stale === undefined ? undefined : git(root, ["worktree", "lock", "--reason", item.stale.held, "--", item.name]);
+    const lost = relocked !== undefined && "error" in relocked ? `; its lock could not be put back: ${relocked.error}` : "";
+    return { reason: `${result.error}${lost}`, command: byHandOf(item) };
+}
+/** Deletes the branch of `item` while it still points at the commit judged Landed; why it stays, or undefined. */
+function removeBranch(root, item, heldBy) {
+    const path = heldBy.get(item.name);
+    if (path !== undefined) {
+        return { reason: `checked out in the worktree at ${path}`, command: null };
+    }
+    // Read just before the delete: git branch -D, the delete the guard lets an agent make, takes no expected tip.
+    const now = tipOf(root, item.name);
+    if (now !== undefined && now !== item.at) {
+        return { reason: `it moved to ${now.slice(0, 9)} since the Sweep judged it`, command: null };
+    }
+    const result = git(root, ["branch", "-D", "--", item.name]);
+    return "error" in result ? { reason: result.error, command: byHandOf(item) } : undefined;
+}
+/** Removes `item`; why it stays, in git's or hc's words or as the time limit it hit, or undefined once it is gone. */
+function removal(root, item, heldBy, unstopped) {
+    try {
+        if (item.kind === "terminal") {
+            return removeTerminalOf(item, unstopped);
+        }
+        return item.kind === "worktree" ? removeTree(root, item, unstopped) : removeBranch(root, item, heldBy);
+    }
+    catch (error) {
+        if (error instanceof TimedOut) {
+            return { reason: error.message, command: byHandOf(item) };
+        }
+        throw error;
+    }
+}
+/** Removes each item judged to go, in order; a worktree that stays keeps the branch it holds as well. */
+export function apply({ base, removed, kept }, root) {
+    const gone = [];
+    const refused = [];
+    const heldBy = new Map();
+    const unstopped = new Map();
+    for (const item of removed) {
+        const why = removal(root, item, heldBy, unstopped);
+        if (why === undefined) {
+            gone.push(item);
+            continue;
+        }
+        if (item.kind === "worktree" && item.holds !== undefined) {
+            heldBy.set(item.holds, item.name);
+        }
+        refused.push({ kind: item.kind, name: item.name, ...why, dev: true });
+    }
+    return { base, removed: gone, kept: [...kept, ...refused] };
+}

package/dist/sweep-terminals.d.ts

@@ -56,7 +56,7 @@ export declare function whyHeld(holders: Holder[]): {
 /** 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: {
+export declare function takeDown(item: {
     name: string;
     stop?: boolean;
 }): string | undefined;

package/dist/sweep-terminals.js

@@ -1,11 +1,10 @@
 // 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 { CannotRun } from "./cannot-run.js";
+import { shellLine } from "./shell-line.js";
 import { worktreesOf } from "./sweep-trees.js";
-import { call, hcObject, isLive, Refusal, said, workersOf } from "./worker/herdr.js";
+import { isLive, listTerminals, readTerminal, removeTerminal, stopTerminal, 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 = {
@@ -18,53 +17,30 @@ 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.
+ * Each Worker with the folder it works in and its program's pid, as `hc get` reports them. One gone since the
+ * listing is dropped; an `hc get` that fails stops the Sweep, since a terminal in a folder it cannot see must
+ * not count as absent.
  */
-function foldersOf(list) {
-    return list.flatMap((worker) => {
+function located(workers) {
+    return workers.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 }];
+        const reading = readTerminal(worker.address);
+        return "gone" in reading ? [] : [{ ...worker, folder: reading.folder ?? worker.folder, pid: reading.pid }];
     });
 }
 /** 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");
+    return listTerminals().flatMap(({ address, name, folder, place }) => {
+        const reading = readTerminal(address);
+        if ("gone" in reading) {
+            return [];
         }
-        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 }];
+        const working = reading.folder ?? folder;
+        return [{ address, name, folder: working, place: place ?? working }];
     });
-    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
@@ -72,7 +48,7 @@ function liveTerminals() {
  */
 export function readTerminals(own) {
     try {
-        const workers = foldersOf(workersOf(own, true));
+        const workers = located(workersOf(own, true));
         const live = liveTerminals();
         const addresses = new Set(workers.map(({ address }) => address));
         return {
@@ -82,10 +58,7 @@ export function readTerminals(own) {
         };
     }
     catch (error) {
-        if (error instanceof Refusal) {
-            throw new CannotRun(error.message, error.remedy ?? "check hc, then call again");
-        }
-        throw error;
+        throw error instanceof CannotRun ? error.orRemedy("check hc, then call again") : error;
     }
 }
 function canonical(path) {
@@ -176,21 +149,12 @@ export function stopsOf(holders, 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) {
+export function takeDown(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)}`;
+        return (item.stop === true ? stopTerminal(item.name) : undefined) ?? removeTerminal(item.name);
     }
     catch (error) {
-        if (error instanceof Refusal) {
+        if (error instanceof CannotRun) {
             return error.message;
         }
         throw error;

package/dist/sweep-trees.d.ts

@@ -1,5 +1,11 @@
-/** `git <args>` at `root`, or a stop naming its problem. */
-export declare function must(root: string, args: string[]): string;
+/** The forced delete of `branch`, the dev's to run. */
+export declare function forcedDelete(branch: string): string;
+/** The forced removal of the worktree at `path`, the dev's to run; git wants --force twice for one still locked. */
+export declare function forcedRemoval(path: string, locked?: boolean): string;
+/** The unlock of the worktree at `path`, the dev's to run. */
+export declare function unlockCommand(path: string): string;
+/** The commit the local `branch` points at, or undefined once it is gone. */
+export declare function tipOf(root: string, branch: string): string | undefined;
 /** The local branches of the repository at `root`. */
 export declare function branchesOf(root: string): string[];
 export type Tree = {
@@ -9,14 +15,24 @@ export type Tree = {
     lock: string | undefined;
     prunable: boolean;
 };
-/** Every worktree of the repository, the main checkout first. */
+/** Every worktree of the repository, the main checkout first; -z leaves a path or a lock's reason unquoted. */
 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;
 };
+/** What in the worktree at `path` a removal could lose, a paused operation or a file git status lists, or null. */
+export declare function whyUnclean(path: string, locked: boolean): {
+    reason: string;
+    command: string | null;
+} | null;
 /** 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;
+/** The branch git keeps from a delete for the worktree `tree`, and why: checked out there, or a rebase of it paused there. */
+export declare function heldBranch(tree: Tree): {
+    branch: string;
+    reason: string;
+} | undefined;
 /** The dev's way off `branch`, checked out in the main checkout at `root`: null until it is Landed and nothing there could be lost. */
 export declare function switchOff(root: string, base: {
     name: string;