pi-crew 0.11.24 → 0.11.26

package/src/prompt/surface-worker.ts

@@ -121,6 +121,40 @@ export function shouldAutoExit(signals: AutoExitSignals): boolean {
 
 // ── parent liveness ───────────────────────────────────────────────────────
 
+/**
+ * Default `/proc/<pid>/stat` reader for {@link parentAlive}.
+ *
+ * R19-M1 (deep-review round 19): the R7-P1 tolerance (a THROWING reader with no
+ * recorded start time ⇒ alive-with-caveat) was UNREACHABLE in production because
+ * the default reader caught its own error and returned `undefined` — which
+ * `parentAlive` reads as “no entry ⇒ parent is dead”. On macOS (no procfs) every
+ * healthy surface worker therefore self-terminated at the first 5 s guard tick
+ * (`terminate("worker.parent-lost")`), and the R7-P1 pin only held for injected
+ * readers.
+ *
+ * The platform distinction is the whole point:
+ *   - Linux with procfs: ENOENT is the DEAD signal (unchanged — keeps Linux
+ *     dead-pid detection exact); any other errno (EACCES/EPERM) is “unreadable”
+ *     and is surfaced as a throw so the tolerance applies.
+ *   - No procfs (macOS / Windows / a Linux container without /proc): the file can
+ *     never exist, so “cannot read” must NOT be reported as “dead”. Throw —
+ *     `parentAlive` then keeps the worker alive and the host watchdog is the
+ *     backstop (a false “alive” is recoverable; a false “dead” kills work).
+ *
+ * `platform` is injectable so the macOS path is testable on every CI OS.
+ */
+export function defaultProcStatReader(pid: number, platform: string = process.platform): string | undefined {
+	if (platform !== "linux" || !fs.existsSync("/proc/self/stat")) {
+		throw new Error(`procfs unavailable on ${platform}: cannot read /proc/${pid}/stat`);
+	}
+	try {
+		return fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
 /**
  * Pure parent-liveness decision.
  *   - stat unreadable → parent is GONE (/proc ENOENT means dead on Linux).
@@ -132,15 +166,7 @@ export function shouldAutoExit(signals: AutoExitSignals): boolean {
  */
 export function parentAlive(pid: number, expectedStartTime: string | undefined, readStat?: (pid: number) => string | undefined): boolean {
 	if (!Number.isFinite(pid) || pid <= 0) return false;
-	const reader =
-		readStat ??
-		((p: number): string | undefined => {
-			try {
-				return fs.readFileSync(`/proc/${p}/stat`, "utf8");
-			} catch {
-				return undefined;
-			}
-		});
+	const reader = readStat ?? ((p: number): string | undefined => defaultProcStatReader(p));
 	let stat: string | undefined;
 	let readerThrew = false;
 	try {

package/src/runtime/broker/crew-broker.ts

@@ -39,7 +39,6 @@
 import { randomUUID } from "node:crypto";
 import * as fsp from "node:fs/promises";
 import * as net from "node:net";
-import { withRunLockSync } from "../../state/coordination/locks.ts";
 import {
 	appendMailboxMessageAsync,
 	appendMailboxMessageIdempotentAsync,
@@ -60,7 +59,9 @@ import { resolveCrewMaxDepth } from "../model/pi-args.ts";
 import { NestedSlotBudget } from "../scheduling/nested-slots.ts";
 import { evaluateDelegateAdmission } from "../spawn-policy.ts";
 import { type BrokerToken, BrokerTokenRegistry } from "./crew-broker-tokens.ts";
+import { DelegateAbortRegistry } from "./delegate/delegate-abort.ts";
 import { type DelegateEventTarget, type DelegateEventType, recordDelegateEvent } from "./delegate/delegate-event.ts";
+import { delegateTerminalEvent, finalizeDelegateResult } from "./delegate/delegate-finalize.ts";
 import { promoteShadowToRunning } from "./delegate/shadow-lifecycle.ts";
 import { fanoutMailboxMessage } from "./mailbox-observer/mailbox-fanout.ts";
 import type { CrewBrokerOptions, ServerConnection } from "./protocol/connection-state.ts";
@@ -155,6 +156,9 @@ export class CrewBroker {
 	/** T3/R5 (ADR-5 §2): nested-slot budget for delegate grandchildren — lazily
 	 *  sized from options (max(1, floor(globalWorkerSemaphore/2)) or override). */
 	private nestedSlots: NestedSlotBudget | undefined;
+	/** M3-5/R43-N3: abort controllers for in-flight delegate grandchildren —
+	 *  aborted on run terminalise (abortDelegatesForRun) and on stop(). */
+	private readonly delegateAborts = new DelegateAbortRegistry();
 	/** A single observable handshake counter (test/observability). */
 	private handshakeCount = 0;
 	/** R10-3: stat-gated manifest/tasks cache shared by all task.waitStatus
@@ -244,6 +248,30 @@ export class CrewBroker {
 		}
 	}
 
+	/** M3-5 / R43-N3: cancel every in-flight DELEGATE GRANDCHILD of `runId`.
+	 *  Called from the run-terminal paths (budget abort / cancellation via
+	 *  budget-enforcement.ts → abortRunDelegates) and from stop(). Before this
+	 *  existed the spawner was fire-and-forget: a budget abort left grandchildren
+	 *  running to their own deadline (up to 24h), still spending and still
+	 *  holding nested slots. Returns the number cancelled; idempotent. */
+	abortDelegatesForRun(runId: string, reason = "run-terminal"): number {
+		if (typeof runId !== "string" || runId.length === 0) return 0;
+		const aborted = this.delegateAborts.abortRun(runId, { reason });
+		if (aborted > 0) {
+			logInternalError(
+				"crew-broker.delegate.abort-run",
+				new Error(`${aborted} delegate grandchild(ren) cancelled`),
+				`runId=${runId} reason=${reason}`,
+			);
+		}
+		return aborted;
+	}
+
+	/** Number of in-flight delegate grandchildren (diagnostics / tests). */
+	get inFlightDelegateCount(): number {
+		return this.delegateAborts.size;
+	}
+
 	/** Issue the orchestrator token for `runId` (F-06). Cryptographically
 	 *  distinct from every per-task token — the ONLY token that grants
 	 *  role:'orchestrator' (required for steer.push / msg.send). */
@@ -363,6 +391,9 @@ export class CrewBroker {
 	async stop(): Promise<void> {
 		if (this.stopped) return;
 		this.stopped = true;
+		// M3-5/R43-N3: cancel every in-flight grandchild FIRST — broker teardown
+		// must not leave delegate spawns running to their own 24h deadline.
+		this.delegateAborts.abortAll({ reason: "broker-stop" });
 		// Phase 1.3: unregister the mailbox observer before closing connections.
 		if (this.mailboxObserverUnsub) {
 			try {
@@ -1527,6 +1558,18 @@ export class CrewBroker {
 				// ADR-5 §12: the delegate surface is an escalation — trusted only by the
 				// explicit user opt-in threaded from config.nesting.enabled (sensitive).
 				untrusted: this.options.nestingTrustedEscalation !== true,
+				// M3-3 / R43-N1 SEED: the run-level token budget is the grant every
+				// task inherits when its own record carries no allocation (pre-fix
+				// state of EVERY task — nothing produced `tokensGranted`, so every
+				// budgeted delegate was denied and every unmetered one slipped by).
+				// `budgetUnlimited` opts out of enforcement entirely ⇒ no seed.
+				...(fresh.manifest.budgetTotal !== undefined && fresh.manifest.budgetUnlimited !== true
+					? { parentBudgetGrantTokens: fresh.manifest.budgetTotal }
+					: {}),
+				// M3-3 / R43-N1: unmetered delegation stays available (documented
+				// pre-fix behavior for nesting runs without a budgetTotal) but is now
+				// an EXPLICIT, audited allow (`unmetered: true` on delegate.admitted).
+				unmeteredDelegates: "allow",
 				workspace: {
 					serializeEnabled: this.options.serializeOnPathOverlap === true,
 					overlappingInFlightExecutors: overlapping,
@@ -1549,20 +1592,25 @@ export class CrewBroker {
 				};
 			}
 			// Reserve the requested budget pessimistically (ADR-5 §5): tokensSpent
-			// += budgetTokens now; the completion roll-up reconciles to actual usage
-			// (refund the difference). Single writer under the run lock.
+			// += budgetTokens now. M3-3/R43-N1: the reservation ALSO seeds the parent
+			// allocation when the record has none — the `decision.budget.grantedTokens`
+			// the gate admitted against is the write-once `tokensGranted`
+			// (state-helpers.ts merge keeps disk's value verbatim). Pre-fix the
+			// `parentAllocation` guard silently skipped the reserve for every task
+			// that had no allocation, i.e. for every task.
+			// M3-4/R44-N4: this reservation IS the spend — no settle-time refund.
 			let reserved = 0;
-			const parentAllocation = task.allocation;
+			const budgetDecision = decision.budget;
 			let tasksAfterReserve = fresh.tasks;
-			if (requested.budgetTokens !== undefined && parentAllocation) {
-				reserved = requested.budgetTokens;
+			if (budgetDecision?.metered === true) {
+				reserved = budgetDecision.requestedTokens ?? 0;
 				const updatedTasks = fresh.tasks.map((t) =>
 					t.id === parentTaskId
 						? {
 								...t,
 								allocation: {
-									tokensGranted: parentAllocation.tokensGranted,
-									tokensSpent: (parentAllocation.tokensSpent ?? 0) + reserved,
+									tokensGranted: budgetDecision.grantedTokens,
+									tokensSpent: budgetDecision.spentTokens + reserved,
 								},
 							}
 						: t,
@@ -1589,7 +1637,7 @@ export class CrewBroker {
 				} satisfies TeamTaskState,
 			]);
 			// RR-023 F3: thread the parent's model out of the locked read (gc fallback).
-			return { code: "ok" as const, decision, reserved, executionCwd, parentModel: task.model };
+			return { code: "ok" as const, decision, reserved, executionCwd, parentModel: task.model, parentRole: task.role };
 		});
 		// RR-023 F4 (finding #4): run.lock held by a live cross-process holder —
 		// degrade to a typed busy frame AND a delegate.rejected event (never
@@ -1604,11 +1652,13 @@ export class CrewBroker {
 			this.sendError(conn, id, admissionOutcome.code, admissionOutcome.message);
 			return;
 		}
-		const { decision, reserved, executionCwd, parentModel } = admissionOutcome;
+		const { decision, reserved, executionCwd, parentModel, parentRole } = admissionOutcome;
 		this.recordDelegateEvent(loaded.manifest, "delegate.admitted", parentTaskId, {
 			subId,
 			childDepth: decision.childDepth,
 			role: requested.role ?? "explorer",
+			// M3-3/R43-N1: an unmetered allow is EXPLICIT in the audit trail.
+			...(decision.budget?.metered === false ? { unmetered: true } : {}),
 			...(reserved > 0 ? { reservedTokens: reserved } : {}),
 		});
 		// S1#1: pre-mint the grandchild-scoped token when (and only when) the
@@ -1623,6 +1673,10 @@ export class CrewBroker {
 		// RR-023 F3 (finding #3, run team_20260929041427): model-less gc spawn fell
 		// through to the pi GLOBAL default — inherit the parent task's model.
 		const gcModel = requested.model ?? parentModel;
+		// M3-5/R43-N3: register the grandchild's abort controller BEFORE the
+		// spawn starts, so a run terminalise / budget abort / broker stop that
+		// lands mid-spawn still cancels it (no orphan outliving the run).
+		const delegateAbort = this.delegateAborts.register(subId, runId);
 		// Background grandchild lifecycle (ADR-5 §1/§6).
 		const spawner = this.options.grandchildSpawner ?? spawnDelegateGrandchild;
 		void (async () => {
@@ -1632,6 +1686,9 @@ export class CrewBroker {
 					cwd: executionCwd,
 					runId,
 					parentTaskId,
+					// R43-S1: transitive tier containment — the spawner applies
+					// min(parentRole, requestedRole) as the grandchild tool policy.
+					parentRole,
 					subId,
 					prompt: requested.prompt,
 					eventsPath: loaded.manifest.eventsPath,
@@ -1641,6 +1698,8 @@ export class CrewBroker {
 					...(requested.maxTurns !== undefined ? { maxTurns: requested.maxTurns } : {}),
 					timeoutSec: decision.timeoutSec ?? 900,
 					depthOverride: decision.childDepth ?? 2,
+					// M3-5/R43-N3: owner cancellation (registry-driven).
+					signal: delegateAbort.signal,
 					// RR-012 F16: promote shadow queued→running once the process exists.
 					onSpawn: (pid) => {
 						if (pid !== null) promoteShadowToRunning(cwd, runId, subId);
@@ -1649,110 +1708,32 @@ export class CrewBroker {
 			} catch (err) {
 				outcome = { ok: false, resultText: `delegate spawn failed: ${(err as Error).message}` };
 			}
-			// S3 fence hardening: neutralize smuggled end-fence markers in the
-			// grandchild's raw text, then wrap (the client re-fences too — the
-			// mailbox is an unauthenticated same-uid channel by design).
-			const sanitizedText = outcome.resultText.replace(/^--- (end )?delegate /gm, "-- ~delegate ").slice(0, 65_536);
-			const fenced = `--- delegate ${subId} ${outcome.timedOut ? "(timed out)" : outcome.ok ? "(ok)" : "(failed)"} ---\n${sanitizedText}\n--- end delegate ${subId} ---`;
-			// Durable delivery (ADR-5 §1): fenced result into the PARENT task's
-			// mailbox + budget roll-up + slot release — run-locked RMW.
 			try {
-				const fresh = loadRunManifestById(cwd, runId);
-				if (fresh) {
-					withRunLockSync(fresh.manifest, () => {
-						const latest = loadRunManifestById(cwd, runId);
-						if (!latest) return;
-						void appendMailboxMessageAsync(latest.manifest, {
-							direction: "inbox",
-							from: `delegate:${subId}`,
-							to: parentTaskId,
-							taskId: parentTaskId,
-							body: fenced,
-							kind: "response",
-							data: { subId, ok: outcome.ok, timedOut: outcome.timedOut === true },
-						}).catch((err) =>
-							logInternalError(
-								"crew-broker.delegate.mailbox",
-								err instanceof Error ? err : new Error(String(err)),
-								`runId=${runId}`,
-							),
-						);
-						// Roll-up (ADR-5 §5): reconcile the pessimistic reservation to
-						// actual usage; refund the difference. Unattributed → keep reserve.
-						let tasksToWrite = latest.tasks;
-						if (reserved > 0) {
-							const parent = latest.tasks.find((t) => t.id === parentTaskId);
-							const parentAlloc = parent?.allocation;
-							if (parentAlloc) {
-								const actual = Math.max(0, Math.min(outcome.usageTokens ?? reserved, reserved));
-								const tokensSpent = (parentAlloc.tokensSpent ?? 0) - reserved + actual;
-								tasksToWrite = tasksToWrite.map((t) =>
-									t.id === parentTaskId
-										? { ...t, allocation: { tokensGranted: parentAlloc.tokensGranted, tokensSpent } }
-										: t,
-								);
-								this.recordDelegateEvent(latest.manifest, "delegate.rolled_up", parentTaskId, {
-									subId,
-									actualTokens: actual,
-								});
-							}
-						}
-						// S1#1 (verifier N1): the terminal flip is UNCONDITIONAL — never depends
-						// on a reservation. RR-012 F16: onSpawn promotes the record to "running"
-						// during execution; this flip terminalizes every settle path.
-						saveRunTasks(
-							latest.manifest,
-							tasksToWrite.map((t) =>
-								t.id === subId
-									? {
-											...t,
-											status: outcome.ok ? ("completed" as const) : ("failed" as const),
-											completedAt: new Date().toISOString(),
-										}
-									: t,
-							),
-						);
-					});
-				}
-			} catch (err) {
-				logInternalError("crew-broker.delegate.finalize", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`);
-				// P2-8c: best-effort refund when finalize fails — the reservation
-				// must not linger inflated after a roll-up write failure.
-				if (reserved > 0) {
-					try {
-						const rf = loadRunManifestById(cwd, runId);
-						if (rf) {
-							withRunLockSync(rf.manifest, () => {
-								const rl = loadRunManifestById(cwd, runId);
-								if (!rl) return;
-								const par = rl.tasks.find((t) => t.id === parentTaskId);
-								const pa = par?.allocation;
-								if (pa) {
-									saveRunTasks(
-										rl.manifest,
-										rl.tasks.map((t) =>
-											t.id === parentTaskId
-												? {
-														...t,
-														allocation: {
-															tokensGranted: pa.tokensGranted,
-															tokensSpent: Math.max(0, (pa.tokensSpent ?? 0) - reserved),
-														},
-													}
-												: t,
-										),
-									);
-								}
-							});
-						}
-					} catch {
-						/* refund is best-effort; the startup reconcile is the follow-up */
-					}
-				}
+				// S3 fence hardening: neutralize smuggled end-fence markers in the
+				// grandchild's raw text, then wrap (the client re-fences too — the
+				// mailbox is an unauthenticated same-uid channel by design).
+				const sanitizedText = outcome.resultText.replace(/^--- (end )?delegate /gm, "-- ~delegate ").slice(0, 65_536);
+				const statusTag = outcome.cancelled ? "(cancelled)" : outcome.timedOut ? "(timed out)" : outcome.ok ? "(ok)" : "(failed)";
+				const fenced = `--- delegate ${subId} ${statusTag} ---\n${sanitizedText}\n--- end delegate ${subId} ---`;
+				// Durable delivery + budget charge + shadow terminal flip — all
+				// inside one run lock, off a fresh disk read (delegate-finalize.ts
+				// owns the R43-N4 reroute and the R44-N4 broker-side charge).
+				finalizeDelegateResult({
+					brokerCwd: cwd,
+					runId,
+					parentTaskId,
+					subId,
+					fenced,
+					ok: outcome.ok,
+					...(outcome.timedOut !== undefined ? { timedOut: outcome.timedOut } : {}),
+					reservedTokens: reserved,
+					...(outcome.usageTokens !== undefined ? { selfReportedTokens: outcome.usageTokens } : {}),
+				});
 			} finally {
+				this.delegateAborts.release(subId);
 				this.nestedSlotBudget().release(subId);
 			}
-			this.recordDelegateEvent(loaded.manifest, outcome.timedOut ? "delegate.timed_out" : "delegate.completed", parentTaskId, {
+			this.recordDelegateEvent(loaded.manifest, delegateTerminalEvent(outcome), parentTaskId, {
 				subId,
 				ok: outcome.ok,
 			});
@@ -1853,10 +1834,31 @@ export class CrewBroker {
 						}
 					: t,
 			);
+			// M4-R1(a) (fix-wave 6 residual, M3-C): `waitState` is a SINGLE
+			// run-level slot and `isWaitAnswerPending` (stale-reconciler) reads
+			// ONLY it — that slot is the shield keeping a parked (deliberately
+			// non-heartbeating) worker from being stale-reaped / orphan-cancelled.
+			// Overwriting it unconditionally with the NEWER park SHORTENED the
+			// shield whenever the new park asked for a shorter timeout (the
+			// clamp allows 1s..1h), so an older, longer park could lose its
+			// protection while still awaiting an answer. Same invariant as
+			// wait.resolve's repointedWaitState: the slot follows the park with
+			// the LATEST deadline — a park never shortens a live shield (living
+			// slightly long only delays repair, the fail-safe direction).
+			const currentSlot = fresh.manifest.waitState;
+			const currentOwner = currentSlot === undefined ? undefined : fresh.tasks.find((t) => t.id === currentSlot.taskId);
+			const keepCurrentSlot =
+				currentSlot !== undefined &&
+				typeof currentSlot.deadline === "number" &&
+				currentSlot.deadline > deadline &&
+				currentSlot.taskId !== taskId &&
+				currentOwner?.status === "waiting" &&
+				currentOwner.waiting?.questionId === currentSlot.questionId;
 			const updatedManifest = {
 				...fresh.manifest,
 				// manifest.status stays "running" — park NEVER flips run status (ADR item 3).
-				waitState: { taskId, questionId, askedAt, deadline }, // R2-M-A2: mirror task.waiting.deadline for shield expiry
+				// R2-M-A2: mirror task.waiting.deadline for shield expiry.
+				waitState: keepCurrentSlot ? currentSlot : { taskId, questionId, askedAt, deadline },
 				updatedAt: askedAt,
 			};
 			saveRunTasks(updatedManifest, updatedTasks);

package/src/runtime/broker/delegate/delegate-abort.ts

@@ -0,0 +1,118 @@
+/**
+ * delegate-abort.ts — in-flight grandchild cancellation (M3-5 / R43-N3).
+ *
+ * R43-N3 (2026-10-18 round 43, fix-wave 6): the `delegate.request` handler
+ * spawned the grandchild inside a detached `void (async () => …)()` with NO
+ * abort path — `CrewBroker.stop()` only cleared its token maps, and the
+ * team-runner's terminalise path drained its OWN dispatch units only. So a
+ * budget abort / run cancel / broker teardown left grandchildren running with
+ * a 900s-…-86400s deadline of their own, still burning tokens and still
+ * holding nested slots (R43-N3: "orphans keep spending up to 24h").
+ *
+ * This module is the missing link: the broker registers one AbortController
+ * per live grandchild, the spawner subscribes to it (delegate-spawn.ts
+ * `signal`), and every terminal path aborts them.
+ *
+ * Two process-local wiring layers:
+ *  1. {@link DelegateAbortRegistry} — owned by the broker instance (one per
+ *     root session), keyed by grandchild subId.
+ *  2. {@link setActiveDelegateAborter} / {@link abortRunDelegates} — the
+ *     process-local singleton the runner side calls without holding a broker
+ *     reference (mirrors `broker-issuer.ts`'s issuer/revoker registry: a
+ *     function reference only, never a token).
+ */
+
+export interface DelegateAbortReason {
+	/** Machine-readable cause, recorded on the `delegate.cancelled` event. */
+	reason: string;
+}
+
+/**
+ * Per-broker registry of live grandchild abort controllers.
+ *
+ * Invariants:
+ *  - `register` is called BEFORE the spawner starts (so a terminal event that
+ *    lands during the spawn still cancels it);
+ *  - `release` is called from the settle `finally` — a settled delegate never
+ *    lingers in the map (bounded memory, no double-abort of a reused subId —
+ *    subIds are UUIDs, so reuse is impossible anyway);
+ *  - `abortAll` is idempotent (AbortController.abort() is idempotent).
+ */
+export class DelegateAbortRegistry {
+	private readonly controllers = new Map<string, { runId: string; controller: AbortController }>();
+
+	/** Number of in-flight grandchildren (diagnostics / tests). */
+	get size(): number {
+		return this.controllers.size;
+	}
+
+	/** Register a controller for `subId` (owned by `runId`) for the spawner. */
+	register(subId: string, runId: string): AbortController {
+		const controller = new AbortController();
+		this.controllers.set(subId, { runId, controller });
+		return controller;
+	}
+
+	/** Drop the controller (settle path). Never aborts. */
+	release(subId: string): void {
+		this.controllers.delete(subId);
+	}
+
+	/** Abort every in-flight grandchild of ONE run. Returns the count aborted. */
+	abortRun(runId: string, reason: DelegateAbortReason): number {
+		return this.abortWhere((entry) => entry.runId === runId, reason);
+	}
+
+	/** Abort every in-flight grandchild (broker teardown). Returns the count. */
+	abortAll(reason: DelegateAbortReason): number {
+		return this.abortWhere(() => true, reason);
+	}
+
+	private abortWhere(predicate: (entry: { runId: string }) => boolean, reason: DelegateAbortReason): number {
+		const victims = [...this.controllers.entries()].filter(([, entry]) => predicate(entry));
+		for (const [subId, entry] of victims) {
+			// The reason rides the signal so the spawner can tell an owner abort
+			// (R43-N3 cancellation) from its own deadline timeout.
+			entry.controller.abort(new Error(reason.reason));
+			this.controllers.delete(subId);
+		}
+		return victims.length;
+	}
+}
+
+/**
+ * Process-local aborter: `runId` — abort every in-flight grandchild of that
+ * run. A run-scoped signature (not global) keeps a multi-run root session from
+ * killing another run's grandchildren; the registry itself is per broker but
+ * tracks runId per entry via the closure the lifecycle controller installs.
+ */
+export type DelegateAborter = (runId: string, reason: string) => number;
+
+let activeAborter: DelegateAborter | undefined;
+
+/** Register the active aborter (called by the broker lifecycle controller). */
+export function setActiveDelegateAborter(aborter: DelegateAborter | undefined): void {
+	activeAborter = aborter;
+}
+
+/** Read the active aborter, if any (undefined = no broker wired). */
+export function getActiveDelegateAborter(): DelegateAborter | undefined {
+	return activeAborter;
+}
+
+/**
+ * Abort in-flight grandchildren of `runId` through the active broker.
+ *
+ * Returns the number aborted (0 when no broker is wired — e.g. a headless
+ * runner without a root session). Never throws: this is called from terminal /
+ * abort paths that must not fail on a broker hiccup.
+ */
+export function abortRunDelegates(runId: string, reason: string): number {
+	const aborter = activeAborter;
+	if (!aborter) return 0;
+	try {
+		return aborter(runId, reason);
+	} catch {
+		return 0;
+	}
+}

package/src/runtime/broker/delegate/delegate-event.ts

@@ -19,7 +19,9 @@ export type DelegateEventType =
 	| "delegate.rejected"
 	| "delegate.completed"
 	| "delegate.timed_out"
-	| "delegate.rolled_up";
+	| "delegate.cancelled"
+	| "delegate.rolled_up"
+	| "delegate.rerouted";
 
 export type DelegateEventTarget = { eventsPath: string; runId: string };