pi-legion 3.0.3 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-legion",
-  "version": "3.0.3",
+  "version": "4.0.0",
   "description": "Pi Legion v2: recursive centurion trees on headless Pi RPC; shared SQLite WAL legion.db. Four-stage planning/implementing/reviewing/verifying state machine, parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
   "type": "module",
   "license": "MIT",
@@ -54,9 +54,11 @@
     "test:integration": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/integration/*.test.ts",
     "test:live": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/live/*.test.ts",
     "test:all": "node --run typecheck && node --run test && node --run test:integration",
-    "test:docker": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH sh -c 'echo \"RPC mainline Docker checks only; legacy Herdr workspace/kind/notification scenarios are archived under test/legacy/docker and require pi-legion v0.16.x\" && bash test/docker/verify-1-child-guard.sh && bash test/docker/verify-2-task-appendix.sh && bash test/docker/verify-3-readonly.sh && bash test/docker/verify-4-acceptance.sh && bash test/docker/verify-5-blocked.sh && bash test/docker/verify-6-cache.sh && bash test/docker/verify-7-budget.sh && bash test/docker/verify-8-verify-command.sh && bash test/docker/verify-9-worktree.sh && bash test/docker/verify-10-fallback.sh && bash test/docker/verify-11-nested-alias.sh'",
+    "test:docker": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH sh -c 'echo \"Docker mainline checks for the RPC path only\" && bash test/docker/verify-1-child-guard.sh && bash test/docker/verify-2-task-appendix.sh && bash test/docker/verify-3-readonly.sh && bash test/docker/verify-4-acceptance.sh && bash test/docker/verify-5-blocked.sh && bash test/docker/verify-6-cache.sh && bash test/docker/verify-7-budget.sh && bash test/docker/verify-8-verify-command.sh && bash test/docker/verify-9-worktree.sh && bash test/docker/verify-10-fallback.sh && bash test/docker/verify-11-nested-alias.sh'",
     "prepublishOnly": "node --run typecheck && node --run test && node --run test:integration",
     "mock-llm": "node --experimental-strip-types test/mock-llm/cli.ts",
+    "test:perf": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/perf/*.test.ts",
+    "test:wal-stress": "node --experimental-strip-types test/stress/wal-stress.ts",
     "test:mock-llm": "env -u PI_SUBAGENT_ROLE -u PI_SUBAGENT_ACCEPTANCE_ROLE -u PI_SUBAGENT_ALLOW_NESTED -u PI_SUBAGENT_CHILD -u PI_SUBAGENT_UTILITY_CHILD -u PI_SUBAGENT_MAX_DEPTH -u PI_SUBAGENT_PARENT_PATH -u PI_LEGION_DB -u PI_LEGION_NODE_ID node --experimental-strip-types --test test/unit/mock-llm*.test.ts test/integration/mock-llm*.test.ts test/integration/railway-mock-e2e.test.ts",
     "test:tui-visual": "docker build -q -f test/docker/Dockerfile.tui-sandbox -t ghcr.io/zzjcool/pi-legion/tui-sandbox:latest . >/dev/null && docker run --rm -v $(pwd):/plugin -w /plugin ghcr.io/zzjcool/pi-legion/tui-sandbox:latest bash test/docker/verify-tui-visual.sh"
   },

package/skills/pi-legion/SKILL.md

@@ -82,9 +82,8 @@ Keep the run/session records while the squad may need to resume. The
 
 A Git worktree is workspace separation, not a security sandbox. Read-only
 checks remain guardrails rather than a process boundary; never rely on them to
-protect against intentional writes. Pi Legion v2 supports `kind: pi`; for a
-role that requires a non-Pi CLI, use the Herdr-era 0.16.x release line rather
-than expecting v2 to launch it.
+protect against intentional writes. Pi Legion runs `kind: pi` roles only; the
+`kind` frontmatter key is still legal but `pi` is the only accepted value.
 
 ## Later control
 

package/src/agents/agents.ts

@@ -30,6 +30,7 @@ import {
 	stripQuotes,
 } from "./frontmatter.ts";
 import { getAgentDir } from "./paths.ts";
+import { ignoredKindMessage, reportIgnoredOnce } from "../shared/ignored-kind.ts";
 
 export const BUILTIN_AGENT_NAMES = [
 	"scout",
@@ -460,7 +461,7 @@ export function parseAgentDocument(
 		inheritProjectContext: bool(fm.inheritProjectContext) ?? true,
 		inheritSkills: bool(fm.inheritSkills) ?? false,
 		...(bool(fm.inheritExtensions) !== undefined ? { inheritExtensions: bool(fm.inheritExtensions) } : {}),
-		kind: enumOr<AgentKind>(fm.kind, VALID_KINDS, "pi"),
+		kind: parseKind(fm.kind, name),
 		systemPrompt: body,
 		source,
 		filePath,
@@ -496,17 +497,23 @@ function setIf<T extends object, K extends keyof T>(
 }
 
 /**
- * Pick a value only when it is a member of `allowed`.
- * An invalid enum degrades to the default rather than failing the whole file,
- * so a typo in one field cannot break discovery.
+ * Resolve the role's `kind`.
+ *
+ * v4 runs `pi` only. The key stays legal frontmatter (and `AgentConfig.kind`
+ * stays), but a value outside `AGENT_KINDS` is ignored: the role launches as
+ * `pi` and this is reported once, naming the role and the value it tried to
+ * set. Silently coercing would leave the user believing a non-pi CLI is in
+ * play, so an invalid/absent value is the only case that speaks up.
  */
-function enumOr<T extends string>(
-	value: unknown,
-	allowed: ReadonlySet<string>,
-	fallback: T,
-): T {
+function parseKind(value: unknown, agentName: string): AgentKind {
 	const raw = str(value);
-	return raw && allowed.has(raw) ? (raw as T) : fallback;
+	if (raw === undefined || raw === "") return "pi";
+	if (VALID_KINDS.has(raw)) return raw as AgentKind;
+	reportIgnoredOnce(
+		`agent:${agentName}:${raw}`,
+		ignoredKindMessage({ origin: "agent", subject: `'${agentName}'`, value: raw }),
+	);
+	return "pi";
 }
 
 /** `systemPromptMode` is a closed set of two; anything else means `replace`. */

package/src/agents/overrides.ts

@@ -24,7 +24,6 @@ export const OVERRIDE_FIELDS = [
 	"preset",
 	"thinking",
 	"output",
-	"kind",
 	"onBlocked",
 	"systemPromptMode",
 	"systemPrompt",

package/src/agents/presets.ts

@@ -8,15 +8,15 @@
  *
  * Two invariants live here:
  *
- *  1. ATOMICITY — `kind` and `model` come from the same preset object.
- *     `nativeModelFor("cursor", "cb/kimi-k3")` returns `undefined`, so a
- *     mismatched pair would silently drop the model and start the child on
- *     the CLI default. `assertKindModelCoherent` rejects that combination
- *     at expansion time instead of letting the launch proceed.
+ *  1. ATOMICITY — `kind`, `model` and `thinking` come from the same preset
+ *     object, so a preset can never ship half of one bundle and half another.
  *
  *  2. LOUD UNDEFINED — a referenced preset name with no matching entry is
  *     an error that names the defined presets, never a silent fallback to
  *     the dispatch model (mirrors `checkModelScope`'s out-of-scope error).
+ *
+ * v4 runs `kind: pi` only: a preset that names another kind is reported once
+ * and applied as `pi` (see `parsePreset`).
  */
 
 import {
@@ -27,7 +27,7 @@ import {
 	type AgentKind,
 	type PresetConfig,
 } from "../shared/types.ts";
-import { nativeModelFor } from "../runs/kind.ts";
+import { ignoredKindMessage, reportIgnoredOnce } from "../shared/ignored-kind.ts";
 
 const VALID_KINDS: ReadonlySet<string> = new Set(AGENT_KINDS);
 
@@ -71,13 +71,17 @@ function parsePreset(
 	const out: PresetConfig = {};
 
 	if (input.kind !== undefined) {
+		// A non-`pi` kind is no longer a validation error (the field is still a
+		// legal key, it just only accepts one value). Report the ignored value once
+		// and apply the preset as `pi`, the single supported kind.
 		if (typeof input.kind !== "string" || !VALID_KINDS.has(input.kind)) {
-			throw new Error(
-				`Subagent settings in '${filePath}' have invalid '${label}.kind'; ` +
-					`expected one of: ${AGENT_KINDS.join(", ")}.`,
+			reportIgnoredOnce(
+				`preset:${name}`,
+				ignoredKindMessage({ origin: `preset '${name}'`, subject: `in ${filePath}`, value: input.kind }),
 			);
+		} else {
+			out.kind = input.kind as AgentKind;
 		}
-		out.kind = input.kind as AgentKind;
 	}
 
 	if (input.model !== undefined) {
@@ -152,36 +156,6 @@ export function requirePreset(
 	);
 }
 
-/**
- * Throw when `nativeModelFor(kind, model)` would silently drop the model.
- *
- * Reuses `nativeModelFor` rather than re-implementing the shape test, so the
- * guard can never disagree with the argv builder about what a kind accepts.
- *
- * `model` is the RESOLVED model — whichever precedence level actually won —
- * not the preset's own `model`, because a per-run tool `model`, `defaultModel`,
- * an override or the dispatch model can all beat or fill in for the preset.
- * The message therefore names the preset's KIND as the origin and reports
- * where the model came from, rather than implying the preset set it.
- */
-export function assertKindModelCoherent(
-	kind: AgentKind,
-	model: string | undefined,
-	presetName: string,
-	modelOrigin?: string,
-): void {
-	if (!model) return;
-	if (nativeModelFor(kind, model) === undefined) {
-		const origin = modelOrigin ? ` (from ${modelOrigin})` : "";
-		throw new SubagentError(
-			`Preset '${presetName}' selects kind '${kind}', but the resolved model '${model}'${origin} ` +
-				`cannot be used with that kind and would be silently dropped at start. ` +
-				`Fix the preset's kind or the model source.`,
-			ErrorCodes.INVALID_PARAMS,
-		);
-	}
-}
-
 /**
  * Return a COPY of `agent` with kind/model/thinking from `preset`.
  *

package/src/agents/settings.ts

@@ -11,7 +11,6 @@ import {
 	AGENT_KINDS,
 	DEFAULT_LEGION_SETTINGS,
 	type AgentOverride,
-	type HerdrSettings,
 	type LegionSettings,
 	type ModelScopeConfig,
 	type OnBlockedPolicy,
@@ -28,6 +27,7 @@ import {
 	readConventionContext,
 } from "./context.ts";
 import { OVERRIDE_FIELDS } from "./overrides.ts";
+import { ignoredKindMessage, reportIgnoredOnce } from "../shared/ignored-kind.ts";
 import { parseModelScopeConfig } from "./model-scope.ts";
 import { parsePresets } from "./presets.ts";
 
@@ -88,8 +88,6 @@ function nonNegativeInt(
 }
 
 const VALID_JOIN_MODES: ReadonlySet<string> = new Set(["each", "smart"]);
-const LEGACY_PLACEMENTS = ["split-down", "split-right", "new-tab"] as const;
-const warnedHerdrSettings = new Set<string>();
 
 const VALID_ON_BLOCKED_POLICIES: ReadonlySet<string> = new Set([
 	"forward",
@@ -116,73 +114,6 @@ function readJoinFields(
 	if (flushMs !== undefined) out.joinFlushMs = flushMs;
 }
 
-function parseHerdrSettings(
-	value: unknown,
-	filePath: string,
-): HerdrSettings | undefined {
-	if (value === undefined) return undefined;
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		throw new Error(
-			`Subagent settings in '${filePath}' have invalid 'herdr'; expected an object.`,
-		);
-	}
-	const input = value as Record<string, unknown>;
-	const out: HerdrSettings = {};
-	if (!warnedHerdrSettings.has(filePath)) {
-		warnedHerdrSettings.add(filePath);
-		console.warn(
-			`[pi-legion] Settings 'subagents.herdr' in ${filePath} are deprecated and ignored by the RPC supervisor; remove them when migrating from v0.16.x.`,
-		);
-	}
-
-	const placement = input.defaultPlacement;
-	if (placement !== undefined) {
-		if (typeof placement !== "string" || !LEGACY_PLACEMENTS.includes(placement as (typeof LEGACY_PLACEMENTS)[number])) {
-			throw new Error(
-				`Subagent settings in '${filePath}' have invalid 'herdr.defaultPlacement'; ` +
-					`expected one of: ${[...LEGACY_PLACEMENTS].join(", ")}.`,
-			);
-		}
-		out.defaultPlacement = placement as NonNullable<HerdrSettings["defaultPlacement"]>;
-	}
-
-	const maxAgents = positiveInt(
-		input.maxConcurrentAgents,
-		"herdr.maxConcurrentAgents",
-		filePath,
-	);
-	if (maxAgents !== undefined) out.maxConcurrentAgents = maxAgents;
-
-	const retries = nonNegativeInt(
-		input.startRetries,
-		"herdr.startRetries",
-		filePath,
-	);
-	if (retries !== undefined) out.startRetries = retries;
-
-	const backoff = nonNegativeInt(
-		input.startRetryBackoffMs,
-		"herdr.startRetryBackoffMs",
-		filePath,
-	);
-	if (backoff !== undefined) out.startRetryBackoffMs = backoff;
-
-	const days = positiveInt(
-		input.sessionRetentionDays,
-		"herdr.sessionRetentionDays",
-		filePath,
-	);
-	if (days !== undefined) out.sessionRetentionDays = days;
-
-	const bytes = positiveInt(
-		input.sessionRetentionMaxBytesPerRun,
-		"herdr.sessionRetentionMaxBytesPerRun",
-		filePath,
-	);
-	if (bytes !== undefined) out.sessionRetentionMaxBytesPerRun = bytes;
-
-	return out;
-}
 
 const LEGION_PHASES = [
 	"planning",
@@ -477,8 +408,6 @@ export function parseSubagentSettings(
 	const modelScope = parseModelScopeConfig(input.modelScope, { filePath });
 	if (modelScope) out.modelScope = modelScope;
 
-	const herdr = parseHerdrSettings(input.herdr, filePath);
-	if (herdr) out.herdr = herdr;
 	const legion = parseLegionSettings(input.legion, filePath);
 	if (legion !== undefined) out.legion = legion;
 
@@ -604,6 +533,21 @@ function parseInProcessLimits(
 		filePath,
 	);
 	if (waitTimeoutMs !== undefined) out.waitTimeoutMs = waitTimeoutMs;
+	// D10: launch-admission-queue bounds. `positiveInt` on purpose — 0 is
+	// invalid, not "queue disabled" (that would silently swallow every queue).
+	// Defaults live in `src/supervisor/admission-queue.ts` (single source).
+	const maxQueuedLaunches = positiveInt(
+		value.maxQueuedLaunches,
+		"inprocess.maxQueuedLaunches",
+		filePath,
+	);
+	if (maxQueuedLaunches !== undefined) out.maxQueuedLaunches = maxQueuedLaunches;
+	const launchQueueTimeoutMs = positiveInt(
+		value.launchQueueTimeoutMs,
+		"inprocess.launchQueueTimeoutMs",
+		filePath,
+	);
+	if (launchQueueTimeoutMs !== undefined) out.launchQueueTimeoutMs = launchQueueTimeoutMs;
 	// Unknown keys are ignored (same as other settings blobs).
 	return out;
 }
@@ -639,6 +583,15 @@ function parseAgentOverride(
 	// though older settings files may still carry it in an agent override.
 	const normalized: Record<string, unknown> = { ...value };
 	delete normalized.placement;
+	// A non-`pi` kind is reported once and ignored rather than rejected: the key
+	// is still legal, it only has one accepted value in v4.
+	if (normalized.kind !== undefined && !isValidOverrideField("kind", normalized.kind)) {
+		reportIgnoredOnce(
+			`override:${field}`,
+			ignoredKindMessage({ origin: `settings override '${field}'`, subject: `in ${filePath}`, value: normalized.kind }),
+		);
+		delete normalized.kind;
+	}
 	for (const [key, member] of Object.entries(normalized)) {
 		const expected = overrideFieldExpected(key);
 		if (
@@ -814,7 +767,7 @@ export function loadSubagentSettings(
 
 /**
  * Merge project settings over user settings.
- * `herdr`, `legion`, `agentOverrides`, `teams` and `presets` shallow-merge;
+ * `legion`, `agentOverrides`, `teams` and `presets` shallow-merge;
  * `legion.phaseTimeouts` also merges per phase. `modelScope` is replaced
  * wholesale. A project team with the same name replaces the user's complete
  * team definition.
@@ -863,10 +816,6 @@ export function resolveSubagentSettings(
 	}
 	if (project.team !== undefined) out.team = project.team;
 
-	if (project.herdr) {
-		out.herdr = { ...(user.herdr ?? {}), ...project.herdr };
-	}
-
 	if (project.legion !== undefined || user.legion !== undefined) {
 		out.legion = mergeLegionSettings(user.legion, project.legion);
 	}

package/src/agents/step-model.ts

@@ -9,18 +9,14 @@
  *   1. A referenced preset's kind/model/thinking reach the child, and its
  *      model beats `agentOverrides` (which `loadCatalog` folds into
  *      `agent.model` before anything here runs).
- *   2. `kind` and the FINAL model are coherent, or the launch is refused
- *      loudly instead of dropping the model at start (`nativeModelFor`).
  *
- * Invariant 2 is checked on the resolved model, NOT on the preset's own
- * `model`: the launched model can come from a level above or below the preset
- * (a per-run tool `model`, `defaultModel`, the dispatch model, an override),
- * so validating the preset's own pair would let an incoherent pair ship.
+ * v4 runs `kind: pi` only, so there is no second invariant to police here:
+ * the resolved model always belongs to the one supported kind.
  */
 
 import type { AgentConfig, ModelOrigin, PresetConfig } from "../shared/types.ts";
 import { providerOf, resolveModel, type ResolvedModel } from "./model-resolution.ts";
-import { assertKindModelCoherent, expandPreset } from "./presets.ts";
+import { expandPreset } from "./presets.ts";
 
 export interface StepModelInput {
 	/** The catalog agent, with `agentOverrides` already folded in. */
@@ -59,9 +55,8 @@ export interface StepModelResult {
 /**
  * Resolve the model (and the effective agent) a step will launch with.
  *
- * Throws when a referenced preset is undefined, or when the resolved
- * kind/model pair would be silently dropped at start. Callers are expected to
- * turn those into a refusal line rather than letting them escape.
+ * Throws when a referenced preset is undefined. Callers are expected to turn
+ * that into a refusal line rather than letting it escape.
  */
 export function resolveStepModel(input: StepModelInput): StepModelResult {
 	const override = input.step.model ?? input.params.model;
@@ -88,18 +83,8 @@ export function resolveStepModel(input: StepModelInput): StepModelResult {
 		settings: input.settings as Parameters<typeof resolveModel>[0]["settings"],
 	});
 
-	// Only a preset can make the kind disagree with the launched model in a way
-	// this module is responsible for. An agent that merely sets `kind` keeps its
-	// pre-existing behaviour (that is an older, separate concern).
-	if (expanded) {
-		const origin = classifyModelOrigin(resolved, override);
-		assertKindModelCoherent(
-			effective.kind,
-			resolved.model,
-			expanded.presetName,
-			origin.label,
-		);
-	}
+	// Only a preset can change the kind, and v4 accepts `pi` alone, so nothing
+	// here can leave the kind and the launched model incoherent.
 
 	return {
 		resolved,

package/src/api.ts

@@ -16,19 +16,6 @@
  * ```
  */
 
-// ── deprecated herdr transport ──────────────────────────────────────────────
-/** @deprecated Use `RpcSupervisor` for the v2 execution path. */
-export {
-	createHerdrClient,
-	parseHerdrResponse,
-	mapHerdrErrorCode,
-	readPaneDiagnostic,
-	SubagentError,
-} from "./backends/legacy/client.ts";
-/** @deprecated Only for pi-legion v0.16.x Herdr workflows. */
-export { createCommandRunner, resolveHerdrBin } from "./backends/legacy/runner.ts";
-export type { RunnerOptions } from "./backends/legacy/runner.ts";
-
 // ── agent definitions ───────────────────────────────────────────────────────
 export {
 	BUILTIN_AGENT_NAMES,
@@ -66,7 +53,6 @@ export type {
 } from "./agents/model-resolution.ts";
 export {
 	applyPreset,
-	assertKindModelCoherent,
 	expandPreset,
 	parsePresets,
 	requirePreset,
@@ -191,13 +177,6 @@ export {
 	THINKING_LEVELS,
 } from "./runs/args.ts";
 export type { BuildArgsInput, BuildArgsResult } from "./runs/args.ts";
-export {
-	cursorModel,
-	isPiShapedModel,
-	nativeModelFor,
-	planKindStart,
-} from "./runs/kind.ts";
-export type { KindStartPlan } from "./runs/kind.ts";
 export {
 	createChildWorktree,
 	isGitRepo,
@@ -292,7 +271,7 @@ export {
 export type { LiveProgress } from "./shared/progress.ts";
 
 // ── shared vocabulary ───────────────────────────────────────────────────────
-export { AGENT_KINDS } from "./shared/types.ts";
+export { AGENT_KINDS, SubagentError } from "./shared/types.ts";
 export type {
 	AcceptanceConfig,
 	AcceptanceCriterion,
@@ -326,16 +305,3 @@ export type {
 	TurnBudgetConfig,
 	Usage,
 } from "./shared/types.ts";
-/** @deprecated v0.16.x pane backend compatibility types. */
-export type {
-	AgentInfo,
-	AgentStartResult,
-	CommandRunner,
-	HerdrClient,
-	HerdrError,
-	HerdrResult,
-	PaneInfo,
-	ProcessInfo,
-	ReadSource,
-	TabInfo,
-} from "./backends/legacy/types.ts";

package/src/extension/event-bus.ts

@@ -2,11 +2,20 @@ import type { DatabaseSync } from "../legion/db.ts";
 import {
 	LEGION_EVENT_TYPES as STORED_LEGION_EVENT_TYPES,
 	getDataVersion,
-	readEventsAfter,
+	readEventsAfterTolerant,
 } from "../legion/events.ts";
 import type { LegionEventType as StoredLegionEventType } from "../legion/events.ts";
 
-/** Process-only activity. These events are never written to the closed DB enum. */
+/**
+ * Process-only activity. These events are never written to the closed DB enum.
+ *
+ * Launch-admission-queue (issue #266, contract D12) belongs here and ONLY here:
+ * queue residency is a fact about *this* process (the queue lives in memory and
+ * dies with it), so persisting it would be meaningless. Adding a type to
+ * `src/legion/events.ts` instead would freeze the DB event cursor (#233); the
+ * mirrored pair of assertions in `test/unit/teams.test.ts` (A13) guards both
+ * directions of that boundary.
+ */
 export const LEGION_PROCESS_EVENT_TYPES = [
 	"node_launched",
 	"node_steered",
@@ -17,6 +26,8 @@ export const LEGION_PROCESS_EVENT_TYPES = [
 	"tool_call",
 	"agent_settled",
 	"turn_start",
+	"launch_queued",
+	"launch_admitted",
 ] as const;
 export type LegionProcessEventType = (typeof LEGION_PROCESS_EVENT_TYPES)[number];
 
@@ -46,14 +57,41 @@ export type LegionEventHandler = (event: LegionEvent) => void;
 export interface LegionEventBus {
 	on(type: LegionEventType, handler: LegionEventHandler): () => void;
 	emit(event: LegionEvent): void;
+	/**
+	 * Report an error raised OUTSIDE a subscriber's synchronous dispatch window
+	 * (a deferred repaint) through the same `onHandlerError` channel a throwing
+	 * handler uses. `createLegionEventBus` isolates a handler's throw so one bad
+	 * consumer cannot break delivery; a subscriber that defers work past its own
+	 * dispatch window would otherwise escape that isolation entirely (#238).
+	 *
+	 * There is deliberately NO `event`/`handler` argument: the throw happened after
+	 * dispatch, so there is no real event to attribute it to, and fabricating one
+	 * (a synthetic `ui_request` on an empty nodeId) would make any consumer that
+	 * groups by `event.nodeId` record a phantom event on a node that never exists.
+	 * Consumers that need correlation should use `context`.
+	 *
+	 * Optional so any structural stand-in for a bus keeps working; a caller with no
+	 * channel must contain the error itself rather than rethrow it onto the
+	 * microtask queue (which is a host-killing crash, the very bug this prevents).
+	 */
+	reportError?(error: unknown, context: "deferred-handler"): void;
 }
 
 export interface LegionEventBusOptions {
 	/** Optional observer for isolated subscriber failures. Failures here are isolated too. */
 	onHandlerError?: (
 		error: unknown,
-		event: LegionEvent,
-		handler: LegionEventHandler,
+		/**
+		 * The event whose handler threw, or `null` for a failure reported outside a
+		 * dispatch window (`reportError`, e.g. a deferred repaint). `null` means "no
+		 * event", never "an event with no node": do not group it by `nodeId`.
+		 */
+		event: LegionEvent | null,
+		/**
+		 * The failing handler, or a short origin tag for a deferred failure
+		 * (`"deferred-handler"`) where no single handler is responsible.
+		 */
+		handler: LegionEventHandler | string,
 	) => void;
 }
 
@@ -110,6 +148,18 @@ export function createLegionEventBus(
 				}
 			}
 		},
+		reportError(error, context) {
+			// No `event`/`handler` to attribute this to: the throw happened after the
+			// dispatch window closed. Pass only what is real (the error and the
+			// origin) — a synthetic event would be a fabricated fact. An unconfigured
+			// `onHandlerError` stays silent, which is what `emit()` already does for a
+			// throwing handler; `index.ts` wires one so the containment is not silent.
+			try {
+				options.onHandlerError?.(error, null, context);
+			} catch {
+				// Error reporting must never itself break delivery.
+			}
+		},
 	};
 }
 
@@ -123,7 +173,15 @@ export interface EventSourceClock {
 export interface DbEventSourceOptions {
 	/** Contract §10.2 recommends 200–500ms; default is 250ms. */
 	pollMs?: number;
-	/** Resume after this persisted event id. Defaults to the beginning of the log. */
+	/**
+	 * Resume after this persisted event id. Defaults to the beginning of the log.
+	 *
+	 * The default is deliberately "replay everything": a caller that attaches to
+	 * a ledger it did not just write should seed this at the current tail instead
+	 * (`maxEventId(db)` from `src/legion/events.ts`) — that is what the production
+	 * attach path in `index.ts` does (#238, `createLegionRuntime`). A caller that
+	 * really wants the full replay passes `cursor: 0` explicitly.
+	 */
 	cursor?: number;
 	/** Injectable interval scheduler for deterministic tests and embedding. */
 	clock?: EventSourceClock;
@@ -193,13 +251,27 @@ export function createDbEventSource(
 			// Drain all batches for this dirty version so the cursor cannot strand
 			// events when a busy producer commits more than one batch at once.
 			for (;;) {
-				const batch = readEventsAfter(db, cursor, { limit: EVENT_BATCH_SIZE });
+				let skipped = 0;
+				const batch = readEventsAfterTolerant(db, cursor, {
+					limit: EVENT_BATCH_SIZE,
+					onInvalidRow: (error, rowId) => {
+						skipped += 1;
+						reportError(error);
+						// Advance past the undecodable row so one bad row cannot stall the stream.
+						if (rowId > cursor) cursor = rowId;
+					},
+				});
 				for (const event of batch) {
 					currentBus.emit(event);
-					cursor = event.id;
+					// Rows are ascending, but onInvalidRow may already have moved the cursor
+					// past a poison row in this same batch. Never let a decoded row rewind it,
+					// or the skipped row is re-read and re-reported on the next poll.
+					if (event.id > cursor) cursor = event.id;
 					if (!running || bus !== currentBus) return;
 				}
-				if (batch.length < EVENT_BATCH_SIZE) break;
+				// Skips count toward fullness: a batch of only poison rows still read
+				// a full page, so it must not be mistaken for the tail of the log.
+				if (batch.length + skipped < EVENT_BATCH_SIZE) break;
 			}
 			lastDataVersion = dataVersion;
 		} catch (error) {