pi-crew 0.9.56 → 0.9.57

package/src/extension/team-tool/goal-wrap.ts

@@ -19,14 +19,14 @@
 
 import { loadConfig } from "../../config/config.ts";
 import type { GoalWrapWorkflowConfig } from "../../config/types.ts";
-import { GoalStore } from "../../runtime/goal-state-store.ts";
-import { snapshotManifests } from "../../runtime/verification-integrity.ts";
+import { spawnBackgroundTeamRun } from "../../runtime/async-runner.ts";
+import { GoalStore } from "../../runtime/goal-workflow/goal-state-store.ts";
+import { snapshotManifests } from "../../runtime/verification/verification-integrity.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { atomicWriteJson } from "../../state/atomic-write.ts";
-import { appendEvent } from "../../state/event-log.ts";
-import { createRunPaths, saveRunManifestAsync } from "../../state/state-store.ts";
+import { appendEvent } from "../../state/event-log/event-log.ts";
+import { createRunPaths, saveRunManifestAsync } from "../../state/stores/state-store.ts";
 import type { GoalLoopState, TeamRunManifest } from "../../state/types.ts";
-import { spawnBackgroundTeamRun } from "../../subagents/async-entry.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import type { WorkflowConfig } from "../../workflows/workflow-config.ts";
 import { result, type TeamContext } from "./context.ts";

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

@@ -14,16 +14,17 @@
  *       §0c C11 (control path: cooperative flag + handleCancel(currentRunId) via abortOwned).
  */
 
-import { GoalStore } from "../../runtime/goal-state-store.ts";
-import { snapshotManifests } from "../../runtime/verification-integrity.ts";
+import { spawnBackgroundTeamRun } from "../../runtime/async-runner.ts";
+import { GoalStore } from "../../runtime/goal-workflow/goal-state-store.ts";
+import { snapshotManifests } from "../../runtime/verification/verification-integrity.ts";
 import { isWorkspaceBusy } from "../../runtime/workspace-lock.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent } from "../../state/event-log.ts";
-import { createRunPaths, saveRunManifestAsync } from "../../state/state-store.ts";
+import { appendEvent } from "../../state/event-log/event-log.ts";
+import { createRunPaths, saveRunManifestAsync } from "../../state/stores/state-store.ts";
 import type { GoalLoopState, GoalLoopStatus, TeamRunManifest } from "../../state/types.ts";
-import { spawnBackgroundTeamRun } from "../../subagents/async-entry.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { result, type TeamContext } from "./context.ts";
+import { paramRequired } from "./param-error.ts";
 
 const MAX_GOAL_OBJECTIVE_CHARS = 4000;
 
@@ -296,7 +297,12 @@ function assertGoalOwnership(goal: GoalLoopState, ctx: TeamContext, action: stri
 function handleStateFlip(input: GoalSubActionInput, nextState: GoalLoopStatus, label: string): ReturnType<typeof result> {
 	const { params, ctx, store } = input;
 	const goalId = params.config?.goalId as string | undefined;
-	if (!goalId) return result(`${label} requires config.goalId.`, { action: "goal", status: "error" }, true);
+	if (!goalId)
+		return result(
+			paramRequired(label, "config.goalId", "{ action: 'goal', config: { goalId: '...' } }"),
+			{ action: "goal", status: "error" },
+			true,
+		);
 	const existing = store.load(goalId);
 	if (!existing) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
 	if (params.force !== true) {
@@ -325,7 +331,12 @@ function handleStateFlip(input: GoalSubActionInput, nextState: GoalLoopStatus, l
 async function handleStop(input: GoalSubActionInput): Promise<ReturnType<typeof result>> {
 	const { params, ctx, store } = input;
 	const goalId = params.config?.goalId as string | undefined;
-	if (!goalId) return result("stop requires config.goalId.", { action: "goal", status: "error" }, true);
+	if (!goalId)
+		return result(
+			paramRequired("stop", "config.goalId", "{ action: 'goal', config: { subAction: 'stop', goalId: '...' } }"),
+			{ action: "goal", status: "error" },
+			true,
+		);
 	const eventsPath = createRunPaths(ctx.cwd, goalId).eventsPath;
 	const before = store.load(goalId);
 	if (!before) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
@@ -386,7 +397,12 @@ async function handleStop(input: GoalSubActionInput): Promise<ReturnType<typeof
 async function handleResume(input: GoalSubActionInput): Promise<ReturnType<typeof result>> {
 	const { params, ctx, store } = input;
 	const goalId = params.config?.goalId as string | undefined;
-	if (!goalId) return result("resume requires config.goalId.", { action: "goal", status: "error" }, true);
+	if (!goalId)
+		return result(
+			paramRequired("resume", "config.goalId", "{ action: 'goal', config: { subAction: 'resume', goalId: '...' } }"),
+			{ action: "goal", status: "error" },
+			true,
+		);
 	const existing = store.load(goalId);
 	if (!existing) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
 	if (params.force !== true) {
@@ -510,7 +526,12 @@ export async function handleGoal(params: TeamToolParamsValue, ctx: TeamContext):
 			// Fix P1-3 + round-5 P2: remove the goal file. But refuse if the loop is still
 			// running (would leave a zombie background process). Require stop first.
 			const clearGoalId = params.config?.goalId as string | undefined;
-			if (!clearGoalId) return result("clear requires config.goalId.", { action: "goal", status: "error" }, true);
+			if (!clearGoalId)
+				return result(
+					paramRequired("clear", "config.goalId", "{ action: 'goal', config: { subAction: 'clear', goalId: '...' } }"),
+					{ action: "goal", status: "error" },
+					true,
+				);
 			const existing = store.load(clearGoalId);
 			if (!existing) return result(`Goal '${clearGoalId}' not found (already cleared?).`, { action: "goal", status: "error" }, true);
 			if (params.force !== true) {

package/src/extension/team-tool/handle-schedule.ts

@@ -1,28 +1,39 @@
 import * as crypto from "node:crypto";
-import { humanizeSchedule, nextRunTime, parseSchedule } from "../../runtime/scheduler.ts";
+import { humanizeSchedule, nextRunTime, parseSchedule } from "../../runtime/scheduling/scheduler.ts";
 import { type CrewSettings, updateCrewSettings } from "../../runtime/settings-store.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
+import { paramRequired } from "./param-error.ts";
 
-// Global key for cross-module scheduler access.
-const CREW_SCHEDULER_KEY = Symbol.for("pi-crew:scheduler");
+// Module-scoped scheduler reference — one per extension load (EXT-9).
+// Previously this lived on `globalThis[Symbol.for("pi-crew:scheduler")]`, which
+// was fragile (cross-realm, no lifecycle, peer extensions could overwrite it).
 type SchedulerRef = {
-	add(job: import("../../runtime/scheduler.ts").ScheduledJob): void;
-	list(): import("../../runtime/scheduler.ts").ScheduledJob[];
+	add(job: import("../../runtime/scheduling/scheduler.ts").ScheduledJob): void;
+	list(): import("../../runtime/scheduling/scheduler.ts").ScheduledJob[];
 	remove(id: string): boolean;
 	update(
 		id: string,
-		patch: Partial<import("../../runtime/scheduler.ts").ScheduledJob>,
-	): import("../../runtime/scheduler.ts").ScheduledJob | undefined;
+		patch: Partial<import("../../runtime/scheduling/scheduler.ts").ScheduledJob>,
+	): import("../../runtime/scheduling/scheduler.ts").ScheduledJob | undefined;
 };
 
-function getCrewScheduler(): SchedulerRef | undefined {
-	return (globalThis as Record<symbol | string, unknown>)[CREW_SCHEDULER_KEY] as SchedulerRef | undefined;
+// Module-scoped scheduler instance — one per extension load (EXT-9).
+let crewSchedulerInstance: SchedulerRef | undefined;
+
+/** @internal — exported for lifecycle tests. */
+export function getCrewScheduler(): SchedulerRef | undefined {
+	return crewSchedulerInstance;
 }
 
 export function registerCrewScheduler(scheduler: SchedulerRef): void {
-	(globalThis as Record<symbol | string, unknown>)[CREW_SCHEDULER_KEY] = scheduler;
+	crewSchedulerInstance = scheduler;
+}
+
+/** Remove the scheduler singleton. Call during session cleanup. */
+export function unregisterCrewScheduler(): void {
+	crewSchedulerInstance = undefined;
 }
 
 interface ScheduleParams {
@@ -35,9 +46,9 @@ interface ScheduleParams {
 }
 
 function buildScheduleSpec(params: ScheduleParams): {
-	spec: import("../../runtime/scheduler.ts").ScheduleSpec;
+	spec: import("../../runtime/scheduling/scheduler.ts").ScheduleSpec;
 	schedule: string;
-	scheduleType: import("../../runtime/scheduler.ts").ScheduleType;
+	scheduleType: import("../../runtime/scheduling/scheduler.ts").ScheduleType;
 	intervalMs?: number;
 } {
 	// Priority: cron > interval > once
@@ -100,7 +111,12 @@ export function handleSchedule(params: TeamToolParamsValue, ctx: TeamContext): P
 
 	const team = params.team ?? "default";
 	const goal = params.goal ?? params.task ?? "";
-	if (!goal) return result("Schedule requires goal or task.", { action: "schedule", status: "error" }, true);
+	if (!goal)
+		return result(
+			paramRequired("schedule", "goal or task", "{ action: 'schedule', goal: '...', cron: '0 9 * * *' }"),
+			{ action: "schedule", status: "error" },
+			true,
+		);
 
 	let specResult: ReturnType<typeof buildScheduleSpec>;
 	try {
@@ -121,7 +137,7 @@ export function handleSchedule(params: TeamToolParamsValue, ctx: TeamContext): P
 	if ("error" in next) return result(next.error, { action: "schedule", status: "error" }, true);
 
 	// Build the ScheduledJob
-	const job: import("../../runtime/scheduler.ts").ScheduledJob = {
+	const job: import("../../runtime/scheduling/scheduler.ts").ScheduledJob = {
 		id: crypto.randomUUID(),
 		name: `${team}: ${goal.slice(0, 60)}`,
 		description: `Scheduled run for team '${team}'`,
@@ -190,11 +206,13 @@ export function handleSchedule(params: TeamToolParamsValue, ctx: TeamContext): P
 	);
 }
 
-function scheduledJobsOf(settings: CrewSettings): import("../../runtime/scheduler.ts").ScheduledJob[] {
-	return Array.isArray(settings.scheduledJobs) ? (settings.scheduledJobs as import("../../runtime/scheduler.ts").ScheduledJob[]) : [];
+function scheduledJobsOf(settings: CrewSettings): import("../../runtime/scheduling/scheduler.ts").ScheduledJob[] {
+	return Array.isArray(settings.scheduledJobs)
+		? (settings.scheduledJobs as import("../../runtime/scheduling/scheduler.ts").ScheduledJob[])
+		: [];
 }
 
-function persistScheduledJob(cwd: string, job: import("../../runtime/scheduler.ts").ScheduledJob): void {
+function persistScheduledJob(cwd: string, job: import("../../runtime/scheduling/scheduler.ts").ScheduledJob): void {
 	try {
 		updateCrewSettings(cwd, (settings) => ({
 			...settings,
@@ -206,7 +224,7 @@ function persistScheduledJob(cwd: string, job: import("../../runtime/scheduler.t
 }
 
 /** Update an existing scheduled job in persistent settings. */
-export function persistScheduledJobUpdate(cwd: string, job: import("../../runtime/scheduler.ts").ScheduledJob): void {
+export function persistScheduledJobUpdate(cwd: string, job: import("../../runtime/scheduling/scheduler.ts").ScheduledJob): void {
 	try {
 		updateCrewSettings(cwd, (settings) => ({
 			...settings,
@@ -309,7 +327,7 @@ export function handleUpdateScheduled(params: TeamToolParamsValue, ctx: TeamCont
 		return result("Scheduler not running.", { action: "schedule", status: "error" }, true);
 	}
 
-	const patch: Partial<import("../../runtime/scheduler.ts").ScheduledJob> = {};
+	const patch: Partial<import("../../runtime/scheduling/scheduler.ts").ScheduledJob> = {};
 	if (subAction === "disable") patch.enabled = false;
 	if (subAction === "enable") patch.enabled = true;
 	// For generic "update", allow patch of cron / interval / goal.

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

@@ -1,15 +1,21 @@
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { readEvents } from "../../state/event-log.ts";
-import { loadRunManifestById } from "../../state/state-store.ts";
+import { readEvents } from "../../state/event-log/event-log.ts";
+import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import { aggregateUsage, formatCostReport, formatUsage } from "../../state/usage.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
 import { formatFailurePatterns } from "./failure-patterns.ts";
+import { paramRequired } from "./param-error.ts";
 import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
 export function handleEvents(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	if (!params.runId) return result("Events requires runId.", { action: "events", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("events", "runId", "{ action: 'events', runId: 'team_...' }"),
+			{ action: "events", status: "error" },
+			true,
+		);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
 	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "events", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
@@ -33,7 +39,12 @@ export function handleEvents(params: TeamToolParamsValue, ctx: TeamContext): PiT
 }
 
 export function handleArtifacts(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	if (!params.runId) return result("Artifacts requires runId.", { action: "artifacts", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("artifacts", "runId", "{ action: 'artifacts', runId: 'team_...' }"),
+			{ action: "artifacts", status: "error" },
+			true,
+		);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
 	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "artifacts", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
@@ -56,7 +67,12 @@ export function handleArtifacts(params: TeamToolParamsValue, ctx: TeamContext):
 }
 
 export function handleSummary(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	if (!params.runId) return result("Summary requires runId.", { action: "summary", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("summary", "runId", "{ action: 'summary', runId: 'team_...' }"),
+			{ action: "summary", status: "error" },
+			true,
+		);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
 	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "summary", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency

package/src/extension/team-tool/lifecycle-actions.ts

@@ -2,11 +2,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { removeGuidance } from "../../config/markers.ts";
 import { appendHookEvent, executeHook } from "../../hooks/registry.ts";
-import { killProcessPid } from "../../runtime/child-pi.ts";
-import { terminateLiveAgentsForRun } from "../../runtime/live-agent-manager.ts";
+import { killProcessPid } from "../../runtime/child-pi/child-pi.ts";
+import { terminateLiveAgentsForRun } from "../../runtime/live-session/live-agent-manager.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent } from "../../state/event-log.ts";
-import { loadRunManifestById } from "../../state/state-store.ts";
+import { appendEvent } from "../../state/event-log/event-log.ts";
+import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot, userPiRoot } from "../../utils/paths.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
@@ -18,10 +18,16 @@ import { pruneFinishedRuns } from "../run-maintenance.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
 import { enforceDestructiveIntent, intentFromConfig } from "./intent-policy.ts";
+import { paramRequired } from "./param-error.ts";
 import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
 export function handleWorktrees(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	if (!params.runId) return result("Worktrees requires runId.", { action: "worktrees", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("worktrees", "runId", "{ action: 'worktrees', runId: 'team_...' }"),
+			{ action: "worktrees", status: "error" },
+			true,
+		);
 	const loaded = loadRunManifestById(ctx.cwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "worktrees", status: "error" }, true);
 	const withWorktrees = loaded.tasks.filter((task) => task.worktree);
@@ -59,7 +65,16 @@ export function handleImports(_params: TeamToolParamsValue, ctx: TeamContext): P
 export function handleImport(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	const cfg = configRecord(params.config);
 	const bundlePath = typeof cfg.path === "string" ? cfg.path : typeof cfg.bundlePath === "string" ? cfg.bundlePath : undefined;
-	if (!bundlePath) return result("Import requires config.path pointing at run-export.json.", { action: "import", status: "error" }, true);
+	if (!bundlePath)
+		return result(
+			paramRequired(
+				"import",
+				"config.path pointing at run-export.json",
+				"{ action: 'import', config: { path: '/path/to/run-export.json' } }",
+			),
+			{ action: "import", status: "error" },
+			true,
+		);
 	const scope = cfg.scope === "user" ? "user" : "project";
 	try {
 		const imported = importRunBundle(ctx.cwd, bundlePath, scope);
@@ -74,7 +89,12 @@ export function handleImport(params: TeamToolParamsValue, ctx: TeamContext): PiT
 }
 
 export async function handleExport(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
-	if (!params.runId) return result("Export requires runId.", { action: "export", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("export", "runId", "{ action: 'export', runId: 'team_...' }"),
+			{ action: "export", status: "error" },
+			true,
+		);
 	const loaded = loadRunManifestById(ctx.cwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "export", status: "error" }, true);
 
@@ -126,7 +146,12 @@ export async function handleExport(params: TeamToolParamsValue, ctx: TeamContext
 export async function handlePrune(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	const intentError = enforceDestructiveIntent("prune", params, ctx.config);
 	if (intentError) return intentError;
-	if (!params.confirm) return result("prune requires confirm: true.", { action: "prune", status: "error" }, true);
+	if (!params.confirm)
+		return result(
+			paramRequired("prune", "confirm: true", "{ action: 'prune', confirm: true }"),
+			{ action: "prune", status: "error" },
+			true,
+		);
 	const keep = params.keep ?? 20;
 	if (keep < 0 || !Number.isInteger(keep)) return result("keep must be an integer >= 0.", { action: "prune", status: "error" }, true);
 	const intent = intentFromConfig(params.config);
@@ -164,8 +189,18 @@ export async function handlePrune(params: TeamToolParamsValue, ctx: TeamContext)
 export async function handleForget(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	const intentError = enforceDestructiveIntent("forget", params, ctx.config);
 	if (intentError) return intentError;
-	if (!params.runId) return result("Forget requires runId.", { action: "forget", status: "error" }, true);
-	if (!params.confirm) return result("forget requires confirm: true.", { action: "forget", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("forget", "runId", "{ action: 'forget', runId: 'team_...', confirm: true }"),
+			{ action: "forget", status: "error" },
+			true,
+		);
+	if (!params.confirm)
+		return result(
+			paramRequired("forget", "confirm: true", "{ action: 'forget', runId: 'team_...', confirm: true }"),
+			{ action: "forget", status: "error" },
+			true,
+		);
 	const loaded = loadRunManifestById(ctx.cwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "forget", status: "error" }, true);
 
@@ -269,6 +304,14 @@ export async function handleCleanup(params: TeamToolParamsValue, ctx: TeamContex
 	// can stay focused on their own logic.
 	const intentError = enforceDestructiveIntent("cleanup", params, ctx.config);
 	if (intentError) return intentError;
+	// SEC-5: self-enforce confirm:true (defense-in-depth), matching handlePrune/handleForget.
+	// dryRun:true is a non-destructive preview and is always allowed.
+	if (params.confirm !== true && params.dryRun !== true)
+		return result(
+			paramRequired("cleanup", "confirm: true", "{ action: 'cleanup', confirm: true }"),
+			{ action: "cleanup", status: "error" },
+			true,
+		);
 	// Three cleanup modes:
 	//  1. WITH runId              → per-run worktree cleanup (existing behavior).
 	//  2. WITHOUT runId, scope=project (default) → PROJECT-LEVEL uninstall:

package/src/extension/team-tool/parallel-dispatch.ts

@@ -8,11 +8,11 @@
  */
 import { discoverAgents } from "../../agents/discover-agents.ts";
 import { loadConfig } from "../../config/config.ts";
-import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
+import { spawnBackgroundTeamRun } from "../../runtime/async-runner.ts";
+import { resolveCrewRuntime } from "../../runtime/model/runtime-resolver.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent } from "../../state/event-log.ts";
-import { createRunManifest } from "../../state/state-store.ts";
-import { spawnBackgroundTeamRun } from "../../subagents/async-entry.ts";
+import { appendEvent } from "../../state/event-log/event-log.ts";
+import { createRunManifest } from "../../state/stores/state-store.ts";
 import { discoverTeams } from "../../teams/discover-teams.ts";
 import type { TeamConfig } from "../../teams/team-config.ts";
 import { discoverWorkflows } from "../../workflows/discover-workflows.ts";
@@ -20,6 +20,7 @@ import type { WorkflowConfig } from "../../workflows/workflow-config.ts";
 import { resolveCwdOverride } from "../registration/team-tool.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
+import { paramRequired } from "./param-error.ts";
 
 const MAX_CONCURRENCY = 8;
 const DEFAULT_CONCURRENCY = 4;
@@ -29,7 +30,15 @@ const DEFAULT_AGENT = "explorer";
 export async function handleParallel(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	const tasksParam = params.config?.tasks;
 	if (!Array.isArray(tasksParam) || tasksParam.length === 0) {
-		return result("parallel action requires config.tasks: [{goal, agent?}]", { action: "parallel", status: "error" }, true);
+		return result(
+			paramRequired(
+				"parallel",
+				"config.tasks: [{goal, agent?}]",
+				"{ action: 'parallel', config: { tasks: [{ goal: '...', agent: 'explorer' }] } }",
+			),
+			{ action: "parallel", status: "error" },
+			true,
+		);
 	}
 
 	const concurrency = Math.min(Math.max(1, Math.floor((params.config?.concurrency as number) ?? DEFAULT_CONCURRENCY)), MAX_CONCURRENCY);

package/src/extension/team-tool/param-error.ts

@@ -112,3 +112,27 @@ export function formatTeamToolParamError(schema: TSchema, params: unknown): stri
 		"as an array/object instead of a single string; params nested instead of flat.",
 	].join("\n");
 }
+
+/**
+ * Build a runtime handler error string for a MISSING REQUIRED FIELD, including
+ * a concrete example shape so the calling agent (LLM) can self-correct instead
+ * of looping on the same malformed call.
+ *
+ * The schema-validation path (`formatTeamToolParamError` above) already
+ * provides rich examples, but runtime handler errors used to return a plain
+ * `"X requires Y."` with NO example — giving LLMs worse guidance for the MORE
+ * COMMON failure (valid action, missing field). This helper closes that
+ * two-tier error-quality gap (AUDIT-2026-07-30 EXT-2).
+ *
+ * @param action The team-tool action (e.g. "status", "cancel").
+ * @param field The required field/fields (e.g. "runId", "goal or task").
+ * @param example Optional concrete example shape,
+ *   e.g. `{ action: 'status', runId: 'team_...' }`.
+ * @returns An error string like
+ *   `"Status requires runId. Example: { action: 'status', runId: 'team_...' }"`.
+ */
+export function paramRequired(action: string, field: string, example?: string): string {
+	const subject = action.charAt(0).toUpperCase() + action.slice(1);
+	const base = `${subject} requires ${field}.`;
+	return example ? `${base} Example: ${example}` : base;
+}

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

@@ -1,13 +1,14 @@
 import { readCrewAgents, recordFromTask, saveCrewAgents } from "../../runtime/crew-agent-records.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent } from "../../state/event-log.ts";
-import { withRunLockSync } from "../../state/locks.ts";
-import { appendMailboxMessage, updateMailboxMessageReply } from "../../state/mailbox.ts";
-import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
+import { withRunLockSync } from "../../state/coordination/locks.ts";
+import { appendMailboxMessage, updateMailboxMessageReply } from "../../state/coordination/mailbox.ts";
+import { appendEvent } from "../../state/event-log/event-log.ts";
+import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
 import { logInternalError } from "../../utils/internal-error.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";
 
 /**
@@ -16,9 +17,22 @@ import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
  * mailbox and the task is re-queued for durable scheduler resume.
  */
 export function handleRespond(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
-	if (!params.runId) return result("Respond requires runId.", { action: "respond", status: "error" }, true);
+	if (!params.runId)
+		return result(
+			paramRequired("respond", "runId", "{ action: 'respond', runId: 'team_...', message: '...' }"),
+			{ action: "respond", status: "error" },
+			true,
+		);
 	if (!params.message && !params.taskId)
-		return result("Respond requires taskId and/or message.", { action: "respond", status: "error" }, true);
+		return result(
+			paramRequired(
+				"respond",
+				"taskId and/or message",
+				"{ action: 'respond', runId: 'team_...', taskId: '01_agent', message: '...' }",
+			),
+			{ action: "respond", status: "error" },
+			true,
+		);
 
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
 	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "respond", status: "error" }, true);

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,