pi-crew 0.9.55 → 0.9.57

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

@@ -1,14 +1,16 @@
 import { statSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import type { TObject } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
 import { loadConfig } from "../../config/config.ts";
+import { findClosestKey } from "../../config/suggestions.ts";
 import type { MetricRegistry } from "../../observability/metric-registry.ts";
 import type { createManifestCache } from "../../runtime/manifest-cache.ts";
 import { TeamToolParams, type TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
 import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
-import { statusIcon, teamToolRenderer } from "../../ui/tool-renderers/index.ts";
+import { statusIcon, type ToolRenderContext, teamToolRenderer } from "../../ui/tool-renderers/index.ts";
 import type { CrewWidgetState } from "../../ui/widget/index.ts";
 import { updateCrewWidget } from "../../ui/widget/index.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
@@ -29,12 +31,39 @@ async function handleTeamTool(
 }
 
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
-import { loadRunManifestById } from "../../state/state-store.ts";
+import type { CrewAgentRecord } from "../../runtime/crew-agent-runtime.ts";
+import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import { formatCompactToolProgress } from "../../ui/tool-progress-formatter.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { withSessionId } from "../team-tool/context.ts";
+import { formatTeamToolParamError } from "../team-tool/param-error.ts";
 import { toolResult } from "../tool-result.ts";
 
+/**
+ * Normalize model-generated tool params before schema validation.
+ *
+ * Calling models (esp. Claude-style tool callers, incl. deepseek-via-commandcode)
+ * routinely emit EVERY schema key with a default/empty value ("", 0, false)
+ * rather than omitting it. Strict TypeBox unions/patterns then reject the call
+ * even though the intent was "unset": e.g. `runId: ""` fails the
+ * `^[A-Za-z0-9_-]+$` pattern, `workspaceMode: ""` fails the
+ * Literal("single"|"worktree") union, `context: ""` / `scope: ""` likewise.
+ *
+ * Only EMPTY string values are dropped — non-empty strings, booleans, numbers,
+ * arrays, objects are preserved verbatim so genuine invalid values still fail
+ * validation with a helpful message.
+ */
+export function normalizeTeamParams(params: unknown): unknown {
+	if (typeof params !== "object" || params === null || Array.isArray(params)) return params;
+	const p = params as Record<string, unknown>;
+	const out: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(p)) {
+		if (typeof value === "string" && value.trim() === "") continue; // drop empty-string "unset" values
+		out[key] = value;
+	}
+	return out;
+}
+
 const TEAM_TOOL_PROGRESS_TICK_MS = 1000;
 
 type OnUpdate = (chunk: { content: { type: "text"; text: string }[] }) => void;
@@ -71,22 +100,72 @@ export function resolveCwdOverride(
 	}
 }
 
+/**
+ * EXT-1: detect unrecognized (likely typo'd) parameter field names.
+ *
+ * `TeamToolParams` is declared with `additionalProperties: true`, so TypeBox
+ * `Value.Check` does NOT reject unknown keys. A mistyped call like
+ * `{ action: "run", goals: "..." }` (typo `goals` vs `goal`) passes validation,
+ * the handler then reads `params.goal` (undefined) and returns a generic
+ * "Run requires goal or task." with ZERO hint about the typo — so calling
+ * agents (LLMs) loop indefinitely on the same malformed shape.
+ *
+ * This scans `params` for keys absent from `schema.properties` (`action` is
+ * excluded — it is validated separately by the schema enum) and, for each
+ * unknown key, suggests the closest known field via Levenshtein distance.
+ *
+ * @returns A multi-line actionable error message, or `null` when every key
+ *          is recognized.
+ */
+export function detectUnrecognizedParams(schema: TObject, params: unknown): string | null {
+	if (typeof params !== "object" || params === null || Array.isArray(params)) return null;
+	const knownKeys = Object.keys(schema.properties ?? {});
+	const knownSet = new Set(knownKeys);
+
+	const p = params as Record<string, unknown>;
+	const unknowns: string[] = [];
+	for (const key of Object.keys(p)) {
+		if (key === "action") continue; // validated separately by the schema action enum
+		if (!knownSet.has(key)) unknowns.push(key);
+	}
+	if (unknowns.length === 0) return null;
+
+	// Suggest the closest known field for each typo (action excluded as a candidate).
+	const candidates = knownKeys.filter((k) => k !== "action");
+	const hints = unknowns.map((key) => {
+		const closest = findClosestKey(key, candidates);
+		return closest ? `Unrecognized field '${key}' — did you mean '${closest}'?` : `Unrecognized field '${key}'.`;
+	});
+
+	return [
+		`Unrecognized team tool parameter field${unknowns.length > 1 ? "s" : ""}:`,
+		...hints.map((h) => `  • ${h}`),
+		"",
+		"Check the field name spelling against the schema. Common fields:",
+		"action, goal, team, runId, task, role, agent, workflow, model, cwd.",
+	].join("\n");
+}
+
 export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps): void {
 	const tool: ToolDefinition = {
 		name: "team",
 		label: "Team",
+		// EXT-11: do NOT embed one-off performance benchmarks ("Run #3", "~30× faster",
+		// "5.7× slower", etc.) in the tool description — they are stale, do not
+		// generalize, and mislead the calling LLM about when to reach for the
+		// team tool. Keep factual usage guidance (what the tool does, preflight
+		// advisory behavior, action='recommend').
 		description: [
 			"Coordinate Pi teams. Use proactively for complex multi-file work, planning, implementation, tests, reviews, security audits, research, async/background runs, and worktree-isolated execution. Use action='recommend' when unsure which team/workflow to choose. Destructive actions require explicit user confirmation.",
 			"",
 			"ℹ️  ADVISORY NOTE (preflight, never blocks): pi-crew prints informational notes about workflow topology. Review the note, then decide. There is no BLOCK — agents always exercise judgment.",
-			"- Single-task run: raw `Agent` tool would be ~30× faster and ~5× cheaper. pi-crew notes this and proceeds anyway.",
-			"- 2–3 step sequential run: measured 5.7× slower than raw `Agent` calls in Run #3. pi-crew notes this and proceeds anyway.",
-			"- ≥3 concurrent or complex DAG: validated good use case, pi-crew notes 'validated use case'.",
+			"- Single-task or 2–3 step sequential run: pi-crew notes that a raw `Agent` call may be simpler and faster, then proceeds anyway.",
+			"- ≥3 concurrent or complex DAG: validated good use case; pi-crew notes 'validated use case'.",
 			"If unsure, call { action: 'recommend', goal } first to get a team/workflow suggestion.",
 		].join("\n"),
 		promptSnippet: [
 			"Use the team tool for multi-agent orchestration when you need ≥3 concurrent agents or a complex DAG.",
-			"For single tasks or 2–3 sequential steps, the raw Agent tool is usually faster (raw calls = ~5× faster for 3-step chains).",
+			"For single tasks or 2–3 sequential steps, the raw Agent tool is usually faster.",
 			"pi-crew notes the topology (informational only) but proceeds either way — you decide based on your context (audit trail, team coordination, etc.).",
 			"If unsure, call { action: 'recommend', goal } first.",
 		].join("\n"),
@@ -99,11 +178,21 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 			signal?.addEventListener("abort", abort, { once: true });
 			const stopProgress = startTeamToolProgressBinder(onUpdate as OnUpdate | undefined);
 			try {
+				// Models emit empty-string defaults for unset keys; drop them BEFORE
+				// validation so strict unions/patterns accept "unset" as omitted.
+				const normalized = normalizeTeamParams(params);
 				// Defense-in-depth: validate params at runtime even though Pi framework already does
-				if (!Value.Check(TeamToolParams, params)) {
-					return toolResult("Invalid team tool parameters", { action: "list", status: "error" }, true);
+				if (!Value.Check(TeamToolParams, normalized)) {
+					return toolResult(formatTeamToolParamError(TeamToolParams, normalized), { action: "list", status: "error" }, true);
+				}
+				// EXT-1: additionalProperties:true lets unknown (typo'd) keys slip past
+				// Value.Check. Catch them here and suggest the closest known field so
+				// the caller gets an actionable hint instead of a generic handler error.
+				const typoError = detectUnrecognizedParams(TeamToolParams, normalized);
+				if (typoError) {
+					return toolResult(typoError, { action: "list", status: "error" }, true);
 				}
-				const resolved = params as TeamToolParamsValue;
+				const resolved = normalized as TeamToolParamsValue;
 				const cwdOverride = resolveCwdOverride(ctx.cwd, resolved.cwd);
 				if (!cwdOverride.ok) return toolResult(cwdOverride.error, { action: resolved.action ?? "list", status: "error" }, true);
 				const toolCtx = withSessionId({ ...ctx, cwd: cwdOverride.cwd });
@@ -148,14 +237,17 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 				stopProgress.stop();
 			}
 		},
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		renderCall(args: any, theme: any, context: any): any {
-			return teamToolRenderer.renderCall(args, theme, context);
+		renderCall(args, theme, context) {
+			return teamToolRenderer.renderCall(args as Record<string, unknown>, theme, context as ToolRenderContext);
 		},
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		renderResult(result: any, options: any, theme: any, context: any): any {
+		renderResult(result, options, theme, context) {
 			try {
-				return teamToolRenderer.renderResult(result, options, theme, context);
+				return teamToolRenderer.renderResult(
+					result as unknown as Record<string, unknown>,
+					options,
+					theme,
+					context as ToolRenderContext,
+				);
 			} catch {
 				return new Text(statusIcon("completed", theme) + " done", 0, 0);
 			}
@@ -171,7 +263,7 @@ interface TeamToolProgressBinder {
 
 function startTeamToolProgressBinder(onUpdate: OnUpdate | undefined): TeamToolProgressBinder {
 	if (!onUpdate) {
-		return { attach: () => {}, stop: () => {} };
+		return { attach: () => undefined, stop: () => undefined };
 	}
 	const startedAt = Date.now();
 	let cwd: string | undefined;
@@ -191,7 +283,7 @@ function startTeamToolProgressBinder(onUpdate: OnUpdate | undefined): TeamToolPr
 				onUpdate({ content: [{ type: "text", text: msg }] });
 				return;
 			}
-			let agents;
+			let agents: CrewAgentRecord[] | undefined;
 			try {
 				agents = readCrewAgents(loaded.manifest);
 			} catch {

package/src/extension/registration/viewers.ts

@@ -1,8 +1,8 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../../config/config.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
-import { listLiveAgents } from "../../runtime/live-agent-manager.ts";
-import { loadRunManifestById } from "../../state/state-store.ts";
+import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
+import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import { LiveConversationOverlay } from "../../ui/live-conversation-overlay.ts";
 import { asCrewTheme } from "../../ui/theme-adapter.ts";
 // Lazy-loaded: DurableTranscriptViewer is 658ms — only needed for /crew transcript command
@@ -84,9 +84,8 @@ export async function openLiveConversation(
 	const handle = liveAgents.find((h) => h.runId === selected.runId && (selected.taskId ? h.taskId === selected.taskId : true));
 	if (!handle) return false;
 	const theme = asCrewTheme({});
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	await ctx.ui.custom<undefined>(
-		(tui: any, _theme: any, _keybindings: any, done: (result: undefined) => void) => {
+		(tui, _theme, _keybindings, done) => {
 			const columns = tui?.terminal?.columns ?? 80;
 			const rows = tui?.terminal?.rows ?? 24;
 			const overlay = new LiveConversationOverlay(handle, theme, columns, rows);

package/src/extension/registration/wire-cross-extension.ts

@@ -4,10 +4,10 @@
  * Two small wires:
  *   • wireRpc — the in-process pi-crew RPC handle (other modules in
  *     the same extension can subscribe via `pi.events`).
- *   • wireGlobalRegistry — the cross-extension crew global registry,
- *     lazily loaded from team-tool.ts (heavy module) and installed under
- *     `globalThis[Symbol.for("pi-crew:registry")]` so peer extensions
- *     (e.g., pi-subagents3) can discover pi-crew at runtime.
+ *   • wireGlobalRegistry — the crew registry, lazily loaded from
+ *     team-tool.ts (heavy module) and installed in module-scoped state so
+ *     the rest of pi-crew can discover pi-crew's RPC handle at runtime
+ *     (EXT-9: no longer on globalThis[Symbol.for(...)]).
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerPiCrewRpc } from "../cross-extension-rpc.ts";
@@ -24,9 +24,9 @@ export function installCrossExtensionWiring(pi: ExtensionAPI, ctx: RegistrationC
 	};
 	ctx.rpcHandle = registerPiCrewRpc(getPiEvents(), () => ctx.currentCtx);
 
-	// Install the cross-extension crew global registry. Lazy import keeps
-	// team-tool.ts (which pulls in the entire runtime chain) out of the
-	// cold-start module graph.
+	// Install the crew registry. Lazy import keeps team-tool.ts (which pulls
+	// in the entire runtime chain) out of the cold-start module graph. EXT-9:
+	// the registry now lives in module-scoped state, not globalThis.
 	void import("../team-tool.ts").then(({ installCrewGlobalRegistry }) => {
 		const manifestCacheForRegistry = ctx.getManifestCache(ctx.currentCtx?.cwd ?? process.cwd());
 		installCrewGlobalRegistry({

package/src/extension/rpc-hmac.ts

@@ -134,8 +134,9 @@ export function verifyRpcSignature(payload: RpcSignedPayload, body: unknown): {
 export function withHmacVerification<P extends { requestId: string }>(
 	handler: (params: P) => unknown | Promise<unknown>,
 	_channel: string,
-): (params: P) => unknown | Promise<unknown> {
-	return (params: P) => {
+): (raw: unknown) => unknown | Promise<unknown> {
+	return (raw: unknown) => {
+		const params = raw as P;
 		if (!isHmacEnabled()) {
 			// No secret configured → backward compat: allow unsigned.
 			// Emit a soft info note (once per process) only when an actual RPC

package/src/extension/run-bundle-schema.ts

@@ -1,5 +1,5 @@
 import { isTeamRunStatus, isTeamTaskStatus } from "../state/contracts.ts";
-import type { TeamEvent } from "../state/event-log.ts";
+import type { TeamEvent } from "../state/event-log/event-log.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import type { ExportedRunBundle } from "./run-export.ts";
 
@@ -52,7 +52,10 @@ function validateManifest(value: unknown, errors: string[]): value is TeamRunMan
 	if (value.workspaceMode !== "single" && value.workspaceMode !== "worktree")
 		errors.push("manifest.workspaceMode must be single or worktree.");
 	if (!Array.isArray(value.artifacts)) errors.push("manifest.artifacts must be an array.");
-	else value.artifacts.forEach((artifact, index) => validateArtifact(artifact, index, errors));
+	else
+		value.artifacts.forEach((artifact, index) => {
+			validateArtifact(artifact, index, errors);
+		});
 	return errors.length === before;
 }
 
@@ -89,9 +92,15 @@ export function validateRunBundle(value: unknown): BundleValidationResult {
 	if (typeof value.exportedAt !== "string") errors.push("exportedAt must be a string.");
 	validateManifest(value.manifest, errors);
 	if (!Array.isArray(value.tasks)) errors.push("tasks must be an array.");
-	else value.tasks.forEach((task, index) => validateTask(task, index, errors));
+	else
+		value.tasks.forEach((task, index) => {
+			validateTask(task, index, errors);
+		});
 	if (!Array.isArray(value.events)) errors.push("events must be an array.");
-	else value.events.forEach((event, index) => validateEvent(event, index, errors));
+	else
+		value.events.forEach((event, index) => {
+			validateEvent(event, index, errors);
+		});
 	if (!Array.isArray(value.artifactPaths) || !value.artifactPaths.every((item) => typeof item === "string"))
 		errors.push("artifactPaths must be an array of strings.");
 	return { ok: errors.length === 0, errors };

package/src/extension/run-export.ts

@@ -2,8 +2,8 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { writeArtifact } from "../state/artifact-store.ts";
-import { readEvents, type TeamEvent } from "../state/event-log.ts";
+import { readEvents, type TeamEvent } from "../state/event-log/event-log.ts";
+import { writeArtifact } from "../state/stores/artifact-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { redactSecrets } from "../utils/redaction.ts";
 

package/src/extension/run-index.ts

@@ -2,8 +2,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
-import { createCancellationToken } from "../runtime/cancellation-token.ts";
-import { activeRunEntries } from "../state/active-run-registry.ts";
+import { createCancellationToken } from "../runtime/process/cancellation-token.ts";
+import { activeRunEntries } from "../state/stores/active-run-registry.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { findRepoRoot, projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
 import { isSafePathId, resolveRealContainedPath } from "../utils/safe-paths.ts";
@@ -124,7 +124,6 @@ export function listRunsByScope(
 			return projectRoot ? collectRuns(projectCrewRoot(cwd), max, signal) : [];
 		case "user":
 			return collectRuns(userCrewRoot(), max, signal);
-		case "all":
 		default:
 			return max !== undefined ? listRecentRuns(cwd, max, signal) : listRuns(cwd, signal);
 	}

package/src/extension/run-maintenance.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
-import { createCancellationToken } from "../runtime/cancellation-token.ts";
+import { createCancellationToken } from "../runtime/process/cancellation-token.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
@@ -21,6 +21,56 @@ export interface PruneRunsOptions {
 	signal?: AbortSignal;
 }
 
+/**
+ * Default age threshold for stale .corrupt-* quarantine files: 7 days.
+ * Quarantined manifests older than this are deleted to prevent unbounded growth.
+ */
+export const DEFAULT_CORRUPT_FILE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Sweep and delete .corrupt-* files older than maxAgeMs in a runs directory tree.
+ *
+ * These files are created by crash-recovery's purgeStaleActiveRunIndex when a
+ * manifest fails to parse (SyntaxError) or encounters an unexpected error.
+ * Without this sweep, they accumulate indefinitely across runs.
+ *
+ * @param runsDir Absolute path to the runs directory (<crewRoot>/state/runs/)
+ * @returns count of stale .corrupt-* files deleted
+ */
+export function sweepStaleCorruptFiles(runsDir: string, maxAgeMs = DEFAULT_CORRUPT_FILE_TTL_MS, now = Date.now()): number {
+	let deleted = 0;
+	let runDirs: fs.Dirent[];
+	try {
+		runDirs = fs.readdirSync(runsDir, { withFileTypes: true });
+	} catch {
+		return 0;
+	}
+	for (const dir of runDirs) {
+		if (!dir.isDirectory()) continue;
+		const runDirPath = path.join(runsDir, dir.name);
+		let files: string[];
+		try {
+			files = fs.readdirSync(runDirPath);
+		} catch {
+			continue;
+		}
+		for (const file of files) {
+			if (!file.includes(".corrupt-")) continue;
+			const filePath = path.join(runDirPath, file);
+			try {
+				const mtime = fs.statSync(filePath).mtimeMs;
+				if (now - mtime > maxAgeMs) {
+					fs.unlinkSync(filePath);
+					deleted++;
+				}
+			} catch {
+				// Best effort — file may have been removed concurrently
+			}
+		}
+	}
+	return deleted;
+}
+
 function isFinished(run: TeamRunManifest): boolean {
 	// P3: "blocked" is NOT a terminal status — the run is waiting on something
 	// (plan approval, mailbox reply, scheduler stall) and can transition to
@@ -98,6 +148,9 @@ export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsO
 		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
 		removed.push(run.runId);
 	}
+	// ST-6: Sweep stale .corrupt-* quarantine files to prevent unbounded growth.
+	sweepStaleCorruptFiles(path.join(projectCrewRoot(cwd), DEFAULT_PATHS.state.runsSubdir));
+
 	const auditPath = appendPruneAudit(cwd, {
 		action: "prune",
 		keep,
@@ -186,5 +239,8 @@ export function pruneUserLevelRuns(keep: number): PruneRunsResult {
 		removed.push(run.runId);
 	}
 
+	// ST-6: Sweep stale .corrupt-* quarantine files at user level too.
+	sweepStaleCorruptFiles(runsRoot);
+
 	return { kept, removed: [...removed, ...ghostRemoved] };
 }

package/src/extension/team-manager-command.ts

@@ -148,6 +148,8 @@ export async function handleTeamManagerCommand(_args: string, ctx: ExtensionComm
 			"Force cleanup?",
 			"Force may remove dirty worktrees. Choose false to preserve dirty worktrees and capture cleanup diffs.",
 		);
-		await notifyResult(ctx, await handleTeamTool({ action: "cleanup", runId, force }, ctx));
+		// SEC-5: confirm:true is implicit — the user explicitly invoked cleanup
+		// via the UI picker, so the self-enforcement guard is satisfied.
+		await notifyResult(ctx, await handleTeamTool({ action: "cleanup", runId, force, confirm: true }, ctx));
 	}
 }

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

@@ -3,7 +3,13 @@
  * Provides set/clear/status commands for anchor points.
  */
 
-import { type AnchorManager, AnchorNotFoundError, createAnchorManager, NoHandoffsError } from "../../runtime/anchor-manager.ts";
+import {
+	type AnchorManager,
+	AnchorNotFoundError,
+	type AnchorStatus,
+	createAnchorManager,
+	NoHandoffsError,
+} from "../../runtime/anchor-manager.ts";
 import type { HandoffSummary } from "../../runtime/handoff-manager.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
@@ -130,7 +136,7 @@ export function handleAnchorStatus(params: TeamToolParamsValue, ctx: TeamContext
 		anchorId = cfg.anchorId as string;
 	}
 
-	let status;
+	let status: AnchorStatus | null;
 	if (anchorId) {
 		status = manager.getAnchorStatus(anchorId);
 	} else {