pi-crew 0.10.2 → 0.10.4

package/src/prompt/worker-events-channel.ts

@@ -26,7 +26,7 @@
  * informational only — the scheduler never derives liveness from them.
  */
 
-import { appendFileSync, readFileSync } from "node:fs";
+import { appendFileSync, closeSync, fstatSync, openSync, readSync } from "node:fs";
 
 export const WORKER_EVENT_TYPE_PATTERN = /^worker\.[a-z0-9_.-]{1,63}$/;
 
@@ -46,6 +46,8 @@ export interface WorkerEventsChannelOptions {
 export interface WorkerEventsChannel {
 	/** Emit a worker.* event. false = dropped (schema/rate/buffer reasons). */
 	emit(type: string, data: Record<string, unknown>): boolean;
+	/** Emit a terminal worker.* event (bypasses rate-limit; schema/buffer still apply). */
+	emitTerminal(type: string, data: Record<string, unknown>): boolean;
 	/** Retry queued appends (called on the next emit internally). */
 	flush(): void;
 	/** Test introspection. */
@@ -67,8 +69,21 @@ export function createWorkerEventsChannel(options: WorkerEventsChannelOptions =
 			// which the orchestrator reader skips).
 			let prefix = "";
 			try {
-				const buf = readFileSync(eventsPath);
-				if (buf.length > 0 && buf[buf.length - 1] !== 0x0a) prefix = "\n";
+				// PERF (2026-08-24): 1-byte tail read (the comment above always
+				// described this; the implementation used to readFileSync the
+				// WHOLE file — O(file) reads up to 300x/min per worker for a
+				// single byte of information).
+				const fd = openSync(eventsPath, "r");
+				try {
+					const size = fstatSync(fd).size;
+					if (size > 0) {
+						const tail = Buffer.alloc(1);
+						readSync(fd, tail, 0, 1, size - 1);
+						if (tail[0] !== 0x0a) prefix = "\n";
+					}
+				} finally {
+					closeSync(fd);
+				}
 			} catch {
 				/* absent file — nothing to separate */
 			}
@@ -163,6 +178,37 @@ export function createWorkerEventsChannel(options: WorkerEventsChannelOptions =
 			suppressedSinceLast = 0;
 			return true;
 		},
+		emitTerminal(type: string, data: Record<string, unknown>): boolean {
+			if (!eventsPath || !runId) return false; // non-team context — no-op
+			if (!WORKER_EVENT_TYPE_PATTERN.test(type)) {
+				counters.droppedSchema++;
+				return false;
+			}
+			// NO sliding-window rate limit — terminal events bypass.
+			// Drain any queued items first (FIFO — oldest first), then the new one.
+			if (pending.length > 0) {
+				const carry = flushInternal(0);
+				if (carry > 0) {
+					// Writer failing: queue the new item under the FIFO cap.
+					if (pending.length >= bufferCap) {
+						pending.shift();
+						counters.droppedBuffer++;
+					}
+					pending.push({ type, data, droppedSinceLast: 0 });
+					return true; // accepted (queued)
+				}
+			}
+			if (write({ type, data, droppedSinceLast: 0 })) {
+				counters.accepted++;
+				return true;
+			}
+			if (pending.length >= bufferCap) {
+				pending.shift();
+				counters.droppedBuffer++;
+			}
+			pending.push({ type, data, droppedSinceLast: 0 });
+			return true;
+		},
 		flush(): void {
 			flushInternal(0);
 		},

package/src/runtime/async-runner.ts

@@ -226,8 +226,36 @@ export const BACKGROUND_RUNNER_ENV_ALLOWLIST: string[] = [
 	// Phase 1.5 #3: V8 diagnostic report on fatal error (RFC 17 — investigation).
 	"PI_CREW_BG_REPORT_ON_FATAL",
 	"PI_TEAMS_BG_REPORT_ON_FATAL",
+	// MuxSurface: multiplexer env the detached runner needs to DETECT and
+	// REACH the host's tmux/herdr — surface follows env + config for async runs
+	// too (2026-08-30 Finding 2: without these, every async run gates to no-mux
+	// and stays headless). None of these are secret-named (sanitizeEnvSecrets
+	// would reject them from the allowlist otherwise).
+	"TMUX",
+	"TMUX_PANE",
+	"TMUX_TMPDIR",
+	"HERDR_ENV",
+	"HERDR_SESSION",
+	"HERDR_PANE_ID",
+	"HERDR_SOCKET_PATH",
+	"HERDR_WORKSPACE_ID",
+	"HERDR_PING_TIMEOUT_MS",
 ];
 
+/**
+ * Stamp the async telemetry marker onto the background runner's env.
+ * (MuxSurface async policy, 2026-08-30): `PI_CREW_ASYNC_RUN` is NOT a surface
+ * gate — surface follows env + `runtime.surface.*` config, same as sync runs.
+ * The marker stays for telemetry (`SurfaceGateEnvSnapshot.asyncRun`). Pane
+ * attach from a detached process is safe: parent-guard (PI_CREW_PARENT_PID)
+ * still reaps panes when the host dies.
+ *
+ * Exported for the unit test asserting the invariant.
+ */
+export function buildBackgroundRunnerEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	return { ...env, PI_CREW_ASYNC_RUN: "1" };
+}
+
 export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise<SpawnBackgroundTeamRunResult> {
 	// FIX (2026-07-02, perf review F-critical): use packageRoot() instead of
 	// import.meta.url-relative path. The previous path.resolve walks
@@ -257,7 +285,7 @@ export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise
 	// `npm root -g` probe. No-op when pi-crew and pi are co-located. See
 	// src/runtime/peer-dep.ts.
 	const peerDepDir = resolvePeerDepDir();
-	const childEnv = peerDepDir ? { ...filteredEnv, [PEER_DEP_DIR_ENV]: peerDepDir } : filteredEnv;
+	const childEnv = buildBackgroundRunnerEnv(peerDepDir ? { ...filteredEnv, [PEER_DEP_DIR_ENV]: peerDepDir } : filteredEnv);
 
 	const loader = resolveTypeScriptLoader();
 	if (!loader) {

package/src/runtime/background-runner.ts

@@ -5,7 +5,7 @@ import { loadConfig } from "../config/config.ts";
 import { getCrewEnv } from "../config/env-vars.ts";
 import { atomicWriteFile } from "../state/atomic-write.ts";
 import { withRunLockSync } from "../state/coordination/locks.ts";
-import { appendEvent, appendEventFireAndForget } from "../state/event-log/event-log.ts";
+import { appendEvent, appendEventBuffered, appendEventFireAndForget } from "../state/event-log/event-log.ts";
 import { createRunPaths, loadRunManifestById, saveRunManifestAsync, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
@@ -18,8 +18,6 @@ import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows
 import { primePeerDep } from "./peer-dep.ts";
 import type { executeTeamRun as ExecuteTeamRunFn } from "./team-runner.ts";
 
-let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
-
 /** Maximum runtime for a single background run before the watchdog force-aborts
  *  it. Prevents zombie background-runner processes when a team run hangs forever
  *  (e.g. a hung child Pi process, a stuck lock, or a test that spawns a run
@@ -33,16 +31,13 @@ const MAX_BACKGROUND_RUN_MS = (() => {
 	return Number.isFinite(env) && env > 0 ? env : 2 * 60 * 60 * 1000;
 })();
 async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
-	if (!_cachedExecuteTeamRun) {
-		// FIX (split-scope install): prime the ESM peer dep BEFORE team-runner is
-		// imported, so its transitive skill-instructions.ts can read getAgentDir()
-		// from the primed cache instead of crashing on `Cannot find module`.
-		await primePeerDep().catch(() => undefined);
-		// LAZY: avoid pulling team-runner into background-runner at module load time.
-		const mod = await import("./team-runner.ts");
-		_cachedExecuteTeamRun = mod.executeTeamRun;
-	}
-	return _cachedExecuteTeamRun(...args);
+	// FIX (split-scope install): prime the ESM peer dep BEFORE team-runner is
+	// imported, so its transitive skill-instructions.ts can read getAgentDir()
+	// from the primed cache instead of crashing on `Cannot find module`.
+	await primePeerDep().catch(() => undefined);
+	// LAZY: avoid pulling team-runner into background-runner at module load time.
+	const mod = await import("./team-runner.ts");
+	return mod.executeTeamRun(...args);
 }
 
 import { logInternalError } from "../utils/internal-error.ts";
@@ -214,13 +209,19 @@ export function startInterruptGuard(
 ): () => void {
 	const controlPath = path.join(manifest.stateRoot, "foreground-control.json");
 	// FIX: Made configurable via PI_CREW_INTERRUPT_GUARD_INTERVAL_MS env var.
-	// Default 250ms balances fast SIGINT response against filesystem overhead.
-	const interruptGuardInterval = Number(getCrewEnv("PI_CREW_INTERRUPT_GUARD_INTERVAL_MS")) || 250;
+	// PERF (2026-08-24): default 1000ms. Each tick does existsSync + readFileSync
+	// + JSON.parse for the whole background run, and the guard is best-effort
+	// interrupt LATENCY, not a correctness deadline — verified by reading the
+	// trigger body below: a late trigger merely delays the SIGTERM (children are
+	// SIGKILLed after HARD_KILL_MS=3s regardless) and no state machine aborts on
+	// a deadline when the guard fires late. Nothing downstream requires the old
+	// 250ms cadence, so trade up to 4×/s of fs+parse churn for 1×/s.
+	const interruptGuardInterval = Number(getCrewEnv("PI_CREW_INTERRUPT_GUARD_INTERVAL_MS")) || 1000;
 	// RT-4 FIX: Module-local gate so the interrupt body runs only once per
 	// interrupt request. Without this, the guard re-fires every
-	// interruptGuardInterval (250ms) — each tick does a full
-	// terminateActiveChildPiProcesses sweep + sync appendEvent = ~4×/s steady
-	// state. The ack write stops the re-fire; this gate is defense-in-depth if
+	// interruptGuardInterval — each tick does a full
+	// terminateActiveChildPiProcesses sweep + sync appendEvent. The ack write
+	// stops the re-fire; this gate is defense-in-depth if
 	// the ack write fails (e.g. transient fs error).
 	let interruptHandled = false;
 	const interval = setInterval(() => {
@@ -238,8 +239,8 @@ export function startInterruptGuard(
 
 				// RT-4 FIX: Write acknowledged:true back to foreground-control.json
 				// SYNCHRONOUSLY. This stops the guard from re-firing on the next tick
-				// (250ms). Must be sync because this is a setInterval polling callback
-				// — we cannot await in a polling callback.
+				// (interruptGuardInterval). Must be sync because this is a setInterval
+				// polling callback — we cannot await in a polling callback.
 				try {
 					const reqs = parsed.requests ?? [];
 					if (reqs.length > 0) {
@@ -250,11 +251,11 @@ export function startInterruptGuard(
 					/* best-effort ack — interruptHandled gate prevents re-fire */
 				}
 
-				appendEvent(manifest.eventsPath, {
+				appendEventBuffered(manifest.eventsPath, {
 					type: "async.interrupt_detected",
 					runId: manifest.runId,
 					message: "Background runner detected foreground interrupt — killing child processes and exiting.",
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.interrupt_detected"));
 				// FIX: Terminate ALL child-pi processes IMMEDIATELY before exiting.
 				// Previously this was missing, causing orphaned child processes to run forever
 				// after the background-runner exited. terminateActiveChildPiProcesses sends
@@ -305,7 +306,7 @@ function setupUnhandledRejectionGuard(
 		console.error("[background-runner] Stack:", reason instanceof Error ? reason.stack : "N/A");
 		try {
 			if (state.eventsPath && state.runId) {
-				appendEvent(state.eventsPath, {
+				appendEventBuffered(state.eventsPath, {
 					type: "async.failed",
 					runId: state.runId,
 					message: `Unhandled rejection: ${message}`,
@@ -314,7 +315,7 @@ function setupUnhandledRejectionGuard(
 						stack: reason instanceof Error ? reason.stack : undefined,
 						handled: false,
 					},
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.failed source=unhandledRejection"));
 			}
 		} catch (appendErr) {
 			console.error("[background-runner] Failed to write async.failed event:", appendErr);
@@ -371,12 +372,12 @@ function runCleanup(
 		console.log(`[background-runner] runCleanup: unregisterWorker error: ${errorMessage(error)}`);
 		if (eventsPath) {
 			try {
-				appendEvent(eventsPath, {
+				appendEventBuffered(eventsPath, {
 					type: "background.unregister_worker_failed",
 					runId: argValue("--run-id") ?? "unknown",
 					message: `unregisterWorker failed: ${errorMessage(error)}`,
 					data: { pid: process.pid },
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=background.unregister_worker_failed"));
 			} catch {
 				/* best-effort */
 			}
@@ -532,12 +533,12 @@ async function main(): Promise<void> {
 		const runId = argValue("--run-id");
 		if (runId && manifest.eventsPath) {
 			try {
-				appendEvent(manifest.eventsPath, {
+				appendEventBuffered(manifest.eventsPath, {
 					type: "async.sigterm_received_graceful_shutdown",
 					runId,
 					message: `SIGTERM received, graceful shutdown via abort pid=${process.pid}`,
 					data: { pid: process.pid, ppid: process.ppid },
-				});
+				}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.sigterm_received_graceful_shutdown"));
 			} catch {
 				/* best-effort */
 			}
@@ -590,12 +591,12 @@ async function main(): Promise<void> {
 			const codeStr = code === undefined ? "<none>" : String(code);
 			if (runId2 && manifest.eventsPath) {
 				try {
-					appendEvent(manifest.eventsPath, {
+					appendEventBuffered(manifest.eventsPath, {
 						type: "async.exit",
 						runId: runId2,
 						message: `Background runner exit(${codeStr}) pid=${process.pid}`,
 						data: { code, pid: process.pid },
-					});
+					}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.exit"));
 				} catch {
 					/* best-effort */
 				}
@@ -629,11 +630,11 @@ async function main(): Promise<void> {
 	// NOTE: intentionally no unref() — the guard keeps the event loop alive
 	// to prevent premature worker exit. See parent-guard.ts:86 for rationale.
 
-	appendEvent(manifest.eventsPath, {
+	appendEventBuffered(manifest.eventsPath, {
 		type: "async.started",
 		runId: manifest.runId,
 		data: { pid: process.pid },
-	});
+	}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.started"));
 	debugLog(`[background-runner] async.started written, pid=${process.pid}`);
 	writeAsyncStartMarker(manifest, {
 		pid: process.pid,
@@ -657,12 +658,12 @@ async function main(): Promise<void> {
 	const watchdogTimer = setTimeout(() => {
 		console.error(`[background-runner] WATCHDOG: run ${runId} exceeded ${MAX_BACKGROUND_RUN_MS}ms — aborting (zombie prevention)`);
 		try {
-			appendEvent(manifest.eventsPath, {
+			appendEventBuffered(manifest.eventsPath, {
 				type: "async.watchdog_fired",
 				runId,
 				message: `Run exceeded ${MAX_BACKGROUND_RUN_MS}ms and was force-aborted to prevent a zombie background-runner process.`,
 				data: { maxRunMs: MAX_BACKGROUND_RUN_MS },
-			});
+			}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.watchdog_fired"));
 		} catch {
 			/* best-effort event log */
 		}
@@ -819,12 +820,12 @@ async function main(): Promise<void> {
 				updatedAt: new Date().toISOString(),
 			};
 			await saveRunManifestAsync(manifest);
-			appendEvent(manifest.eventsPath, {
+			appendEventBuffered(manifest.eventsPath, {
 				type: "runtime.resolved",
 				runId: manifest.runId,
 				message: `Runtime resolved: ${runtime.kind} safety=${runtime.safety}`,
 				data: { runtimeResolution, async: true },
-			});
+			}).catch((e) => logInternalError("background-runner.buffered", e, "type=runtime.resolved"));
 			if (runtime.safety === "blocked")
 				throw new Error(runtime.reason ?? "Child worker execution is disabled; refusing to create no-op scaffold subagents.");
 			const executeWorkers = runtime.kind !== "scaffold";
@@ -884,11 +885,11 @@ async function main(): Promise<void> {
 		} // close if (!earlyResult) — team-run setup+execute done; earlyResult path skips to here
 		manifest = result!.manifest;
 		tasks = result!.tasks;
-		appendEvent(manifest.eventsPath, {
+		appendEventBuffered(manifest.eventsPath, {
 			type: "async.completed",
 			runId: manifest.runId,
 			data: { status: manifest.status, tasks: tasks.length },
-		});
+		}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.completed"));
 		console.log(`[background-runner] async.completed written, status=${manifest.status}`);
 		if (manifest.status === "failed" || manifest.status === "cancelled" || manifest.status === "blocked") process.exitCode = 1;
 	} catch (error) {
@@ -909,11 +910,11 @@ async function main(): Promise<void> {
 					const fresh = loaded?.manifest ?? manifest;
 					if (fresh) {
 						manifest = updateRunStatus(fresh, "failed", message);
-						appendEvent(manifest.eventsPath, {
+						appendEventBuffered(manifest.eventsPath, {
 							type: "async.failed",
 							runId: manifest.runId,
 							message,
-						});
+						}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.failed source=updateFailed"));
 					}
 					return fresh;
 				},
@@ -982,12 +983,12 @@ try {
 		const mRunId = argValue("--run-id");
 		if (mCwd && mRunId) {
 			const mEventsPath = createRunPaths(mCwd, mRunId).eventsPath;
-			appendEvent(mEventsPath, {
+			appendEventBuffered(mEventsPath, {
 				type: "async.failed",
 				runId: mRunId,
 				message: errorMessage(err),
 				data: { stack: err instanceof Error ? err.stack : undefined },
-			});
+			}).catch((e) => logInternalError("background-runner.buffered", e, "type=async.failed source=catch"));
 		}
 	} catch {
 		/* best-effort — don't let event-write failure mask the original error */

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

@@ -28,8 +28,9 @@ export interface BrokerSpawnCredentials {
  *  ADR-5 §4 (governed nesting): `childDepth` carries the DEPTH-2+ grandchild's
  *  depth when the root-side delegate handler spawns it. The issuer mints only
  *  for children that may themselves delegate (childDepth < resolved
- *  PI_CREW_MAX_DEPTH) — at the default maxDepth=2 a depth-2 grandchild gets NO
- *  credentials (env containment AC: no PI_CREW_BROKER_SOCKET/TOKEN at depth 2).
+ *  PI_CREW_MAX_DEPTH) — at the default maxDepth=4 a depth-4 grandchild gets NO
+ *  credentials (env containment AC: no PI_CREW_BROKER_SOCKET/TOKEN at the cap
+ *  depth).
  *  Undefined childDepth = legacy worker spawn (depth 1) — unchanged behavior. */
 export type BrokerIssuer = (runId: string, taskId?: string, childDepth?: number) => Promise<BrokerSpawnCredentials | undefined>;
 
@@ -44,3 +45,27 @@ export function setActiveBrokerIssuer(issuer: BrokerIssuer | undefined): void {
 export function getActiveBrokerIssuer(): BrokerIssuer | undefined {
 	return activeIssuer;
 }
+
+/**
+ * MuxSurface A1 (spec §7 D3 step 2): process-local revoker for per-task tokens.
+ * The team-runner's surface-degrade controller calls it when a pane is lost so
+ * the zombie worker left in that pane can no longer authenticate to the broker;
+ * the headless respawn mints a FRESH token (T10 re-issue).
+ *
+ * Same registration model as the issuer: the lifecycle controller publishes a
+ * closure on start and clears it on stop, so the degrade path needs no wiring
+ * through every runner layer. A function reference only — never a token.
+ */
+export type BrokerRevoker = (taskId: string) => void;
+
+let activeRevoker: BrokerRevoker | undefined;
+
+/** Register the active revoker (called by the lifecycle controller on start). */
+export function setActiveBrokerRevoker(revoker: BrokerRevoker | undefined): void {
+	activeRevoker = revoker;
+}
+
+/** Read the active revoker, if any. Returns undefined when no broker is wired. */
+export function getActiveBrokerRevoker(): BrokerRevoker | undefined {
+	return activeRevoker;
+}

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

@@ -10,7 +10,7 @@
  * independently testable.
  */
 
-import { randomUUID, timingSafeEqual } from "node:crypto";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 
 /** Length guard: tokens are 128-bit-class (UUID v4). */
 export type BrokerToken = string;
@@ -37,6 +37,21 @@ export function newBrokerToken(): BrokerToken {
  */
 export class BrokerTokenRegistry {
 	private readonly map = new Map<string, BrokerToken>();
+	/** Task 10 (mux-surface A1 §5.2): sha256 hashes of explicitly revoked
+	 *  tokens. Heap-only like the map; hashing keeps the registry from holding
+	 *  a second plaintext copy of a secret. Revocation is per-SECRET, not
+	 *  per-key: `issue()` mints a fresh token when the registered one is in
+	 *  this set (fix round 1 BUG #1), so the A2 re-issue remedy always
+	 *  produces a live token while the old secret stays dead. */
+	private readonly revokedTokenHashes = new Set<string>();
+
+	/** Public so the broker can hash the hello secret ONCE at auth time and
+	 *  keep only the digest on the connection (fix round 2 BUG #3: the frame
+	 *  revocation check is secret-based — a connection authenticated with a
+	 *  revoked secret stays dead even after the key is re-issued). */
+	static hashToken(token: BrokerToken): string {
+		return createHash("sha256").update(token, "utf8").digest("hex");
+	}
 
 	/** Compute the registry key. Compound when taskId is present, bare
 	 *  runId otherwise (backward-compat with the original per-run model). */
@@ -72,8 +87,12 @@ export class BrokerTokenRegistry {
 	/** Issue a token for `runId` (+optional `taskId`). Idempotent per key:
 	 *  if a token already exists for the computed key, the existing token is
 	 *  returned unchanged so that concurrent sibling tasks sharing a key all
-	 *  authenticate with the same token. Pass an explicit `token` only in
-	 *  tests that need a deterministic value. */
+	 *  authenticate with the same token — UNLESS that token was revoked (fix
+	 *  round 1, BUG #1): a revoked secret is never resurrected, a fresh one
+	 *  is minted and overwrites the entry (the degrade respawn flow re-issues
+	 *  after revokeTaskToken and the new worker must get a live token).
+	 *  Pass an explicit `token` only in tests that need a deterministic
+	 *  value. */
 	issue(runId: string, taskId?: string, token?: BrokerToken): BrokerToken {
 		if (typeof runId !== "string" || runId.length === 0) {
 			throw new Error("BrokerTokenRegistry.issue: runId must be a non-empty string");
@@ -81,7 +100,9 @@ export class BrokerTokenRegistry {
 		const k = this.key(runId, taskId);
 		if (token === undefined) {
 			const existing = this.map.get(k);
-			if (existing !== undefined) return existing;
+			if (existing !== undefined && !this.revokedTokenHashes.has(BrokerTokenRegistry.hashToken(existing))) {
+				return existing;
+			}
 			const fresh = newBrokerToken();
 			this.map.set(k, fresh);
 			return fresh;
@@ -184,9 +205,40 @@ export class BrokerTokenRegistry {
 		if (!taskId) this.map.delete(this.orchestratorKey(runId));
 	}
 
+	/** Task 10 (mux-surface A1 §5.2): mark `token` revoked. The next hello
+	 *  presenting it — and every subsequent frame on a connection already
+	 *  authenticated with it — is rejected with code "revoked". No-op on a
+	 *  non-string/empty input. */
+	revokeToken(token: BrokerToken): void {
+		if (typeof token !== "string" || token.length === 0) return;
+		this.revokedTokenHashes.add(BrokerTokenRegistry.hashToken(token));
+	}
+
+	/** Task 10: whether the token currently registered for the compound
+	 *  (runId, taskId) key has been revoked. False when no such key exists
+	 *  (undefined ids, orchestrator connections, legacy bare-runId fallbacks)
+	 *  and short-circuits while nothing was ever revoked. This is the HELLO
+	 *  path check — at hello time the candidate must still match the map, so
+	 *  key resolution is equivalent to secret resolution. */
+	isTaskTokenRevoked(runId: string | undefined, taskId: string | undefined): boolean {
+		if (this.revokedTokenHashes.size === 0 || !runId || !taskId) return false;
+		const token = this.map.get(this.key(runId, taskId));
+		return token !== undefined && this.revokedTokenHashes.has(BrokerTokenRegistry.hashToken(token));
+	}
+
+	/** Fix round 2 (BUG #3): whether a specific SECRET digest has been
+	 *  revoked. The post-hello frame check uses this — it must evaluate the
+	 *  secret the connection ACTUALLY authenticated with, not whatever token
+	 *  the key currently holds (a revoke → re-issue window must not let an
+	 *  old connection ride a freshly issued token). */
+	isSecretRevoked(hash: string): boolean {
+		return this.revokedTokenHashes.has(hash);
+	}
+
 	/** Wipe every token. Called from CrewBroker.stop(). */
 	clear(): void {
 		this.map.clear();
+		this.revokedTokenHashes.clear();
 	}
 
 	/** Diagnostic — count of registered tokens. Never returns the tokens. */