pi-crew 0.9.46 → 0.9.48

package/src/runtime/dynamic-workflow-context.ts

@@ -236,9 +236,13 @@ export function synthesizeAgentConfig(name: string, model?: string): AgentConfig
 		description: `Synthesized agent for dynamic workflow (${name}).`,
 		source: "dynamic",
 		filePath: `<dynamic-workflow>`,
-		systemPrompt: `You are ${name}.`,
+		systemPrompt: `You are ${name}, an agent in a dynamic pi-crew workflow. Use the provided tools (read, grep, find, ls, bash) to investigate the target and produce concrete written findings. Do not return an empty response — always output substantive content for your task.`,
 		model,
-		tools: [],
+		// Round-N fix: give synthesized agents the STANDARD file-investigation toolkit
+		// (matches real built-in agents). Previously tools:[] relied on pi-args default
+		// behavior, which left most synthesized agents (explorer/analyst/critic/executor)
+		// unable to read the codebase → 10/11 agents returned empty/!ok in distill-dwf runs.
+		tools: ["read", "grep", "find", "ls", "bash"],
 		inheritProjectContext: false,
 		inheritSkills: false,
 	};
@@ -420,7 +424,7 @@ export function makeWorkflowCtx(manifest: TeamRunManifest, opts: MakeWorkflowCtx
 				// This correctly reduces spent when actualUsage < ESTIMATE.
 				wfState.spent += (parsed.usage?.input ?? 0) + (parsed.usage?.output ?? 0) - ESTIMATE;
 				reserved = false;
-				let text = parsed.finalText ?? "";
+				let text = childResult.rawFinalText || parsed.finalText || "";
 				// Round-11 test fix: parsePiJsonOutput only extracts text from pi event stream
 				// ({type:"message_end", message:{role:"assistant", content:[...]}}). When the
 				// agent emits plain JSON, plain text, or a different format, finalText is empty.

package/src/runtime/dynamic-workflow-runner.ts

@@ -208,7 +208,7 @@ export async function runDynamicWorkflow(input: RunDynamicWorkflowInput): Promis
 		// it does NOT kill the script. Promise.race with a hard timeout at least returns an
 		// error so the runner doesn't hang. The spawned child process is leaked, but the
 		// dynamic-workflow returns failure promptly. (v1.5: use Worker threads to actually kill.)
-		const SCRIPT_TIMEOUT_MS = Number.parseInt(process.env.PI_CREW_DWF_SCRIPT_TIMEOUT_MS ?? "", 10) || 600_000; // 10 min default
+		const SCRIPT_TIMEOUT_MS = Number.parseInt(process.env.PI_CREW_DWF_SCRIPT_TIMEOUT_MS ?? "", 10) || 1_800_000; // 30 min default (was 10 min; raised for distill-dwf + similar long pipelines)
 		let timeoutHandle: NodeJS.Timeout | undefined;
 		const timeoutPromise = new Promise<never>((_, reject) => {
 			timeoutHandle = setTimeout(() => {

package/src/runtime/plan-templates.ts

@@ -140,14 +140,15 @@ registerPlanTemplate({
 		{
 			name: "verify",
 			role: "verifier",
-			taskTemplate: "Verify that all review findings are addressed. Run tests if applicable. Confirm: {{goal}} is achieved.",
+			taskTemplate:
+				"Verify that all review findings are addressed. Run FAST checks (completes in <2 min): `npm run test:critical && npx tsc --noEmit`. Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Confirm: {{goal}} is achieved.",
 			maxTasks: 1,
 			dependsOn: ["review"],
-			verificationCommand: "npm test",
+			verificationCommand: "npm run test:critical && npx tsc --noEmit",
 		},
 	],
 	verificationCommands: {
-		verify: "npm test",
+		verify: "npm run test:critical && npx tsc --noEmit",
 	},
 });
 
@@ -187,13 +188,14 @@ registerPlanTemplate({
 		{
 			name: "verify",
 			role: "verifier",
-			taskTemplate: "Verify the complete implementation of: {{goal}}. Run tests, check types, validate all acceptance criteria.",
+			taskTemplate:
+				"Verify the complete implementation of: {{goal}}. Run FAST checks (`npm run test:critical && npx tsc --noEmit`, completes in <2 min). Do NOT run `npm run test:unit` or `npm test` — too slow for in-loop verification (642 files, >4 min). Validate all acceptance criteria.",
 			maxTasks: 1,
 			dependsOn: ["review"],
-			verificationCommand: "npm test && npx tsc --noEmit",
+			verificationCommand: "npm run test:critical && npx tsc --noEmit",
 		},
 	],
 	verificationCommands: {
-		verify: "npm test && npx tsc --noEmit",
+		verify: "npm run test:critical && npx tsc --noEmit",
 	},
 });

package/src/schema/config-schema.ts

@@ -275,6 +275,19 @@ export const PiTeamsUiConfigSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
+/** Phase 0 inter-pi broker config schema. Numeric limits are bounded per
+ *  the plan: pathHashLen 4..32, maxFrameBytes 1024..1048576 (default 256 KiB),
+ *  outboundQueueCap 32..4096 (default 256). */
+export const CrewBrokerConfigSchema = Type.Object(
+	{
+		enabled: Type.Optional(Type.Boolean()),
+		pathHashLen: Type.Optional(Type.Integer({ minimum: 4, maximum: 32 })),
+		maxFrameBytes: Type.Optional(Type.Integer({ minimum: 1024, maximum: 1_048_576 })),
+		outboundQueueCap: Type.Optional(Type.Integer({ minimum: 32, maximum: 4096 })),
+	},
+	{ additionalProperties: false },
+);
+
 export const PiTeamsConfigSchema = Type.Object(
 	{
 		asyncByDefault: Type.Optional(Type.Boolean()),
@@ -297,6 +310,7 @@ export const PiTeamsConfigSchema = Type.Object(
 		reliability: Type.Optional(PiTeamsReliabilityConfigSchema),
 		otlp: Type.Optional(PiTeamsOtlpConfigSchema),
 		ui: Type.Optional(PiTeamsUiConfigSchema),
+		broker: Type.Optional(CrewBrokerConfigSchema),
 	},
 	{ additionalProperties: false },
 );

package/src/state/mailbox.ts

@@ -14,6 +14,47 @@ export type MailboxMessageKind = "message" | "steer" | "follow-up" | "response"
 export type MailboxMessagePriority = "urgent" | "normal" | "low";
 export type MailboxDeliveryMode = "interrupt" | "next_turn";
 
+// ============================================================================
+// Phase 1.3: post-append observer (single notification point)
+// ============================================================================
+// A registry of callbacks invoked AFTER a durable mailbox append completes
+// (both sync and async paths). The broker registers here to fan out live
+// notifications to connected recipients. The notifier is non-throwing and
+// never blocks the append — it queues work via queueMicrotask so a slow
+// observer cannot stall the mailbox write path. Registration is idempotent.
+
+export type MailboxAppendObserver = (message: MailboxMessage) => void;
+
+const mailboxAppendObservers = new Set<MailboxAppendObserver>();
+
+/** Register a post-append observer. Returns an unsubscribe function. */
+export function registerMailboxAppendObserver(fn: MailboxAppendObserver): () => void {
+	mailboxAppendObservers.add(fn);
+	return () => {
+		mailboxAppendObservers.delete(fn);
+	};
+}
+
+/**
+ * Internal: invoked by appendMailboxMessage[Async] AFTER the durable write +
+ * delivery RMW have completed. Non-throwing; never blocks the caller.
+ */
+function notifyMailboxAppended(message: MailboxMessage): void {
+	if (mailboxAppendObservers.size === 0) return;
+	// Snapshot the message so a later mutation by the caller cannot affect
+	// what the observer sees.
+	const snapshot = { ...message };
+	queueMicrotask(() => {
+		for (const fn of mailboxAppendObservers) {
+			try {
+				fn(snapshot);
+			} catch {
+				/* observer must not break the append path */
+			}
+		}
+	});
+}
+
 export interface MailboxMessage {
 	id: string;
 	runId: string;
@@ -539,6 +580,7 @@ export function appendMailboxMessage(
 		// F4: complete transitions are terminal-ish — keep full durability.
 		writeDeliveryState(manifest, delivery, { durability: "full" });
 	});
+	notifyMailboxAppended(complete);
 	return complete;
 }
 
@@ -647,6 +689,7 @@ export async function appendMailboxMessageAsync(
 		delivery.updatedAt = createdAt;
 		writeDeliveryState(manifest, delivery, { durability: "full" });
 	});
+	notifyMailboxAppended(complete);
 	return complete;
 }
 

package/src/ui/key-utils.ts

@@ -0,0 +1,42 @@
+/**
+ * key-utils.ts — Centralised key matching helpers.
+ *
+ * Pi 0.81+'s TUI input layer (`@earendil-works/pi-tui`) ships a `matchesKey()`
+ * helper that handles multiple terminal key encodings: legacy CSI escapes
+ * (`\x1b[A`), application cursor mode (`\x1bOA`), and Kitty keyboard protocol
+ * variants. Pi-crew components previously compared against raw escape bytes
+ * (`data === "\x1b[A"`), which silently failed on terminals that emit the
+ * alternate encodings. This module wraps `matchesKey` with a single
+ * `keyOf()` helper so overlay code reads naturally while picking up the
+ * terminal-aware match logic for free.
+ *
+ * Returns the canonical KeyId when matchesKey recognises it, otherwise the
+ * raw input string so callers can fall through to ASCII-letter shortcuts.
+ */
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+
+export type PiKeyName = KeyId | string;
+
+const COMMON_IDS: readonly KeyId[] = [
+	"up",
+	"down",
+	"left",
+	"right",
+	"enter",
+	"escape",
+	"tab",
+	"shift+tab",
+	"space",
+	"backspace",
+	"home",
+	"end",
+	"pageUp",
+	"pageDown",
+];
+
+export function keyOf(data: string): KeyId | string {
+	for (const id of COMMON_IDS) {
+		if (matchesKey(data, id)) return id;
+	}
+	return data;
+}

package/src/ui/keybinding-map.ts

@@ -23,9 +23,12 @@
  * `use-global-shortcuts.ts:38-61`.
  */
 
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+import { keyOf } from "./key-utils.ts";
+
 export const DASHBOARD_KEYS = {
-	close: ["q", "\u001b"],
-	select: ["\r", "\n", "s"],
+	close: ["q", "escape", "\u001b"],
+	select: ["enter", "s", "\r", "\n", "tab", "\t", " "],
 	help: ["?"],
 	root: {
 		summary: ["u"],
@@ -48,7 +51,7 @@ export const DASHBOARD_KEYS = {
 		health: ["5"],
 		metrics: ["6"],
 	},
-	navigation: { up: ["k", "\u001b[A"], down: ["j", "\u001b[B"] },
+	navigation: { up: ["k", "up"], down: ["j", "down"] },
 	mailbox: {
 		ack: ["A"],
 		nudge: ["N"],
@@ -214,9 +217,32 @@ export { KEY_RESERVED };
  *                   arg skipped the `activePane === ...` branches).
  */
 export function dashboardActionForKey(data: string, activePane?: ActivePane): DashboardKeyAction | undefined {
+	// Two-pass dispatch to preserve case-sensitivity for plain ASCII keys
+	// while still normalizing escape sequences via matchesKey().
+	//
+	// Background: pi-tui's matchesKey() is case-insensitive, so matchesKey("d",
+	// "D") === true. A single-pass loop that intermixes exact + matchesKey
+	// checks would let the pane-scoped health-diagnostic-export binding
+	// (candidate "D") win over the unscoped agents binding (candidate "d")
+	// when activePane === "health" — collapsing the d/D case distinction.
+	//
+	// Pass 1 — exact string match (case-sensitive). Handles literal ASCII
+	// keystrokes ('d', 'D', 'q', 'S', …) and preserves their distinct meanings.
 	for (const binding of BINDINGS) {
 		if (binding.pane !== undefined && binding.pane !== activePane) continue;
 		if (binding.keys.includes(data)) return binding.action;
 	}
+	// Pass 2 — terminal-aware match for escape sequences / canonical KeyIds.
+	// Only reached when no exact ASCII match exists (data is e.g. '\x1b[A',
+	// '\x1bOA', or an app-cursor-mode variant). Uses matchesKey() to normalize
+	// legacy CSI, app-cursor-mode, and Kitty-protocol variants uniformly.
+	const key = keyOf(data);
+	for (const binding of BINDINGS) {
+		if (binding.pane !== undefined && binding.pane !== activePane) continue;
+		for (const candidate of binding.keys) {
+			if (key === candidate) return binding.action;
+			if (matchesKey(data, candidate as KeyId)) return binding.action;
+		}
+	}
 	return undefined;
 }

package/src/ui/run-dashboard.ts

@@ -401,6 +401,11 @@ function countByStatus(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache
 }
 
 export class RunDashboard implements DashboardComponent {
+	// TEMP DIAGNOSTIC (remove after verifying keybind fix on Pi 0.81.1)
+	private static _instanceCounter = 0;
+	private readonly _instanceId: number;
+	// END TEMP DIAGNOSTIC
+
 	private selected = 0;
 	private runScrollOffset = 0;
 	private showFullProgress = false;
@@ -426,6 +431,14 @@ export class RunDashboard implements DashboardComponent {
 		theme: unknown = {},
 		options: RunDashboardOptions = {},
 	) {
+		// TEMP DIAGNOSTIC: log every constructor + handleInput + focus change
+		this._instanceId = ++RunDashboard._instanceCounter;
+		try {
+			process.stderr.write(
+				`[PI-CREW-DIAG] RunDashboard#${this._instanceId}.constructor runs=${runs.length} workspaceId=${options.workspaceId ?? "n/a"}\n`,
+			);
+		} catch {}
+		// END TEMP DIAGNOSTIC
 		// Filter runs by workspaceId for session isolation
 		// If workspaceId is provided, only show runs owned by that session or runs with no owner (legacy)
 		const filteredRuns = options.workspaceId
@@ -806,7 +819,22 @@ export class RunDashboard implements DashboardComponent {
 		return this.cachedLines;
 	}
 
+	// Pi 0.81+ requires the Focusable contract: a string-indexable `focused`
+	// marker that TUI toggles to track which component currently receives
+	// input. Without it, isFocusable() returns false and downstream
+	// dispatch may skip the component. Declared as an own property so
+	// `"focused" in component` is true.
+	public focused = false;
+
 	handleInput(data: string): void {
+		// TEMP DIAGNOSTIC (remove after verifying keybind fix on Pi 0.81.1)
+		if (process.env.PI_CREW_BROKER_DIAG_UI === "1") {
+			try {
+				process.stderr.write(
+					`[PI-CREW-DIAG] RunDashboard#${this._instanceId}.handleInput data=${JSON.stringify(data)} focused=${this.focused}\n`,
+				);
+			} catch {}
+		}
 		const action = dashboardActionForKey(data, this.activePane);
 		// K-1: "?" toggles the help overlay; while it is shown, any other key
 		// (including Esc) just dismisses it first instead of acting.

package/src/ui/settings-overlay.ts

@@ -6,6 +6,7 @@
 
 import { truncateToWidth, visibleWidth } from "../utils/visual.ts";
 import { DynamicCrewBorder } from "./dynamic-border.ts";
+import { keyOf } from "./key-utils.ts";
 import type { CrewTheme } from "./theme-adapter.ts";
 import { discoverPiThemes, getActivePiTheme } from "./theme-discovery.ts";
 
@@ -410,6 +411,7 @@ function currentValueFor(config: Record<string, unknown>, id: string): unknown {
 // ---------------------------------------------------------------------------
 
 class SelectSubmenu {
+	public focused = false;
 	private selectedIndex = 0;
 	private scrollOffset = 0;
 	private readonly maxVisible = 14;
@@ -479,21 +481,25 @@ class SelectSubmenu {
 	}
 
 	handleInput(data: string): void {
-		if (data === "\x1b[A" || data === "k") {
+		// Use keyOf() so that upstream Arrow / Esc encodings (legacy CSI,
+		// application cursor mode, Kitty protocol) all dispatch correctly.
+		// See key-utils.ts for details.
+		const k = keyOf(data);
+		if (k === "up" || k === "k") {
 			this.selectedIndex = (this.selectedIndex - 1 + this.items.length) % this.items.length;
 			this.ensureVisible();
 			return;
 		}
-		if (data === "\x1b[B" || data === "j") {
+		if (k === "down" || k === "j") {
 			this.selectedIndex = (this.selectedIndex + 1) % this.items.length;
 			this.ensureVisible();
 			return;
 		}
-		if (data === "\r" || data === "\n") {
+		if (k === "enter") {
 			this.onSelect(this.items[this.selectedIndex]!);
 			return;
 		}
-		if (data === "\x1b" || data === "q") {
+		if (k === "escape" || k === "q") {
 			this.onCancel();
 			return;
 		}
@@ -505,6 +511,7 @@ class SelectSubmenu {
 // ---------------------------------------------------------------------------
 
 class TextinputSubmenu {
+	public focused = false;
 	private buffer = "";
 	private readonly title: string;
 	private readonly description: string;
@@ -544,16 +551,17 @@ class TextinputSubmenu {
 	}
 
 	handleInput(data: string): void {
-		if (data === "\r" || data === "\n") {
+		const k = keyOf(data);
+		if (k === "enter") {
 			this.onSubmit(this.buffer);
 			return;
 		}
-		if (data === "\x1b" || data === "q") {
+		if (k === "escape" || k === "q") {
 			this.onCancel();
 			return;
 		}
 		// Backspace
-		if (data === "\x7f" || data === "\b") {
+		if (data === "\x7f" || data === "\b" || k === "backspace") {
 			this.buffer = this.buffer.slice(0, -1);
 			return;
 		}
@@ -570,6 +578,7 @@ class TextinputSubmenu {
 // ---------------------------------------------------------------------------
 
 class AgentOverridesSubmenu {
+	public focused = false;
 	private readonly overrides: Record<string, { model?: string; thinking?: string }>;
 	private readonly theme: CrewTheme;
 	private readonly agents: string[];
@@ -654,15 +663,16 @@ class AgentOverridesSubmenu {
 	handleInput(data: string): void {
 		if (this.editField) return this.handleEditInput(data);
 
-		if (data === "\x1b[A" || data === "k") {
+		const k = keyOf(data);
+		if (k === "up" || k === "k") {
 			this.selectedIndex = (this.selectedIndex - 1 + this.agents.length) % this.agents.length;
 			return;
 		}
-		if (data === "\x1b[B" || data === "j") {
+		if (k === "down" || k === "j") {
 			this.selectedIndex = (this.selectedIndex + 1) % this.agents.length;
 			return;
 		}
-		if (data === "\r" || data === "\n") {
+		if (k === "enter") {
 			const agent = this.agents[this.selectedIndex]!;
 			this.editField = "model";
 			this.editBuffer = this.overrides[agent]?.model ?? "";
@@ -674,14 +684,15 @@ class AgentOverridesSubmenu {
 			this.editBuffer = this.overrides[agent]?.thinking ?? "";
 			return;
 		}
-		if (data === "\x1b") {
+		if (k === "escape") {
 			this.onCancel();
 			return;
 		}
 	}
 
 	private handleEditInput(data: string): void {
-		if (data === "\r" || data === "\n") {
+		const k = keyOf(data);
+		if (k === "enter") {
 			const agent = this.agents[this.selectedIndex]!;
 			if (!this.overrides[agent]) this.overrides[agent] = {};
 			if (this.editField === "model") {
@@ -696,11 +707,11 @@ class AgentOverridesSubmenu {
 			this.editField = null;
 			return;
 		}
-		if (data === "\x1b") {
+		if (k === "escape") {
 			this.editField = null;
 			return;
 		}
-		if (data === "\x7f" || data === "\b") {
+		if (data === "\x7f" || data === "\b" || k === "backspace") {
 			this.editBuffer = this.editBuffer.slice(0, -1);
 			return;
 		}
@@ -718,6 +729,10 @@ class SettingsOverlay {
 	private config: Record<string, unknown>;
 	private theme: CrewTheme;
 	private callbacks: SettingsOverlayCallbacks;
+	// Pi 0.81+ Focusable contract — see RunDashboard. Same reasoning: without
+	// `focused` as an own property, isFocusable() returns false and keybind
+	// dispatch may skip the overlay.
+	public focused = false;
 	private currentTabIndex = 0;
 	private selectedIndex = 0;
 	private scrollOffset = 0;
@@ -844,6 +859,10 @@ class SettingsOverlay {
 	}
 
 	handleInput(data: string): void {
+		// Route through keyOf() so upstream Arrow/Esc/Tab/Enter encodings
+		// (legacy CSI, application cursor mode, Kitty protocol, shift-modifier
+		// variants) are all recognized. See key-utils.ts.
+		const k = keyOf(data);
 		// Submenu takes priority
 		if (this.submenu) {
 			this.submenu.handleInput(data);
@@ -851,19 +870,19 @@ class SettingsOverlay {
 		}
 
 		// Escape closes overlay
-		if (data === "\x1b" || data === "q") {
+		if (k === "escape" || k === "q") {
 			this.callbacks.onClose();
 			return;
 		}
 
-		// Tab navigation
-		if (data === "\t" || data === "\x1b[C") {
+		// Tab navigation — tab (forward) + shift+tab (backtab)
+		if (k === "tab") {
 			this.currentTabIndex = (this.currentTabIndex + 1) % TABS.length;
 			this.selectedIndex = 0;
 			this.scrollOffset = 0;
 			return;
 		}
-		if (data === "Z" || data === "\x1b[D") {
+		if (k === "shift+tab") {
 			this.currentTabIndex = (this.currentTabIndex - 1 + TABS.length) % TABS.length;
 			this.selectedIndex = 0;
 			this.scrollOffset = 0;
@@ -874,19 +893,20 @@ class SettingsOverlay {
 		const tabId = TABS[this.currentTabIndex]?.id ?? "runtime";
 		const settings = SETTINGS.filter((s) => s.tab === tabId);
 
-		if (data === "\x1b[A" || data === "k") {
+		if (k === "up" || k === "k") {
 			this.selectedIndex = Math.max(0, this.selectedIndex - 1);
 			this.ensureVisible(settings.length);
 			return;
 		}
-		if (data === "\x1b[B" || data === "j") {
+		if (k === "down" || k === "j") {
 			this.selectedIndex = Math.min(settings.length - 1, this.selectedIndex + 1);
 			this.ensureVisible(settings.length);
 			return;
 		}
 
-		// Activate item
-		if (data === "\r" || data === "\n" || data === " ") {
+		// Activate item — Enter, Space, or Space-bar; matchesKey unifies carriage
+		// return / newline / spacebar as the same key family.
+		if (k === "enter" || k === "space") {
 			this.activateItem(settings);
 		}
 	}

package/src/utils/ndjson.ts

@@ -0,0 +1,115 @@
+/**
+ * ndjson.ts — Canonical broker NDJSON framing primitives (encoder + decoder
+ *              + typed errors). Newline-delimited JSON, one frame per `\\n`.
+ *
+ * Moved out of the parallel-work stub `src/runtime/crew-broker-deps.ts`.
+ * The public surface (MAX_BROKER_FRAME_BYTES, BrokerError, BrokerErrorCode,
+ * encodeBrokerFrame, NdjsonDecoder) is preserved verbatim so importers
+ * can be updated with a single import-path change.
+ *
+ * No internal dependencies on other src/ modules — only Node built-ins.
+ */
+
+/** Maximum encoded NDJSON frame size in UTF-8 bytes, INCLUDING the trailing `\n`. */
+export const MAX_BROKER_FRAME_BYTES = 256 * 1024;
+
+// ============================================================================
+// BrokerError — typed protocol errors
+// ============================================================================
+
+export type BrokerErrorCode = "oversize-frame" | "auth" | "protocol" | "timeout" | "close" | "not-implemented" | "rate-limit";
+
+export class BrokerError extends Error {
+	readonly code: BrokerErrorCode;
+	constructor(code: BrokerErrorCode, message: string) {
+		super(message);
+		this.name = "BrokerError";
+		this.code = code;
+	}
+}
+
+// ============================================================================
+// NDJSON encoder
+// ============================================================================
+
+/**
+ * Encode a value as a single NDJSON frame (one JSON object terminated by `\n`).
+ * Rejects values whose encoded byte length exceeds MAX_BROKER_FRAME_BYTES BEFORE
+ * returning. Throws BrokerError("oversize-frame") for over-size payloads.
+ */
+export function encodeBrokerFrame(value: unknown): Buffer {
+	// Stringify with replacer to drop undefined/function values (matches JSON.stringify semantics).
+	const json = JSON.stringify(value);
+	if (json === undefined) {
+		// Cannot encode (e.g. circular) — surface a typed protocol error.
+		throw new BrokerError("protocol", "encodeBrokerFrame: value is not JSON-serializable");
+	}
+	const enc = Buffer.from(json, "utf8");
+	// +1 for the trailing '\n'.
+	if (enc.length + 1 > MAX_BROKER_FRAME_BYTES) {
+		throw new BrokerError("oversize-frame", `frame exceeds ${MAX_BROKER_FRAME_BYTES} bytes (got ${enc.length + 1})`);
+	}
+	const out = Buffer.allocUnsafe(enc.length + 1);
+	enc.copy(out);
+	out[enc.length] = 0x0a; // '\n'
+	return out;
+}
+
+// ============================================================================
+// NDJSON decoder
+// ============================================================================
+
+/** Cap the partial-frame accumulator to 2 * MAX_BROKER_FRAME_BYTES. Beyond that
+ *  we surface oversize-frame and let the caller close. The 2x headroom is
+ *  enough to assemble one full frame from chunks of any size. */
+const MAX_DECODER_BUFFER = 2 * MAX_BROKER_FRAME_BYTES;
+
+export class NdjsonDecoder {
+	private buffer: Buffer = Buffer.alloc(0);
+
+	/**
+	 * Push a chunk; return the array of complete parsed values (each was
+	 * followed by a `\n` in the stream). May return zero items (no full
+	 * frame yet), one item, or many items. Malformed JSON throws
+	 * BrokerError("protocol"); over-size accumulated buffer throws
+	 * BrokerError("oversize-frame"). Callers must catch and close the socket.
+	 */
+	push(chunk: Buffer): unknown[] {
+		if (chunk.length === 0) return [];
+		this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+		if (this.buffer.length > MAX_DECODER_BUFFER) {
+			throw new BrokerError("oversize-frame", `decoder buffer exceeded ${MAX_DECODER_BUFFER} bytes`);
+		}
+		const out: unknown[] = [];
+		let idx = this.buffer.indexOf(0x0a);
+		while (idx !== -1) {
+			const line = this.buffer.subarray(0, idx);
+			// Empty lines are skipped (lenient — mirrors herdr/NDJSON practice).
+			if (line.length > 0) {
+				// Reject an oversize LINE before parse.
+				if (line.length > MAX_BROKER_FRAME_BYTES) {
+					throw new BrokerError("oversize-frame", `line exceeds ${MAX_BROKER_FRAME_BYTES} bytes (got ${line.length})`);
+				}
+				try {
+					out.push(JSON.parse(line.toString("utf8")));
+				} catch (cause) {
+					throw new BrokerError("protocol", `ndjson: malformed JSON: ${(cause as Error).message}`);
+				}
+			}
+			// Advance past the consumed line + newline.
+			this.buffer = this.buffer.subarray(idx + 1);
+			idx = this.buffer.indexOf(0x0a);
+		}
+		return out;
+	}
+
+	reset(): void {
+		this.buffer = Buffer.alloc(0);
+	}
+}
+
+// ============================================================================
+// External re-exports
+// ============================================================================
+// Re-exported here for callers that import all broker primitives from ndjson.ts.
+export { newBrokerToken } from "../runtime/crew-broker-tokens.ts";

package/src/utils/session-utils.ts

@@ -78,3 +78,33 @@ export function extractSessionId(ctx: unknown): string | undefined {
 	if (typeof raw !== "string" || raw.length === 0) return undefined;
 	return raw;
 }
+
+/**
+ * Broker-only session id extractor.
+ *
+ * Pi's `ExtensionContext` does NOT expose a top-level `sessionId` property on
+ * its public surface — the id is reachable via `ctx.sessionManager.getSessionId()`.
+ * This helper is only called from `installCrewBrokerLifecycleController.setSessionId`
+ * (once per session_start), so the extra method invocation is safe here. It is
+ * INTENTIONALLY a separate function from `extractSessionId`, which is called on
+ * every `context` event (before every LLM call) from `context-status-injection.ts`
+ * — extending that hot path with method calls was observed to freeze the TUI
+ * (dashboard opens but is unresponsive, footer does not render) during smoke
+ * testing, so it stays on the trivial property lookup.
+ *
+ * Tries the sessionManager path first, then falls back to a direct
+ * `ctx.sessionId` for test mock compatibility.
+ */
+export function extractBrokerSessionId(ctx: unknown): string | undefined {
+	if (typeof ctx !== "object" || ctx === null) return undefined;
+	try {
+		const sm = (ctx as { sessionManager?: { getSessionId?: () => unknown } }).sessionManager;
+		const viaManager = sm?.getSessionId?.();
+		if (typeof viaManager === "string" && viaManager.length > 0) return viaManager;
+		const direct = Object.getOwnPropertyDescriptor(ctx, "sessionId")?.value;
+		if (typeof direct === "string" && direct.length > 0) return direct;
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}