pi-crew 0.9.7 → 0.9.9

package/src/skills/validate.ts

@@ -0,0 +1,267 @@
+/**
+ * SKILL.md frontmatter validation (L3 of deer-flow→pi-crew plan).
+ *
+ * Parses a SKILL.md's YAML frontmatter and validates it against the
+ * `ALLOWED_SKILL_PROPS` whitelist using HYBRID policy:
+ *   - HARD errors (missing/malformed `name`/`description`, type mismatches,
+ *     read/parse failures): EXCLUDE the skill from `discoverSkills()`.
+ *   - SOFT warnings (unknown props, missing `name` derived from directory):
+ *     KEEP the skill; surface via `getLastDiscoveryDiagnostics()`.
+ *
+ * YAML parsing uses the `yaml` package (^2.9.0). It is now a direct dep;
+ * before L3 it was only transitively available through
+ * `@earendil-works/pi-coding-agent`. Adding it as a direct dep is justified by:
+ *   - Replaces a fragile line-prefix parser that broke on multi-line folded
+ *     scalars (`description: >`), quoted strings, and nested YAML.
+ *   - Standard lib (eemeli/yaml), MIT, actively maintained.
+ *   - Already in the lockfile at the same version → zero install cost.
+ *   - Frontmatter is small and well-formed; YAML parsing cost is negligible.
+ *
+ * The validator runs once per skill at discovery. Discovery is already cached
+ * (`CACHE_TTL_MS = 30_000` in discover-skills.ts) so the validation cost is
+ * bounded regardless of how many skills exist.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "yaml";
+
+/**
+ * Properties allowed in SKILL.md frontmatter.
+ *
+ * Why this list:
+ *   - `name`, `description` are the contract used by pi-crew's prompt
+ *     rendering (see src/runtime/skill-instructions.ts) and capability
+ *     inventory. Both are HARD-required.
+ *   - `license`, `allowed-tools`, `compatibility`, `version`, `author` are
+ *     common metadata; we surface but don't enforce content beyond type.
+ *   - `metadata` is a free-form key/value bag (mirrors deer-flow `validation.py`).
+ *
+ * Unknown props (e.g. bundled skills' `origin`, `triggers`) are SOFT-warned,
+ * not rejected — see HYBRID policy in the module docstring.
+ */
+export const ALLOWED_SKILL_PROPS = new Set<string>([
+	"name",
+	"description",
+	"license",
+	"allowed-tools",
+	"metadata",
+	"compatibility",
+	"version",
+	"author",
+]);
+
+/** Hyphen-case name regex (Anthropic Agent Skills spec compatible). */
+const NAME_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const NAME_MAX_LEN = 64;
+const DESCRIPTION_MAX_LEN = 1024;
+const VERSION_REGEX = /^\d+\.\d+(\.\d+)?(-[A-Za-z0-9.-]+)?$/;
+
+/**
+ * Structured error so callers (capability inventory, logs) can present
+ * actionable diagnostics instead of silently dropping malformed skills.
+ */
+export interface SkillValidationError {
+	/** Absolute path to the skill directory. */
+	path: string;
+	/** Field name (e.g. "name", "description", "<unknown-prop>") or "frontmatter" for parse errors. */
+	field: string;
+	/** Human-readable reason. Safe to surface in capability listings. */
+	reason: string;
+	/** Severity — "error" excludes the skill; "warn" keeps it. */
+	severity: "error" | "warn";
+}
+
+/**
+ * Validated manifest exposes the parsed frontmatter fields in a typed shape.
+ * Only present for valid skills; undefined for invalid ones.
+ */
+export interface ValidatedSkillManifest {
+	name: string;
+	description: string;
+	license?: string;
+	allowedTools?: string[];
+	metadata?: Record<string, unknown>;
+	compatibility?: string;
+	version?: string;
+	author?: string;
+}
+
+export interface ValidationResult {
+	ok: boolean;
+	errors: SkillValidationError[];
+	manifest?: ValidatedSkillManifest;
+}
+
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ *
+ * Returns an empty object when there is no frontmatter block. Parsing errors
+ * surface as `{ ok: false }` rather than throwing — discovery must remain
+ * exception-safe.
+ */
+export function parseSkillFrontmatter(
+	content: string,
+): { ok: true; data: Record<string, unknown> } | { ok: false; error: string } {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match) return { ok: true, data: {} };
+	try {
+		const parsed = yaml.parse(match[1]);
+		if (parsed === null || parsed === undefined) return { ok: true, data: {} };
+		if (typeof parsed !== "object" || Array.isArray(parsed)) {
+			return { ok: false, error: "Frontmatter must be a YAML mapping, not a scalar or list." };
+		}
+		return { ok: true, data: parsed as Record<string, unknown> };
+	} catch (e) {
+		return { ok: false, error: `YAML parse error: ${(e as Error).message}` };
+	}
+}
+
+function hard(path: string, field: string, reason: string): SkillValidationError {
+	return { path, field, reason, severity: "error" };
+}
+
+function warn(path: string, field: string, reason: string): SkillValidationError {
+	return { path, field, reason, severity: "warn" };
+}
+
+/**
+ * Validate a single skill's frontmatter.
+ *
+ * @param skillDir Absolute path to the skill directory (must contain SKILL.md).
+ * @returns ValidationResult — `ok` is true when there are no HARD errors.
+ *          `errors[]` always lists ALL violations (HARD + SOFT).
+ *
+ * Back-compat: when `name` is missing from frontmatter, the validator
+ * DERIVES it from the directory name and emits a SOFT warning. Bundled
+ * pi-crew skills always set `name` explicitly, so the warning is informational.
+ */
+export function validateSkillFrontmatter(skillDir: string): ValidationResult {
+	const errors: SkillValidationError[] = [];
+	const skillMdPath = path.join(skillDir, "SKILL.md");
+	const derivedName = path.basename(skillDir);
+
+	let content: string;
+	try {
+		content = fs.readFileSync(skillMdPath, "utf-8");
+	} catch (e) {
+		errors.push(hard(skillDir, "SKILL.md", `Cannot read SKILL.md: ${(e as Error).message}`));
+		return { ok: false, errors };
+	}
+
+	const parsed = parseSkillFrontmatter(content);
+	if (!parsed.ok) {
+		errors.push(hard(skillDir, "frontmatter", parsed.error));
+		return { ok: false, errors };
+	}
+
+	const data = parsed.data;
+
+	// No frontmatter at all → back-compat: derive everything from the
+	// directory. Pre-L3 skills shipped without frontmatter and we don't want
+	// to regress them. Surface a SOFT warning so authors know to add YAML.
+	if (Object.keys(data).length === 0) {
+		errors.push(warn(skillDir, "frontmatter", "No frontmatter block; deriving name from directory and leaving description empty."));
+		return {
+			ok: true,
+			errors,
+			manifest: { name: derivedName, description: "" },
+		};
+	}
+
+	// ── name: HARD if type/length/regex bad; SOFT if missing (derive from dir)
+	const nameRaw = data.name;
+	let resolvedName = derivedName;
+	if (nameRaw === undefined || nameRaw === null) {
+		errors.push(warn(skillDir, "name", `Frontmatter 'name' missing; using directory name "${derivedName}" as fallback. Add explicit 'name' to silence this.`));
+	} else if (typeof nameRaw !== "string") {
+		errors.push(hard(skillDir, "name", `'name' must be a string, got ${typeof nameRaw}.`));
+	} else if (nameRaw.length === 0) {
+		errors.push(hard(skillDir, "name", "'name' is empty."));
+	} else if (nameRaw.length > NAME_MAX_LEN) {
+		errors.push(hard(skillDir, "name", `'name' exceeds ${NAME_MAX_LEN} chars (got ${nameRaw.length}).`));
+	} else if (!NAME_REGEX.test(nameRaw)) {
+		errors.push(hard(skillDir, "name", `'name' must be hyphen-case lowercase (a-z, 0-9, single hyphens); got "${nameRaw}".`));
+	} else {
+		resolvedName = nameRaw;
+	}
+
+	// ── description: HARD required
+	const descRaw = data.description;
+	if (descRaw === undefined || descRaw === null) {
+		errors.push(hard(skillDir, "description", "Required field 'description' is missing."));
+	} else if (typeof descRaw !== "string") {
+		errors.push(hard(skillDir, "description", `'description' must be a string, got ${typeof descRaw}.`));
+	} else if (descRaw.length > DESCRIPTION_MAX_LEN) {
+		errors.push(hard(skillDir, "description", `'description' exceeds ${DESCRIPTION_MAX_LEN} chars (got ${descRaw.length}).`));
+	} else if (descRaw.includes("<") || descRaw.includes(">")) {
+		errors.push(hard(skillDir, "description", `'description' must not contain '<' or '>' (prompt-safety).`));
+	}
+
+	// ── OPTIONAL: license
+	if (data.license !== undefined && typeof data.license !== "string") {
+		errors.push(hard(skillDir, "license", `'license' must be a string.`));
+	}
+
+	// ── OPTIONAL: allowed-tools
+	if (data["allowed-tools"] !== undefined) {
+		const at = data["allowed-tools"];
+		if (!Array.isArray(at) || !at.every((x) => typeof x === "string")) {
+			errors.push(hard(skillDir, "allowed-tools", `'allowed-tools' must be an array of strings.`));
+		}
+	}
+
+	// ── OPTIONAL: metadata
+	if (data.metadata !== undefined) {
+		const m = data.metadata;
+		if (typeof m !== "object" || m === null || Array.isArray(m)) {
+			errors.push(hard(skillDir, "metadata", `'metadata' must be an object.`));
+		}
+	}
+
+	// ── OPTIONAL: compatibility
+	if (data.compatibility !== undefined && typeof data.compatibility !== "string") {
+		errors.push(hard(skillDir, "compatibility", `'compatibility' must be a string.`));
+	}
+
+	// ── OPTIONAL: version
+	if (data.version !== undefined) {
+		if (typeof data.version !== "string" || !VERSION_REGEX.test(data.version)) {
+			errors.push(hard(skillDir, "version", `'version' must be a semver string (e.g. "1.2.3" or "1.2.3-beta.1"); got "${String(data.version)}".`));
+		}
+	}
+
+	// ── OPTIONAL: author
+	if (data.author !== undefined && typeof data.author !== "string") {
+		errors.push(hard(skillDir, "author", `'author' must be a string.`));
+	}
+
+	// ── UNKNOWN PROPS: SOFT warn (HYBRID policy)
+	for (const key of Object.keys(data)) {
+		if (!ALLOWED_SKILL_PROPS.has(key)) {
+			errors.push(warn(skillDir, `<unknown-prop:${key}>`, `Unknown property '${key}' is not in the whitelist; keeping for forward-compat.`));
+		}
+	}
+
+	// ── Result: ok iff no HARD errors
+	const hasHardError = errors.some((e) => e.severity === "error");
+	if (!hasHardError) {
+		const manifest: ValidatedSkillManifest = {
+			name: resolvedName,
+			description: typeof data.description === "string" ? data.description : "",
+		};
+		if (typeof data.license === "string") manifest.license = data.license;
+		if (Array.isArray(data["allowed-tools"])) {
+			manifest.allowedTools = (data["allowed-tools"] as unknown[]).filter((x) => typeof x === "string") as string[];
+		}
+		if (typeof data.metadata === "object" && data.metadata !== null && !Array.isArray(data.metadata)) {
+			manifest.metadata = data.metadata as Record<string, unknown>;
+		}
+		if (typeof data.compatibility === "string") manifest.compatibility = data.compatibility;
+		if (typeof data.version === "string") manifest.version = data.version;
+		if (typeof data.author === "string") manifest.author = data.author;
+		return { ok: true, errors, manifest };
+	}
+
+	return { ok: false, errors };
+}

package/src/state/types.ts

@@ -3,6 +3,7 @@ import type { TaskClaimState } from "./task-claims.ts";
 import type { WorkerHeartbeatState } from "../runtime/worker-heartbeat.ts";
 import type { CrewAgentProgress } from "../runtime/crew-agent-runtime.ts";
 import type { RolloutEntry, CoherenceMark } from "./decision-ledger.ts";
+import type { CrashClass } from "../runtime/crash-classification.ts";
 export type { RolloutEntry, CoherenceMark };
 export type { CrewAgentProgress };
 
@@ -116,6 +117,10 @@ export interface WorkerExitStatus {
 	signal?: string;
 	cleanupErrors: string[];
 	finalDrainMs: number;
+	/** Categorical classification of the exit (P0 crash taxonomy). Optional
+	 *  because it is populated by child-pi.ts at settle time; older/synthetic
+	 *  exit statuses may omit it. */
+	crashClass?: CrashClass;
 	/** Phase-0 diagnostic (HB-003a): final-drain race state for the exit-null
 	 *  disableTools bug. Optional + read-only — absent when no drain timer was
 	 *  ever armed. Phase 1 will use `finalDrainArmed` to decide whether a

package/src/ui/keybinding-map.ts

@@ -1,3 +1,28 @@
+/**
+ * Dashboard keybinding map (L2 refactor: data-driven dispatch).
+ *
+ * Before L2 this module exposed `DASHBOARD_KEYS` (a data table) but dispatched
+ * via a 30-line `if (includes(...)) return "..."` chain — adding a key meant
+ * editing BOTH the table AND the dispatch, a DRY violation. L2 collapses the
+ * dispatch into a single `for (const b of BINDINGS)` loop driven by the
+ * `BINDINGS` table below. `DASHBOARD_KEYS` is retained as the raw key data so
+ * existing imports and the dead-but-intentional `KEY_RESERVED` set keep working.
+ *
+ * Recalibration vs. the original L2 plan: the plan also called for an
+ * `inTextInput` guard to prevent letter-key leaks into TUI text inputs.
+ * Verified during implementation that this is NOT needed — overlays are
+ * mutually exclusive and each has its own `handleInput`. `mailbox-compose-overlay.ts:111`
+ * captures every single-char key via `appendText(data)` and never delegates to
+ * `dashboardActionForKey`, so there is no leak path. Adding the guard would
+ * complicate the API (`run-dashboard.ts:485` has no text-input state to pass)
+ * for zero benefit. The input-guard half of L2 is therefore intentionally
+ * skipped; only the DRY/data-driven dispatch refactor landed.
+ *
+ * Origin pattern: deer-flow `frontend/src/components/workspace/command-palette.tsx:39-50`
+ * drives shortcuts from a single data array consumed by one loop in
+ * `use-global-shortcuts.ts:38-61`.
+ */
+
 export const DASHBOARD_KEYS = {
 	close: ["q", "\u001b"],
 	select: ["\r", "\n", "s"],
@@ -21,20 +46,23 @@ export const DASHBOARD_KEYS = {
 	notification: { dismissAll: ["H"] },
 } as const;
 
-/** @internal */
-const KEY_RESERVED = new Set<string>([
-	...DASHBOARD_KEYS.close,
-	...DASHBOARD_KEYS.select,
-	...Object.values(DASHBOARD_KEYS.root).flat(),
-	...Object.values(DASHBOARD_KEYS.pane).flat(),
-	...Object.values(DASHBOARD_KEYS.navigation).flat(),
-	...Object.values(DASHBOARD_KEYS.mailbox).flat(),
-	...Object.values(DASHBOARD_KEYS.health).flat(),
-	...Object.values(DASHBOARD_KEYS.notification).flat(),
-]);
+/**
+ * Pane identifiers that can scope a binding. `undefined` means the binding
+ * fires in every pane.
+ */
+export type ActivePane = "agents" | "progress" | "mailbox" | "output" | "health" | "metrics";
 
-function includes(values: readonly string[], data: string): boolean {
-	return values.includes(data);
+/**
+ * A single keybinding: the keys that trigger it, the action it produces, and
+ * an optional pane restriction. The dispatch loop returns the FIRST matching
+ * binding, so table ORDER IS SIGNIFICANT and must mirror the old if-chain
+ * precedence (pane-specific overrides before their generic competitors).
+ */
+export interface KeyBinding {
+	readonly keys: readonly string[];
+	readonly action: DashboardKeyAction;
+	/** When set, the binding only fires when `activePane === pane`. */
+	readonly pane?: ActivePane;
 }
 
 export type DashboardKeyAction =
@@ -65,34 +93,93 @@ export type DashboardKeyAction =
 	| "health-diagnostic-export"
 	| "notifications-dismiss";
 
-export function dashboardActionForKey(data: string, activePane?: "agents" | "progress" | "mailbox" | "output" | "health" | "metrics"): DashboardKeyAction | undefined {
-	if (includes(DASHBOARD_KEYS.close, data)) return "close";
-	if (activePane === "mailbox" && includes(DASHBOARD_KEYS.mailbox.openDetail, data)) return "mailbox-detail";
-	if (activePane === "health") {
-		if (includes(DASHBOARD_KEYS.health.recovery, data)) return "health-recovery";
-		if (includes(DASHBOARD_KEYS.health.killStale, data)) return "health-kill-stale";
-		if (includes(DASHBOARD_KEYS.health.diagnosticExport, data)) return "health-diagnostic-export";
+/**
+ * The dispatch table. ORDER MATTERS — first match wins.
+ *
+ * Precedence notes (must match the pre-L2 if-chain exactly):
+ *   1. `close` always wins (q / Esc).
+ *   2. `mailbox-detail` (\r, \n) is pane-scoped to mailbox and MUST precede
+ *      `select` (which also binds \r, \n) so Enter opens the detail instead of
+ *      triggering select while in the mailbox pane.
+ *   3. `health-*` are pane-scoped to health.
+ *   4. `notifications-dismiss` (H) is global.
+ *   5. `select`, then the root actions, pane switches, and navigation.
+ *
+ * NOTE: mailbox action keys A/N/C/P/X (ack/nudge/compose/preview/ackAll) are
+ * intentionally NOT in this table. They live in `DASHBOARD_KEYS.mailbox` for
+ * reservation but are handled by the mailbox overlay's own `handleInput`,
+ * not by the dashboard dispatch. Adding them here would change behavior.
+ */
+const BINDINGS: readonly KeyBinding[] = [
+	{ keys: DASHBOARD_KEYS.close, action: "close" },
+	{ keys: DASHBOARD_KEYS.mailbox.openDetail, action: "mailbox-detail", pane: "mailbox" },
+	{ keys: DASHBOARD_KEYS.health.recovery, action: "health-recovery", pane: "health" },
+	{ keys: DASHBOARD_KEYS.health.killStale, action: "health-kill-stale", pane: "health" },
+	{ keys: DASHBOARD_KEYS.health.diagnosticExport, action: "health-diagnostic-export", pane: "health" },
+	{ keys: DASHBOARD_KEYS.notification.dismissAll, action: "notifications-dismiss" },
+	{ keys: DASHBOARD_KEYS.select, action: "select" },
+	{ keys: DASHBOARD_KEYS.root.summary, action: "summary" },
+	{ keys: DASHBOARD_KEYS.root.artifacts, action: "artifacts" },
+	{ keys: DASHBOARD_KEYS.root.api, action: "api" },
+	{ keys: DASHBOARD_KEYS.root.agents, action: "agents" },
+	{ keys: DASHBOARD_KEYS.root.mailbox, action: "mailbox" },
+	{ keys: DASHBOARD_KEYS.root.events, action: "events" },
+	{ keys: DASHBOARD_KEYS.root.output, action: "output" },
+	{ keys: DASHBOARD_KEYS.root.transcript, action: "transcript" },
+	{ keys: DASHBOARD_KEYS.root.liveConversation, action: "live-conversation" },
+	{ keys: DASHBOARD_KEYS.root.reload, action: "reload" },
+	{ keys: DASHBOARD_KEYS.root.progressToggle, action: "progressToggle" },
+	{ keys: DASHBOARD_KEYS.pane.agents, action: "pane-agents" },
+	{ keys: DASHBOARD_KEYS.pane.progress, action: "pane-progress" },
+	{ keys: DASHBOARD_KEYS.pane.mailbox, action: "pane-mailbox" },
+	{ keys: DASHBOARD_KEYS.pane.output, action: "pane-output" },
+	{ keys: DASHBOARD_KEYS.pane.health, action: "pane-health" },
+	{ keys: DASHBOARD_KEYS.pane.metrics, action: "pane-metrics" },
+	{ keys: DASHBOARD_KEYS.navigation.up, action: "up" },
+	{ keys: DASHBOARD_KEYS.navigation.down, action: "down" },
+];
+
+/**
+ * Reserved keys — every key the dashboard claims, including mailbox/health
+ * action keys that are NOT dispatched here but are handled by their own
+ * overlays. Derived from `DASHBOARD_KEYS` (the full key set) rather than from
+ * `BINDINGS` (the dispatched subset) so overlay-handled keys stay reserved.
+ *
+ * @internal Currently unused outside this module but retained to document
+ * intent and support future callers that need to know which keys the
+ * dashboard ecosystem owns.
+ */
+const KEY_RESERVED = new Set<string>([
+	...DASHBOARD_KEYS.close,
+	...DASHBOARD_KEYS.select,
+	...Object.values(DASHBOARD_KEYS.root).flat(),
+	...Object.values(DASHBOARD_KEYS.pane).flat(),
+	...Object.values(DASHBOARD_KEYS.navigation).flat(),
+	...Object.values(DASHBOARD_KEYS.mailbox).flat(),
+	...Object.values(DASHBOARD_KEYS.health).flat(),
+	...Object.values(DASHBOARD_KEYS.notification).flat(),
+]);
+
+export { KEY_RESERVED };
+
+/**
+ * Resolve a raw input `data` string to a dashboard action.
+ *
+ * Data-driven dispatch: iterates `BINDINGS` in order and returns the action of
+ * the first binding whose `keys` contain `data` and whose optional `pane`
+ * restriction matches `activePane`. Behavior is identical to the pre-L2
+ * if-chain (verified by `test/unit/keybinding-map.parity.test.ts`).
+ *
+ * @param data Raw key input (single char or escape sequence).
+ * @param activePane Currently focused pane; pane-scoped bindings only fire
+ *                   when this matches. `undefined` disables all pane-scoped
+ *                   bindings (matching the old behavior where omitting the
+ *                   arg skipped the `activePane === ...` branches).
+ */
+export function dashboardActionForKey(data: string, activePane?: ActivePane): DashboardKeyAction | undefined {
+	for (const binding of BINDINGS) {
+		if (binding.pane !== undefined && binding.pane !== activePane) continue;
+		if (binding.keys.includes(data)) return binding.action;
 	}
-	if (includes(DASHBOARD_KEYS.notification.dismissAll, data)) return "notifications-dismiss";
-	if (includes(DASHBOARD_KEYS.select, data)) return "select";
-	if (includes(DASHBOARD_KEYS.root.summary, data)) return "summary";
-	if (includes(DASHBOARD_KEYS.root.artifacts, data)) return "artifacts";
-	if (includes(DASHBOARD_KEYS.root.api, data)) return "api";
-	if (includes(DASHBOARD_KEYS.root.agents, data)) return "agents";
-	if (includes(DASHBOARD_KEYS.root.mailbox, data)) return "mailbox";
-	if (includes(DASHBOARD_KEYS.root.events, data)) return "events";
-	if (includes(DASHBOARD_KEYS.root.output, data)) return "output";
-	if (includes(DASHBOARD_KEYS.root.transcript, data)) return "transcript";
-	if (includes(DASHBOARD_KEYS.root.liveConversation, data)) return "live-conversation";
-	if (includes(DASHBOARD_KEYS.root.reload, data)) return "reload";
-	if (includes(DASHBOARD_KEYS.root.progressToggle, data)) return "progressToggle";
-	if (includes(DASHBOARD_KEYS.pane.agents, data)) return "pane-agents";
-	if (includes(DASHBOARD_KEYS.pane.progress, data)) return "pane-progress";
-	if (includes(DASHBOARD_KEYS.pane.mailbox, data)) return "pane-mailbox";
-	if (includes(DASHBOARD_KEYS.pane.output, data)) return "pane-output";
-	if (includes(DASHBOARD_KEYS.pane.health, data)) return "pane-health";
-	if (includes(DASHBOARD_KEYS.pane.metrics, data)) return "pane-metrics";
-	if (includes(DASHBOARD_KEYS.navigation.up, data)) return "up";
-	if (includes(DASHBOARD_KEYS.navigation.down, data)) return "down";
 	return undefined;
 }

package/src/ui/run-event-bus.ts

@@ -1,4 +1,5 @@
 import type { TeamEvent } from "../state/event-log.ts";
+import { readEventsCursor } from "../state/event-log.ts";
 
 export type RunEventType =
 	| "task_started"
@@ -59,6 +60,18 @@ export interface RunEventPayload {
 	timestamp?: string;
 	data?: unknown;
 	channel?: EventChannel;
+	/**
+	 * L1: monotonic sequence from the durable event log
+	 * (`TeamEvent.metadata.seq`). Present on events that originated from a
+	 * logged TeamEvent (via emitFromTeamEvent). Absent on transient live-only
+	 * events (e.g. worker_status from the stream bridge) that are never
+	 * persisted and therefore cannot be replayed or deduped.
+	 *
+	 * Used by onWithReplay() to dedup: a live event with seq <= the last seq
+	 * replayed to a subscriber is suppressed (it was already delivered from
+	 * the durable log).
+	 */
+	seq?: number;
 }
 
 export type RunEventCallback = (event: RunEventPayload) => void;
@@ -115,6 +128,73 @@ class RunEventBus {
 		};
 	}
 
+	/**
+	 * L1: subscribe with a catch-up replay from the durable event log.
+	 *
+	 * Closes the transient-subscriber-absence gap: when an overlay/widget is
+	 * disposed and recreated (toggle, reconnect), live events emitted in that
+	 * window are lost as notification triggers. This method replays the
+	 * missed TeamEvents from the durable JSONL log BEFORE attaching the live
+	 * listener, then dedups so events delivered both ways fire exactly once.
+	 *
+	 * Unlike deer-flow's 256-event RAM ring buffer (lost on crash), this uses
+	 * pi-crew's existing durable `readEventsCursor` — O(new bytes) via
+	 * byte-offset incremental reads, monotonic seq, tail-capped. Strictly
+	 * better: survives crashes, bounded memory.
+	 *
+	 * @param runId       Run to subscribe to (live listener scope).
+	 * @param eventsPath  Path to the run's events JSONL (manifest.eventsPath).
+	 * @param lastSeenSeq Last seq the caller processed; events with seq > this
+	 *                    are replayed. Pass 0 to replay everything.
+	 * @param callback    Receives both replayed and live events. Replayed
+	 *                    events are delivered directly (NOT via emit, so no
+	 *                    fan-out to other subscribers).
+	 * @returns unsubscribe handle (detaches the live listener).
+	 */
+	onWithReplay(
+		runId: string,
+		eventsPath: string,
+		lastSeenSeq: number,
+		callback: RunEventCallback,
+	): () => void {
+		// Phase 1: replay missed events from the durable log directly to this
+		// callback. Bounded by limit; readEventsCursor already tail-caps.
+		let maxReplayedSeq = lastSeenSeq;
+		try {
+			const cursor = readEventsCursor(eventsPath, { sinceSeq: lastSeenSeq, limit: 1000 });
+			for (const teamEvent of cursor.events) {
+				const type = teamEventToRunEventType(teamEvent);
+				if (!type) continue; // not all TeamEvents map to a RunEventType
+				const payload: RunEventPayload = {
+					type,
+					runId: teamEvent.runId,
+					taskId: teamEvent.taskId,
+					timestamp: teamEvent.time,
+					data: teamEvent.data,
+					channel: classifyEventChannel(type),
+					seq: teamEvent.metadata?.seq,
+				};
+				try { callback(payload); } catch { /* subscriber errors are non-fatal */ }
+				if (typeof teamEvent.metadata?.seq === "number") {
+					maxReplayedSeq = Math.max(maxReplayedSeq, teamEvent.metadata.seq);
+				}
+			}
+		} catch {
+			// Log read failures are non-fatal — fall through to live-only
+			// subscription. The durable log may not exist yet for a brand-new run.
+		}
+
+		// Phase 2: attach the live listener with dedup. A live event whose seq
+		// was already replayed (seq <= maxReplayedSeq) is suppressed. Events
+		// without a seq (transient live-only, e.g. worker_status) always
+		// deliver — they are never persisted and thus never replayed.
+		const liveCallback: RunEventCallback = (event) => {
+			if (typeof event.seq === "number" && event.seq <= maxReplayedSeq) return;
+			callback(event);
+		};
+		return this.on(runId, liveCallback);
+	}
+
 	emit(event: RunEventPayload): void {
 		// Auto-classify channel if not already set.
 		// M2: Use local variable for routing, but also set on event
@@ -206,5 +286,8 @@ export function emitFromTeamEvent(event: TeamEvent): void {
 		taskId: event.taskId,
 		timestamp: event.time,
 		data: event.data,
+		// L1: stamp the durable-log seq so onWithReplay() can dedup live
+		// delivery against replayed events.
+		seq: event.metadata?.seq,
 	});
 }