pi-crew 0.9.68 → 0.10.1

package/src/config/role-tools.ts

@@ -22,7 +22,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// excluded. State-mutation safety is enforced separately by
 	// READ_ONLY_ROLES in role-permission.ts.
 	explorer: {
-		tools: ["read", "grep", "find", "ls", "glob", "bash"],
+		tools: ["read", "grep", "find", "ls", "glob", "bash", "ask"],
 		excludeTools: ["edit", "write", "web"],
 	},
 
@@ -39,14 +39,14 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// planner to WRITE_ROLES would fire the gate before planning, breaking the
 	// default/implementation workflows.
 	planner: {
-		tools: ["read", "grep", "find", "ls", "glob"],
+		tools: ["read", "grep", "find", "ls", "glob", "ask"],
 		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
 	},
 
 	// Critic - Read-only plan/design critique (F2: was missing from the map,
 	// so a custom critic agent had no tool-level read-only enforcement).
 	critic: {
-		tools: ["read", "grep", "find", "ls", "glob"],
+		tools: ["read", "grep", "find", "ls", "glob", "ask"],
 		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
@@ -59,13 +59,13 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 
 	// Reviewer - Read and review, no write
 	reviewer: {
-		tools: ["read", "grep", "find", "ls", "glob", "bash"],
+		tools: ["read", "grep", "find", "ls", "glob", "bash", "ask"],
 		excludeTools: ["edit", "write"],
 	},
 
 	// Writer - Documentation focused
 	writer: {
-		tools: ["read", "edit", "write", "ls"],
+		tools: ["read", "edit", "write", "ls", "ask"],
 		excludeTools: ["bash", "web", "ask_question"],
 	},
 
@@ -74,7 +74,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// security-reviewer.md → "security-reviewer"). The underscore form never
 	// resolved at runtime (returned {}), silently dropping enforcement.
 	"security-reviewer": {
-		tools: ["read", "grep", "find"],
+		tools: ["read", "grep", "find", "ask"],
 		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
 	},
 
@@ -84,7 +84,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// agents/verifier.md). Tool-set keeps bash but excludes edit/write so source
 	// integrity is preserved during verification. Mirrors cold-verifier behavior.
 	verifier: {
-		tools: ["read", "grep", "find", "ls", "bash", "scratchpad"],
+		tools: ["read", "grep", "find", "ls", "bash", "scratchpad", "ask"],
 		excludeTools: ["edit", "write", "web"],
 		// Phase 1 scratchpad: multi-cell test/verify flows reuse parsed state.
 		scratchpad: true,
@@ -92,7 +92,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 
 	// Test Engineer - Can write tests (F1: hyphenated key)
 	"test-engineer": {
-		tools: ["read", "edit", "write", "bash", "ls", "scratchpad"],
+		tools: ["read", "edit", "write", "bash", "ls", "scratchpad", "ask"],
 		excludeTools: ["web"],
 		// Phase 1 scratchpad: build/run test suites with state across cells.
 		scratchpad: true,

package/src/config/sanitize-project-config.ts

@@ -0,0 +1,172 @@
+import { collectSensitiveConfigPaths } from "../schema/sensitive-config-paths.ts";
+import type { ConfigValidationResult, PiTeamsConfig } from "./types.ts";
+
+/**
+ * Phase 5.1 (ADR docs/decisions/2026-08-15-schema-driven-sanitize.md): the
+ * drop-list is derived from `sensitive: true` marks in the config schema
+ * (see src/schema/sensitive-config-paths.ts) instead of being hardcoded.
+ *
+ * Legacy shape preserved verbatim from the pre-Phase-5.1 implementation:
+ * - warning format: `${projectPath}: project-level sensitive config '<dotted>' is ignored; set it in user config to trust it explicitly`
+ * - warning order: top-level keys first (executeWorkers, asyncByDefault,
+ *   requireCleanWorktreeLeader), then sections runtime → autonomous →
+ *   worktree → otlp → agents → tools; newly-marked sections (policy) follow
+ *   in schema order. Within a section, keys follow schema property order.
+ * - empty-object collapse: a section whose defined keys were all dropped
+ *   becomes `undefined`.
+ * - worktree/otlp redact via `{ ...section, key: undefined }` (the dropped
+ *   key remains as an own `undefined` key) while other sections `delete` it —
+ *   pinned by config-sanitize-merge.test.ts. runtime/autonomous are always
+ *   replaced by a shallow copy even when nothing was dropped (legacy shape).
+ *
+ * Wave 1A (S19-1/S19-2/S19-5, F19-4/F19-7): two extensions on top of the
+ * unconditional sensitive walk —
+ * - new unconditional marks: `goalWrap` (whole subtree, terminal Record
+ *   mark) and `autonomous.magicKeywords` are now user-only;
+ * - CONDITIONAL_PROJECT_DROPS (below): guard-tiering — the project tier may
+ *   only TIGHTEN these fields, never loosen them. The legacy inline
+ *   `requirePlanApproval === false` special-case is folded into that table
+ *   (same warning output).
+ */
+
+export function projectOverrideWarning(projectPath: string, dottedPath: string): string {
+	return `${projectPath}: project-level sensitive config '${dottedPath}' is ignored; set it in user config to trust it explicitly`;
+}
+
+/** Wave 1A guard-tiering (S19-1/S19-5, F19-4/F19-7 — ADR
+ * docs/decisions/2026-08-15-schema-driven-sanitize.md, "Wave 1A remediation"):
+ * dotted path -> predicate over the project value. When the predicate holds
+ * (the value LOOSENS a guard or disables an availability control) the key is
+ * dropped with the standard warning; every other value survives untouched.
+ * Applied AFTER the unconditional sensitive walk.
+ *
+ * `limits.maxConcurrentWorkers` deliberately has NO entry: the schema already
+ * bounds it (Type.Integer minimum 1, reader-side sanity ceilings) and a project
+ * can only lower it — i.e. tighten — so no drop is needed (ADR Wave 1A).
+ */
+export const CONDITIONAL_PROJECT_DROPS: Record<string, (value: unknown) => boolean> = {
+	// Legacy exception (ADR Decision 3, folded in here): only `=== false`
+	// loosens plan approval; `true` tightens and survives.
+	"runtime.requirePlanApproval": (value) => value === false,
+	// S19-1: both guards are ACTIVE by default ("warn") — "off" silently
+	// disables them for every contributor who has not pinned the field in
+	// user config. "warn"/"block"/"fail" tighten or keep the guard and survive.
+	"runtime.completionMutationGuard": (value) => value === "off",
+	"runtime.effectivenessGuard": (value) => value === "off",
+	// S19-1: unbounded concurrency is a resource-exhaustion loosening.
+	"limits.allowUnboundedConcurrency": (value) => value === true,
+	// S19-1: disabling recovery / model scoping loosens reliability guards.
+	"reliability.autoRecover": (value) => value === false,
+	"reliability.scopeModels": (value) => value === false,
+	// F19-7 (availability-only): a project may ENABLE the broker, never
+	// disable it repo-wide. Other broker fields are unmarked (as-is).
+	"broker.enabled": (value) => value === false,
+};
+
+/** Legacy top-level warning order (kept byte-identical to the pre-5.1 code). */
+const TOP_LEVEL_LEGACY_ORDER = ["executeWorkers", "asyncByDefault", "requireCleanWorktreeLeader"] as const;
+
+/** Legacy section processing order; unlisted sections (e.g. policy) follow in schema order. */
+const SECTION_LEGACY_ORDER = ["runtime", "autonomous", "worktree", "otlp", "agents", "tools"] as const;
+
+/** Sections where the pre-5.1 code always replaced `sanitized.<section>` with a
+ * shallow copy, even when nothing was dropped (runtime/autonomous). */
+const LEGACY_ALWAYS_COPY_SECTIONS = new Set<string>(["runtime", "autonomous"]);
+
+/** Sections redacting via assignment (`key: undefined`, own key remains) instead
+ * of `delete` — legacy quirk pinned by config-sanitize-merge.test.ts. */
+const ASSIGN_REDACT_SECTIONS = new Set<string>(["worktree", "otlp"]);
+
+function groupPathsBySection(dottedPaths: string[]): Map<string, string[]> {
+	const groups = new Map<string, string[]>();
+	for (const dotted of dottedPaths) {
+		const separator = dotted.indexOf(".");
+		const section = separator === -1 ? "" : dotted.slice(0, separator);
+		const key = separator === -1 ? dotted : dotted.slice(separator + 1);
+		const bucket = groups.get(section);
+		if (bucket) bucket.push(key);
+		else groups.set(section, [key]);
+	}
+	return groups;
+}
+
+function sectionProcessingOrder(sections: string[]): string[] {
+	return [...sections].sort((a, b) => {
+		const rankA = (SECTION_LEGACY_ORDER as readonly string[]).indexOf(a);
+		const rankB = (SECTION_LEGACY_ORDER as readonly string[]).indexOf(b);
+		// Unlisted sections (new sensitive marks) sort after legacy ones,
+		// preserving their schema-walk order (stable sort).
+		if (rankA === -1 && rankB === -1) return 0;
+		if (rankA === -1) return 1;
+		if (rankB === -1) return -1;
+		return rankA - rankB;
+	});
+}
+
+export function sanitizeProjectConfig(projectPath: string, userConfig: PiTeamsConfig, config: PiTeamsConfig): ConfigValidationResult {
+	const sanitized: PiTeamsConfig = { ...config };
+	const warnings: string[] = [];
+	const groups = groupPathsBySection(collectSensitiveConfigPaths());
+
+	const dropTopLevel = (key: string): void => {
+		if ((config as Record<string, unknown>)[key] === undefined) return;
+		delete (sanitized as Record<string, unknown>)[key];
+		warnings.push(projectOverrideWarning(projectPath, key));
+	};
+	const topLevelKeys = groups.get("") ?? [];
+	for (const key of [...topLevelKeys].sort((a, b) => {
+		const rankA = (TOP_LEVEL_LEGACY_ORDER as readonly string[]).indexOf(a);
+		const rankB = (TOP_LEVEL_LEGACY_ORDER as readonly string[]).indexOf(b);
+		if (rankA === -1 && rankB === -1) return 0;
+		if (rankA === -1) return 1;
+		if (rankB === -1) return -1;
+		return rankA - rankB;
+	})) {
+		dropTopLevel(key);
+	}
+
+	const sanitizedRecord = sanitized as Record<string, unknown>;
+	const configRecord = config as Record<string, unknown>;
+	for (const section of sectionProcessingOrder([...groups.keys()].filter((s) => s !== ""))) {
+		const sectionValue = configRecord[section];
+		if (sectionValue === undefined || typeof sectionValue !== "object") continue;
+		const sectionConfig = { ...(sectionValue as Record<string, unknown>) };
+		let changed = false;
+		for (const key of groups.get(section) ?? []) {
+			if (sectionConfig[key] === undefined) continue;
+			if (ASSIGN_REDACT_SECTIONS.has(section)) sectionConfig[key] = undefined;
+			else delete sectionConfig[key];
+			warnings.push(projectOverrideWarning(projectPath, `${section}.${key}`));
+			changed = true;
+		}
+		if (!changed && !LEGACY_ALWAYS_COPY_SECTIONS.has(section)) continue;
+		sanitizedRecord[section] = Object.values(sectionConfig).some((entry) => entry !== undefined) ? sectionConfig : undefined;
+	}
+
+	// Wave 1A guard-tiering: conditional drops run AFTER the unconditional
+	// sensitive walk. Sections holding conditional keys that carry no sensitive
+	// marks (limits, reliability, broker) never appear in `groups`, so this pass
+	// reads the SANITIZED config (runtime is already a shallow copy there),
+	// shallow-copies before deleting (input stays unmutated), and applies the
+	// same empty-object-collapse convention. runtime.* conditional drops thus
+	// integrate with the existing runtime section copy into one coherent result.
+	const conditionalGroups = groupPathsBySection(Object.keys(CONDITIONAL_PROJECT_DROPS));
+	for (const section of sectionProcessingOrder([...conditionalGroups.keys()].filter((s) => s !== ""))) {
+		const sectionValue = sanitizedRecord[section];
+		if (sectionValue === undefined || typeof sectionValue !== "object") continue;
+		const sectionConfig = { ...(sectionValue as Record<string, unknown>) };
+		let changed = false;
+		for (const key of conditionalGroups.get(section) ?? []) {
+			if (!CONDITIONAL_PROJECT_DROPS[`${section}.${key}`](sectionConfig[key])) continue;
+			delete sectionConfig[key];
+			warnings.push(projectOverrideWarning(projectPath, `${section}.${key}`));
+			changed = true;
+		}
+		if (!changed) continue;
+		sanitizedRecord[section] = Object.values(sectionConfig).some((entry) => entry !== undefined) ? sectionConfig : undefined;
+	}
+	return { config: sanitized, warnings };
+}
+
+/** @internal — direct-test seam for Phase 2.2 extraction target (refactor-plan step 1.9c). */
+export const __test__sanitizeProjectConfig = sanitizeProjectConfig;

package/src/config/types.ts

@@ -119,6 +119,10 @@ export interface CrewModelFallbackConfig {
 export interface CrewControlConfig {
 	enabled?: boolean;
 	needsAttentionAfterMs?: number;
+	/** Consecutive tool-failure threshold before a worker is flagged. Default 3 (applied at read site). */
+	consecutiveFailureThreshold?: number;
+	/** Minutes after which a running worker is flagged long-running. Default 10 (applied at read site). */
+	longRunningMinutes?: number;
 }
 
 export interface CrewWorktreeConfig {
@@ -282,6 +286,26 @@ export interface PiTeamsConfig {
 	 * schema (`src/schema/config-schema.ts`).
 	 */
 	broker?: CrewBrokerConfig;
+	/**
+	 * Governed nesting (ADR-5 docs/decisions/2026-08-17-governed-nesting.md).
+	 * Worker→grandchild delegation via the `delegate` tool. Default is OFF
+	 * (`enabled:false`) — fail-closed until WP-5 completes (B3 battery +
+	 * security sign-off), then flipped to true. While false, `delegate`
+	 * admission is rejected with a structured policy message and a
+	 * `delegate.rejected` event (never silent).
+	 */
+	nesting?: CrewNestingConfig;
+}
+
+/** Governed-nesting config (ADR-5). */
+export interface CrewNestingConfig {
+	/** Master switch. `false` (default) keeps the `delegate` surface dormant. */
+	enabled?: boolean;
+	/** Nested-slot budget override. Default max(1, floor(globalSem/2)). 1..64. */
+	maxSlots?: number;
+	/** Max crew depth for delegate-driven nesting. Default 2. 1..10 (mirrors
+	 *  the PI_CREW_MAX_DEPTH env clamp). */
+	maxDepth?: number;
 }
 
 /** CrewBroker config (Phase 0 inter-pi broker). */
@@ -294,6 +318,12 @@ export interface CrewBrokerConfig {
 	maxFrameBytes?: number;
 	/** Per-connection outbound queue cap. 32..4096 (default 256). */
 	outboundQueueCap?: number;
+	/** WP-2/R2 (ADR-0 docs/decisions/2026-08-17-waiting-producer-ask item 7):
+	 *  capability gate for the broker `wait.*` methods (waiting-producer park
+	 *  contract). DEFAULT FALSE — fail-closed until WP-2 completes; while
+	 *  false, wait.request/wait.resolve are rejected with a policy-disabled
+	 *  error plus a policy.action event in events.jsonl (never silent). */
+	waitMethodsEnabled?: boolean;
 }
 
 export interface LoadedPiTeamsConfig {

package/src/extension/async-notifier.ts

@@ -26,6 +26,21 @@ function isFinished(status: string): boolean {
 	return status === "completed" || status === "failed" || status === "cancelled" || status === "blocked";
 }
 
+// R5-M2 (Round 5 MEDIUM-2): FIFO cap for the dedupe Set. Set preserves
+// insertion order, so evicting .values().next().value drops the oldest-seen
+// runId. 256 >> the ~20 runs polled per tick; eviction only matters for a
+// long-lived host session that observes thousands of finished runs.
+const MAX_SEEN_FINISHED_RUN_IDS = 256;
+
+function addSeenFinishedRunId(state: AsyncNotifierState, runId: string): void {
+	state.seenFinishedRunIds.add(runId);
+	while (state.seenFinishedRunIds.size > MAX_SEEN_FINISHED_RUN_IDS) {
+		const oldest = state.seenFinishedRunIds.values().next().value;
+		if (oldest === undefined) break;
+		state.seenFinishedRunIds.delete(oldest);
+	}
+}
+
 export function isAsyncTerminalEvent(event: TeamEvent): boolean {
 	return event.type === "async.completed" || event.type === "async.failed" || event.type === "async.died";
 }
@@ -129,11 +144,15 @@ export function startAsyncRunNotifier(
 	const sid = extractSessionId(ctx);
 	const ownsRun = (run: TeamRunManifest): boolean => !sid || !run.ownerSessionId || run.ownerSessionId === sid;
 	for (const run of listRuns(ctx.cwd).filter(ownsRun)) {
+		// R5-M2: the seed scans the FULL listRuns() index (newest-first); stop
+		// seeding once the Set is at capacity so a huge historical index cannot
+		// push the newest finished runIds out via FIFO eviction.
+		if (state.seenFinishedRunIds.size >= MAX_SEEN_FINISHED_RUN_IDS) break;
 		// Suppress only terminal runs that were already finished before this owner
 		// session (or before the previous session switch). Active runs must remain
 		// un-seen so completions during auto-compaction/session restart are delivered.
 		const updatedAtMs = timeMs(run.updatedAt) ?? 0;
-		if (isFinished(run.status) && updatedAtMs < staleBeforeMs) state.seenFinishedRunIds.add(run.runId);
+		if (isFinished(run.status) && updatedAtMs < staleBeforeMs) addSeenFinishedRunId(state, run.runId);
 	}
 	let cachedRuns: TeamRunManifest[] | undefined;
 	state.interval = setInterval(() => {
@@ -147,7 +166,7 @@ export function startAsyncRunNotifier(
 			for (const run of cachedRuns) {
 				const current = markDeadAsyncRunIfNeeded(run) ?? run;
 				if (!isFinished(current.status) || state.seenFinishedRunIds.has(current.runId)) continue;
-				state.seenFinishedRunIds.add(current.runId);
+				addSeenFinishedRunId(state, current.runId);
 				// Suppress notifications for INTERNAL goal-loop sub-runs.
 				// The outer goal-loop creates a synthetic 'goal-turn' workflow per turn
 				// (see buildTurnWorkflow in goal-loop-runner.ts). These runs are
@@ -182,6 +201,10 @@ export function startAsyncRunNotifier(
 export function stopAsyncRunNotifier(state: AsyncNotifierState): void {
 	if (state.interval) clearInterval(state.interval);
 	state.interval = undefined;
+	// R5-M2: clear the dedupe Set on stop so entries do not persist across
+	// stop/start cycles; startAsyncRunNotifier re-seeds from listRuns() using
+	// lastStoppedAtMs, so runs finished before the stop stay suppressed.
+	state.seenFinishedRunIds.clear();
 	state.generation = (state.generation ?? 0) + 1;
 	state.lastStoppedAtMs = Date.now();
 }

package/src/extension/crew-vibes/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { getCrewEnv } from "../../config/env-vars.ts";
 import { hasCrewFontFile, isWebTerminal } from "./font-detect.ts";
 
 /**
@@ -13,7 +14,7 @@ export const CAPACITY_STATUS_ID = "pi-crew-bar";
 export const PROVIDER_STATUS_ID = "pi-crew-bar";
 
 function resolveHome(): string {
-	return (process.env.PI_TEAMS_HOME ?? process.env.PI_CREW_HOME)?.trim() || process.env.HOME || process.env.USERPROFILE || "";
+	return getCrewEnv("PI_CREW_HOME")?.trim() || process.env.HOME || process.env.USERPROFILE || "";
 }
 
 export function configPath(): string {

package/src/extension/plan-orchestrate.ts

@@ -5,7 +5,9 @@
  * for sequential agent chain execution based on ECC recommendations.
  */
 
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import type { PlanRecord } from "../state/types.ts";
 
 /**
  * Tag → Agent chain mapping from ECC recommendations.
@@ -300,3 +302,133 @@ export async function orchestratePlan(options: OrchestrateOptions): Promise<{
 
 	return { steps, chain, overview };
 }
+
+/**
+ * T2/R4 (ADR-4 §6, producer 1): convert parsed orchestrate steps into a
+ * PlanRecord. Pure — persistence (appendPlanRevision) is the caller's job.
+ * Phases group steps by tag in encounter order; item ids reuse the stable
+ * stepId so revisions diff cleanly. taskIds stay EMPTY (single-writer rule:
+ * only the scheduler links tasks, ADR-4 §3).
+ */
+export function stepsToPlanRecord(steps: OrchestratedStep[], runId: string, opts: { title?: string } = {}): PlanRecord {
+	const phaseOrder: string[] = [];
+	const byTag = new Map<string, OrchestratedStep[]>();
+	for (const step of steps) {
+		if (!byTag.has(step.tag)) {
+			byTag.set(step.tag, []);
+			phaseOrder.push(step.tag);
+		}
+		(byTag.get(step.tag) as OrchestratedStep[]).push(step);
+	}
+	return {
+		id: randomUUID(),
+		runId,
+		version: 1,
+		title: opts.title ?? "Orchestrated plan",
+		phases: phaseOrder.map((tag, i) => ({
+			id: `phase-${i + 1}-${tag}`,
+			title: byTag.get(tag)?.[0]?.heading ?? tag,
+			itemIds: (byTag.get(tag) ?? []).map((sqs) => sqs.stepId),
+			status: "pending",
+		})),
+		items: steps.map((sqs) => ({
+			id: sqs.stepId,
+			ref: sqs.stepId,
+			title: sqs.heading ?? sqs.prompt.slice(0, 80),
+			taskIds: [],
+			specIds: [],
+			acceptance: [],
+			status: "pending",
+		})),
+		createdAt: new Date().toISOString(),
+	};
+}
+
+/**
+ * T2/R4 (ADR-4 §6, producer 3): parse a planner-role task output into a
+ * PlanRecord. Contract: one fenced/tagged block
+ *
+ *   <plan>
+ *   { "title": "...", "phases": [{ "title": "...", "items": [{"id": "...", "title": "...", "task": "...", "acceptance": ["..."]}] }] }
+ *   </plan>
+ *
+ * The block content is JSON (code fences tolerated). Returns undefined when no
+ * block or malformed — callers treat that as "no plan record" (pre-v2 path).
+ * Item ids are namespaced `pi-<n>-<slug>` when the planner omits them, so ids
+ * stay stable across revisions for diff/carry-over.
+ */
+export function parsePlannerPlanOutput(text: string, runId: string, authorTaskId?: string): PlanRecord | undefined {
+	const blockMatch = text.match(/<plan>\s*([\s\S]*?)\s*<\/plan>/);
+	if (!blockMatch) return undefined;
+	let raw = blockMatch[1] as string;
+	// Security hardening (review S5): producer text is untrusted worker output —
+	// bound the parse input (deep nesting already fails safe via JSON.parse
+	// RangeError → catch → undefined; this caps the flat size too).
+	if (raw.length > 1_048_576) return undefined;
+	raw = raw.replace(/^```[a-z]*\n?/, "").replace(/\n?```$/, "");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+	const obj = parsed as { title?: unknown; phases?: unknown };
+	if (!Array.isArray(obj.phases) || obj.phases.length === 0) return undefined;
+	const phases: PlanRecord["phases"] = [];
+	const items: PlanRecord["items"] = [];
+	let n = 0;
+	for (const [phaseIndex, phaseRaw] of obj.phases.entries()) {
+		if (!phaseRaw || typeof phaseRaw !== "object" || Array.isArray(phaseRaw)) return undefined;
+		const phaseObj = phaseRaw as { title?: unknown; items?: unknown };
+		if (!Array.isArray(phaseObj.items) || phaseObj.items.length === 0) return undefined;
+		const phaseId = `phase-${phaseIndex + 1}`;
+		const itemIds: string[] = [];
+		for (const itemRaw of phaseObj.items) {
+			if (!itemRaw || typeof itemRaw !== "object" || Array.isArray(itemRaw)) return undefined;
+			const itemObj = itemRaw as { id?: unknown; title?: unknown; task?: unknown; acceptance?: unknown; ref?: unknown };
+			const taskText = typeof itemObj.task === "string" ? itemObj.task : undefined;
+			const title = typeof itemObj.title === "string" && itemObj.title.trim() ? itemObj.title.trim() : taskText?.slice(0, 80);
+			if (!title) return undefined;
+			n++;
+			const id = typeof itemObj.id === "string" && itemObj.id.trim() ? itemObj.id.trim() : `pi-${n}-${slugText(title)}`;
+			if (items.some((i) => i.id === id)) return undefined;
+			itemIds.push(id);
+			items.push({
+				id,
+				ref: typeof itemObj.ref === "string" ? itemObj.ref : undefined,
+				title,
+				taskIds: [],
+				specIds: [],
+				acceptance: Array.isArray(itemObj.acceptance) ? itemObj.acceptance.filter((a): a is string => typeof a === "string") : [],
+				status: "pending",
+			});
+		}
+		phases.push({
+			id: phaseId,
+			title: typeof phaseObj.title === "string" && phaseObj.title.trim() ? phaseObj.title.trim() : `Phase ${phaseIndex + 1}`,
+			itemIds,
+			status: "pending",
+		});
+	}
+	return {
+		id: randomUUID(),
+		runId,
+		version: 1,
+		title: typeof obj.title === "string" && obj.title.trim() ? obj.title.trim() : "Planner plan",
+		phases,
+		items,
+		createdAt: new Date().toISOString(),
+		authorTaskId,
+	};
+}
+
+function slugText(value: string): string {
+	return (
+		value
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "")
+			.slice(0, 32) || "item"
+	);
+}

package/src/extension/registration/commands/dashboard.ts

@@ -0,0 +1,158 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../../config/config.ts";
+import { DEFAULT_UI } from "../../../config/defaults.ts";
+import { readCrewAgents } from "../../../runtime/crew-agent-records.ts";
+import { loadRunManifestById } from "../../../state/stores/state-store.ts";
+import { requestRenderTarget } from "../../../ui/pi-ui-compat.ts";
+import { suggestRunIds, suggestTaskIds } from "../../command-completions.ts";
+import { commandText, notifyCommandResult } from "../command-utils.ts";
+import { openTranscriptViewer, selectAgentTask } from "../viewers.ts";
+import type { RegisterTeamCommandsDeps } from "./shared.ts";
+import { handleTeamTool, openTeamDashboard, teamCommandContext, ui } from "./shared.ts";
+
+export function registerDashboardCommands(pi: ExtensionAPI, deps: RegisterTeamCommandsDeps): void {
+	pi.registerCommand("team-result", {
+		description: "Open a pi-crew agent result viewer: <runId> [taskId]",
+		getArgumentCompletions: async (argumentPrefix: string) => {
+			const parts = argumentPrefix.trim().split(/\s+/);
+			return parts.length <= 1 ? suggestRunIds(parts[0] ?? "") : suggestTaskIds(parts[0] ?? "", parts[1] ?? "");
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const [runId, rawTaskId] = args.trim().split(/\s+/).filter(Boolean);
+			const selected = await selectAgentTask(ctx, runId, rawTaskId);
+			const loaded = selected ? loadRunManifestById(ctx.cwd, selected.runId) : undefined; // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+			if (ctx.hasUI && loaded) {
+				const agent =
+					readCrewAgents(loaded.manifest).find((item) => item.taskId === selected?.taskId || item.id === selected?.taskId) ??
+					readCrewAgents(loaded.manifest)[0];
+				const resultText = agent?.resultArtifactPath
+					? commandText(
+							await handleTeamTool(
+								{
+									action: "api",
+									runId: selected?.runId ?? "",
+									config: {
+										operation: "read-agent-output",
+										agentId: agent.taskId,
+										maxBytes: 64_000,
+									},
+								},
+								teamCommandContext(ctx),
+							),
+						)
+					: "(no result)";
+				const { DurableTextViewer } = await ui();
+				await ctx.ui.custom<undefined>(
+					(_tui, theme, _keybindings, done) =>
+						new DurableTextViewer(
+							"pi-crew result",
+							`${selected?.runId ?? ""}:${agent?.taskId ?? "unknown"}`,
+							resultText.split(/\r?\n/),
+							theme,
+							done,
+						),
+					{
+						overlay: true,
+						overlayOptions: {
+							width: "90%",
+							maxHeight: "85%",
+							anchor: "center",
+						},
+					},
+				);
+				return;
+			}
+			const result = await handleTeamTool(
+				{
+					action: "api",
+					runId,
+					config: {
+						operation: "read-agent-output",
+						agentId: rawTaskId,
+						maxBytes: 64_000,
+					},
+				},
+				teamCommandContext(ctx),
+			);
+			await notifyCommandResult(ctx, commandText(result));
+		},
+	});
+
+	pi.registerCommand("team-transcript", {
+		description: "Open a pi-crew transcript viewer: <runId> [taskId]",
+		getArgumentCompletions: async (argumentPrefix: string) => {
+			const parts = argumentPrefix.trim().split(/\s+/);
+			return parts.length <= 1 ? suggestRunIds(parts[0] ?? "") : suggestTaskIds(parts[0] ?? "", parts[1] ?? "");
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const [runId, taskId] = args.trim().split(/\s+/).filter(Boolean);
+			if (await openTranscriptViewer(ctx, runId, taskId)) return;
+			const result = await handleTeamTool(
+				{
+					action: "api",
+					runId,
+					config: {
+						operation: "read-agent-transcript",
+						agentId: taskId,
+					},
+				},
+				teamCommandContext(ctx),
+			);
+			await notifyCommandResult(ctx, commandText(result));
+		},
+	});
+
+	pi.registerCommand("team-dashboard", {
+		description: "Open a pi-crew run dashboard overlay",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			await openTeamDashboard(ctx);
+		},
+	});
+
+	pi.registerCommand("team-mascot", {
+		description: "Show an animated mascot splash",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			if (!ctx.hasUI) return;
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const uiConfig = loadConfig(ctx.cwd).config.ui;
+			const styleArg = tokens.find((t) => t === "cat" || t === "armin");
+			const effectArg = tokens.find((t) =>
+				["random", "none", "typewriter", "scanline", "rain", "fade", "crt", "glitch", "dissolve"].includes(t),
+			);
+			const style = (styleArg as "cat" | "armin" | undefined) ?? uiConfig?.mascotStyle ?? DEFAULT_UI.mascotStyle;
+			const effect =
+				(effectArg as
+					| "random"
+					| "none"
+					| "typewriter"
+					| "scanline"
+					| "rain"
+					| "fade"
+					| "crt"
+					| "glitch"
+					| "dissolve"
+					| undefined) ??
+				uiConfig?.mascotEffect ??
+				DEFAULT_UI.mascotEffect;
+			const { AnimatedMascot } = await ui();
+			await ctx.ui.custom<undefined>(
+				(tui, theme, _keybindings, done) =>
+					new AnimatedMascot(theme, () => done(undefined), {
+						frameIntervalMs: style === "armin" ? 100 : 180,
+						autoCloseMs: 7000,
+						requestRender: () => requestRenderTarget(tui),
+						style,
+						effect,
+					}),
+				{
+					overlay: true,
+					overlayOptions: {
+						width: style === "armin" ? 48 : 62,
+						maxHeight: "85%",
+						anchor: "center",
+					},
+				},
+			);
+		},
+	});
+}