dw-sdlc 0.11.0 → 0.12.1

package/dist/agentic-config.d.ts

@@ -36,7 +36,7 @@ export type PrConfig = {
     reviewCommand: string;
 };
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
-declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
 export type WorkerEffort = (typeof WORKER_EFFORTS)[number];
 /** How a Worker's Claude Code session starts: the words that start it, its model and its effort. */
 export type WorkerConfig = {

package/dist/agentic-config.js

@@ -14,7 +14,7 @@ export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
 /** The Review depths, strictest first: what the dev's `--review` names. */
 export const REVIEW_DEPTHS = ["full", "light", "off"];
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
-const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+export const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],

package/dist/cli.js

@@ -12,6 +12,9 @@ import * as recap from "./commands/recap.js";
 import * as referencesSetup from "./commands/references-setup.js";
 import * as referencesSync from "./commands/references-sync.js";
 import * as setup from "./commands/setup.js";
+import * as workerLs from "./commands/worker-ls.js";
+import * as workerReport from "./commands/worker-report.js";
+import * as workerStart from "./commands/worker-start.js";
 const COMMANDS = new Map([
     ["gate", gate],
     ["check", check],
@@ -23,7 +26,10 @@ const COMMANDS = new Map([
     ["references setup", referencesSetup],
     ["pr ship", prShip],
     ["pr reviewed", prReviewed],
-    ["recap", recap]
+    ["recap", recap],
+    ["worker start", workerStart],
+    ["worker ls", workerLs],
+    ["worker report", workerReport]
 ]);
 function usage() {
     const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;

package/dist/commands/doctor.d.ts

@@ -40,11 +40,6 @@ export type Inputs = {
 };
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export declare function claudeConfigDir(env: Record<string, string | undefined>, home: string): string;
-/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
-export declare const MARKETPLACE = "dw-sdlc";
-export declare const PLUGIN = "sdlc";
-export declare const PLUGIN_ID = "sdlc@dw-sdlc";
-export declare const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export declare const RTK_FIND_EXEC_FIXED = "0.46.0";
 export declare const PNPM_MINIMUM_RELEASE_AGE = 10080;

package/dist/commands/doctor.js

@@ -7,19 +7,12 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { findRepository, resolveConfig } from "../agentic-config.js";
-import { EXACT_VERSION, parseCatalog, parsePins } from "../pins.js";
+import { checkPackage, checkPlugin, checkSessions, parseJson, runningPluginRoot, versionBefore } from "../doctor-plugins.js";
+import { isObject } from "../json-text.js";
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export function claudeConfigDir(env, home) {
     return env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
 }
-/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
-export const MARKETPLACE = "dw-sdlc";
-export const PLUGIN = "sdlc";
-export const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
-/** The plugin of the session helpers: optional, and it links a copy of the package of its own. */
-const SESSIONS = "sdlc-sessions";
-const SESSIONS_ID = `${SESSIONS}@${MARKETPLACE}`;
-export const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export const RTK_FIND_EXEC_FIXED = "0.46.0";
 export const PNPM_MINIMUM_RELEASE_AGE = 10080;
@@ -37,20 +30,6 @@ export const realProbe = {
         return (result.stdout ?? "").trim().split("\n")[0] ?? "";
     }
 };
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function parseJson(text) {
-    if (text === undefined) {
-        return undefined;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-}
 function checkJq(probe) {
     const { status, stdout } = probe.run("jq", ["--version"]);
     if (status === 0) {
@@ -58,151 +37,6 @@ function checkJq(probe) {
     }
     return { name: "jq", level: "FAIL", detail: "missing: every guard is silent without it. brew install jq" };
 }
-/** The checkout a directory marketplace runs the plugin from, or undefined for a snapshot. */
-function liveCheckout(probe, claude) {
-    const known = parseJson(probe.read(join(claude, "plugins", "known_marketplaces.json")));
-    const entry = isObject(known) && isObject(known[MARKETPLACE]) ? known[MARKETPLACE] : undefined;
-    const source = entry !== undefined && isObject(entry.source) ? entry.source : undefined;
-    return source?.source === "directory" && typeof source.path === "string" ? source.path : undefined;
-}
-function pluginOrigin(probe, claude, installPath) {
-    const checkout = liveCheckout(probe, claude);
-    if (checkout !== undefined) {
-        return `runs live from ${checkout}/plugins/${PLUGIN}; a change there is in the next session`;
-    }
-    return `installed at ${installPath}; a change reaches it through claude plugin update`;
-}
-/** What `claude plugin list --json` prints, one object a plugin, or undefined when it does not answer. */
-function listedPlugins(probe) {
-    const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
-    const list = status === 0 ? parseJson(stdout) : undefined;
-    return Array.isArray(list) ? list.filter(isObject) : undefined;
-}
-/** The directory `plugin` runs from on this machine: the checkout of a directory marketplace, else the installed snapshot. */
-function runningPluginRoot(probe, claude, plugin = PLUGIN) {
-    const checkout = liveCheckout(probe, claude);
-    if (checkout !== undefined) {
-        return join(checkout, "plugins", plugin);
-    }
-    const entry = listedPlugins(probe)?.find((item) => item.id === `${plugin}@${MARKETPLACE}`);
-    return entry !== undefined && typeof entry.installPath === "string" ? entry.installPath : undefined;
-}
-function checkPlugin(probe, claude) {
-    const list = listedPlugins(probe);
-    if (list === undefined) {
-        return { name: "plugin", level: "FAIL", detail: "claude plugin list did not answer; is Claude Code installed?" };
-    }
-    const entry = list.find((item) => item.id === PLUGIN_ID);
-    if (entry === undefined) {
-        return {
-            name: "plugin",
-            level: "FAIL",
-            detail: `${PLUGIN_ID} is not installed. claude plugin marketplace add dominikwozniak/dw-sdlc --sparse .claude-plugin plugins packages && claude plugin install ${PLUGIN_ID} --scope user`
-        };
-    }
-    const version = typeof entry.version === "string" ? entry.version : "?";
-    const installPath = typeof entry.installPath === "string" ? entry.installPath : "?";
-    if (entry.enabled !== true) {
-        return {
-            name: "plugin",
-            level: "FAIL",
-            detail: `${version} installed but disabled, so no guard runs. claude plugin enable ${PLUGIN_ID}`
-        };
-    }
-    return {
-        name: "plugin",
-        level: "PASS",
-        detail: `${version} enabled; ${pluginOrigin(probe, claude, installPath)}`
-    };
-}
-/** The `version` of the package.json in `dir`, or undefined when there is none. */
-function manifestVersion(probe, dir) {
-    const manifest = parseJson(probe.read(join(dir, "package.json")));
-    return isObject(manifest) && typeof manifest.version === "string" ? manifest.version : undefined;
-}
-/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
-function checkPackage(probe, claude, root) {
-    const name = "package";
-    const manifest = root === undefined ? undefined : probe.read(join(root, "package.json"));
-    if (root === undefined || manifest === undefined) {
-        return { name, level: "INFO", detail: `no package.json here to pin ${PACKAGE}` };
-    }
-    let spec;
-    try {
-        spec = parsePins(manifest, parseCatalog(probe.read(join(root, "pnpm-workspace.yaml")) ?? ""))[PACKAGE];
-    }
-    catch {
-        return { name, level: "INFO", detail: `${join(root, "package.json")} is not JSON` };
-    }
-    if (spec === undefined) {
-        return { name, level: "INFO", detail: `the repository does not pin ${PACKAGE}` };
-    }
-    // `workspace:` or a range names no one version: the copy installed under node_modules is the one that runs.
-    const pinned = EXACT_VERSION.test(spec) ? spec : manifestVersion(probe, join(root, "node_modules", PACKAGE));
-    if (pinned === undefined) {
-        return { name, level: "WARN", detail: `the repository pins ${PACKAGE} ${spec}, not installed: pnpm install` };
-    }
-    const plugin = runningPluginRoot(probe, claude);
-    if (plugin === undefined) {
-        return { name, level: "INFO", detail: `no ${PLUGIN_ID} runs here to compare with the pinned ${pinned}` };
-    }
-    const linked = manifestVersion(probe, join(plugin, PACKAGE));
-    if (linked === undefined) {
-        return {
-            name,
-            level: "WARN",
-            detail: `the plugin at ${plugin} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
-        };
-    }
-    if (linked !== pinned) {
-        const remedy = versionBefore(linked, pinned)
-            ? `claude plugin update ${PLUGIN_ID}`
-            : `pnpm add --save-dev --save-exact ${PACKAGE}@${linked}`;
-        return {
-            name,
-            level: "WARN",
-            detail: `drift: the plugin runs ${PACKAGE} ${linked} and the repository pins ${pinned}, so its hooks and skills run other code than the Gate. ${remedy}`
-        };
-    }
-    return { name, level: "PASS", detail: `${PACKAGE} ${linked} in the plugin and in the repository` };
-}
-/**
- * `sdlc-sessions`, which a machine may go without, so it never fails. Its copy of the package against
- * the sdlc plugin's copy: the `package` line holds that one to the repository's pin.
- */
-function checkSessions(probe, claude) {
-    const name = "sessions";
-    const list = listedPlugins(probe);
-    const entry = list?.find((item) => item.id === SESSIONS_ID);
-    if (entry === undefined) {
-        const detail = list === undefined ? "claude plugin list did not answer" : `no ${SESSIONS_ID}, so no /sdlc-recap`;
-        return { name, level: "INFO", detail };
-    }
-    const version = typeof entry.version === "string" ? entry.version : "?";
-    if (entry.enabled !== true) {
-        return { name, level: "WARN", detail: `${version} installed but disabled. claude plugin enable ${SESSIONS_ID}` };
-    }
-    const root = runningPluginRoot(probe, claude, SESSIONS);
-    const copy = root === undefined ? undefined : manifestVersion(probe, join(root, PACKAGE));
-    if (copy === undefined) {
-        return {
-            name,
-            level: "WARN",
-            detail: `${version} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
-        };
-    }
-    const guards = runningPluginRoot(probe, claude);
-    const other = guards === undefined ? undefined : manifestVersion(probe, join(guards, PACKAGE));
-    if (other !== undefined && other !== copy) {
-        const behind = versionBefore(copy, other) ? SESSIONS_ID : PLUGIN_ID;
-        return {
-            name,
-            level: "WARN",
-            detail: `drift: ${SESSIONS} runs ${PACKAGE} ${copy} and ${PLUGIN} runs ${other}. claude plugin update ${behind}`
-        };
-    }
-    return { name, level: "PASS", detail: `${version} enabled, on ${PACKAGE} ${copy}` };
-}
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {
     if (!isObject(settings) || !isObject(settings.hooks)) {
@@ -241,18 +75,6 @@ export function rtkExcludes(toml) {
     }
     return [...(match[1] ?? "").matchAll(/"([^"]*)"/g)].map((entry) => entry[1] ?? "");
 }
-function versionBefore(version, threshold) {
-    const a = version.split(".").map((part) => Number.parseInt(part, 10));
-    const b = threshold.split(".").map((part) => Number.parseInt(part, 10));
-    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
-        const x = a[i] ?? 0;
-        const y = b[i] ?? 0;
-        if (x !== y) {
-            return x < y;
-        }
-    }
-    return false;
-}
 // The plugin's rtk-rewrite.sh is the one wiring of `rtk hook claude`; a second one in the user
 // settings rewrites again, and in a linked worktree that copy is what the isolation check refuses.
 function checkRtk(probe, home, claude) {
@@ -299,6 +121,14 @@ function checkRtk(probe, home, claude) {
         detail: `rtk ${version} behind the plugin's rewrite hook; exclude_commands: ${excludes.join(", ") || "none"}`
     };
 }
+/** herdr's `hc` in the agent's shell, which a Lead starts its Workers through; a machine may go without it. */
+function checkHc(probe) {
+    const hc = probe.shell("command -v hc");
+    if (hc === "") {
+        return { name: "hc", level: "INFO", detail: "no hc on PATH, so no /sdlc-delegate: install herdr to run Workers" };
+    }
+    return { name: "hc", level: "PASS", detail: `${hc}, so a Lead can start Workers` };
+}
 function checkSafeChain(probe) {
     const binary = probe.shell("command -v safe-chain");
     if (binary === "") {
@@ -381,6 +211,7 @@ export function diagnose(inputs) {
         checkPlugin(probe, claude),
         checkPackage(probe, claude, inputs.config === undefined ? undefined : inputs.root),
         checkSessions(probe, claude),
+        checkHc(probe),
         checkRtk(probe, home, claude),
         checkSafeChain(probe),
         checkPnpmReleaseAge(probe, home),

package/dist/commands/pr-ship.js

@@ -4,7 +4,7 @@
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig, REVIEW_DEPTHS } from "../agentic-config.js";
 import { decide, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
-import { CannotRun, carriesBase, gh, namedProblem, now, read, readAgain, said } from "../pr/read.js";
+import { CannotRun, carriesBase, gh, namedProblem, now, read, readAgain, said, withBehind } from "../pr/read.js";
 export const summary = "decide the Action one pull request needs next, as a line or JSON";
 const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--review full|light|off] [--dry-run] [--json] [--verbose]
 
@@ -13,7 +13,9 @@ is omitted, and answers the Action it needs next: the status, the action, whose
 The script performs its own Actions, each at most once and then reads again: it updates a branch
 behind its base, marks a draft ready once nothing else holds it back, and squash merges a pull
 request ready to merge under pr.merge auto in .ai/agentic.config.json or with --merge for this call;
-under ask, the default, it parks with the merge command. A head without a ${REVIEW} success
+under ask, the default, it parks with the merge command. A branch is behind when the compare of
+the base with the head shows the head lacks a commit of the base, or GitHub reports BEHIND, which
+it does only under a rule that a branch be up to date. A head without a ${REVIEW} success
 gets the Review depth --review names for this call, else pr.review: under full the agent reviews it
 with the command pr.reviewCommand names, /code-review by default; under light one sdlc-reviewer
 subagent reads the diff; under off the script posts the success itself, its description saying
@@ -143,7 +145,7 @@ function handedOver(pr, policy, answer, action, reason) {
 function ship(cli, policy) {
     // Only pr.review auto routes the depth from the changes, so only it reads them.
     const sized = policy.review.depth === "auto";
-    let pr = read(cli, "pr ship", sized);
+    let pr = withBehind(read(cli, "pr ship", sized));
     const performed = [];
     // The head each Action ran on.
     const postedOn = new Map();
@@ -177,7 +179,7 @@ function ship(cli, policy) {
         const record = { action, command, exit: status, ...(message === "" ? {} : { stderr: message }) };
         postedOn.set(action, before.head);
         try {
-            pr = readAgain(pr, sized);
+            pr = withBehind(readAgain(pr, sized));
             performed.push({ ...record, ok: TOOK[action](before, pr) });
         }
         catch (error) {

package/dist/commands/recap.js

@@ -6,6 +6,7 @@ import { parseArgs } from "node:util";
 import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
 import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
 import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
+import { isLive, Refusal, workersOf, workingFolders } from "../worker/herdr.js";
 import { git } from "../working-tree.js";
 export const summary = "the facts a Recap rests on and whether the session can be closed";
 const USAGE = `Usage: dw-sdlc recap [--json]
@@ -21,7 +22,9 @@ The session cannot be closed over any of these:
   a commit pushed nowhere or only part of the way;
   an open pull request, whatever its Action;
   commits on top of the base that no pull request holds. The default branch and a branch
-  guardrails.protectedBranches names need no pull request.
+  guardrails.protectedBranches names need no pull request;
+  a live Worker this session started as a Lead, in a terminal herdr started ($HC_TERMINAL_ID): its
+  report has no one to reach once the Lead is gone. A Worker whose turn ended is still live.
 
 A pull request closed without merging merges nothing, and a detached HEAD names no pull request. There a
 commit counts as pushed only on a remote branch, and the command asks the remote which branches still
@@ -30,8 +33,9 @@ stand. A branch force-pushed since the last fetch can still read as holding it,
 A linked worktree is a reason beside the verdict, never against it: the session cannot remove the
 directory it runs in.
 
-One line a fact, or one document with --json. Needs an authenticated gh and a remote it can read. A
-detached HEAD or a repository with no remote asks gh nothing, and the pull request fact says so.
+One line a fact, or one document with --json. Needs an authenticated gh and a remote it can read, and in
+herdr hc on PATH. A detached HEAD or a repository with no remote asks gh nothing, and the pull request
+fact says so; outside herdr the workers fact says so.
 
 Exit 0 the session can be closed, 1 it cannot, 2 when it cannot run.`;
 function plural(howMany, word) {
@@ -96,23 +100,64 @@ function readLocal(root) {
         worktree: { linked: mainCheckout(root) !== undefined, path: root }
     };
 }
-/** The current branch's pull request and the Action the Ship script's decision gives it, or null. */
-function readShipped(root) {
+/** The live Workers this session started as a Lead, each in the folder it works in; null outside herdr. */
+function liveWorkers() {
+    const lead = process.env.HC_TERMINAL_ID;
+    if (lead === undefined || lead === "") {
+        return null;
+    }
+    try {
+        return workingFolders(workersOf(lead, false).filter(isLive));
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            throw new CannotRun(error.message, error.remedy ?? "check hc ls, then call again");
+        }
+        throw error;
+    }
+}
+function workersText(workers) {
+    return workers.map((worker) => `${worker.name} (${worker.status})`).join(", ");
+}
+/**
+ * The remote branch name `branch` tracks, when it differs from `branch`. Read from the config, so it holds
+ * after the remote deleted the branch.
+ */
+function upstreamName(root, branch) {
+    const remote = asked(root, ["config", "--get", `branch.${branch}.remote`]);
+    const merge = asked(root, ["config", "--get", `branch.${branch}.merge`]);
+    if (remote === undefined || remote === "." || merge === undefined || !merge.startsWith("refs/heads/")) {
+        return undefined;
+    }
+    const name = merge.slice("refs/heads/".length);
+    return name === branch ? undefined : name;
+}
+/** Whether `pr`'s commits hold `head`, so the head is on GitHub whatever became of the upstream. */
+function holds(pr, head) {
+    return head !== null && pr.commits.includes(head);
+}
+/**
+ * The current branch's pull request and the Action the Ship script's decision gives it, or null. The one
+ * found by the upstream's name counts only when it holds the head: a branch started from another tracks
+ * that branch until its first push.
+ */
+function readShipped(root, branch, head) {
     // An invalid config layer resolves to ask and full, as in the Ship script.
     const policy = declaredPolicy(resolveConfig(root).config.pr);
-    const pr = readBranch(policy.review.depth === "auto");
-    return pr === null ? null : { pr, answer: decide(pr, now(), policy) };
+    const found = readBranch(policy.review.depth === "auto", head === null ? undefined : upstreamName(root, branch));
+    if (found === null || (found.byUpstream && !holds(found.pr, head))) {
+        return null;
+    }
+    return { pr: found.pr, answer: decide(found.pr, now(), policy) };
 }
 /**
  * The tracking refs, as `--remotes` names them, that the remote contradicts, which only a fetch would show:
- * a branch it no longer has, its `HEAD`, and the session's own branch where it moved. Any other branch that
- * moved, such as the base, counts as holding what it held; plugins/sdlc-sessions/README.md says why.
+ * a branch it no longer has, its `HEAD`, and the session's own branch where it moved. A remote out of reach
+ * holds nothing; any other moved branch counts as before (plugins/sdlc-sessions/README.md says why).
  */
 function staleTracking(root, { branch, upstream }) {
     return remotesOf(root).flatMap((remote) => {
-        const live = new Map(must(root, ["ls-remote", "--heads", remote])
-            .split("\n")
-            .map((line) => {
+        const live = new Map((asked(root, ["ls-remote", "--heads", remote]) ?? "").split("\n").map((line) => {
             const [oid = "", ref = ""] = line.split("\t");
             return [ref.replace("refs/heads/", `${remote}/`), oid];
         }));
@@ -196,7 +241,7 @@ function cleanReason(askedGh) {
         : "nothing is uncommitted or unpushed; gh was not asked";
     return { id: "clean", blocks: false, text };
 }
-function reasonsOf(local, shipped, ahead, orphaned, askedGh) {
+function reasonsOf(local, { shipped, ahead, orphaned, askedGh, workers }) {
     const all = [];
     if (local.paused !== null) {
         all.push({ id: "paused", blocks: true, text: `a ${local.paused} is paused` });
@@ -218,6 +263,10 @@ function reasonsOf(local, shipped, ahead, orphaned, askedGh) {
     if (shipped !== null) {
         all.push(pullRequestReason(shipped));
     }
+    if (workers !== null && workers.length > 0) {
+        const text = `${plural(workers.length, "live Worker")}: ${workersText(workers)}`;
+        all.push({ id: "workers", blocks: true, text });
+    }
     if (!all.some((reason) => reason.blocks)) {
         all.unshift(cleanReason(askedGh));
     }
@@ -234,7 +283,13 @@ function closeOf(reasons) {
     const line = `Close the session: ${verdict}, because ${shown.map((reason) => reason.text).join("; ")}`;
     return { verdict, line, reasons };
 }
-function linesOf(local, shipped, askedGh, line) {
+function workersLine(workers) {
+    if (workers === null) {
+        return "not in herdr";
+    }
+    return workers.length === 0 ? "none live" : `${workers.length} live: ${workersText(workers)}`;
+}
+function linesOf(local, { shipped, askedGh, workers }, line) {
     const none = askedGh ? "none" : "gh not asked";
     return [
         `branch: ${local.branch ?? "detached HEAD"}`,
@@ -242,6 +297,7 @@ function linesOf(local, shipped, askedGh, line) {
         `upstream: ${local.upstream ?? "none"}, ${local.unpushed} unpushed`,
         `pull request: ${shipped === null ? none : `${shipped.pr.url} ${lineOf(shipped.answer)}`}`,
         `worktree: ${local.worktree.linked ? `linked at ${local.worktree.path}` : "main checkout"}`,
+        `workers: ${workersLine(workers)}`,
         line
     ].join("\n");
 }
@@ -270,20 +326,26 @@ function report(json) {
     const { branch, head } = read;
     // A detached HEAD names no branch for gh to look up, and a repository with no remote has no GitHub.
     const asksGh = branch !== null && remotesOf(root).length > 0;
-    const shipped = asksGh ? readShipped(root) : null;
-    const held = shipped !== null && head !== null && shipped.pr.commits.includes(head);
+    const shipped = asksGh ? readShipped(root, branch, head) : null;
+    const held = shipped !== null && holds(shipped.pr, head);
     const local = standing(root, read, shipped, held);
     // An open pull request can still take the head, and a commit-less repository has nothing to merge.
     const nothingToMerge = held || shipped?.pr.state === "OPEN" || head === null;
     const ahead = asksGh && !nothingToMerge ? aheadOf(root, branch, shipped) : null;
-    const orphaned = orphanedOf(root, read, shipped, held);
-    const close = closeOf(reasonsOf(local, shipped, ahead, orphaned, asksGh));
+    const facts = {
+        shipped,
+        ahead,
+        orphaned: orphanedOf(root, read, shipped, held),
+        askedGh: asksGh,
+        workers: liveWorkers()
+    };
+    const close = closeOf(reasonsOf(local, facts));
     const pullRequest = shipped === null
         ? null
         : { url: shipped.pr.url, number: shipped.pr.number, state: shipped.pr.state, ...shipped.answer };
     const output = json
-        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, close }, null, 2)
-        : linesOf(local, shipped, asksGh, close.line);
+        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, close }, null, 2)
+        : linesOf(local, facts, close.line);
     process.stdout.write(`${output}\n`);
     return close.verdict === "yes" ? 0 : 1;
 }

package/dist/commands/worker-ls.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "list the Workers this Lead started and their states";
+export declare function run(argv: string[]): number;

package/dist/commands/worker-ls.js

@@ -0,0 +1,53 @@
+// `dw-sdlc worker ls`: the Workers the calling Lead started, with the state herdr holds them in.
+import { parseArgs } from "node:util";
+import { describe, lead, refuse, table, workersOf, workingFolders } from "../worker/herdr.js";
+export const summary = "list the Workers this Lead started and their states";
+const USAGE = `Usage: dw-sdlc worker ls [--json]
+
+Lists the Workers the calling Lead started (terminals labelled role=worker whose parent is this
+terminal): name, address, herdr's state, status and folder. A live Worker's folder is the one it works
+in, its worktree, as hc get reports it; a finished one, or one herdr cannot tell it for, shows the folder
+it was launched in. The status is what the Worker reports, one of idle, working, done, blocked, error, or
+finished once its terminal has ended; unknown before it reports. herdr's done means a turn ended, not the
+task: the Worker's Recap says whether the task is done. Finished Workers stay listed until they are
+removed with hc rm.
+
+Needs a terminal herdr started ($HC_TERMINAL_ID) and hc on PATH. One line a Worker, or one JSON array
+with --json.
+
+Exit 0 listed, 2 when it cannot run.`;
+export function run(argv) {
+    let json;
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" } }
+        });
+        if (values.help === true) {
+            process.stdout.write(`${USAGE}\n`);
+            return 0;
+        }
+        json = values.json === true;
+    }
+    catch (error) {
+        process.stderr.write(`dw-sdlc worker ls: ${describe(error)}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        const workers = workingFolders(workersOf(lead(), true));
+        if (json) {
+            process.stdout.write(`${JSON.stringify(workers, null, 2)}\n`);
+        }
+        else if (workers.length === 0) {
+            process.stdout.write("no Workers\n");
+        }
+        else {
+            const rows = workers.map((worker) => [worker.name, worker.address, worker.state, worker.status, worker.folder]);
+            process.stdout.write(`${table([["NAME", "ADDRESS", "STATE", "STATUS", "FOLDER"], ...rows])}\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        return refuse("worker ls", error);
+    }
+}

package/dist/commands/worker-report.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "deliver a Recap to the Lead, retrying while it is blocked";
+export declare function run(argv: string[]): Promise<number>;