dw-sdlc 0.21.0 → 0.21.1

package/dist/sweep-trees.js

@@ -1,20 +1,27 @@
 // What a Sweep reads of a repository's branches and worktrees: where each worktree lies, what it has checked
-// out, its lock, the files that hold it and the operation paused in it, and the way off the main checkout's.
-import { existsSync } from "node:fs";
+// out, its lock, the files that hold it and the operation paused in it, and the way off the main checkout's;
+// beside them, the commands the dev runs for what the Sweep keeps.
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { exec } from "./exec.js";
-import { repositoryFreeEnv } from "./git-env.js";
+import { asked, git, must } from "./git.js";
 import { isLanded } from "./landed.js";
-import { shellLine } from "./pr/decide.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;
+import { pausedIn } from "./paused-operation.js";
+import { shellLine } from "./shell-line.js";
+/** The forced delete of `branch`, the dev's to run. */
+export function forcedDelete(branch) {
+    return shellLine(["git", "branch", "-D", branch]);
+}
+/** The forced removal of the worktree at `path`, the dev's to run; git wants --force twice for one still locked. */
+export function forcedRemoval(path, locked = false) {
+    return shellLine(["git", "worktree", "remove", "--force", ...(locked ? ["--force"] : []), path]);
+}
+/** The unlock of the worktree at `path`, the dev's to run. */
+export function unlockCommand(path) {
+    return shellLine(["git", "worktree", "unlock", path]);
+}
+/** The commit the local `branch` points at, or undefined once it is gone. */
+export function tipOf(root, branch) {
+    return asked(root, ["rev-parse", "--verify", "-q", `refs/heads/${branch}^{commit}`]);
 }
 /** The local branches of the repository at `root`. */
 export function branchesOf(root) {
@@ -22,11 +29,11 @@ export function branchesOf(root) {
         .split("\n")
         .filter((name) => name !== "");
 }
-/** 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 function worktreesOf(root) {
     const trees = [];
     let tree;
-    for (const line of must(root, ["worktree", "list", "--porcelain"]).split("\n")) {
+    for (const line of must(root, ["worktree", "list", "--porcelain", "-z"]).split("\0")) {
         if (line.startsWith("worktree ")) {
             tree = { path: line.slice("worktree ".length), head: "", branch: undefined, lock: undefined, prunable: false };
             trees.push(tree);
@@ -48,14 +55,12 @@ export function worktreesOf(root) {
 }
 /** 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 = exec("git", args, { env: repositoryFreeEnv() });
-    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 status = git(path, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { raw: true });
+    if ("error" in status) {
+        return status;
     }
     const files = [];
-    const entries = result.stdout.split("\0").filter((entry) => entry !== "");
+    const entries = status.out.split("\0").filter((entry) => entry !== "");
     for (let index = 0; index < entries.length; index++) {
         const entry = entries[index] ?? "";
         files.push(entry.slice(3));
@@ -65,18 +70,49 @@ export function dirtyFiles(path) {
     }
     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"]
-];
+/** What in the worktree at `path` a removal could lose, a paused operation or a file git status lists, or null. */
+export function whyUnclean(path, locked) {
+    const operation = pausedOperation(path);
+    if (operation !== undefined) {
+        return { reason: `a ${operation} is paused in it`, command: null };
+    }
+    const files = dirtyFiles(path);
+    if ("error" in files) {
+        return { reason: files.error, command: null };
+    }
+    return files.length === 0
+        ? null
+        : { reason: `modified or untracked: ${files.join(", ")}`, command: forcedRemoval(path, locked) };
+}
 /** 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];
+    return dir === undefined ? undefined : pausedIn(dir);
+}
+/** The branch a rebase paused in the worktree at `path` works on; git lists that worktree as detached. */
+function rebasedBranch(path) {
+    const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
+    if (dir === undefined) {
+        return undefined;
+    }
+    for (const state of ["rebase-merge", "rebase-apply"]) {
+        const file = join(dir, state, "head-name");
+        const name = existsSync(file) ? readFileSync(file, "utf8").trim() : "";
+        if (name.startsWith("refs/heads/")) {
+            return name.slice("refs/heads/".length);
+        }
+    }
+    return 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 function heldBranch(tree) {
+    if (tree.branch !== undefined) {
+        return { branch: tree.branch, reason: `checked out in the worktree at ${tree.path}` };
+    }
+    const branch = rebasedBranch(tree.path);
+    return branch === undefined
+        ? undefined
+        : { branch, reason: `a rebase paused in the worktree at ${tree.path} holds it` };
 }
 /** 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 function switchOff(root, base, branch) {

package/dist/worker/herdr.d.ts

@@ -1,24 +1,68 @@
-import { type JsonObject } from "../json-text.ts";
-/** What stops a `worker` command before it acts: exit 2, the problem and, when there is one, its remedy. */
-export declare class Refusal extends Error {
-    remedy: string | undefined;
-    constructor(message: string, remedy?: string);
-}
-export type Called = {
-    status: number;
-    stdout: string;
-    stderr: string;
+import { type Called } from "../exec.ts";
+/** A terminal as `hc ls --json` lists it. */
+export type Listed = {
+    address: string;
+    /** Its name, else its address. */
+    name: string;
+    /** The terminal that started it. */
+    parent: string | undefined;
+    /** herdr's state: live or finished. */
+    state: string;
+    /** The word it reports, undefined before it reports one. */
+    status: string | undefined;
+    /** The folder it was launched in. */
+    folder: string;
+    /** The place herdr shows it at: its space and tab. */
+    place: string | undefined;
+};
+/** A terminal as `hc get --json` reports it. */
+export type Reading = {
+    /** herdr's state: live or finished. */
+    state: string | undefined;
+    /** The state its program reports. */
+    status: string | undefined;
+    /** The herdr space it sits in, its `herdr.space` label. */
+    space: string | undefined;
+    /** Whether herdr sent its first message, and why not when it did not. */
+    firstMessage: {
+        sent: boolean;
+        reason: string | undefined;
+    } | undefined;
+    /** The folder its foreground program works in. */
+    folder: string | undefined;
+    /** That program's pid. */
+    pid: number | undefined;
+};
+/** `herdr-app args`, the window's CLI; one not on PATH, or past its limit, stops the command. */
+export declare function herdrApp(args: string[]): Called;
+/** The terminals `hc ls` lists: the live ones, every one with `all`, only those labelled `label` when given. */
+export declare function listTerminals(filter?: {
+    all?: boolean;
+    label?: string;
+}): Listed[];
+/** What `hc get` reports of the terminal at `address`, or `gone`, in hc's words, when herdr has no such terminal. */
+export declare function readTerminal(address: string): Reading | {
+    gone: string;
+};
+export type Start = {
+    name: string;
+    /** Its labels, each passed as `--label key=value` in order. */
+    labels: Record<string, string>;
+    /** The folder it starts in. */
+    cwd: string;
+    /** The program and its arguments. */
+    argv: string[];
+};
+/** Runs `argv` in a terminal of its own in the background, outliving its caller; the address hc gives it. */
+export declare function startTerminal({ name, labels, cwd, argv }: Start): string;
+/** Stops the terminal at `address`: hc's words when it refuses, undefined once it is stopped or had finished. */
+export declare function stopTerminal(address: string): string | undefined;
+/** Removes the terminal at `address`: hc's words when it refuses, undefined once it is gone. */
+export declare function removeTerminal(address: string): string | undefined;
+/** Types `message` into the terminal at `address`: `sent`, `blocked` while it sits on a dialog, else hc's words. */
+export declare function sendTo(address: string, message: string): "sent" | "blocked" | {
+    refused: string;
 };
-/** The first line of a tool's output that says anything, or the exit it ended with. */
-export declare function said(called: Called): string;
-/** `tool args` as a child process; a tool that is not on PATH stops the command. */
-export declare function call(tool: "hc" | "herdr-app", args: string[]): Called;
-/** The JSON object `hc <args>` prints; a failing call or a reply that is no object stops the command. */
-export declare function hcObject(args: string[]): JsonObject;
-/** What an error says, whatever was thrown. */
-export declare function describe(error: unknown): string;
-/** Reports a `Refusal` of `command` on stderr and answers exit 2; any other error is a bug and goes on up. */
-export declare function refuse(command: string, error: unknown): number;
 /** The option `flag` as a whole number from `min`, `fallback` when the command line leaves it out. */
 export declare function wholeNumber(flag: string, value: string | undefined, fallback: number, min: number): number | {
     error: string;
@@ -38,11 +82,11 @@ export type Worker = {
 /** Whether herdr still runs the Worker's terminal; the one test of it every command shares. */
 export declare function isLive(worker: Worker): boolean;
 /**
- * The Workers with the folder each live one works in, its worktree, which `hc get` reports as
- * `foreground.cwd` and `hc ls` leaves out. A Worker herdr cannot tell it for keeps its launch folder.
+ * The Workers with the folder each live one works in, its worktree, which `hc get` reports and `hc ls`
+ * leaves out. A Worker herdr cannot tell it for keeps its launch folder.
  */
 export declare function workingFolders(workers: Worker[]): Worker[];
-/** The Workers `lead` started, in the order herdr lists them; `all` adds the finished ones. */
+/** The Workers `leadId` started, in the order herdr lists them; `all` adds the finished ones. */
 export declare function workersOf(leadId: string, all: boolean): Worker[];
 /** A table of rows, every column but the last padded to its widest cell and two spaces apart. */
 export declare function table(rows: string[][]): string;

package/dist/worker/herdr.js

@@ -1,66 +1,126 @@
-// What the `worker` commands share: `hc` and `herdr-app` as child processes, the Lead a command acts for,
-// and the Workers herdr lists for it.
-import { exec, TimedOut } from "../exec.js";
+// herdr's CLI, `hc`, run from this one place, each reply parsed once into a typed value: a read that fails
+// stops the command through `CannotRun` with hc's words, an action answers its refusal. Beside it:
+// `herdr-app`, the Lead a command acts for, and the Workers herdr lists for it.
+import { CannotRun } from "../cannot-run.js";
+import { need, whyFailed } from "../exec.js";
 import { isObject, parseObject } from "../json-text.js";
-/** What stops a `worker` command before it acts: exit 2, the problem and, when there is one, its remedy. */
-export class Refusal extends Error {
-    remedy;
-    constructor(message, remedy) {
-        super(message);
-        this.remedy = remedy;
-    }
+const REMEDIES = {
+    missing: "install herdr, or run the command in a terminal herdr started",
+    stalled: "check herdr is responding, then call again"
+};
+/** The remedy for a reply in a shape this module does not read. */
+const SHAPE = "check hc --version";
+/** hc's exit when it has no such terminal. */
+const NO_TERMINAL = 3;
+/** `hc send`'s exit when the target sits on a permission or a question. */
+const BLOCKED = 9;
+/** `hc kill`'s exit when the terminal finished before the stop. */
+const FINISHED = 11;
+/** `hc args`; one not on PATH, or past its limit, stops the command. */
+function hc(args) {
+    return need("hc", args, REMEDIES);
 }
-/** The first line of a tool's output that says anything, or the exit it ended with. */
-export function said(called) {
-    const line = `${called.stderr}\n${called.stdout}`.split("\n").find((text) => text.trim() !== "");
-    return line?.trim() ?? `exited ${called.status}`;
+/** `herdr-app args`, the window's CLI; one not on PATH, or past its limit, stops the command. */
+export function herdrApp(args) {
+    return need("herdr-app", args, REMEDIES);
 }
-/** `tool args` as a child process; past its limit it stops the command as any failed call does. */
-function reach(tool, args) {
-    try {
-        return exec(tool, args);
+/** The JSON object `hc <args>` prints, or why it printed none; `shown` names the call, as `hc get t3`. */
+function answer(args, shown) {
+    const called = hc(args);
+    if (called.status !== 0) {
+        return { status: called.status, problem: `${shown} failed: ${whyFailed(called)}` };
     }
-    catch (error) {
-        if (error instanceof TimedOut) {
-            throw new Refusal(error.message, "check herdr is responding, then call again");
-        }
-        throw error;
+    const object = parseObject(called.stdout);
+    return object === undefined
+        ? { status: 0, problem: `${shown} answered something that is no JSON object`, remedy: SHAPE }
+        : { object };
+}
+/** The object `answered` holds; a call that answered none stops the command. */
+function objectOf(answered) {
+    if ("object" in answered) {
+        return answered.object;
     }
+    throw new CannotRun(answered.problem, answered.remedy);
 }
-/** `tool args` as a child process; a tool that is not on PATH stops the command. */
-export function call(tool, args) {
-    const result = reach(tool, args);
-    if (result.error !== undefined) {
-        if ("code" in result.error && result.error.code === "ENOENT") {
-            throw new Refusal(`${tool} is not on PATH`, "install herdr, or run the command in a terminal herdr started");
-        }
-        throw result.error;
+/** A string that says something, else undefined. */
+function word(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+function listedOf(entry) {
+    const address = isObject(entry) ? word(entry.address) : undefined;
+    if (!isObject(entry) || address === undefined || typeof entry.state !== "string" || typeof entry.cwd !== "string") {
+        throw new CannotRun("hc ls answered a terminal without an address, state or folder", SHAPE);
     }
-    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+    return {
+        address,
+        name: word(entry.name) ?? address,
+        parent: word(entry.parent),
+        state: entry.state,
+        status: word(entry.status),
+        folder: entry.cwd,
+        place: word(entry.where)
+    };
 }
-/** The JSON object `hc <args>` prints; a failing call or a reply that is no object stops the command. */
-export function hcObject(args) {
-    const called = call("hc", args);
-    if (called.status !== 0) {
-        throw new Refusal(`hc ${args[0] ?? ""} failed: ${said(called)}`);
+function readingOf({ state, status, labels, first_message: first, foreground }) {
+    const program = isObject(foreground) ? foreground : {};
+    return {
+        state: word(state),
+        status: isObject(status) ? word(status.state) : undefined,
+        space: isObject(labels) ? word(labels["herdr.space"]) : undefined,
+        firstMessage: isObject(first) && typeof first.sent === "boolean" ? { sent: first.sent, reason: word(first.reason) } : undefined,
+        folder: word(program.cwd),
+        pid: typeof program.pid === "number" ? program.pid : undefined
+    };
+}
+/** The terminals `hc ls` lists: the live ones, every one with `all`, only those labelled `label` when given. */
+export function listTerminals(filter = {}) {
+    const all = filter.all === true ? ["--all"] : [];
+    const label = filter.label === undefined ? [] : ["--label", filter.label];
+    const { terminals } = objectOf(answer(["ls", "--json", ...all, ...label], "hc ls"));
+    if (!Array.isArray(terminals)) {
+        throw new CannotRun("hc ls answered no list of terminals", SHAPE);
     }
-    const parsed = parseObject(called.stdout);
-    if (parsed === undefined) {
-        throw new Refusal(`hc ${args[0] ?? ""} answered something that is no JSON object`, "check hc --version");
+    return terminals.map(listedOf);
+}
+/** What `hc get` reports of the terminal at `address`, or `gone`, in hc's words, when herdr has no such terminal. */
+export function readTerminal(address) {
+    const answered = answer(["get", address, "--json"], `hc get ${address}`);
+    if ("status" in answered && answered.status === NO_TERMINAL) {
+        return { gone: answered.problem };
     }
-    return parsed;
+    return readingOf(objectOf(answered));
 }
-/** What an error says, whatever was thrown. */
-export function describe(error) {
-    return error instanceof Error ? error.message : String(error);
+/** Runs `argv` in a terminal of its own in the background, outliving its caller; the address hc gives it. */
+export function startTerminal({ name, labels, cwd, argv }) {
+    const label = Object.entries(labels).flatMap(([key, value]) => ["--label", `${key}=${value}`]);
+    const args = ["run", "--bg", "--json", "--name", name, ...label, "--outlive-parent", "--cwd", cwd, "--", ...argv];
+    const address = word(objectOf(answer(args, "hc run")).address);
+    if (address === undefined) {
+        throw new CannotRun("hc run answered no address for the terminal it started", "check hc ls before starting it again");
+    }
+    return address;
+}
+/** Stops the terminal at `address`: hc's words when it refuses, undefined once it is stopped or had finished. */
+export function stopTerminal(address) {
+    const called = hc(["kill", address]);
+    return called.status === 0 || called.status === FINISHED
+        ? undefined
+        : `hc kill ${address} failed: ${whyFailed(called)}`;
+}
+/** Removes the terminal at `address`: hc's words when it refuses, undefined once it is gone. */
+export function removeTerminal(address) {
+    const called = hc(["rm", address]);
+    return called.status === 0 || called.status === NO_TERMINAL
+        ? undefined
+        : `hc rm ${address} failed: ${whyFailed(called)}`;
 }
-/** Reports a `Refusal` of `command` on stderr and answers exit 2; any other error is a bug and goes on up. */
-export function refuse(command, error) {
-    if (!(error instanceof Refusal)) {
-        throw error;
+/** Types `message` into the terminal at `address`: `sent`, `blocked` while it sits on a dialog, else hc's words. */
+export function sendTo(address, message) {
+    const called = hc(["send", address, message]);
+    if (called.status === 0) {
+        return "sent";
     }
-    process.stderr.write(`dw-sdlc ${command}: ${error.message}${error.remedy === undefined ? "" : ` — ${error.remedy}`}\n`);
-    return 2;
+    return called.status === BLOCKED ? "blocked" : { refused: `hc send failed: ${whyFailed(called)}` };
 }
 /** The option `flag` as a whole number from `min`, `fallback` when the command line leaves it out. */
 export function wholeNumber(flag, value, fallback, min) {
@@ -73,7 +133,7 @@ export function wholeNumber(flag, value, fallback, min) {
 export function lead() {
     const id = process.env.HC_TERMINAL_ID;
     if (id === undefined || id === "") {
-        throw new Refusal("outside herdr: $HC_TERMINAL_ID is not set", "run it in a terminal herdr started, where the Lead has an address");
+        throw new CannotRun("outside herdr: $HC_TERMINAL_ID is not set", "run it in a terminal herdr started, where the Lead has an address");
     }
     return id;
 }
@@ -82,41 +142,30 @@ export function isLive(worker) {
     return worker.state === "live";
 }
 /**
- * The Workers with the folder each live one works in, its worktree, which `hc get` reports as
- * `foreground.cwd` and `hc ls` leaves out. A Worker herdr cannot tell it for keeps its launch folder.
+ * The Workers with the folder each live one works in, its worktree, which `hc get` reports and `hc ls`
+ * leaves out. A Worker herdr cannot tell it for keeps its launch folder.
  */
 export function workingFolders(workers) {
     return workers.map((worker) => {
         if (!isLive(worker)) {
             return worker;
         }
-        const got = call("hc", ["get", worker.address, "--json"]);
-        const foreground = got.status === 0 ? parseObject(got.stdout)?.foreground : undefined;
-        const cwd = isObject(foreground) ? foreground.cwd : undefined;
-        return typeof cwd === "string" && cwd !== "" ? { ...worker, folder: cwd } : worker;
+        const answered = answer(["get", worker.address, "--json"], `hc get ${worker.address}`);
+        const folder = "object" in answered ? readingOf(answered.object).folder : undefined;
+        return folder === undefined ? worker : { ...worker, folder };
     });
 }
-function word(value) {
-    return typeof value === "string" ? value : undefined;
-}
-/** The Workers `lead` started, in the order herdr lists them; `all` adds the finished ones. */
+/** The Workers `leadId` started, in the order herdr lists them; `all` adds the finished ones. */
 export function workersOf(leadId, all) {
-    const listing = hcObject(["ls", "--json", ...(all ? ["--all"] : []), "--label", "role=worker"]);
-    const { terminals } = listing;
-    if (!Array.isArray(terminals)) {
-        throw new Refusal("hc ls answered no list of terminals", "check hc --version");
-    }
-    return terminals.flatMap((entry) => {
-        if (!isObject(entry) || entry.parent !== leadId) {
-            return [];
-        }
-        const { address, state, cwd } = entry;
-        if (typeof address !== "string" || typeof state !== "string" || typeof cwd !== "string") {
-            throw new Refusal("hc ls answered a terminal without an address, state or folder", "check hc --version");
-        }
-        const status = state === "finished" ? "finished" : (word(entry.status) ?? "unknown");
-        return [{ name: word(entry.name) ?? address, address, state, status, folder: cwd }];
-    });
+    return listTerminals({ all, label: "role=worker" })
+        .filter(({ parent }) => parent === leadId)
+        .map(({ name, address, state, status, folder }) => ({
+        name,
+        address,
+        state,
+        status: state === "finished" ? "finished" : (status ?? "unknown"),
+        folder
+    }));
 }
 /** A table of rows, every column but the last padded to its widest cell and two spaces apart. */
 export function table(rows) {

package/dist/worker/launch.js

@@ -1,8 +1,8 @@
 // What `worker start` and `lead start` share: a session started in a herdr terminal of its own beside the
 // caller, its tab named, and the terminal read back until the session shows it took its first message.
 import { setTimeout as sleep } from "node:timers/promises";
-import { isObject } from "../json-text.js";
-import { describe, hcObject, Refusal } from "./herdr.js";
+import { CannotRun } from "../cannot-run.js";
+import { readTerminal, startTerminal } from "./herdr.js";
 import { nameTab } from "./tabs.js";
 /** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
 export const NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
@@ -12,42 +12,43 @@ export const TAB_WAIT = 10;
 const WORKING = new Set(["working", "blocked", "done"]);
 /** How long the read-back waits between two reads of the terminal. */
 const POLL_MS = 1000;
-/** The status a session reports, if it has reported one. */
-function reportedStatus(terminal) {
-    const { status } = terminal;
-    return isObject(status) && typeof status.state === "string" ? status.state : undefined;
-}
 /** Why the session, called `who`, can no longer take its first message, or undefined while it still may. */
-function failure(terminal, who) {
-    const { first_message: first, state } = terminal;
-    if (isObject(first) && first.sent === false) {
-        return typeof first.reason === "string" ? first.reason : "herdr gave no reason";
+function failure({ firstMessage, state, status }, who) {
+    if (firstMessage?.sent === false) {
+        return firstMessage.reason ?? "herdr gave no reason";
     }
     if (state !== "live") {
         return "the terminal has finished";
     }
-    return reportedStatus(terminal) === "error" ? `the ${who} reports its status as error` : undefined;
+    return status === "error" ? `the ${who} reports its status as error` : undefined;
+}
+/** The terminal at `address` as `hc get` reports it, or why it could not be read. */
+function readBack(address) {
+    try {
+        const reading = readTerminal(address);
+        return "gone" in reading ? { unread: reading.gone } : reading;
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            return { unread: error.message };
+        }
+        throw error;
+    }
 }
 /** Reads the terminal until the session shows work, for up to `wait` seconds; why it did not, or undefined once it did. */
 async function delivery(address, wait, who) {
     const deadline = Date.now() + wait * 1000;
     for (;;) {
-        let terminal;
-        try {
-            terminal = hcObject(["get", address, "--json"]);
-        }
-        catch (error) {
-            if (!(error instanceof Refusal)) {
-                throw error;
-            }
-            // The session is running by now, so a failed read is a message not confirmed, never a start that did not happen.
-            return `the terminal could not be read back: ${describe(error)}`;
+        const reading = readBack(address);
+        // The session is running by now, so a failed read is a message not confirmed, never a start that did not happen.
+        if ("unread" in reading) {
+            return `the terminal could not be read back: ${reading.unread}`;
         }
-        const failed = failure(terminal, who);
+        const failed = failure(reading, who);
         if (failed !== undefined) {
             return failed;
         }
-        if (WORKING.has(reportedStatus(terminal) ?? "")) {
+        if (WORKING.has(reading.status ?? "")) {
             return undefined;
         }
         if (Date.now() >= deadline) {
@@ -58,33 +59,19 @@ async function delivery(address, wait, who) {
 }
 /** The id of the herdr space the terminal `id` sits in, if it sits in one. */
 export function spaceOf(id) {
-    const { labels } = hcObject(["get", id, "--json"]);
-    const space = isObject(labels) ? labels["herdr.space"] : undefined;
-    return typeof space === "string" ? space : undefined;
+    const reading = readTerminal(id);
+    if ("gone" in reading) {
+        throw new CannotRun(reading.gone);
+    }
+    return reading.space;
 }
 /**
  * Runs `hc run` once for `launch`, outliving its caller, then names the tab and reads the terminal back side
  * by side. It never sends the first message again; `reason` says why the session did not take it.
  */
 export async function launch(command, { name, role, space, cwd, argv, wait }) {
-    const { address } = hcObject([
-        "run",
-        "--bg",
-        "--json",
-        "--name",
-        name,
-        "--label",
-        `role=${role}`,
-        ...(space === undefined ? [] : ["--label", `herdr.space=${space}`]),
-        "--outlive-parent",
-        "--cwd",
-        cwd,
-        "--",
-        ...argv
-    ]);
-    if (typeof address !== "string") {
-        throw new Refusal("hc run answered no address for the terminal it started", "check hc ls before starting it again");
-    }
+    const labels = { role, ...(space === undefined ? {} : { "herdr.space": space }) };
+    const address = startTerminal({ name, labels, cwd, argv });
     // Side by side, so the wait for the tab overlaps the wait for the session to start.
     const naming = space === undefined ? Promise.resolve("none") : nameTab(address, name, Math.min(TAB_WAIT, wait));
     const [named, reason] = await Promise.all([naming, delivery(address, wait, role === "lead" ? "Lead" : "Worker")]);

package/dist/worker/origin.d.ts

@@ -1,6 +1,6 @@
 /**
  * Fetches origin's default branch, or every branch of origin when no default is known, into the remote-tracking
- * refs at `root`; a clone with no origin has nothing to fetch and is left alone. Throws a `Refusal` when the
+ * refs at `root`; a clone with no origin has nothing to fetch and is left alone. Throws `CannotRun` when the
  * fetch fails, since a Worker started on a stale base is the fault this prevents.
  */
 export declare function freshenOrigin(root: string, baseBranch: string): void;