pi-crew 0.10.3 → 0.10.4

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

@@ -0,0 +1,37 @@
+/**
+ * delegate-event.ts — Event recording for the broker delegate surface.
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * recordDelegateEvent uses ONLY the module-scoped event-log + error helpers;
+ * no broker state. Promoted to a top-level function so the class method is
+ * a 1-line delegation.
+ */
+
+import { appendEventAsync } from "../../../state/event-log/event-log.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
+
+/** Fire-and-forget async append; an append failure is logged, never thrown
+ *  (broker handlers must not block the event loop on the sync event-log lock).
+ *  See `crew-broker.delegate.event` event scope conventions in ADR-5 §10. */
+export function recordDelegateEvent(
+	manifest: { eventsPath: string; runId: string },
+	type:
+		| "delegate.requested"
+		| "delegate.admitted"
+		| "delegate.rejected"
+		| "delegate.completed"
+		| "delegate.timed_out"
+		| "delegate.rolled_up",
+	taskId: string,
+	data: Record<string, unknown>,
+): void {
+	void appendEventAsync(manifest.eventsPath, {
+		type,
+		runId: manifest.runId,
+		taskId,
+		message: `${type}: ${JSON.stringify(data).slice(0, 200)}`,
+		data,
+	}).catch((err) =>
+		logInternalError("crew-broker.delegate.event", err instanceof Error ? err : new Error(String(err)), `runId=${manifest.runId}`),
+	);
+}

package/src/runtime/broker/mailbox-observer/mailbox-fanout.ts

@@ -0,0 +1,59 @@
+/**
+ * mailbox-fanout.ts — Phase 1.3 mailbox-event fanout helper.
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * Operates only on the connectionsByRun index + writeOrQueue/enqueueFrame
+ * functions passed in. Promoted to a top-level function so the class
+ * method is a 1-line delegation.
+ */
+
+import type { MailboxMessage } from "../../../state/coordination/mailbox.ts";
+import { encodeBrokerFrame } from "../../../utils/ndjson.ts";
+import type { ServerConnection } from "../protocol/connection-state.ts";
+
+export interface FanoutWriters {
+	writeOrQueue(conn: ServerConnection, buf: Buffer, force: boolean): void;
+}
+
+/** Phase 1.3: push a durable-appended mailbox message to any connected
+ *  recipient for the message's run. Best-effort — silently skips
+ *  recipients that are offline (they recover via msg.inbox). Never throws. */
+export function fanoutMailboxMessage(
+	connectionsByRun: Map<string, Set<ServerConnection>>,
+	writers: FanoutWriters,
+	msg: MailboxMessage,
+): void {
+	const set = connectionsByRun.get(msg.runId);
+	if (!set || set.size === 0) return;
+	// Recipient delivery dedup lives in src/prompt/prompt-runtime.ts and is
+	// keyed by the same message id in this mailbox event and the steering JSONL.
+	const eventFrame = encodeBrokerFrame({
+		event: "mailbox.message",
+		data: {
+			id: msg.id,
+			from: msg.from,
+			to: msg.to,
+			body: msg.body,
+			kind: msg.kind,
+			priority: msg.priority,
+		},
+		seq: 0, // mailbox messages don't carry a TeamEvent seq; dedup by msg.id
+	});
+	for (const conn of set) {
+		if (conn.closed || !conn.authed) continue;
+		// Recipient filter: deliver to the addressed task, or to all if 'all'.
+		// Task 5b (§15.2 wake): "parent"-addressed messages land in the
+		// run-level inbox, whose live consumer is the run's orchestrator
+		// connection (role from the orchestrator token — its taskId never
+		// equals "parent"), so without this branch the wake frame would be
+		// filtered out and the orchestrator would only see the message on
+		// its next inbox poll.
+		const isRecipient = !msg.to || msg.to === "all" || conn.taskId === msg.to || (msg.to === "parent" && conn.role === "orchestrator");
+		if (!isRecipient) continue;
+		try {
+			writers.writeOrQueue(conn, eventFrame, false);
+		} catch {
+			/* a slow/dead recipient must not break fanout to others */
+		}
+	}
+}

package/src/runtime/broker/protocol/connection-state.ts

@@ -0,0 +1,103 @@
+/**
+ * connection-state.ts — Type definitions for crew-broker connection state
+ * and broker options.
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * These are pure types/interfaces used by the CrewBroker class but they
+ * contribute ~80 lines to the file's line count. Splitting them out
+ * contributes to the ≤2000-line gate (spec §5 M4 acceptance).
+ */
+
+import type * as net from "node:net";
+import type { NdjsonDecoder } from "../../../utils/ndjson.ts";
+import type { GrandchildSpawnInput, GrandchildSpawnResult } from "../../delegate-spawn.ts";
+import type { WaitStatusCache } from "../wait-status-cache.ts";
+
+export interface CrewBrokerOptions {
+	/** Root session ID used to derive the socket path. */
+	sessionId: string;
+	/** Pre-resolved socket path (skips re-derivation; useful for tests). */
+	socketPath?: string;
+	/** Frame cap in UTF-8 bytes. Default 256 KiB. */
+	maxFrameBytes?: number;
+	/** Per-connection outbound queue cap. Default 256. */
+	outboundQueueCap?: number;
+	/** Required: when false, start() is a no-op and the server never binds.
+	 *  Lets the lifecycle controller install the broker unconditionally and
+	 *  have a single kill switch. */
+	enabled: boolean;
+	/** CWD for `loadRunManifestById` (Phase 1 msg.send / msg.inbox resolution).
+	 *  When omitted, manifest-touching methods return no-manifest errors. */
+	cwd?: string;
+	/** Optional test seam: override the `net` module (allows fake-server tests). */
+	netModule?: typeof net;
+	/** Optional test seam: inject a pre-configured WaitStatusCache (e.g. one
+	 *  wrapping a loader spy). Production uses a plain cache — see
+	 *  wait-status-cache.ts (R10-3). */
+	waitStatusCache?: WaitStatusCache;
+	/** WP-2/R2 (ADR-0 2026-08-17-waiting-producer-ask item 7): capability
+	 *  gate for the `wait.*` methods. DEFAULT FALSE — fail-closed. When not
+	 *  explicitly true, wait.request/wait.resolve are rejected with a
+	 *  `policy-disabled` error AND a `policy.action` event is appended to the
+	 *  run's events.jsonl (never silent). The production wiring threads
+	 *  `config.broker.waitMethodsEnabled` here; tests pass it explicitly. */
+	waitMethodsEnabled?: boolean;
+	/** T3/R5 (ADR-5 §10): capability gate for the `delegate` surface. DEFAULT
+	 *  TRUE since D8 (spec v0.7) — nested spawning is open out of the box; the
+	 *  broker still fail-closes when the flag is anything but true. The
+	 *  production wiring threads `config.nesting.enabled` (loadConfig layers
+	 *  DEFAULT_NESTING.enabled=true; a user `false` closes the surface); tests
+	 *  pass it explicitly. Rejections are NEVER silent (delegate.rejected). */
+	nestingEnabled?: boolean;
+	/** Optional override for the nested-slot budget size (config nesting.maxSlots). */
+	nestingMaxSlots?: number;
+	nestingMaxDepth?: number;
+	nestingTrustedEscalation?: boolean;
+	/** Global worker semaphore size, used to size the nested-slot budget. */
+	globalWorkerSemaphore?: number;
+	/** Test seam / alternative spawner for delegate grandchildren. Production
+	 *  uses spawnDelegateGrandchild (direct runChildPi call-site, ADR-5 §2). */
+	grandchildSpawner?: (input: GrandchildSpawnInput) => Promise<GrandchildSpawnResult>;
+	/** Resolved model catalog (canonical provider/id strings) for admission-time
+	 *  model validation (ADR-5 §7). When omitted, model validation is skipped
+	 *  (documented gap — the production wiring must always supply it). */
+	modelCatalog?: () => string[] | undefined;
+	/** ADR-5 §9: mirrors config limits.serializeOnPathOverlap for the workspace
+	 *  admission gate. Default false. */
+	serializeOnPathOverlap?: boolean;
+}
+
+/** Per-connection server-side state. */
+export interface ServerConnection {
+	socket: net.Socket;
+	decoder: NdjsonDecoder;
+	/** Whether the connection has completed `hello` successfully. */
+	authed: boolean;
+	/** Run id bound by hello. */
+	runId?: string;
+	/** Task id bound by hello. */
+	taskId?: string;
+	/** Role bound by hello: orchestrator can steer/msg-send; workers default. */
+	role?: "orchestrator" | "worker";
+	/** How the hello token matched the registry (ADR-0 item 6). Derived,
+	 *  non-secret metadata recorded at hello time so `wait.*` can reject a
+	 *  legacy bare-runId fallback match WITHOUT keeping the raw token on the
+	 *  connection (tokens stay confined to the heap-only registry). */
+	authMatchKind?: "compound" | "runId-fallback";
+	/** Task 10 fix round 2 (BUG #3): sha256 of the secret this connection
+	 *  authenticated with. Derived, one-way — never the plaintext token. The
+	 *  post-hello revocation check evaluates THIS digest so a revoke →
+	 *  re-issue window cannot let an old connection ride the freshly issued
+	 *  token for the same key. */
+	authedSecretHash?: string;
+	/** Outbound queue of encoded frames awaiting drain. */
+	outbound: Buffer[];
+	/** Set when the queue has hit the cap and a frame was dropped. */
+	needsResync: boolean;
+	/** Set when the connection is closing (idempotent). */
+	closed: boolean;
+	/** Timer for the hello deadline. */
+	helloTimer: NodeJS.Timeout | null;
+	/** Monotonic seq counter for outbound events (diagnostic). */
+	outboundSeq: number;
+}

package/src/runtime/broker/protocol/events-replay.ts

@@ -0,0 +1,68 @@
+/**
+ * events-replay.ts — Phase 1.5 events.since handler (label corrected
+ * 2026-09-10 per review F4 — "Phase 2" is events.subscribe). Used by clients
+ * to resync after a missed live frame (e.g. after a queue overflow or
+ * reconnect).
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * Operates only on the connection + a writers adapter (sendError/sendResult).
+ * Promoted to a top-level function so the class method is a 1-line delegation.
+ */
+
+import { readEventsCursor } from "../../../state/event-log/event-log.ts";
+import { loadRunManifestById } from "../../../state/stores/state-store.ts";
+import type { ServerConnection } from "./connection-state.ts";
+
+export interface EventWriterHelpers {
+	sendError(conn: ServerConnection, id: string, code: string, message: string): void;
+	sendResult(conn: ServerConnection, id: string, result: unknown): void;
+}
+
+/** Phase 2: events.since — page-replay handler. Returns events with
+ *  seq > sinceSeq from the durable log, capped to `limit` (default 1000). */
+export async function handleEventsSince(
+	conn: ServerConnection,
+	id: string,
+	params: unknown,
+	helpers: EventWriterHelpers,
+	cwd: string | undefined,
+): Promise<void> {
+	if (!conn.runId) {
+		helpers.sendError(conn, id, "auth", "not authed");
+		return;
+	}
+	if (!cwd) {
+		helpers.sendError(conn, id, "no-manifest", "broker has no cwd configured");
+		return;
+	}
+	let eventsPath: string;
+	try {
+		const loaded = loadRunManifestById(cwd, conn.runId);
+		if (!loaded) {
+			helpers.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
+			return;
+		}
+		eventsPath = loaded.manifest.eventsPath;
+	} catch (err) {
+		helpers.sendError(conn, id, "no-manifest", (err as Error).message);
+		return;
+	}
+	const v = params && typeof params === "object" && !Array.isArray(params) ? (params as Record<string, unknown>) : {};
+	const sinceSeq = typeof v.sinceSeq === "number" && Number.isFinite(v.sinceSeq) ? Math.max(0, Math.floor(v.sinceSeq)) : 0;
+	const limit = typeof v.limit === "number" && Number.isFinite(v.limit) ? Math.min(Math.max(1, Math.floor(v.limit)), 1000) : 1000;
+	try {
+		const result = readEventsCursor(eventsPath, { sinceSeq, limit });
+		// hasMore is true iff the total filtered count exceeds the page we
+		// returned. When `total === events.length` we are at the exact end
+		// of the stream (caller will discover this on the next call when
+		// `nextSeq` is unchanged from `sinceSeq`).
+		const hasMore = result.total > result.events.length;
+		helpers.sendResult(conn, id, {
+			events: result.events,
+			nextSeq: result.nextSeq,
+			hasMore,
+		});
+	} catch (err) {
+		helpers.sendError(conn, id, "replay-failed", (err as Error).message);
+	}
+}

package/src/runtime/broker/protocol/manifest-loader.ts

@@ -0,0 +1,20 @@
+/**
+ * manifest-loader.ts — Helper for loading run manifests during hello.
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * The CrewBroker.loadRunForHello method delegated entirely to
+ * loadRunManifestById after one safety check (cwd absence); the helper is
+ * now a top-level function the class method delegates to in 1 line.
+ */
+
+import { loadRunManifestById } from "../../../state/stores/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../../state/types.ts";
+
+export function loadRunForHello(cwd: string | undefined, runId: string): { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined {
+	if (!cwd) return undefined;
+	try {
+		return loadRunManifestById(cwd, runId) ?? undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/runtime/broker/protocol/msg-inbox.ts

@@ -0,0 +1,69 @@
+/**
+ * msg-inbox.ts — Phase 1.2 msg.inbox broker handler (Phase 1.1 = msg.send;
+ * label corrected 2026-09-10 per review F3 — it was mislabeled 1.1 at extraction).
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * Operates on a connection + writers adapter + cwd. Top-level function so
+ * the class method is a 1-line delegation.
+ */
+
+import { readMailbox } from "../../../state/coordination/mailbox.ts";
+import { loadRunManifestById } from "../../../state/stores/state-store.ts";
+import type { ServerConnection } from "./connection-state.ts";
+import { parseMsgInboxParams } from "./request-parsers.ts";
+
+export interface MsgInboxHelpers {
+	sendError(conn: ServerConnection, id: string, code: string, message: string): void;
+	sendResult(conn: ServerConnection, id: string, result: unknown): void;
+}
+
+/** Phase 1.1: read the durable mailbox for the addressed task (or run-level
+ *  "inbox" lane) with cursor/limit pagination. Returns messages whose status
+ *  is NOT yet `acknowledged`; callers should ack after processing. */
+export async function handleMsgInbox(
+	conn: ServerConnection,
+	id: string,
+	params: unknown,
+	helpers: MsgInboxHelpers,
+	cwd: string | undefined,
+): Promise<void> {
+	if (!conn.runId) {
+		helpers.sendError(conn, id, "auth", "not authed");
+		return;
+	}
+	const parsed = parseMsgInboxParams(params);
+	if (!parsed) {
+		helpers.sendError(conn, id, "bad-params", "msg.inbox: invalid params");
+		return;
+	}
+	if (!cwd) {
+		helpers.sendError(conn, id, "no-manifest", "broker has no cwd configured");
+		return;
+	}
+	let manifest: Parameters<typeof readMailbox>[0];
+	try {
+		const loaded = loadRunManifestById(cwd, conn.runId);
+		if (!loaded) {
+			helpers.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
+			return;
+		}
+		manifest = loaded.manifest;
+	} catch (err) {
+		helpers.sendError(conn, id, "no-manifest", (err as Error).message);
+		return;
+	}
+	const limit = Math.min(Math.max(parsed.limit ?? 100, 1), 1000);
+	const taskId = conn.taskId ?? undefined;
+	const all = readMailbox(manifest, "inbox", taskId);
+	const filtered = all.filter((m) => m.status !== "acknowledged");
+	const offset = parsed.cursor ? Number.parseInt(parsed.cursor, 10) || 0 : 0;
+	const page = filtered.slice(offset, offset + limit);
+	const nextOffset = offset + page.length;
+	const hasMore = nextOffset < filtered.length;
+	helpers.sendResult(conn, id, {
+		messages: page,
+		nextCursor: hasMore ? String(nextOffset) : undefined,
+		hasMore,
+		total: filtered.length,
+	});
+}

package/src/runtime/broker/protocol/request-parsers.ts

@@ -0,0 +1,175 @@
+/**
+ * request-parsers.ts — Protocol-level parameter parsers and type guards for
+ * the crew-broker wire protocol.
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * Every parser rejects malformed frames at the boundary so handlers see only
+ * typed params. Method-name charset check (^[a-zA-Z][a-zA-Z0-9._-]{0,63}$)
+ * guards against control chars / oversized names reaching the dispatcher.
+ */
+
+import type { MailboxMessageKind, MailboxMessagePriority } from "../../../state/coordination/mailbox.ts";
+
+/** Protocol version negotiated at `hello` time. Bump on breaking change. */
+export const BROKER_PROTOCOL = 1;
+
+// ============================================================================
+// Type guards (no `any`)
+// ============================================================================
+
+export function isRequestObject(value: unknown): value is { id: string; method: string; params: unknown } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const v = value as Record<string, unknown>;
+	if (typeof v.id !== "string" || v.id.length === 0 || v.id.length > 256) return false;
+	if (typeof v.method !== "string" || v.method.length === 0 || v.method.length > 64) return false;
+	// Method names are restricted to a small safe charset. This guards against
+	// odd inputs (control chars, very long names) reaching the dispatcher.
+	if (!/^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/.test(v.method)) return false;
+	// params may be anything (validated per-method), but not undefined-shaped.
+	return "params" in v;
+}
+
+export function isHelloParams(value: unknown): value is {
+	protocol: number;
+	runId: string;
+	taskId: string;
+	token: string;
+	role?: string;
+} {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const v = value as Record<string, unknown>;
+	if (v.protocol !== BROKER_PROTOCOL) {
+		// Force exact-type comparison (must be the number 1, not "1").
+		if (typeof v.protocol !== "number" || !Number.isInteger(v.protocol)) return false;
+	}
+	if (typeof v.runId !== "string" || v.runId.length === 0 || v.runId.length > 256) return false;
+	if (typeof v.taskId !== "string" || v.taskId.length === 0 || v.taskId.length > 256) return false;
+	if (typeof v.token !== "string" || v.token.length === 0 || v.token.length > 256) return false;
+	return true;
+}
+
+// ============================================================================
+// Phase 1 parameter parsers (module-level; no `any`)
+// ============================================================================
+
+export interface MsgSendParams {
+	to: string | string[] | "all";
+	body: unknown;
+	kind?: MailboxMessageKind;
+	priority?: MailboxMessagePriority;
+	replyTo?: string;
+	/** Task 5b (§15.2): short subject echoed into the worker.message wake
+	 * event (bounded like the tool-side MSG_SUBJECT_MAX_CHARS). */
+	subject?: string;
+}
+
+export function parseMsgSendParams(value: unknown): MsgSendParams | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const v = value as Record<string, unknown>;
+	const to = v.to;
+	if (typeof to !== "string" && !Array.isArray(to)) return undefined;
+	if (Array.isArray(to) && !to.every((s) => typeof s === "string" && s.length > 0)) return undefined;
+	if (typeof to === "string" && to.length === 0) return undefined;
+	if (v.body === undefined) return undefined;
+	const kind = v.kind as MailboxMessageKind | undefined;
+	if (kind !== undefined && !["message", "notify", "steer", "follow-up", "response", "group_join"].includes(kind)) {
+		return undefined;
+	}
+	const priority = v.priority as MailboxMessagePriority | undefined;
+	if (priority !== undefined && !["urgent", "normal", "low"].includes(priority)) {
+		return undefined;
+	}
+	const replyTo = typeof v.replyTo === "string" ? v.replyTo : undefined;
+	const subject = typeof v.subject === "string" && v.subject.length > 0 && v.subject.length <= 256 ? v.subject : undefined;
+	return { to: to as string | string[] | "all", body: v.body, kind, priority, replyTo, subject };
+}
+
+export interface MsgInboxParams {
+	limit?: number;
+	cursor?: string;
+}
+
+export function parseMsgInboxParams(value: unknown): MsgInboxParams | undefined {
+	if (value === undefined || value === null) return { limit: 100, cursor: undefined };
+	if (typeof value !== "object" || Array.isArray(value)) return undefined;
+	const v = value as Record<string, unknown>;
+	const limit = v.limit;
+	if (limit !== undefined && (typeof limit !== "number" || !Number.isFinite(limit) || limit < 1)) {
+		return undefined;
+	}
+	const cursor = v.cursor;
+	if (cursor !== undefined && typeof cursor !== "string") return undefined;
+	return { limit: limit as number | undefined, cursor: cursor as string | undefined };
+}
+
+export function safeStringify(value: unknown): string {
+	try {
+		return JSON.stringify(value) ?? "{}";
+	} catch {
+		return "{}";
+	}
+}
+
+// ============================================================================
+// WP-2/R2 wait.* parameter parsers (ADR-0 2026-08-17-waiting-producer-ask)
+// ============================================================================
+
+/** Server-side ceiling for the ask deadline (ADR P2-7): worker-controlled
+ *  timeoutSec may NEVER exceed 1h — an unbounded timeout would pin slots and
+ *  amplify I/O. Applied as deadline = now + min(timeoutSec, 3600). */
+export const WAIT_REQUEST_TIMEOUT_SEC_MAX = 3600;
+/** Default ask timeout when the caller omits timeoutSec (ADR item 1). */
+export const WAIT_REQUEST_TIMEOUT_SEC_DEFAULT = 600;
+/** Bounded question payload (defense-in-depth under the 256 KiB frame cap). */
+export const WAIT_QUESTION_MAX_CHARS = 8192;
+/** Bounded answer-choice list: at most 16 options, 256 chars each. */
+export const WAIT_OPTIONS_MAX = 16;
+export const WAIT_OPTION_MAX_CHARS = 256;
+
+export interface WaitRequestParams {
+	to: string;
+	question: string;
+	options?: string[];
+	timeoutSec?: number;
+}
+
+export function parseWaitRequestParams(value: unknown): WaitRequestParams | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const v = value as Record<string, unknown>;
+	if (typeof v.to !== "string" || v.to.length === 0 || v.to.length > 256) return undefined;
+	if (typeof v.question !== "string" || v.question.length === 0 || v.question.length > WAIT_QUESTION_MAX_CHARS) {
+		return undefined;
+	}
+	let options: string[] | undefined;
+	if (v.options !== undefined) {
+		if (!Array.isArray(v.options) || v.options.length === 0 || v.options.length > WAIT_OPTIONS_MAX) return undefined;
+		for (const o of v.options) {
+			if (typeof o !== "string" || o.length === 0 || o.length > WAIT_OPTION_MAX_CHARS) return undefined;
+		}
+		options = v.options as string[];
+	}
+	// timeoutSec is clamped server-side in the handler (max 3600); the parser
+	// only rejects non-finite values. Non-positive values clamp to 1s.
+	if (v.timeoutSec !== undefined && (typeof v.timeoutSec !== "number" || !Number.isFinite(v.timeoutSec))) {
+		return undefined;
+	}
+	return {
+		to: v.to,
+		question: v.question,
+		options,
+		timeoutSec: v.timeoutSec as number | undefined,
+	};
+}
+
+export interface WaitResolveParams {
+	to: string;
+	questionId: string;
+}
+
+export function parseWaitResolveParams(value: unknown): WaitResolveParams | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const v = value as Record<string, unknown>;
+	if (typeof v.to !== "string" || v.to.length === 0 || v.to.length > 256) return undefined;
+	if (typeof v.questionId !== "string" || v.questionId.length === 0 || v.questionId.length > 128) return undefined;
+	return { to: v.to, questionId: v.questionId };
+}

package/src/runtime/broker/protocol/wait-auth.ts

@@ -0,0 +1,46 @@
+/**
+ * wait-auth.ts — Auth + policy-rejection helpers for the broker wait.*
+ * surface.
+ *
+ * Moved from crew-broker.ts (M4 / WI-4.1) — pure move, no behavior change.
+ * waitAuthError is pure (operates only on conn metadata). recordWaitPolicyRejection
+ * uses module-scoped event-log + internal-error helpers — same as the class
+ * method did. Both are now top-level functions; the class delegates to them.
+ */
+
+import { appendEventAsync } from "../../../state/event-log/event-log.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
+import type { ServerConnection } from "./connection-state.ts";
+
+/** Auth failure for the wait.* methods: worker role + task-scoped (compound)
+ *  token ONLY (ADR-0 2026-08-17 item 6). Legacy bare-runId fallback match is
+ *  REJECTED with a migrate hint; orchestrator token is rejected by role. */
+export function waitAuthError(conn: ServerConnection): { code: string; message: string } | null {
+	if (conn.role !== "worker" || conn.authMatchKind === undefined) {
+		return { code: "forbidden", message: "wait.* requires a worker task-scoped token" };
+	}
+	if (conn.authMatchKind !== "compound") {
+		return {
+			code: "forbidden",
+			message: "wait.* requires a task-scoped token; re-dispatch with PI_CREW_BROKER_TASK_ID",
+		};
+	}
+	return null;
+}
+
+/** ADR-0 item 7: a disabled-gate rejection MUST leave a durable trace in
+ *  events.jsonl. The gate fails CLOSED but never SILENTLY. Fire-and-forget
+ *  async append (broker handlers must not block the event loop on the sync
+ *  event-log lock); an append failure is logged, never thrown. */
+export function recordWaitPolicyRejection(manifest: { eventsPath: string; runId: string }, taskId: string, method: string): void {
+	const runId = manifest.runId;
+	void appendEventAsync(manifest.eventsPath, {
+		type: "policy.action",
+		runId,
+		taskId,
+		message: `${method} rejected: waitMethodsEnabled=false (fail-closed)`,
+		data: { action: method, reason: "wait-methods-disabled", policy: "broker.waitMethodsEnabled=false" },
+	}).catch((err) =>
+		logInternalError("crew-broker.wait.policy-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+	);
+}

package/src/runtime/child-pi/child-pi.ts

@@ -157,6 +157,17 @@ export interface ChildPiRunInput {
 	onSpawn?: (pid: number) => void;
 	/** Structured lifecycle events for durable logging (spawn, crash, timeout, kill, exit). */
 	onLifecycleEvent?: (event: ChildPiLifecycleEvent) => void;
+	/** F1 fix (battery 2026-09-10): task-state activity bridge for SURFACE workers.
+	 * Surface workers have no stdout pipe, so onJsonEvent/onStdoutLine never fire
+	 * and task.heartbeat/agentProgress starve - the heartbeat-watcher then flags a
+	 * healthy pane worker dead (~340s) and the stale-reconciler cancels the run
+	 * (observed live: run team_20260910161234, worker productive 7min in pane
+	 * w2:p8Z, 0 task.progress events). This callback receives every event tailed
+	 * from the per-agent recorder log so the CALLER can update task liveness state.
+	 * Contract: the callback MUST NOT append to the per-agent events file being
+	 * tailed (watch->append loop - see event-log-tail-source.ts header); task-state
+	 * persist + run-level task.progress are safe (different files). */
+	onSurfaceActivity?: (event: Record<string, unknown>) => void;
 	maxDepth?: number;
 	finalDrainMs?: number;
 	/** F12: early-exit the drain when stdout has been silent for this many ms
@@ -492,6 +503,10 @@ async function trySurfaceBranch(
 			}
 			const bridgeEvent = bridgeEventFromJsonEvent(runId, taskId, event);
 			if (bridgeEvent) runEventBus.emit({ type: "worker_status", runId, taskId, data: bridgeEvent });
+			// F1 fix (battery 2026-09-10): feed the same tailed event to the task-state
+			// bridge so child-executor can keep task.heartbeat/agentProgress fresh for
+			// surface workers (see ChildPiRunInput.onSurfaceActivity doc).
+			input.onSurfaceActivity?.(event as Record<string, unknown>);
 		});
 	}
 	let exitInfo: SurfaceExitInfo;

package/src/runtime/finalize-run.ts

@@ -19,7 +19,7 @@ import type { CrewLimitsConfig, CrewRuntimeConfig } from "../config/config.ts";
 import { flushPendingAtomicWrites } from "../state/atomic-write.ts";
 import { TEAM_TERMINAL_TASK_STATUSES } from "../state/contracts.ts";
 import { withRunLock } from "../state/coordination/locks.ts";
-import { appendEvent, appendEventAsync, appendEventFireAndForget, readEvents } from "../state/event-log/event-log.ts";
+import { appendEventAsync, appendEventBuffered, appendEventFireAndForget, readEvents } from "../state/event-log/event-log.ts";
 import { hashArtifactContent as hashContent, writeArtifact } from "../state/stores/artifact-store.ts";
 import { HealthStore } from "../state/stores/health-store.ts";
 import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
@@ -211,12 +211,12 @@ function applyPolicy(manifest: TeamRunManifest, tasks: TeamTaskState[], limits?:
 			createdAt: new Date().toISOString(),
 		};
 		decisions = [...decisions, branchDecision];
-		appendEvent(manifest.eventsPath, {
+		appendEventBuffered(manifest.eventsPath, {
 			type: "branch.stale",
 			runId: manifest.runId,
 			message: branchFreshness.message,
 			data: { branchFreshness },
-		});
+		}).catch((e) => logInternalError("finalize-run.buffered", e, "type=branch.stale"));
 	}
 	const policyArtifact = writeArtifact(manifest.artifactsRoot, {
 		kind: "metadata",
@@ -232,15 +232,17 @@ function applyPolicy(manifest: TeamRunManifest, tasks: TeamTaskState[], limits?:
 		content: `${JSON.stringify(recoveryLedger, null, 2)}\n`,
 	});
 	for (const item of decisions)
-		appendEvent(manifest.eventsPath, {
+		appendEventBuffered(manifest.eventsPath, {
 			type: item.action === "escalate" ? "policy.escalated" : "policy.action",
 			runId: manifest.runId,
 			taskId: item.taskId,
 			message: item.message,
 			data: { action: item.action, reason: item.reason },
-		});
+		}).catch((e) =>
+			logInternalError("finalize-run.buffered", e, `type=${item.action === "escalate" ? "policy.escalated" : "policy.action"}`),
+		);
 	for (const item of recoveryLedger.entries)
-		appendEvent(manifest.eventsPath, {
+		appendEventBuffered(manifest.eventsPath, {
 			type: item.state === "escalation_required" ? "recovery.escalated" : "recovery.attempted",
 			runId: manifest.runId,
 			taskId: item.taskId,
@@ -251,7 +253,13 @@ function applyPolicy(manifest: TeamRunManifest, tasks: TeamTaskState[], limits?:
 				attempt: item.attempt,
 				state: item.state,
 			},
-		});
+		}).catch((e) =>
+			logInternalError(
+				"finalize-run.buffered",
+				e,
+				`type=${item.state === "escalation_required" ? "recovery.escalated" : "recovery.attempted"}`,
+			),
+		);
 	return {
 		...manifest,
 		updatedAt: new Date().toISOString(),