pi-crew 0.9.55 → 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

@@ -0,0 +1,138 @@
+/**
+ * Friendly team-tool parameter validation error formatting.
+ *
+ * The team tool validates every call with `Value.Check(TeamToolParams, ...)`.
+ * On failure it used to return the opaque `"Invalid team tool parameters"` —
+ * which gave calling agents (LLMs) no clue WHAT was wrong, so they retried the
+ * same malformed shape indefinitely (observed in the wild: agents passing
+ * `goal` as an array/object, or `action` with wrong casing, then looping).
+ *
+ * `formatTeamToolParamError` produces an actionable message:
+ *   1. Targeted heuristics for the COMMON mistakes (action casing; goal/team/
+ *      runId passed as a non-string) — pinpoint the exact field, because the
+ *      TypeBox Union reports only a root-level "Expected union value".
+ *   2. TypeBox `Value.Errors` output (catches anything the heuristics miss).
+ *   3. Concrete correct-call examples for the common actions.
+ * Agents can self-correct from this instead of looping.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+/** Short human description of a received value (for error messages). */
+function describeValue(v: unknown): string {
+	if (v === null) return "null";
+	if (Array.isArray(v)) return `array (length ${v.length})`;
+	if (typeof v === "object") return "object";
+	if (typeof v === "string") return `string "${v.length > 40 ? `${v.slice(0, 37)}...` : v}"`;
+	return `${typeof v} (${String(v).slice(0, 40)})`;
+}
+
+/** Pinpoint the common agent mistakes that TypeBox Union can't field-locate. */
+function diagnoseCommonMistakes(params: unknown): string[] {
+	const hints: string[] = [];
+	if (typeof params !== "object" || params === null || Array.isArray(params)) {
+		return hints;
+	}
+	const p = params as Record<string, unknown>;
+
+	// action: casing / non-string
+	if ("action" in p) {
+		const a = p.action;
+		if (typeof a !== "string") {
+			hints.push(`  • 'action': must be a lowercase string (e.g. "run", "status", "list") — got ${describeValue(a)}.`);
+		} else if (a !== a.toLowerCase()) {
+			hints.push(`  • 'action': "${a}" has wrong casing — action is case-sensitive. Use "${a.toLowerCase()}".`);
+		}
+	}
+
+	// Flat-string fields that agents commonly pass as objects/arrays
+	const stringFields = ["goal", "team", "runId", "task", "role", "agent", "workflow", "model", "cwd", "chain"];
+	for (const f of stringFields) {
+		if (!(f in p)) continue;
+		const v = p[f];
+		if (typeof v === "string") continue;
+		if (Array.isArray(v)) {
+			hints.push(
+				`  • '${f}': must be a single flat string — got an array (length ${v.length}). Pass e.g. "${f}": "<value>", not a list.`,
+			);
+		} else if (typeof v === "object" && v !== null) {
+			hints.push(`  • '${f}': must be a single flat string — got an object. Pass e.g. "${f}": "<value>".`);
+		} else {
+			hints.push(`  • '${f}': must be a string — got ${describeValue(v)}.`);
+		}
+	}
+	return hints;
+}
+
+/**
+ * Build a helpful validation-failure message for a team-tool call.
+ *
+ * @param schema The TypeBox schema (TeamToolParams) that rejected the params.
+ * @param params The raw params the caller passed.
+ * @returns A multi-line message: what went wrong + correct-call examples.
+ */
+export function formatTeamToolParamError(schema: TSchema, params: unknown): string {
+	const issues = [...diagnoseCommonMistakes(params)];
+
+	try {
+		const errors = [...Value.Errors(schema, params)];
+		const seen = new Set<string>();
+		for (const e of errors) {
+			if (issues.length >= 8) break;
+			const key = `${e.path}|${e.type}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			const pathLabel = e.path ? `'${e.path}'` : "(schema)";
+			issues.push(`  • ${pathLabel}: ${e.message} — received ${describeValue(e.value)}`);
+		}
+	} catch {
+		/* Value.Errors itself threw — the heuristic issues are still shown */
+	}
+
+	if (issues.length === 0) {
+		issues.push("  • params did not match any valid team-tool action shape");
+	}
+
+	return [
+		"Invalid team tool parameters — the call was rejected by schema validation.",
+		"",
+		"What went wrong:",
+		...issues,
+		"",
+		"Correct call shapes — `action` is case-sensitive (lowercase); `goal`,",
+		"`team`, `runId`, `task`, `role` MUST be flat strings, never objects/arrays:",
+		'  • Run a team:       { "action": "run", "goal": "<what to achieve>", "team": "implementation" }',
+		'  • Suggest a team:   { "action": "recommend", "goal": "<what to achieve>" }',
+		'  • List recent runs: { "action": "list" }',
+		'  • Run status:       { "action": "status", "runId": "<runId>" }',
+		'  • Direct one agent: { "action": "run", "role": "<agent>", "task": "<one task>" }',
+		"",
+		'Common mistakes: `action` uppercase (use "run" not "Run"); `goal` passed',
+		"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);