pi-crew 0.9.55 → 0.9.57

package/src/extension/team-tool/run.ts

@@ -4,10 +4,10 @@ import { sanitizeTaskText } from "../../runtime/task-packet.ts";
 // Heavy runtime — lazy-loaded to avoid 1.4s import cost at extension registration.
 import type { executeTeamRun as ExecuteTeamRunFn } from "../../runtime/team-runner.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { registerActiveRun, unregisterActiveRun } from "../../state/active-run-registry.ts";
-import { writeArtifact } from "../../state/artifact-store.ts";
 import { atomicWriteJson } from "../../state/atomic-write.ts";
-import { createRunManifest, loadRunManifestById, updateRunStatus } from "../../state/state-store.ts";
+import { registerActiveRun, unregisterActiveRun } from "../../state/stores/active-run-registry.ts";
+import { writeArtifact } from "../../state/stores/artifact-store.ts";
+import { createRunManifest, loadRunManifestById, updateRunStatus } from "../../state/stores/state-store.ts";
 import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
 import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
 import { assertCleanLeaderAsync, findGitRootAsync } from "../../worktree/worktree-manager.ts";
@@ -18,6 +18,7 @@ const _typeCheck: typeof ExecuteTeamRunFn = null as never as typeof ExecuteTeamR
 import { errorMessage } from "../../utils/guards.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { paramRequired } from "./param-error.ts";
 
 let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
 async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
@@ -29,11 +30,11 @@ async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Pro
 	return _cachedExecuteTeamRun(...args);
 }
 
-import { resolveCrewRuntime, runtimeResolutionState } from "../../runtime/runtime-resolver.ts";
-import { appendEventAsync, readEvents } from "../../state/event-log.ts";
-import type { RunMetrics } from "../../state/run-metrics.ts";
+import { spawnBackgroundTeamRun } from "../../runtime/async-runner.ts";
+import { resolveCrewRuntime, runtimeResolutionState } from "../../runtime/model/runtime-resolver.ts";
+import { appendEventAsync, readEvents } from "../../state/event-log/event-log.ts";
+import type { RunMetrics } from "../../state/stores/run-metrics.ts";
 import type { RuntimeResolutionState, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
-import { spawnBackgroundTeamRun } from "../../subagents/async-entry.ts";
 
 /**
  * Module-scoped latch for the crew-init dynamic import.
@@ -72,10 +73,11 @@ function loadCrewInit(): Promise<typeof import("../../state/crew-init.ts")> {
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { t } from "../../i18n.ts";
 import { hasAsyncStartMarker } from "../../runtime/async-marker.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../../runtime/process-status.ts";
 import { waitForRun } from "../../runtime/run-tracker.ts";
-import { collectRunMetrics } from "../../state/run-metrics.ts";
+import { collectRunMetrics } from "../../state/stores/run-metrics.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { effectiveRunConfig } from "./config-patch.ts";
 import { buildParentContext, result, type TeamContext } from "./context.ts";
@@ -256,7 +258,7 @@ function formatRunResult(manifest: TeamRunManifest, options: FormatRunResultOpti
 					? "Experimental live-session worker execution was enabled."
 					: "Safe scaffold mode: child Pi workers were not launched because runtime.mode=scaffold or executeWorkers=false was configured.";
 		const text = [
-			`Created pi-crew run ${manifest.runId}.`,
+			t("team.run.created", { runId: manifest.runId }),
 			`Team: ${team}`,
 			`Workflow: ${workflow}`,
 			`Status: ${manifest.status}`,
@@ -285,7 +287,10 @@ function formatRunResult(manifest: TeamRunManifest, options: FormatRunResultOpti
 	}
 
 	// mode === "waited" — detailed per-task summary.
-	const lines: string[] = [`pi-crew run ${manifest.status}: ${manifest.runId} (${team})`, `Goal: ${goal.slice(0, 100)}`];
+	const lines: string[] = [
+		t("team.run.completed", { status: manifest.status, runId: manifest.runId, team }),
+		`Goal: ${goal.slice(0, 100)}`,
+	];
 	if (metrics) {
 		lines.push("");
 		lines.push(
@@ -346,10 +351,10 @@ function formatRunResult(manifest: TeamRunManifest, options: FormatRunResultOpti
 
 		if (failedCount === 0) {
 			lines.push("");
-			lines.push("All tasks completed successfully.");
+			lines.push(t("team.run.allCompleted"));
 		} else {
 			lines.push("");
-			lines.push(`${failedCount} task(s) failed: ${failedIds.join(", ")}. Consider retrying.`);
+			lines.push(t("team.run.tasksFailed", { count: failedCount, ids: failedIds.join(", ") }));
 		}
 	} else {
 		lines.push(
@@ -385,7 +390,12 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		return handleChainRun(params, ctx, handleRun);
 	}
 	const goal = params.goal ?? params.task;
-	if (!goal) return result("Run requires goal or task.", { action: "run", status: "error" }, true);
+	if (!goal)
+		return result(
+			paramRequired("run", "goal or task", "{ action: 'run', goal: '<what to achieve>' }"),
+			{ action: "run", status: "error" },
+			true,
+		);
 	const intentPrefix = goal.length > 60 ? `${goal.slice(0, 57)}...` : goal;
 
 	// P0: Ensure .crew directory structure exists before creating any manifests.
@@ -494,7 +504,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	if (analysisParam.error) return result(analysisParam.error, { action: "run", status: "error" }, true);
 
 	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { expandParallelResearchWorkflow }` above (issue #28, RFC 17). At call time the module body has fully evaluated, so the dynamic import returns a live binding. Multi-line form breaks scripts/check-lazy-imports.mjs (which does `lines[lineNum - 2]`), so keep destructuring + await import on one line.
-	const { expandParallelResearchWorkflow: expandParallelResearch } = await import("../../runtime/parallel-research.ts");
+	const { expandParallelResearchWorkflow: expandParallelResearch } = await import("../../runtime/scheduling/parallel-research.ts");
 	const workflow = directAgent ? baseWorkflow : expandParallelResearch(baseWorkflow, resolvedCtx.cwd);
 	const isDynamicWorkflow =
 		!directAgent && (workflow as import("../../workflows/workflow-config.ts").WorkflowConfig).runtime === "dynamic";
@@ -623,8 +633,8 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		console.warn(
 			`[pi-crew SECURITY] Dynamic workflow '${workflow.name}' executes as trusted Node.js code with full process/require/import access; run only reviewed .dwf.ts files.`,
 		);
-		// LAZY: defer dynamic import of ../../runtime/dynamic-workflow-runner.ts to its call site.
-		const { runDynamicWorkflow } = await import("../../runtime/dynamic-workflow-runner.ts");
+		// LAZY: defer dynamic import of ../../runtime/goal-workflow/dynamic-workflow-runner.ts to its call site.
+		const { runDynamicWorkflow } = await import("../../runtime/goal-workflow/dynamic-workflow-runner.ts");
 		// Re-synthesize a dynamic-team (§0c C9) for role resolution.
 		const dwfTeam: import("../../teams/team-config.ts").TeamConfig = {
 			name: `dwf-${manifest.runId.slice(-12)}`,
@@ -643,7 +653,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		// CORE-8: unified deadline — resolve params > config > 1h default.
 		const dwfDeadline = resolveRunDeadline(ctx, params);
 		try {
-			let dwfResult: import("../../runtime/dynamic-workflow-runner.ts").RunDynamicWorkflowResult | undefined;
+			let dwfResult: import("../../runtime/goal-workflow/dynamic-workflow-runner.ts").RunDynamicWorkflowResult | undefined;
 			try {
 				dwfResult = await runDynamicWorkflow({
 					manifest: dwfManifest,

package/src/extension/team-tool/status.ts

@@ -1,25 +1,31 @@
 import { loadConfig } from "../../config/config.ts";
 import { applyAttentionState, formatActivityAge, resolveCrewControlConfig } from "../../runtime/agent-control.ts";
 import { extractCommandTrace } from "../../runtime/command-trace.ts";
-import { verifyTaskCompletion } from "../../runtime/completion-guard.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { evaluateRunEffectiveness } from "../../runtime/effectiveness.ts";
 import { computePhaseProgress } from "../../runtime/phase-progress.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../../runtime/process-status.ts";
 import { formatTaskGraphLines, waitingReason } from "../../runtime/task-display.ts";
+import { verifyTaskCompletion } from "../../runtime/verification/completion-guard.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent, readEvents } from "../../state/event-log.ts";
-import { readDeliveryState, readMailbox } from "../../state/mailbox.ts";
-import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
+import { readDeliveryState, readMailbox } from "../../state/coordination/mailbox.ts";
+import { appendEvent, readEvents } from "../../state/event-log/event-log.ts";
+import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
 import { aggregateUsage, formatCost, formatUsage } from "../../state/usage.ts";
 import { formatDuration } from "../../ui/format-helpers.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
+import { paramRequired } from "./param-error.ts";
 import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
 export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	if (!params.runId) return result("Status requires runId.", { action: "status", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("status", "runId", "{ action: 'status', runId: 'team_...' }"),
+			{ action: "status", status: "error" },
+			true,
+		);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
 	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "status", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
@@ -60,6 +66,11 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 	const phaseProgress = computePhaseProgress(tasks);
 	const allEvents = readEvents(manifest.eventsPath);
 	const events = allEvents.slice(-8);
+	// P1-8: pre-build the ack-timeout requestId set once (was O(events × messages)
+	// via allEvents.some() inside the mailbox loop).
+	const ackTimeoutRequestIds = new Set(
+		allEvents.filter((event) => event.type === "agent.group_join.ack_timeout").map((event) => String(event.data?.requestId ?? "")),
+	);
 	const attentionByTask = new Map(
 		allEvents.filter((event) => event.type === "task.attention" && event.taskId).map((event) => [event.taskId!, event]),
 	);
@@ -80,7 +91,7 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		const ageMs = Date.now() - new Date(message.createdAt).getTime();
 		const requestId = String(message.data?.requestId ?? "unknown");
 		const timedOut = ack === "pending" && ackTimeoutMs !== undefined && Number.isFinite(ageMs) && ageMs > ackTimeoutMs;
-		if (timedOut && !allEvents.some((event) => event.type === "agent.group_join.ack_timeout" && event.data?.requestId === requestId)) {
+		if (timedOut && !ackTimeoutRequestIds.has(requestId)) {
 			appendEvent(manifest.eventsPath, {
 				type: "agent.group_join.ack_timeout",
 				runId: manifest.runId,

package/src/extension/team-tool.ts

@@ -7,12 +7,12 @@ import { loadConfig } from "../config/config.ts";
 // executeTeamRun is only called when a team run actually executes.
 import type { executeTeamRun as _executeTeamRunFn } from "../runtime/team-runner.ts";
 import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
-import { writeArtifact } from "../state/artifact-store.ts";
 import { TEAM_TERMINAL_TASK_STATUSES } from "../state/contracts.ts";
-import { appendEvent, appendEventFireAndForget } from "../state/event-log.ts";
-import { withRunLock } from "../state/locks.ts";
-import { replayPendingMailboxMessages } from "../state/mailbox.ts";
-import { loadRunManifestById, saveRunManifestAsync, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
+import { withRunLock } from "../state/coordination/locks.ts";
+import { replayPendingMailboxMessages } from "../state/coordination/mailbox.ts";
+import { appendEvent, appendEventFireAndForget } from "../state/event-log/event-log.ts";
+import { writeArtifact } from "../state/stores/artifact-store.ts";
+import { loadRunManifestById, saveRunManifestAsync, saveRunTasks, updateRunStatus } from "../state/stores/state-store.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
@@ -32,8 +32,8 @@ async function executeTeamRun(...args: Parameters<ExecuteTeamRunFn>): Promise<Aw
 }
 
 import { directTeamAndWorkflowFromRun } from "../runtime/direct-run.ts";
-import { parsePiJsonOutput } from "../runtime/pi-json-output.ts";
-import { resolveCrewRuntime, runtimeResolutionState } from "../runtime/runtime-resolver.ts";
+import { resolveCrewRuntime, runtimeResolutionState } from "../runtime/model/runtime-resolver.ts";
+import { parsePiJsonOutput } from "../runtime/output/pi-json-output.ts";
 import { effectiveRunConfig } from "./team-tool/config-patch.ts";
 import { buildParentContext, formatScoped, result, type TeamContext } from "./team-tool/context.ts";
 // Lazy-loaded: run.ts pulls in spawnBackgroundTeamRun, resolveCrewRuntime, etc.
@@ -51,6 +51,7 @@ async function handleRun(...args: Parameters<HandleRunFn>): Promise<Awaited<Retu
 	return _cachedHandleRun(...args);
 }
 
+import { t } from "../i18n.ts";
 import { waitForRun } from "../runtime/run-tracker.ts";
 import { normalizeSkillOverride } from "../runtime/skill-instructions.ts";
 import { formatActionSuggestion } from "./action-suggestions.ts";
@@ -638,10 +639,9 @@ export async function handleTeamTool(params: TeamToolParamsValue, ctx: TeamConte
 			return handleManageDomain(params, ctx);
 		case "automate":
 			return handleAutomateDomain(params, ctx);
-		case undefined:
 		default:
 			return result(
-				`Unknown action: ${action}${formatActionSuggestion(String(action))}`,
+				t("team.unknownAction", { action: String(action) }) + formatActionSuggestion(String(action)),
 				{ action: "unknown", status: "error" },
 				true,
 			);
@@ -649,11 +649,15 @@ export async function handleTeamTool(params: TeamToolParamsValue, ctx: TeamConte
 }
 
 /**
- * Global RPC registry for cross-extension access to pi-crew's team orchestrator.
- * Uses Symbol.for() for cross-package singleton pattern (same as OpenTelemetry).
- * Extensions can access via: const reg = globalThis[Symbol.for("pi-crew:registry")];
+ * Module-scoped RPC registry for access to pi-crew's team orchestrator.
+ *
+ * EXT-9: Previously this used a `globalThis[Symbol.for("pi-crew:registry")]`
+ * singleton — fragile (cross-realm, no lifecycle, peer extensions could
+ * read/overwrite it). It is now a module-level variable: exactly one instance
+ * per extension load (one per pi session), invisible to peer extensions.
+ * Cross-extension consumers should use the `pi.events` RPC channel
+ * (`registerPiCrewRpc`) instead of poking globalThis.
  */
-const CREW_REGISTRY_KEY = Symbol.for("pi-crew:registry");
 interface CrewRegistry {
 	version: 2;
 	getRecord: (runId: string) => TeamRunManifest | undefined;
@@ -674,13 +678,16 @@ interface CrewRegistry {
 // discovery results with highest priority. The CrewRegistry interface exposes
 // registerAgent/unregisterAgent/listDynamicAgents for cross-extension access.
 
+// Module-scoped singleton instance — one per extension load (EXT-9).
+let crewRegistryInstance: CrewRegistry | undefined;
+
 export function registerCrewGlobalRegistry(registry: CrewRegistry): void {
-	(globalThis as Record<symbol | string, unknown>)[CREW_REGISTRY_KEY] = registry;
+	crewRegistryInstance = registry;
 }
 
-/** @internal */
-function getCrewGlobalRegistry(): CrewRegistry | undefined {
-	return (globalThis as Record<symbol | string, unknown>)[CREW_REGISTRY_KEY] as CrewRegistry | undefined;
+/** @internal — exported for lifecycle tests. */
+export function getCrewGlobalRegistry(): CrewRegistry | undefined {
+	return crewRegistryInstance;
 }
 
 /** Manifest cache shape needed to construct the global registry's read-side. */
@@ -744,7 +751,7 @@ export function installCrewGlobalRegistry(deps?: { manifestCache: ManifestCacheF
 	registerCrewGlobalRegistry(registry);
 }
 
-/** Remove the global CrewRegistry singleton. Call during session cleanup. */
+/** Remove the CrewRegistry singleton. Call during session cleanup. */
 export function uninstallCrewGlobalRegistry(): void {
-	delete (globalThis as Record<symbol | string, unknown>)[CREW_REGISTRY_KEY];
+	crewRegistryInstance = undefined;
 }

package/src/hooks/registry.ts

@@ -1,4 +1,4 @@
-import { appendEvent } from "../state/event-log.ts";
+import { appendEvent } from "../state/event-log/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { runEventBus } from "../ui/run-event-bus.ts";
 import type { HookContext, HookDefinition, HookExecutionReport, HookName, HookResult } from "./types.ts";

package/src/i18n.ts

@@ -24,6 +24,13 @@ const fallback = {
 	"steer.noted": "Steering request noted for {id}.",
 	"steer.unavailable": "Current default pi-crew backend is child-process, so mid-turn session.steer is not available yet.",
 	"steer.cancelHint": "Use team cancel runId={runId} if the agent must be interrupted.",
+	// PR-F12 (EXT-12): team tool user-facing strings routed through t() for
+	// consistency with the subagent tools (Agent / get_subagent_result).
+	"team.run.created": "Created pi-crew run {runId}.",
+	"team.run.completed": "pi-crew run {status}: {runId} ({team})",
+	"team.run.allCompleted": "All tasks completed successfully.",
+	"team.run.tasksFailed": "{count} task(s) failed: {ids}. Consider retrying.",
+	"team.unknownAction": "Unknown action: {action}",
 } as const;
 
 type Key = keyof typeof fallback;
@@ -50,6 +57,11 @@ const translations: Record<string, Partial<Record<Key, string>>> = {
 		"steer.unavailable":
 			"El backend predeterminado actual de pi-crew es child-process, así que session.steer a mitad de turno aún no está disponible.",
 		"steer.cancelHint": "Usa team cancel runId={runId} si hay que interrumpir el agente.",
+		"team.run.created": "Ejecución de pi-crew creada {runId}.",
+		"team.run.completed": "Ejecución de pi-crew {status}: {runId} ({team})",
+		"team.run.allCompleted": "Todas las tareas se completaron con éxito.",
+		"team.run.tasksFailed": "{count} tarea(s) fallaron: {ids}. Considera reintentar.",
+		"team.unknownAction": "Acción desconocida: {action}",
 	},
 	fr: {
 		"agent.requiresPrompt": "Agent nécessite un prompt.",
@@ -71,6 +83,11 @@ const translations: Record<string, Partial<Record<Key, string>>> = {
 		"steer.unavailable":
 			"Le backend pi-crew par défaut actuel est child-process, donc session.steer en milieu de tour n'est pas encore disponible.",
 		"steer.cancelHint": "Utilisez team cancel runId={runId} si l'agent doit être interrompu.",
+		"team.run.created": "Exécution pi-crew créée {runId}.",
+		"team.run.completed": "Exécution pi-crew {status} : {runId} ({team})",
+		"team.run.allCompleted": "Toutes les tâches ont été effectuées avec succès.",
+		"team.run.tasksFailed": "{count} tâche(s) ont échoué : {ids}. Envisagez de réessayer.",
+		"team.unknownAction": "Action inconnue : {action}",
 	},
 	"pt-BR": {
 		"agent.requiresPrompt": "Agent requer prompt.",
@@ -92,6 +109,11 @@ const translations: Record<string, Partial<Record<Key, string>>> = {
 		"steer.unavailable":
 			"O backend padrão atual do pi-crew é child-process, então session.steer no meio do turno ainda não está disponível.",
 		"steer.cancelHint": "Use team cancel runId={runId} se o agente precisar ser interrompido.",
+		"team.run.created": "Execução do pi-crew criada {runId}.",
+		"team.run.completed": "Execução do pi-crew {status}: {runId} ({team})",
+		"team.run.allCompleted": "Todas as tarefas foram concluídas com sucesso.",
+		"team.run.tasksFailed": "{count} tarefa(s) falharam: {ids}. Considere tentar novamente.",
+		"team.unknownAction": "Ação desconhecida: {action}",
 	},
 };
 

package/src/observability/event-bus.ts

@@ -1,4 +1,4 @@
-import type { AgentProgress } from "../runtime/progress-tracker.ts";
+import type { AgentProgress } from "../runtime/output/progress-tracker.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 
 export type CrewEventType = "agent:progress" | "agent:complete" | "agent:error" | "run:start" | "run:complete";

package/src/prompt/prompt-runtime.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { startChildBrokerClient } from "../runtime/crew-broker-child.ts";
+import { startChildBrokerClient } from "../runtime/broker/crew-broker-child.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 
@@ -362,7 +362,7 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 	// already .unref()'d so it never blocks event-loop exit; errors are
 	// swallowed because teardown failures during shutdown are harmless.
 	pi.on("session_shutdown", () => {
-		void brokerHandle.close().catch(() => {});
+		void brokerHandle.close().catch(() => undefined);
 	});
 
 	// ── Prompt rewriting (existing) ────────────────────────────────────────

package/src/runtime/README.md

@@ -0,0 +1,35 @@
+# src/runtime/ — runtime cluster map
+
+This directory holds the team-run execution machinery. After the v0.9.x reorg, the largest
+clusters are extracted into subdirectories; the remaining files stay at the root.
+
+## Extracted subdirectories (navigable clusters)
+
+| Subdir | Phase | Cluster | Key files |
+|--------|-------|---------|-----------|
+| [`child-pi/`](./child-pi/) | B-1 | child Pi worker spawn/lifecycle/steering/transcript | `child-pi.ts`, `child-pi-spawn.ts`, `child-pi-kill.ts`, `child-pi-constants.ts`, `child-pi-steering.ts`, `child-pi-streams.ts`, `child-pi-transcript.ts`, `child-pi-pool.ts` |
+| [`broker/`](./broker/) | B-2 | crew broker server/client/auth (child-pi ↔ parent IPC) | `crew-broker.ts`, `crew-broker-client.ts`, `crew-broker-child.ts`, `crew-broker-tokens.ts`, `broker-issuer.ts` |
+| [`task-runner/`](./task-runner/) | (pre-existing) | per-task execution (pre-execution, child-executor) | `child-executor.ts`, `pre-execution.ts`, ... |
+| [`live-session/`](./live-session/) | 3 | live agent control/manager, session runtime, IRC, health, extension bridge | `live-session-runtime.ts`, `live-agent-manager.ts`, `live-agent-control.ts`, `live-control-realtime.ts`, `live-irc.ts`, `live-session-health.ts`, `live-extension-bridge.ts`, `intercom-bridge.ts` |
+| [`recovery/`](./recovery/) | 4 | crash recovery, retry, checkpoint | `crash-recovery.ts`, `crash-classification.ts`, `recovery-recipes.ts`, `overflow-recovery.ts`, `retry-executor.ts`, `retry-runner.ts`, `checkpoint.ts` |
+| [`scheduling/`](./scheduling/) | 5 | scheduler, concurrency, task-graph, batch-barrier, parallel utils | `scheduler.ts`, `semaphore.ts`, `concurrency.ts`, `task-graph.ts`, `task-graph-scheduler.ts`, `batch-barrier.ts`, `coalesce-tasks.ts`, `run-coalesced-task-group.ts`, `global-worker-cap.ts`, `parallel-research.ts`, `parallel-utils.ts` |
+| [`verification/`](./verification/) | 6a | verification gates, green-contract, post-checks, completion-guard | `verification-gates.ts`, `verification-integrity.ts`, `verification-worktree.ts`, `green-contract.ts`, `post-checks.ts`, `completion-guard.ts` |
+| [`model/`](./model/) | 6b | model fallback/resolver/scope, pi-args, runtime policy/resolver/warmup | `model-fallback.ts`, `model-resolver.ts`, `model-scope.ts`, `pi-args.ts`, `runtime-policy.ts`, `runtime-resolver.ts`, `runtime-warmup.ts` |
+| [`output/`](./output/) | 6c | streaming output, progress tracking, sidechain, result extraction | `streaming-output.ts`, `stream-preview.ts`, `output-validator.ts`, `pi-json-output.ts`, `tool-progress.ts`, `progress-event-coalescer.ts`, `progress-tracker.ts`, `result-extractor.ts`, `sidechain-output.ts` |
+| [`heartbeat/`](./heartbeat/) | 6d | heartbeat gradient/watcher, worker heartbeat/startup | `heartbeat-gradient.ts`, `heartbeat-watcher.ts`, `worker-heartbeat.ts`, `worker-startup.ts` |
+| [`process/`](./process/) | 6e | cancellation, process lifecycle, zombie scanner, stdio guard | `cancellation-token.ts`, `cancellation.ts`, `process-lifecycle.ts`, `zombie-scanner.ts`, `post-exit-stdio-guard.ts` |
+| [`goal-workflow/`](./goal-workflow/) | 6f | goal achievement/evaluation/loop, dynamic-workflow, adaptive plan | `goal-achievement.ts`, `goal-evaluator.ts`, `goal-loop-runner.ts`, `goal-state-store.ts`, `dynamic-workflow-context.ts`, `dynamic-workflow-runner.ts`, `adaptive-plan.ts`, `plan-templates.ts` |
+| [`compaction/`](./compaction/) | 6g | compaction pipeline, tool-output-pruner, important-line-classifier, compact-stages | `compact-pipeline.ts`, `compaction-summary.ts`, `tool-output-pruner.ts`, `important-line-classifier.ts`, [`compact-stages/`](./compaction/compact-stages/) |
+| [`custom-tools/`](./custom-tools/) | (pre-existing) | custom tool definitions | `irc-tool.ts`, `submit-result-tool.ts`, ... |
+| [`errors/`](./errors/) | (pre-existing) | error types | ... |
+
+## Remaining flat files at root (~77)
+
+- **team-runner** — `team-runner.ts` (the orchestrator) + `run-worker.ts`, `run-tracker.ts`
+- **chain/pipeline runners** — `chain-parser.ts`, `chain-runner.ts`, `pipeline-runner.ts`, `direct-run.ts`
+- **foreground/background runners** — `foreground-control.ts`, `foreground-watchdog.ts`, `async-runner.ts`, `background-runner.ts`
+- **crew agent** — `crew-agent-records.ts`, `crew-agent-runtime.ts`, `crew-hooks.ts`, `single-agent-compose.ts`
+- **observability** — `effectiveness.ts`, `agent-observability.ts`, `command-trace.ts`, `metric-parser.ts`
+- **misc** — `stale-reconciler.ts`, `parent-guard.ts`, `manifest-cache.ts`, `event-stream-bridge.ts`, `policy-engine.ts`, `role-permission.ts`, `workspace-lock.ts`, `workspace-tree.ts`, `session-*.ts`, ...
+
+See `docs/COVERAGE-ASSESSMENT-2026-08-01.md` § "Source reorganization" for the reorg history + remaining-cluster plan.

package/src/runtime/agent-control.ts

@@ -32,7 +32,7 @@ export function resolveCrewControlConfig(config: PiTeamsConfig | undefined): Cre
 		  })
 		| undefined;
 	return {
-		enabled: raw?.control?.enabled === false ? false : true,
+		enabled: raw?.control?.enabled !== false,
 		needsAttentionAfterMs: positiveInt(raw?.control?.needsAttentionAfterMs) ?? DEFAULT_NEEDS_ATTENTION_MS,
 		consecutiveFailureThreshold: positiveInt(raw?.control?.consecutiveFailureThreshold) ?? DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD,
 		longRunningMinutes: positiveInt(raw?.control?.longRunningMinutes) ?? DEFAULT_LONG_RUNNING_MINUTES,

package/src/runtime/anchor-manager.ts

@@ -16,8 +16,6 @@ const MAX_HANDOFFS_PER_ANCHOR = 100;
  * - accumulateHandoff() adds handoffs to the anchor
  * - clearAnchor() finalizes and returns accumulated summaries
  * - getAnchorHandoff() retrieves accumulated summary without clearing
- *
- * @see docs/pi-boomerang-integration-plan.md
  */
 
 import type { HandoffSummary } from "./handoff-manager.ts";

package/src/runtime/async-runner.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { appendEventAsync } from "../state/event-log.ts";
+import { appendEventAsync } from "../state/event-log/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";

package/src/runtime/attention-events.ts

@@ -1,5 +1,6 @@
-import { appendEvent, readEvents } from "../state/event-log.ts";
+import { appendEvent, type TeamEvent } from "../state/event-log/event-log.ts";
 import type { CrewAttentionEventData, TeamRunManifest } from "../state/types.ts";
+import { readJsonlTail } from "../utils/incremental-reader.ts";
 
 export interface AppendTaskAttentionInput {
 	manifest: TeamRunManifest;
@@ -9,7 +10,7 @@ export interface AppendTaskAttentionInput {
 }
 
 export function appendTaskAttentionEvent(input: AppendTaskAttentionInput): boolean {
-	const recent = readEvents(input.manifest.eventsPath).slice(-200);
+	const recent = readJsonlTail<TeamEvent>(input.manifest.eventsPath, 256 * 1024).items.slice(-200);
 	const dedupKey = `${input.taskId ?? ""}:${input.data.reason}:${input.data.activityState}`;
 	const duplicate = recent.some(
 		(event) =>

package/src/runtime/auto-summarize.ts

@@ -5,8 +5,6 @@
  * - toggle() enables/disables auto-summarization
  * - shouldAutoSummarize() checks if task should auto-summarize
  * - Token and tool thresholds control when summarization triggers
- *
- * @see docs/pi-boomerang-integration-plan.md
  */
 
 import type { TaskPacket, TaskResult } from "./handoff-manager.ts";