@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/lib/board/store.ts

@@ -2,7 +2,7 @@
  * The board store: one directory of card files per repository, and the only code
  * that writes one.
  *
- * A board is a directory — `<agentDir>/board/<repo-key>/cards/0004.json` — so a
+ * A board is a directory — `<agent-dir>/board/<repo-key>/cards/0004.json` — so a
  * reader needs no index, no daemon, and no dependency; the listing *is* the
  * index. The key comes from `lib/repo-key.ts`, so every worktree of one repository
  * shares one board, and a directory outside git keys on itself.
@@ -35,15 +35,17 @@ import { shortenPath } from "../format.ts";
 import { repoKeyFor } from "../repo-key.ts";
 import {
 	type Card,
-	CARD_STATUSES,
-	CARD_VERSION,
 	cardRef,
 	type EndedCard,
-	isCard,
+	ENDED_VERSION,
 	type Priority,
 	priorityRank,
+	SUPPORTED_VERSIONS,
 } from "./card.ts";
+import { LANES } from "./lanes.ts";
+import { readCard } from "./read.ts";
 import { indexOf } from "./links.ts";
+import { type BoardConfig, DEFAULT_BOARD_CONFIG, readBoardConfig } from "./config.ts";
 import { type Actor, applyOp, type CardOp, createCard } from "./rules.ts";
 
 /** The directory under the agent directory that holds every board. */
@@ -108,9 +110,26 @@ export interface Skip {
 export interface BoardStore {
 	/** The board's own directory, for `where` and for a refusal that names it. */
 	readonly dir: string;
+	/**
+	 * The repository key this board is filed under.
+	 *
+	 * Carried rather than read back off {@link dir}'s last segment: the same key is what
+	 * `session-bus` files this repository's records under, so a caller that needs it must
+	 * not learn it from the board's layout — otherwise regrouping the board's own files
+	 * moves the roster to a directory no bus writes to, and the page reads "no record" for
+	 * every peer instead of failing where someone would notice.
+	 */
+	readonly key: string;
+	/**
+	 * The settings this board works by: its WIP limits and the name its two signatures carry.
+	 *
+	 * Read once when the store opened, and handed to every operation: the page shows the same
+	 * numbers a refusal would, so a head cannot claim room a claim would refuse.
+	 */
+	config(): BoardConfig;
 	/** Create the directories and sweep a temp file a dead process left. */
 	ensure(): Promise<void>;
-	/** Every card on the board, in lane order: todo, doing, blocked, done. */
+	/** Every card on the board, in lane order: backlog, plan, execute, blocked, done. */
 	list(): Promise<Card[]>;
 	/**
 	 * The board in one read: the cards, and the files it refused.
@@ -170,14 +189,41 @@ export async function openBoard(
 	// environment carries the active root, so the two are reconciled before the
 	// repository lookup — the same path `plan` and `session-bus` take.
 	const repo = await repoKeyFor(pi, resolveEffectiveCwd(cwd));
-	return createStore(boardDirFor(agentDir, repo.key), { root: repo.root });
+	// Read once per store: the settings are a setting, not a card, and a board that re-read
+	// a file on every write would spend a stat to answer a question nobody changed.
+	const config = readBoardConfig(resolveEffectiveCwd(cwd), { agentDir });
+	// The key is handed on, not left to be read off the directory it named: `session-bus`
+	// files this repository's records under the same key, so the two must not be able to
+	// disagree about it.
+	return createStore(boardDirFor(agentDir, repo.key), { root: repo.root, key: repo.key, config });
 }
 
 /** Build a store over one directory. Exported for tests and for a second backend. */
-export function createStore(dir: string, options: { root?: string } = {}): BoardStore {
+export function createStore(
+	dir: string,
+	options: {
+		root?: string;
+		key?: string;
+		config?: BoardConfig;
+		/**
+		 * A suite's seam: called once an operation is ready to write and before the re-read that
+		 * decides whether it still may.
+		 *
+		 * A race between a write and a pile move cannot be made deterministic from outside — the
+		 * window is inside one `mutate` — so a test stands here and lets the other write land. The
+		 * product supplies nothing.
+		 */
+		beforeWrite?: (id: string, kind: CardOp["kind"]) => Promise<void> | void;
+	} = {},
+): BoardStore {
+	// A store built over a directory by hand has no repository to ask, so it is keyed by
+	// that directory's own name: the one place this fallback lives, and the one reason it
+	// is not a proof about `openBoard`'s boards.
+	const key = options.key ?? basename(dir);
 	// A store built over a directory by hand has no repository to name, so it names its
 	// own directory: the page then says something true instead of something blank.
 	const root = options.root ?? dir;
+	const config = options.config ?? DEFAULT_BOARD_CONFIG;
 	const cardsDir = join(dir, CARDS_DIR_NAME);
 	const endedDir = join(dir, ENDED_DIR_NAME);
 	const archiveDir = join(dir, ARCHIVE_DIR_NAME);
@@ -278,11 +324,22 @@ export function createStore(dir: string, options: { root?: string } = {}): Board
 			// The preconditions are checked against the card as it is *now*, and against the
 			// board as it is now, so an operation re-applied to a card that changed is refused
 			// rather than forced.
-			const result = applyOp(card, op, actor, now, indexOf(await list()));
+			const result = applyOp(card, op, actor, now, indexOf(await list()), config);
 			if (!result.ok) return { ok: false, error: result.error, card };
 			if (!result.changed) {
 				return { ok: true, card: result.card, changed: false, dropped: false, archived: false };
 			}
+			// Last look before the write, asked for every path that writes: the card must still be
+			// where it was read and at the revision it had. A writer that landed in between is the
+			// re-read the next pass applies against — and the pile is part of the answer, because
+			// `archive` moves the file without moving its revision, so a write carrying a stale
+			// pile would recreate the card on the board beside its copy in the archive.
+			await options.beforeWrite?.(id, op.kind);
+			const current = await locate(id);
+			if (current === undefined || current.card.rev !== card.rev || current.pile !== pile) {
+				changedUnderneath = true;
+				continue;
+			}
 			if (op.kind === "drop") {
 				// The record lands first: a crash between the two leaves a card that still
 				// exists with a note explaining it, never a card that is gone unexplained.
@@ -299,13 +356,6 @@ export function createStore(dir: string, options: { root?: string } = {}): Board
 				await moveCard(cardsDir, archiveDir, id);
 				return { ok: true, card: result.card, changed: true, dropped: false, archived: true };
 			}
-			// Last look before the rename: a writer that landed in between is the
-			// re-read the next pass applies against.
-			const current = await read(id);
-			if (!current || current.rev !== card.rev) {
-				changedUnderneath = true;
-				continue;
-			}
 			await writeCardFile(pile, id, result.card);
 			return { ok: true, card: result.card, changed: true, dropped: false, archived: false };
 		}
@@ -329,6 +379,8 @@ export function createStore(dir: string, options: { root?: string } = {}): Board
 
 	return {
 		dir,
+		key,
+		config: () => config,
 		ensure,
 		list,
 		scan,
@@ -366,19 +418,23 @@ async function readCardFile(pileDir: string, entry: string): Promise<{ card: Car
 	} catch {
 		return { skip: { file: entry, id, why: "bad JSON" } };
 	}
-	// A version above this build's is the one refusal a reader can act on: the file was
-	// written by a newer build, so the board is not empty, it is not readable here.
+	// A version this build does not read is the one refusal a reader can act on: the file was
+	// written by a newer build, so the board is not empty, it is not readable here. Every
+	// version `readCard` can map is read; the number is named rather than guessed at.
 	const version = typeof parsed === "object" && parsed !== null ? (parsed as { v?: unknown }).v : undefined;
-	if (typeof version === "number" && version !== CARD_VERSION) {
+	if (typeof version === "number" && !SUPPORTED_VERSIONS.some((known) => known === version)) {
 		return { skip: { file: entry, id, why: `version ${version}` } };
 	}
-	if (!isCard(parsed)) return { skip: { file: entry, id, why: "not a card record" } };
+	// The one gate a file read passes: an older spelling of the lane field is read as
+	// this build's, and everything else is a shape this build does not trust.
+	const card = readCard(parsed);
+	if (card === undefined) return { skip: { file: entry, id, why: "not a card record" } };
 	// The file name is the id's canonical spelling: a padded id inside the record
 	// (or a record moved under another name) is a disagreement, not a card.
-	if (parsed.id !== String(Number(match[1]))) {
-		return { skip: { file: entry, id, why: `names card ${parsed.id}` } };
+	if (card.id !== String(Number(match[1]))) {
+		return { skip: { file: entry, id, why: `names card ${card.id}` } };
 	}
-	return { card: parsed };
+	return { card };
 }
 
 /** The highest id a directory holds, or 0 when it holds none. */
@@ -412,10 +468,10 @@ async function nextCardId(cardsDir: string, endedDir: string, archiveDir: string
 async function writeEnded(endedDir: string, card: Card, actor: Actor, now: number): Promise<void> {
 	await mkdir(endedDir, { recursive: true, mode: DIR_MODE });
 	const ended: EndedCard = {
-		v: 1,
+		v: ENDED_VERSION,
 		id: card.id,
 		title: card.title,
-		status: card.status,
+		lane: card.lane,
 		by: actor.label,
 		...(card.owner === undefined ? {} : { owner: card.owner }),
 		at: now,
@@ -472,7 +528,6 @@ async function writeCardFile(dir: string, id: string, card: Card): Promise<void>
 	}
 }
 
-/** One card's bytes, ending in a newline so the file reads well in an editor. */
 /** One record as the bytes a file holds: tab-indented JSON with a closing newline. */
 function serialize(record: Card | EndedCard): string {
 	return `${JSON.stringify(record, null, "\t")}\n`;
@@ -503,21 +558,23 @@ async function readdirSafe(dir: string): Promise<string[]> {
 }
 
 /**
- * Lane order, then the lead's order inside it, then oldest first, with the id as the
- * tie-break.
+ * Lane order, then the lead's order inside it, then the order the cards were added in: the
+ * id, which is allocated once and never reissued.
  *
  * Priority sorts inside a lane rather than beside it: a `high` card in Done is still
  * history, and a lane that mixed the two would have to say so in its head.
+ *
+ * The id carries the age, and `updatedAt` deliberately does not: every write moves that
+ * stamp, so ordering by it makes a note, a claim, or a contract push a card to the end of
+ * its priority and reshuffle the listing a reader was working down.
  */
 function sortForLane(cards: Card[]): Card[] {
-	const lane = (card: Card): number => CARD_STATUSES.indexOf(card.status);
+	const lane = (card: Card): number => LANES.indexOf(card.lane);
 	return cards.sort((a, b) => {
 		const byLane = lane(a) - lane(b);
 		if (byLane !== 0) return byLane;
 		const byPriority = priorityRank(a) - priorityRank(b);
 		if (byPriority !== 0) return byPriority;
-		const byAge = a.updatedAt - b.updatedAt;
-		if (byAge !== 0) return byAge;
 		return Number(a.id) - Number(b.id);
 	});
 }

package/lib/board/tone.ts

@@ -0,0 +1,92 @@
+/**
+ * What tone a lane, a reason, and a Team decision row wear.
+ *
+ * The page and the terminal each decide a colour, and before this table they decided it in
+ * seven places: a lane role in the lane table, a reason class in the browser bundle, two
+ * hand-written `[data-kind]` edge rules, a second `blocked` rule for the queue's why line,
+ * and a transcript that painted every lane the same accent. A tone stated once is the only
+ * version of that which cannot drift.
+ *
+ * A tone is a word the page's kit already names as a property (`var(--warn)`), so the page
+ * wears one directly and needs no map. The terminal speaks its own vocabulary — `ok`, `warn`,
+ * `bad`, `meta`, `faint` — and that bridge lives in `extensions/board/tone.ts`, because only
+ * the transcript speaks it.
+ *
+ * The rule behind the words, so a future kind is not a guess: **warn is a person who must act
+ * next** (approve, review, decide), **danger is a refusal or a loss** (blocked, gone), and
+ * anything merely true of the card — waiting, offered, executing, done, noted — is muted.
+ *
+ * Value-only: no I/O, no clock, no card.
+ */
+
+import type { LaneRole } from "./lanes.ts";
+import type { ReasonKind } from "./reason.ts";
+
+/**
+ * A colour a board surface may wear.
+ *
+ * `dim` joins the lane roles because a Team queue row nobody has to act on yet is quieter
+ * than a muted one: drawn, not emphasised.
+ */
+export type BoardTone = LaneRole | "dim";
+
+/** Every tone, in the order a rule is written for one. */
+export const BOARD_TONES = ["muted", "dim", "warn", "accent", "danger", "success"] as const;
+
+/**
+ * The tone a card's reason line wears, by the kind `reason.ts` reports.
+ *
+ * `waiting` is here even though `reasonFor` never returns it: the page's card face invents it
+ * for a card that names what it waits on (`view/card.ts`), so the table has to answer for it
+ * or that line would draw the default.
+ */
+export const REASON_TONE: Record<ReasonKind, BoardTone> = {
+	waiting: "muted",
+	blocked: "danger",
+	offered: "muted",
+	contract: "warn",
+	approval: "warn",
+	executing: "muted",
+	review: "warn",
+	done: "muted",
+	note: "muted",
+};
+
+/**
+ * The Team queue's decision kinds, in the order a lead reads them.
+ *
+ * One list for both facts a row needs: the position is the rank (a `gone` owner outranks a
+ * card merely sitting still), and {@link DECISION_TONE} is the colour. They were two lists — a
+ * `KIND_RANK` object in the bundle and a hand-written set of `[data-kind]` rules in the
+ * stylesheet — which is how `gone` came to be ranked second and drawn quietest.
+ */
+export const DECISION_KINDS = ["blocked", "gone", "approval", "waiting", "idle", "unplanned", "unassigned"] as const;
+
+/** One reason a card is in the lead's queue. */
+export type DecisionKind = (typeof DECISION_KINDS)[number];
+
+/** The tone a decision row's edge, and a danger row's reason line, wear. */
+export const DECISION_TONE: Record<DecisionKind, BoardTone> = {
+	blocked: "danger",
+	gone: "danger",
+	approval: "warn",
+	waiting: "dim",
+	idle: "warn",
+	unplanned: "dim",
+	unassigned: "dim",
+};
+
+/**
+ * {@link DECISION_KINDS} as the browser bundle's own source.
+ *
+ * The page ranks its queue by this list, and the bundle is a string, so the order travels as
+ * data the way `reasonFor` and `matchesQuery` do: one list in `lib/`, spliced in, never a
+ * second copy in the browser. `test` parses it back to the tuple.
+ */
+export const DECISION_RANK_JS = JSON.stringify(DECISION_KINDS);
+
+/** {@link DECISION_TONE} as the bundle's own source, spliced in like the rank. */
+export const DECISION_TONE_JS = JSON.stringify(DECISION_TONE);
+
+/** {@link REASON_TONE} as the bundle's own source, spliced in like the rank. */
+export const REASON_TONE_JS = JSON.stringify(REASON_TONE);

package/lib/board/view.ts

@@ -15,15 +15,10 @@
  */
 
 import { type RosterSession, type RosterState, rosterStateOf } from "../session-roster.ts";
-import {
-	type Card,
-	CARD_STATUSES,
-	type CardStatus,
-	laneSince,
-	priorityOf,
-	type Priority,
-	signatureOf,
-} from "./card.ts";
+import { type Card, laneSince, priorityOf, type Priority, signatureOf } from "./card.ts";
+import type { Skip } from "./store.ts";
+import { LANE_RULES, LANES, type Lane, type LaneRole } from "./lanes.ts";
+import { DEFAULT_WIP, limitOf, type WipLimits } from "./limits.ts";
 import { blockersOf, indexOf, lanesText, openDependentsOf } from "./links.ts";
 import type { Actor } from "./rules.ts";
 import { buildRound, type RoundSummary } from "./round.ts";
@@ -39,7 +34,7 @@ export interface ViewTeammate {
 	mail: number;
 	/** Whether it is listening for mail; absent means its record does not say so. */
 	listening?: boolean;
-	/** Whether this is the session the page writes as. */
+	/** Whether this is the seat the page is read as. */
 	you: boolean;
 }
 
@@ -55,14 +50,16 @@ export interface ViewCard extends Card {
 	/** The priority it acts on: a card that never set one is ordinary. */
 	priority: Priority;
 	/**
-	 * The unfinished cards it waits for, as `#2 (doing)`; absent when nothing blocks it.
+	 * The unfinished cards it waits for, as `#2 (execute) Patch the gateway`; absent when
+	 * nothing blocks it.
 	 *
 	 * `undefined` is the whole fact — a waiting card is one with a `waits` — because a
 	 * boolean beside it would be one more thing that can disagree with the string.
 	 */
 	waits?: string;
 	/**
-	 * The unfinished cards waiting on it, as `#9 (todo)`; absent when none do.
+	 * The unfinished cards waiting on it, as `#9 (backlog) Ship the picker`; absent when none
+	 * do.
 	 *
 	 * The other side of `waits`: what leaving this card undone holds up. Derived here
 	 * rather than in the page's script for the same reason, and filtered to the unfinished
@@ -80,32 +77,31 @@ export interface ViewCard extends Card {
 	since?: number;
 }
 
-/** One lane and the cards in it, in the order the page draws them. */
+/**
+ * One lane, as the page draws it: the name, the words, the colour, the limit, and the cards.
+ *
+ * The page holds no lane table of its own — it renders this — so a lane's label, its empty
+ * word, and its head's `n/limit` cannot read one way here and another in the transcript.
+ */
 export interface ViewLane {
-	status: CardStatus;
+	key: Lane;
+	/** The word a head, a row, and a sentence print. */
+	label: string;
+	/** What the tray says when it holds nothing. */
+	empty: string;
+	/** The colour role the lane's dot and its card faces take. */
+	role: LaneRole;
+	/** The WIP limit this lane is held to, for the heads that show `n/limit`; absent when it is not pulled. */
+	limit?: number;
+	count: number;
 	cards: ViewCard[];
 }
 
-/** The per-lane tallies the toolbar shows. */
-export interface ViewCounts {
-	total: number;
-	todo: number;
-	doing: number;
-	blocked: number;
-	done: number;
-}
-
 /** Everything the page is allowed to know. */
 export interface BoardView {
-	/**
-	 * The session a page write is made as, and the one the page is read as: its seat.
-	 *
-	 * The page is not a session that happens to be serving — it is a seat that outlives
-	 * whichever session serves it — so the browser is told one identity and no other.
-	 */
-	me: { id?: string; label: string };
 	lanes: ViewLane[];
-	counts: ViewCounts;
+	/** Every card on the board: the sum of the lanes, said once so a head need not add them up. */
+	total: number;
 	round: RoundSummary<ViewCard>;
 	/**
 	 * The sessions on this repository's bus, or absent when there is no bus here.
@@ -119,10 +115,11 @@ export interface BoardView {
 	/**
 	 * Card files the reader refused, so the footer can say the board is not empty.
 	 *
-	 * Zero is the ordinary answer and draws nothing; a count above it is the one fact
-	 * that separates "no work here" from "this build cannot read your work".
+	 * An empty list is the ordinary answer and draws nothing; anything in it is the one fact
+	 * that separates "no work here" from "this build cannot read your work" — and the file
+	 * names and reasons are what let a reader open the file, so the page carries them whole.
 	 */
-	skipped: number;
+	skipped: readonly Skip[];
 	/** Changes when a card's revision, a teammate's state, or its mail does. */
 	sig: string;
 	/** The root's last segment, e.g. `my-pi-agent`: what the tab and the footer lead with. */
@@ -135,13 +132,19 @@ export interface BoardView {
 
 /** What the server read before building one snapshot. */
 export interface ViewInput {
-	/** The page's own actor, which is both who it writes as and who is looking. */
+	/**
+	 * The page's own actor: the seat the snapshot is read as.
+	 *
+	 * The page is not a session that happens to be serving — it is a seat that outlives
+	 * whichever session serves it — so this is the one identity the browser's roster is marked
+	 * against, and the page shows no other.
+	 */
 	me: Actor;
 	cards: readonly Card[];
 	now: number;
 	bytes: number;
 	/** Card files the reader refused; absent reads as none, which is the ordinary board. */
-	skipped?: number;
+	skipped?: readonly Skip[];
 	where: string;
 	/** The repository's name, from `BoardStore.name()`. */
 	repo: string;
@@ -149,6 +152,8 @@ export interface ViewInput {
 	root: string;
 	/** The bus's records, when the page could read them at all. */
 	roster?: readonly RosterSession[];
+	/** The board's WIP limits, so a head can say `n/limit`; absent reads as the defaults. */
+	limits?: WipLimits;
 }
 
 /** Build the page's snapshot. */
@@ -160,25 +165,39 @@ export function buildView(input: ViewInput): BoardView {
 	// card the lane does, so a client reading `round.unassigned` is not handed a card
 	// missing the facts every other card has.
 	const cards = input.cards.map((card) => viewCardOf(card, index));
-	const lanes = CARD_STATUSES.map((status) => ({
-		status,
-		cards: cards.filter((card) => card.status === status),
-	}));
+	const limits = input.limits ?? DEFAULT_WIP;
+	const lanes = LANES.map((key) => {
+		const rule = LANE_RULES[key];
+		const inLane = cards.filter((card) => card.lane === key);
+		const limit = limitOf(key, limits);
+		return {
+			key,
+			label: rule.label,
+			empty: rule.empty,
+			role: rule.role,
+			...(limit === undefined ? {} : { limit }),
+			count: inLane.length,
+			cards: inLane,
+		};
+	});
 	const reader = input.me;
 	const teammates = input.roster === undefined ? undefined : teammatesOf(input.roster, reader.label, input.now);
 	return {
-		me: input.me.id === undefined ? { label: input.me.label } : { id: input.me.id, label: input.me.label },
 		lanes,
-		counts: countOf(lanes),
+		total: cards.length,
 		round: buildRound(cards, input.now),
 		...(teammates === undefined ? {} : { teammates }),
 		bytes: input.bytes,
-		skipped: input.skipped ?? 0,
+		skipped: input.skipped ?? [],
 		// The roster enters the signature at its coarse facts only: a heartbeat every ten
 		// seconds is not news, while a join, a quiet and a letter are. A file that became
-		// readable, or unreadable, is news too: the footer counts it, and a frame that is
-		// not pushed leaves the page saying the board holds less than it does.
-		sig: signatureOf(input.cards) + rosterSignature(teammates) + `|skipped:${input.skipped ?? 0}`,
+		// readable, or unreadable, is news too, and so is a *different* file becoming
+		// unreadable: the footer names them, so the signature carries the names and reasons
+		// rather than a count that a swap would leave unchanged.
+		sig:
+			signatureOf(input.cards) +
+			rosterSignature(teammates) +
+			`|skipped:${(input.skipped ?? []).map((entry) => `${entry.file}:${entry.why}`).join(",")}`,
 		repo: input.repo,
 		root: input.root,
 		where: input.where,
@@ -192,8 +211,11 @@ export function buildView(input: ViewInput): BoardView {
  * derived field written onto one would outlive the read that made it.
  */
 function viewCardOf(card: Card, index: ReadonlyMap<string, Card>): ViewCard {
-	const waits = lanesText(blockersOf(card, index));
-	const dependents = lanesText(openDependentsOf(card.id, index));
+	// The page draws these two as its own lines, and a reader has to know *which* card: the
+	// lane alone is a state, and the title is the card. The transcript asks for no titles —
+	// a refusal is a row, and the sentence is the point there.
+	const waits = lanesText(blockersOf(card, index), { titles: true });
+	const dependents = lanesText(openDependentsOf(card.id, index), { titles: true });
 	const since = laneSince(card);
 	return {
 		...card,
@@ -228,13 +250,3 @@ function rosterSignature(teammates: readonly ViewTeammate[] | undefined): string
 		teammates.map((teammate) => `${teammate.label}:${teammate.state}:${teammate.mail}:${teammate.listening}`).join(",")
 	);
 }
-
-/** The tallies, summed from the lanes so the two can never disagree. */
-function countOf(lanes: readonly ViewLane[]): ViewCounts {
-	const counts: ViewCounts = { total: 0, todo: 0, doing: 0, blocked: 0, done: 0 };
-	for (const lane of lanes) {
-		counts[lane.status] = lane.cards.length;
-		counts.total += lane.cards.length;
-	}
-	return counts;
-}

package/{extensions/watch → lib}/child.ts

@@ -1,23 +1,32 @@
 /**
- * A command watcher's process lifecycle: spawn, tree-kill, escalate, and drain.
+ * A spawned command's lifecycle: spawn, tree-kill, escalate, and drain.
  *
- * A command source is a spawned process whose merged stdout and stderr feed the
- * matcher. This module owns the process side only — the spawn, the SIGTERM →
- * SIGKILL grace, and the shutdown drain — over the injected `SpawnFn` and
- * `KillTreeFn` seams, so the runtime keeps the watcher's status, its repaint,
- * and its clock.
+ * A `job` or a `watch` command source is a process whose merged stdout and
+ * stderr feed its owner. This module owns the process side only — the spawn, the
+ * SIGTERM → SIGKILL grace, and the shutdown drain — over the injected `SpawnFn`
+ * and `KillTreeFn` seams, so each owner keeps its own status, repaint, and clock.
+ * The escalation has one body and one default (`KILL_GRACE_MS`); each owner passes
+ * its configured grace, so `job` escalates at its `killGraceMs` and `watch` at its
+ * own, and neither re-implements the SIGTERM → SIGKILL step.
  *
  * Value-only: the child handle and its escalation timer live on the caller's
  * slot, never here, because Pi loads each extension with its own module cache.
  */
 
-import { defaultKillTree, defaultSpawn, type KillTreeFn, type SpawnFn, type SpawnedProcess } from "../../lib/spawn.ts";
+import {
+	defaultKillTree,
+	defaultSpawn,
+	type KillTreeFn,
+	type SpawnFn,
+	type SpawnedProcess,
+	type SpawnOptions,
+} from "./spawn.ts";
 
 /** Grace period before a stopped command is escalated to SIGKILL. */
 export const KILL_GRACE_MS = 2000;
 
 /**
- * The process fields a watcher record carries. The supervisor mutates them in
+ * The process fields a caller's record carries. The supervisor mutates them in
  * place, so the runtime's record and the module's handle cannot disagree about
  * whether a child is still live.
  */
@@ -27,7 +36,7 @@ export interface ChildSlot {
 	killTimer?: ReturnType<typeof setTimeout>;
 }
 
-/** How a child settled, for the sink that owns the watcher's status transition. */
+/** How a child settled, for the sink that owns the caller's status transition. */
 export type ChildOutcome =
 	| { kind: "closed"; code: number | null; signal: string | null }
 	| { kind: "failed"; message: string };
@@ -37,7 +46,7 @@ export interface ChildSink {
 	onData(chunk: Buffer): void;
 	/**
 	 * The child closed or failed to spawn. The sink owns the status, because only
-	 * it knows whether the watcher was still running when that happened.
+	 * it knows whether the job or watcher was still running when that happened.
 	 */
 	onSettled(outcome: ChildOutcome): void;
 }
@@ -50,12 +59,19 @@ export interface ChildSupervisorOptions {
 }
 
 export interface ChildSupervisor {
-	/** Spawn `command`, or return the spawn error and leave the slot's child unset. */
-	start(slot: ChildSlot, command: string, cwd: string, sink: ChildSink): string | undefined;
-	/** SIGTERM a command, escalating to SIGKILL when it has not closed in time. */
-	terminate(slot: ChildSlot): void;
-	/** Kill immediately, without arming an escalation. */
-	kill(slot: ChildSlot, signal: "SIGTERM" | "SIGKILL"): void;
+	/**
+	 * Spawn `command` with the caller's options, or return the spawn error and
+	 * leave the slot's child unset. The child is readable as `slot.child`.
+	 */
+	start(slot: ChildSlot, command: string, options: SpawnOptions, sink: ChildSink): string | undefined;
+	/**
+	 * Send `signal` (SIGTERM by default) and escalate to SIGKILL when the command
+	 * has not closed within the grace. A SIGKILL was already final, so it is not
+	 * escalated.
+	 */
+	terminate(slot: ChildSlot, signal?: NodeJS.Signals): void;
+	/** Signal now, without arming an escalation. */
+	kill(slot: ChildSlot, signal: NodeJS.Signals): void;
 	/** Cancel a pending escalation. */
 	clearTimer(slot: ChildSlot): void;
 	/** Resolve when every slot's child has closed, or after `ms`, whichever comes first. */
@@ -74,7 +90,7 @@ export function createChildSupervisor(options: ChildSupervisorOptions = {}): Chi
 		}
 	};
 
-	const kill = (slot: ChildSlot, signal: "SIGTERM" | "SIGKILL"): void => {
+	const kill = (slot: ChildSlot, signal: NodeJS.Signals): void => {
 		const pid = slot.pid;
 		try {
 			if (pid !== undefined) killTree(pid, signal, signal === "SIGKILL");
@@ -84,9 +100,12 @@ export function createChildSupervisor(options: ChildSupervisorOptions = {}): Chi
 		}
 	};
 
-	const terminate = (slot: ChildSlot): void => {
+	const terminate = (slot: ChildSlot, signal: NodeJS.Signals = "SIGTERM"): void => {
 		clearTimer(slot);
-		kill(slot, "SIGTERM");
+		kill(slot, signal);
+		// A SIGKILL is already final: arming an escalation behind it would only fire against
+		// a slot that is about to be cleared, and the doc above says it does not.
+		if (signal === "SIGKILL") return;
 		if (slot.pid === undefined && !slot.child) return;
 		slot.killTimer = setTimeout(() => {
 			slot.killTimer = undefined;
@@ -95,10 +114,10 @@ export function createChildSupervisor(options: ChildSupervisorOptions = {}): Chi
 		slot.killTimer.unref?.();
 	};
 
-	const start = (slot: ChildSlot, command: string, cwd: string, sink: ChildSink): string | undefined => {
+	const start = (slot: ChildSlot, command: string, options: SpawnOptions, sink: ChildSink): string | undefined => {
 		let child: SpawnedProcess;
 		try {
-			child = spawnFn(command, { cwd });
+			child = spawnFn(command, options);
 		} catch (error) {
 			return error instanceof Error ? error.message : String(error);
 		}