pi-crew 0.9.68 → 0.10.2

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,15 +84,17 @@ 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,
 	},
 
-	// Test Engineer - Can write tests (F1: hyphenated key)
+	// Test Engineer - Can write tests (F1: hyphenated key). Tool list mirrors
+	// agents/test-engineer.md frontmatter (T3 binding, commit c25dfbe2):
+	// search tools + delegate for spawning depth-1 helpers.
 	"test-engineer": {
-		tools: ["read", "edit", "write", "bash", "ls", "scratchpad"],
+		tools: ["read", "edit", "write", "bash", "ls", "glob", "grep", "find", "scratchpad", "ask", "delegate"],
 		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 {
@@ -139,8 +143,26 @@ export interface GoalWrapWorkflowConfig {
 }
 
 export interface CrewUiConfig {
-	widgetPlacement?: "aboveEditor" | "belowEditor";
+	/**
+	 * Where the crew dock (agents list) renders:
+	 *  - `aboveEditor` / `belowEditor`: pi's widget slots around the prompt;
+	 *  - `bottom`: inside the crew-vibes footer, BELOW the quota/meter lines
+	 *    (the very bottom of the screen). Falls back to `belowEditor` when
+	 *    crew-vibes is not active (no footer sink).
+	 */
+	widgetPlacement?: "aboveEditor" | "belowEditor" | "bottom";
 	widgetMaxLines?: number;
+	/**
+	 * Per-agent row layout in the widget. `compact` is one width-budgeted line
+	 * per agent; `detailed` keeps the two-line tree (name row + activity row).
+	 */
+	widgetRowStyle?: "compact" | "detailed";
+	/**
+	 * Keyboard-navigable agent rows under the prompt (`↓` from an empty prompt).
+	 * Requires owning pi's editor component, so it yields to any other extension
+	 * that already installed a custom editor.
+	 */
+	inlinePanel?: boolean;
 	powerbar?: boolean;
 	dashboardPlacement?: "center" | "right";
 	dashboardWidth?: number;
@@ -282,6 +304,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 +336,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-cleanup.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { cleanupAllTrackedTempDirs } from "../runtime/model/pi-args.ts";
+import { isSessionSwitchInFlight } from "../ui/inline-panel/view-session-store.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 
 // NOTE: globalProgressTracker import kept for documentation but not directly used
@@ -67,6 +68,18 @@ export function registerCleanupHandler(pi: ExtensionAPI, opts?: { disposeTermina
 		console.log("[pi-crew] Session shutdown - cleaning up resources");
 
 		try {
+			// Navigational switches (pi's own resume/new/fork) tear the session
+			// down on purpose — the user is only LOOKING at a different pi
+			// session; foreground team runs + their workers share this process
+			// and must keep running (P0: "jumping into any session stops the
+			// run" — exit 143 signature). Killing them here bypasses child-pi's
+			// abort flags, so the worker exit reads as an "unexpected
+			// code=143 signal=null" and the run is cancelled. Same contract as
+			// stopSessionBoundSubagents and the run-deadline caller-abort
+			// suppression; on REAL shutdowns (quit/reload) the flag is unset
+			// and this cleanup still drains the registry, as does the
+			// process-exit hook (tryRegisterSessionCleanup) when pi dies.
+			if (isSessionSwitchInFlight()) return;
 			// Kill all child-pi processes
 			await cleanupChildProcesses();
 

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/crew-vibes/footer.ts

@@ -1,7 +1,9 @@
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getFooterDockProvider } from "../../ui/dock-footer.ts";
 import { requestRenderTarget } from "../../ui/pi-ui-compat.ts";
 import { asCrewTheme, type CrewTheme } from "../../ui/theme-adapter.ts";
+import { colorWidgetLine, renderLines } from "../../ui/widget/widget-renderer.ts";
 import { truncateToWidth, visibleWidth } from "../../utils/visual.ts";
 import type { CrewVibesConfig } from "./config.ts";
 import type { ProviderUsage } from "./provider-usage.ts";
@@ -280,11 +282,28 @@ class CrewVibesFooter implements FooterComponent {
 		return [truncateToWidth(cap, width, "…"), this.rightAlign(quota, width)];
 	}
 
+	/** Dock lines registered by the crew widget (`widgetPlacement: "bottom"`):
+	 *  painted as the very last block of the footer, below the quota/meters.
+	 *  The provider returns RAW lines; we color them with this footer's theme
+	 *  (same per-line palette the widget would have used) and truncate to the
+	 *  real render width. */
+	private buildDockLines(width: number): string[] {
+		const provider = getFooterDockProvider();
+		if (!provider) return [];
+		const raw = provider(width);
+		if (raw.length === 0) return [];
+		return renderLines(
+			raw.map((line, index) => colorWidgetLine(line, index, this.theme)),
+			width,
+		).map((line) => truncateToWidth(line, width, "…"));
+	}
+
 	render(width: number): string[] {
 		const lines = [this.buildPwdLine(width), this.buildStatsLine(width)];
 		const statusLine = this.buildStatusLine(width);
 		if (statusLine) lines.push(statusLine);
 		lines.push(...this.buildMeterLines(width));
+		lines.push(...this.buildDockLines(width));
 		return lines;
 	}
 }

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

@@ -19,6 +19,7 @@ function safeUiCall(scope: string, fn: () => void): void {
 	}
 }
 
+import { setFooterDockSinkActive } from "../../ui/dock-footer.ts";
 import { type CrewVibesConfig, loadConfig, saveConfig } from "./config.ts";
 import { intervalForSpeed } from "./figures.ts";
 import { type CrewVibesFooterSource, createCrewVibesFooter } from "./footer.ts";
@@ -91,11 +92,18 @@ export function registerCrewVibes(pi: ExtensionAPI): void {
 	function installFooter(ctx: ExtensionContext): void {
 		if (!ctx?.hasUI) return;
 		if (!metersActive()) {
-			safeUiCall("clear-footer", () => setFooter(ctx, undefined));
+			safeUiCall("clear-footer", () => {
+				// The crew dock can no longer render at the very bottom — the
+				// widget falls back to pi's belowEditor slot automatically.
+				setFooterDockSinkActive(false);
+				setFooter(ctx, undefined);
+			});
 			return;
 		}
 		safeUiCall("install-footer", () => {
 			setFooter(ctx, (tui, theme, footerData) => createCrewVibesFooter({ tui, theme, footerData, ctx, source: footerSource }));
+			// The footer can now host the crew dock below the quota lines.
+			setFooterDockSinkActive(true);
 			requestRender(ctx);
 		});
 	}
@@ -245,6 +253,7 @@ export function registerCrewVibes(pi: ExtensionAPI): void {
 			stopFooterTimer();
 			stopCapacityTimer();
 			stopProviderTimer();
+			setFooterDockSinkActive(false);
 			setFooter(ctx, undefined);
 			clearVibesStatus(ctx);
 			return;
@@ -370,6 +379,7 @@ export function registerCrewVibes(pi: ExtensionAPI): void {
 		stopFooterTimer();
 		stopCapacityTimer();
 		stopProviderTimer();
+		setFooterDockSinkActive(false);
 		setFooter(ctx, undefined);
 		clearVibesStatus(ctx);
 	});

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"
+	);
+}