pi-crew 0.10.2 → 0.10.3

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

@@ -214,13 +214,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 +244,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) {

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. */