pi-crew 0.10.2 → 0.10.4

package/src/config/config-merge.ts

@@ -31,7 +31,8 @@ export function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTea
 	}
 	if (base.nesting || override.nesting) {
 		// ADR-5: per-key user-wins deep merge — a partial user-side nesting block
-		// (e.g. just maxSlots) must not erase DEFAULT_NESTING.enabled=false.
+		// (e.g. just maxSlots) must not erase DEFAULT_NESTING.enabled (true since
+		// the D8 flip; explicit user false still wins as the kill switch).
 		merged.nesting = {
 			...(base.nesting ?? {}),
 			...withoutUndefined((override.nesting ?? {}) as Record<string, unknown>),
@@ -59,6 +60,15 @@ export function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTea
 				...withoutUndefined((override.runtime?.modelFallback ?? {}) as Record<string, unknown>),
 			};
 		}
+		// Spec v0.7 §8.1 (Task 6): same per-key treatment for the surface
+		// block — a user surface with only visibleAgents must not wholesale-
+		// erase a project surface.mode (the WP-2/R2 bug class).
+		if (base.runtime?.surface || override.runtime?.surface) {
+			merged.runtime.surface = {
+				...(base.runtime?.surface ?? {}),
+				...withoutUndefined((override.runtime?.surface ?? {}) as Record<string, unknown>),
+			};
+		}
 	}
 	if (base.control || override.control) {
 		merged.control = {

package/src/config/config-validation.ts

@@ -23,6 +23,7 @@ import type {
 	CrewUiConfig,
 	CrewWorktreeConfig,
 	GoalWrapWorkflowConfig,
+	PersistenceConfig,
 	PiTeamsAutonomousConfig,
 	PiTeamsAutonomyProfile,
 	PiTeamsConfig,
@@ -155,7 +156,13 @@ function parseProfile(value: unknown): PiTeamsAutonomyProfile | undefined {
 
 function parseStringList(value: unknown): string[] | undefined {
 	const items = parseWithSchema(Type.Array(Type.String()), value);
-	if (!items || items.length === 0) return undefined;
+	if (!items) return undefined;
+	// F3 (real-test 2026-08-30-post-tab-layout-live, Finding 3): an explicit
+	// empty array is a VALUE ("nobody"/"none"), not "unset" — dropping it here
+	// made `team-settings set <key> []` a no-op that silently kept the previous
+	// list on disk. Whitespace-only entries below still collapse to undefined
+	// (unchanged legacy behavior).
+	if (items.length === 0) return [];
 	const normalized = items.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
 	return normalized.length > 0 ? normalized : undefined;
 }
@@ -281,6 +288,24 @@ function parseIsolationPolicy(value: unknown): CrewRuntimeConfig["isolationPolic
 	};
 }
 
+/** Mux-surface policy (spec v0.7 §8.1) — mirrors the isolationPolicy parse
+ *  shape: unknown literals are dropped field-wise (never thrown), and an
+ *  all-invalid block collapses to undefined. */
+function parseSurfacePolicy(value: unknown): CrewRuntimeConfig["surface"] | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	const mode = parseWithSchema(
+		Type.Union([Type.Literal("auto"), Type.Literal("tmux"), Type.Literal("herdr"), Type.Literal("off")]),
+		obj.mode,
+	);
+	const visibleAgents = parseStringList(obj.visibleAgents);
+	if (mode === undefined && visibleAgents === undefined) return undefined;
+	return {
+		...(mode !== undefined ? { mode } : {}),
+		...(visibleAgents !== undefined ? { visibleAgents } : {}),
+	};
+}
+
 /**
  * F19-1 (Round 19 parity): runtime.modelFallback was declared in types.ts and the
  * schema (PiTeamsModelFallbackConfigSchema) but parseRuntimeConfig never emitted
@@ -338,6 +363,7 @@ function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 		excludeContextBash: parseWithSchema(Type.Boolean(), obj.excludeContextBash),
 		agentExtensions: parseStringList(obj.agentExtensions),
 		isolationPolicy: parseIsolationPolicy(obj.isolationPolicy),
+		surface: parseSurfacePolicy(obj.surface),
 		modelFallback: parseModelFallbackConfig(obj.modelFallback),
 	};
 	return Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;
@@ -384,6 +410,18 @@ function parseBrokerConfig(value: unknown): CrewBrokerConfig | undefined {
 	return Object.values(broker).some((entry) => entry !== undefined) ? broker : undefined;
 }
 
+/** PERF round 2, Task 3: state-layer persistence parser. Opt-in only;
+ *  the default (false) is layered in loadConfig via DEFAULT_PERSISTENCE,
+ *  so a missing block here means "not set", never "false" by default. */
+function parsePersistenceConfig(value: unknown): PersistenceConfig | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	const persistence: PersistenceConfig = {
+		skipTasksFsync: parseWithSchema(Type.Boolean(), obj.skipTasksFsync),
+	};
+	return Object.values(persistence).some((entry) => entry !== undefined) ? persistence : undefined;
+}
+
 function parseWorktreeConfig(value: unknown): CrewWorktreeConfig | undefined {
 	const obj = asRecord(value);
 	if (!obj) return undefined;
@@ -676,6 +714,7 @@ export function parseConfig(raw: unknown): PiTeamsConfig {
 		otlp: parseOtlpConfig(obj.otlp),
 		ui: parseUiConfig(obj.ui),
 		broker: parseBrokerConfig(obj.broker),
+		persistence: parsePersistenceConfig(obj.persistence),
 	};
 }
 

package/src/config/config.ts

@@ -7,8 +7,8 @@ import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 import { mergeConfig } from "./config-merge.ts";
 import { parseConfig, parseConfigWithWarnings } from "./config-validation.ts";
-import { DEFAULT_BROKER, DEFAULT_NESTING, resolveBrokerEnvOverride } from "./defaults.ts";
-import { getCrewEnv } from "./env-vars.ts";
+import { DEFAULT_BROKER, DEFAULT_NESTING, DEFAULT_PERSISTENCE, resolveBrokerEnvOverride } from "./defaults.ts";
+import { getCrewEnv, getCrewEnvBool } from "./env-vars.ts";
 import { sanitizeProjectConfig } from "./sanitize-project-config.ts";
 
 // 2.9: interface types extracted to ./types.ts; re-export for back-compat.
@@ -45,6 +45,7 @@ import type {
 	CrewBrokerConfig,
 	CrewNestingConfig,
 	LoadedPiTeamsConfig,
+	PersistenceConfig,
 	PiTeamsAutonomousConfig,
 	PiTeamsConfig,
 	SavedPiTeamsConfig,
@@ -225,8 +226,9 @@ export function projectPiCrewJsonPath(cwd: string): string {
  * config block, or default.
  */
 
-/** ADR-5 §10: layer DEFAULT_NESTING under any user-set keys — the
- *  fail-closed enabled=false default must hold when no nesting block exists. */
+/** ADR-5 §10: layer DEFAULT_NESTING under any user-set keys — the default-on
+ *  enabled=true (D8 flip) must hold when no nesting block exists, and an
+ *  explicit user `enabled: false` still wins as the kill switch. */
 function applyNestingDefaults(parsed: CrewNestingConfig | undefined): CrewNestingConfig {
 	return { ...DEFAULT_NESTING, ...parsed };
 }
@@ -235,6 +237,21 @@ function applyBrokerEnvOverrideAndDefaults(parsed: CrewBrokerConfig | undefined)
 	return { ...DEFAULT_BROKER, ...envOverridden };
 }
 
+/**
+ * Resolve the persistence section (perf round 2, Task 3).
+ * Precedence: env `PI_CREW_PERSISTENCE_SKIP_TASKS_FSYNC` ("1"/"true") BEATS a
+ * config `persistence.skipTasksFsync`; config beats the DEFAULT_PERSISTENCE
+ * default (false). Mirrors resolveBrokerEnvOverride's env-beats-config shape.
+ */
+function resolvePersistenceEnvOverrideAndDefaults(parsed: PersistenceConfig | undefined): PersistenceConfig {
+	const envOverride = getCrewEnvBool("PI_CREW_PERSISTENCE_SKIP_TASKS_FSYNC");
+	return {
+		...DEFAULT_PERSISTENCE,
+		...parsed,
+		...(envOverride === undefined ? {} : { skipTasksFsync: envOverride }),
+	};
+}
+
 function unsetPath(record: Record<string, unknown>, dottedPath: string): void {
 	const parts = dottedPath.split(".").filter(Boolean);
 	if (parts.length === 0) return;
@@ -377,15 +394,20 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 			// the enabled flag even when no broker block is configured.
 			broker: applyBrokerEnvOverrideAndDefaults(config.broker),
 			nesting: applyNestingDefaults(config.nesting),
+			// PERF round 2, Task 3: env beats config, config beats the default.
+			persistence: resolvePersistenceEnvOverrideAndDefaults(config.persistence),
 		},
 		warnings: warnings.length > 0 ? warnings : undefined,
 	};
+	// PERF (2026-08-24): readCacheMtimes stats up to 4 files per call and ran
+	// twice back-to-back here (guard + store). Compute once.
+	const storeMtimes = readCacheMtimes(cacheParts);
 	// Only cache when at least one of the watched paths exists — this avoids
 	// pinning stale empty results when a user later creates one of these files
 	// in the cache window. mtime stat below picks up the new file (it appears
 	// in currentMtimes but not in cached.mtimes) and triggers a re-parse.
-	if (Object.keys(readCacheMtimes(cacheParts)).length > 0) {
-		setConfigCache(cacheKey, result, readCacheMtimes(cacheParts));
+	if (Object.keys(storeMtimes).length > 0) {
+		setConfigCache(cacheKey, result, storeMtimes);
 	}
 	return result;
 }

package/src/config/defaults.ts

@@ -194,24 +194,49 @@ export const DEFAULT_BROKER = {
 	maxFrameBytes: 262144,
 	outboundQueueCap: 256,
 	/** WP-2/R2 (ADR-0 docs/decisions/2026-08-17-waiting-producer-ask item 7):
-	 *  capability gate for the broker's `wait.*` methods. DEFAULT FALSE —
-	 *  fail-closed until WP-2 completes, then flipped to true. While false,
+	 *  capability gate for the broker's `wait.*` methods. FLIPPED TO TRUE
+	 *  (2026-08-26): WP-2 completed and its battery landed, so the ADR-0
+	 *  "then flipped to true" step is now done — ask works out of the box.
+	 *  (Before this flip, every production ask was rejected policy-disabled
+	 *  whenever no user config existed — the feature slept silently.) Set
+	 *  `broker.waitMethodsEnabled: false` to re-close. While false,
 	 *  wait.request/wait.resolve are rejected with a policy-disabled error
 	 *  AND a policy.action event in events.jsonl (never silent). */
-	waitMethodsEnabled: false,
+	waitMethodsEnabled: true,
 } as const;
 
 /**
  * Governed-nesting defaults (ADR-5 docs/decisions/2026-08-17-governed-nesting.md §10).
- * `enabled` is DEFAULT FALSE — fail-closed until WP-5 completes (B3 battery +
- * security sign-off), then flipped to true. While false, the `delegate`
- * surface rejects with a structured policy message and a `delegate.rejected`
- * event in events.jsonl (never silent). `maxSlots` default is computed at the
- * spawn policy from the global worker semaphore: max(1, floor(globalSem/2)).
+ * `enabled` is DEFAULT TRUE since D8 (spec v0.7, 2026-08-26): the WP-5
+ * completion gate (B3 battery + security sign-off) passed and Task 3 opened
+ * the `delegate` role gate for every role, so nested spawning — child creates
+ * child — is on out of the box. The security border moved to the depth cap
+ * (maxDepth 4) + the nested-slot budget; `nesting.enabled: false` in USER
+ * config (sensitive — project config cannot flip it) closes the surface, and
+ * while closed `delegate` rejects with a structured policy message plus a
+ * `delegate.rejected` event in events.jsonl (never silent). `maxSlots` default
+ * is computed at the spawn policy from the global worker semaphore:
+ * max(1, floor(globalSem/2)).
  */
 export const DEFAULT_NESTING = {
-	enabled: false,
-	maxDepth: 2,
+	enabled: true,
+	// D8 (spec v0.7): nested spawning open — child creates child. Kept in
+	// lockstep with DEFAULT_MAX_CREW_DEPTH (pi-args) so the broker-admission
+	// depth gate and the spawn-side cap can never disagree.
+	maxDepth: 4,
+} as const;
+
+/**
+ * State-layer persistence defaults (perf round 2, Task 3).
+ * `skipTasksFsync` is DEFAULT FALSE — opt-in only. Because the flag is
+ * consumed at the save site in the state layer, `loadConfig` must READ it
+ * (not default-on-borrow): the flag affects the cost of every non-terminal
+ * tasks checkpoint, so it must never silently flip from "fsync" to "no
+ * fsync" due to a config default alone. Env `PI_CREW_PERSISTENCE_SKIP_TASKS_FSYNC`
+ * ("1"/"true") beats config; config beats this default.
+ */
+export const DEFAULT_PERSISTENCE = {
+	skipTasksFsync: false,
 } as const;
 
 /**

package/src/config/env-vars.ts

@@ -270,8 +270,8 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	PI_CREW_INTERRUPT_GUARD_INTERVAL_MS: {
 		name: "PI_CREW_INTERRUPT_GUARD_INTERVAL_MS",
 		parser: "int",
-		default: 250,
-		doc: "interrupt-guard poll interval; default 250ms (background-runner.ts:217)",
+		default: 1000,
+		doc: "interrupt-guard poll interval; default 1000ms (background-runner.ts:217)",
 	},
 	PI_CREW_MAX_RUN_MS: {
 		name: "PI_CREW_MAX_RUN_MS",
@@ -323,6 +323,11 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_PLAN_UI",
 		doc: "'1' enables the Plan dashboard pane (7) + plans snapshot slice (WP-7/R7)",
 	},
+	PI_CREW_PERSISTENCE_SKIP_TASKS_FSYNC: {
+		name: "PI_CREW_PERSISTENCE_SKIP_TASKS_FSYNC",
+		parser: "boolean",
+		doc: "'1'/'true' writes non-terminal tasks checkpoints best-effort (no fsync; 50ms coalesce kept, only durability skipped); terminal transitions stay full (defaults.ts, config.ts persistence.skipTasksFsync)",
+	},
 	PI_CREW_TRUST_PROJECT_DWF: {
 		name: "PI_CREW_TRUST_PROJECT_DWF",
 		doc: "'1' allows project-sourced .dwf.ts workflows (dynamic-workflow-runner.ts:154)",
@@ -390,6 +395,10 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_ASK_ENABLED",
 		doc: "'1' enables the worker-side ask tool — dormant-until-env gate (written UNCONDITIONALLY by child-pi-spawn.ts, read by prompt-runtime.ts per ADR-0 WP-2 item 2)",
 	},
+	PI_CREW_MSG_ENABLED: {
+		name: "PI_CREW_MSG_ENABLED",
+		doc: "'1' enables the worker-side message tool (D9/§15.2) — dormant-until-env gate (written UNCONDITIONALLY by child-pi-spawn.ts, read by prompt-runtime.ts)",
+	},
 	PI_CREW_STATE_ROOT: {
 		name: "PI_CREW_STATE_ROOT",
 		doc: "run stateRoot for the ask-tool mailbox poll (<stateRoot>/mailbox; written by child-pi-spawn.ts, read by prompt-runtime.ts per ADR-0 WP-2 item 2)",
@@ -398,6 +407,22 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_BROKER_RUN_ID",
 		doc: "broker run id; aliases PI_CREW_RUN_ID (scratchpad-lifecycle.ts:81, crew-broker-child.ts:51)",
 	},
+	PI_CREW_AGENT_EVENTS_PATH: {
+		name: "PI_CREW_AGENT_EVENTS_PATH",
+		doc: "per-agent events log (<stateRoot>/agents/<taskId>/events.jsonl) written by the surface worker recorder (surface-worker.ts; derived by prepareSurfaceSpawn)",
+	},
+	PI_CREW_AUTO_EXIT: {
+		name: "PI_CREW_AUTO_EXIT",
+		doc: "'1' → the worker shuts its session down after the final settled turn — spec §5.2 D7 (written by prepareSurfaceSpawn, read by surface-worker.ts)",
+	},
+	PI_CREW_SURFACE: {
+		name: "PI_CREW_SURFACE",
+		doc: "surface provider kind for this worker ('tmux'|'herdr') — arms the worker-side recorder/parent-guard (written by prepareSurfaceSpawn.ts:214, read by surface-worker.ts)",
+	},
+	PI_CREW_PARENT_START_TIME: {
+		name: "PI_CREW_PARENT_START_TIME",
+		doc: "parent starttime ticks (/proc/<pid>/stat field 22) captured at spawn — pid-reuse-safe parent-guard comparison (written by prepareSurfaceSpawn.ts:223, read by surface-worker.ts)",
+	},
 	PI_CREW_ARTIFACTS_ROOT: {
 		name: "PI_CREW_ARTIFACTS_ROOT",
 		doc: "artifacts root for scratchpad containment (scratchpad-lifecycle.ts:228/281)",

package/src/config/migration-validator.ts

@@ -0,0 +1,113 @@
+/**
+ * migration-validator.ts — WI-5.6 (M5 spec §5).
+ *
+ * Validates a parsed config against deprecated/removed env keys and
+ * returns an advisory list (not a failure). Per spec acceptance:
+ *   "Migration validator: test case cũ config + key deprecated →
+ *    warning không fail."
+ *
+ * Key principles (additive-only, READ-ONLY — the validator never mutates
+ * env or config):
+ *   - Deprecated: emit warning (severity "deprecated"), keep the value,
+ *     do not fail.
+ *   - Removed/dead/reverted: emit warning (severity "removed"), do not
+ *     fail, do NOT delete the key (cleanup is a separate concern).
+ *   - Keys not in the registry are not scanned (registry-driven scan).
+ *
+ * Returns an advisory list; never throws.
+ */
+
+import { CREW_ENV_VARS } from "./env-vars.ts";
+
+export interface ValidationWarning {
+	scope: "env-var" | "config-key";
+	name: string;
+	severity: "deprecated" | "removed";
+	message: string;
+	/** Optional policy note from the registry entry. */
+	policy?: string;
+}
+
+export interface EnvValidationResult {
+	warnings: ValidationWarning[];
+	/** Fast-bool for callers that don't need detail. */
+	hasWarnings: boolean;
+}
+
+/** Validate `process.env` against the registry. Returns warnings; never
+ *  throws. */
+export function validateEnv(env: NodeJS.ProcessEnv = process.env): EnvValidationResult {
+	const warnings: ValidationWarning[] = [];
+	if (!env || typeof env !== "object") return { warnings, hasWarnings: false };
+	for (const [name, spec] of Object.entries(CREW_ENV_VARS)) {
+		let value: string | undefined;
+		try {
+			value = (env as Record<string, string | undefined>)[name];
+		} catch {
+			value = undefined;
+		}
+		if (value === undefined) continue;
+		if (spec.deprecated !== undefined) {
+			// Distinguish DEAD/REMOVED vs DEPRECATED-but-working.
+			const lower = spec.deprecated.toLowerCase();
+			if (lower === "dead" || lower === "removed" || lower.startsWith("reverted")) {
+				warnings.push({
+					scope: "env-var",
+					name,
+					severity: "removed",
+					message: `${name} is ${spec.deprecated}; setting it has no effect`,
+					policy: spec.deprecated,
+				});
+				// Note: we DO NOT delete env[name] here; that's a separate
+				// cleanup concern. The validator is read-only.
+			} else {
+				warnings.push({
+					scope: "env-var",
+					name,
+					severity: "deprecated",
+					message: `${name} is deprecated (${spec.deprecated}); prefer the canonical name`,
+					policy: spec.deprecated,
+				});
+			}
+		}
+	}
+	return { warnings, hasWarnings: warnings.length > 0 };
+}
+
+/** Validate a parsed config object against the env-var registry.
+ *  Useful for: a config file that hardcodes a removed key. */
+export function validateConfigAgainstEnvRegistry(config: Record<string, unknown>): EnvValidationResult {
+	const warnings: ValidationWarning[] = [];
+	if (!config || typeof config !== "object") return { warnings, hasWarnings: false };
+	for (const [name, spec] of Object.entries(CREW_ENV_VARS)) {
+		let present = false;
+		try {
+			present = name in config;
+		} catch {
+			present = false;
+		}
+		if (present) {
+			if (spec.deprecated !== undefined) {
+				const lower = spec.deprecated.toLowerCase();
+				if (lower === "dead" || lower === "removed" || lower.startsWith("reverted")) {
+					warnings.push({
+						scope: "config-key",
+						name,
+						severity: "removed",
+						message: `${name} config key is ${spec.deprecated}`,
+						policy: spec.deprecated,
+					});
+				} else {
+					warnings.push({
+						scope: "config-key",
+						name,
+						severity: "deprecated",
+						message: `${name} config key is deprecated (${spec.deprecated})`,
+						policy: spec.deprecated,
+					});
+				}
+			}
+		}
+	}
+	return { warnings, hasWarnings: warnings.length > 0 };
+}

package/src/config/types.ts

@@ -85,6 +85,21 @@ export interface CrewRuntimeConfig {
 	};
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens. Default: false */
 	excludeContextBash?: boolean;
+	/**
+	 * Mux-surface policy (mux-surface spec v0.7 §8.1): WHERE worker processes
+	 * live — a pane in tmux/herdr or headless child processes. Surface only
+	 * picks the process home; scheduler, broker, and state-on-disk are
+	 * unaffected. Not sensitive — any config tier may set it.
+	 */
+	surface?: {
+		/** auto = detect tmux/herdr and use panes when present, else headless.
+		 *  "tmux"/"herdr" force a backend (detect fail → headless + warning
+		 *  event, never a throw). "off" disables panes entirely. Default: "auto". */
+		mode?: "auto" | "tmux" | "herdr" | "off";
+		/** Exact-match agent/role names that get a surface pane; ["*"] = all.
+		 *  Default: [] in A1 (surface visible to nobody until opted in). */
+		visibleAgents?: string[];
+	};
 	/** Subagent model fallback policy: auto-tail ordering, cap, credential filtering, default model. */
 	modelFallback?: CrewModelFallbackConfig;
 }
@@ -313,6 +328,27 @@ export interface PiTeamsConfig {
 	 * `delegate.rejected` event (never silent).
 	 */
 	nesting?: CrewNestingConfig;
+	/** State-layer persistence knobs (perf round 2, Task 3). Opt-in only. */
+	persistence?: PersistenceConfig;
+}
+
+/** State-layer persistence knobs (perf round 2, Task 3). */
+export interface PersistenceConfig {
+	/**
+	 * Opt-in (default `false`): write non-terminal tasks checkpoints with
+	 * `durability:"best-effort"` (no fsync) while KEEPING the 50ms coalesced
+	 * write grouping — only the durability of the flush changes, not its
+	 * timing. tasks.json is fully reconstructible from the fsync'd event log,
+	 * so a crash loses at most the tail of an in-flight checkpoint and
+	 * recovers from events.jsonl. Terminal task transitions (completed/failed/
+	 * cancelled/needs_attention/skipped) ALWAYS stay full-durability
+	 * regardless of this flag.
+	 * Set via env `PI_CREW_PERSISTENCE_SKIP_TASKS_FSYNC` (`"1"`/`"true"`) or
+	 * config `persistence.skipTasksFsync`. Env beats config; default false.
+	 * @see src/state/stores/state-store.ts saveRunTasksCoalesced
+	 * @see src/runtime/task-runner/state-helpers.ts persistSingleTaskUpdate
+	 */
+	skipTasksFsync?: boolean;
 }
 
 /** Governed-nesting config (ADR-5). */

package/src/extension/cross-extension-rpc.ts

@@ -5,17 +5,13 @@ import { withHmacVerification } from "./rpc-hmac.ts";
 // Lazy-loaded to avoid pulling team-tool.ts (and its entire runtime chain) into module load.
 import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
 
-let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 async function handleTeamTool(
 	params: Parameters<typeof HandleTeamToolFn>[0],
 	ctx: Parameters<typeof HandleTeamToolFn>[1],
 ): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
-	if (!_cachedHandleTeamTool) {
-		// LAZY: avoid pulling team-tool.ts (and its entire runtime chain) into module load.
-		const mod = await import("./team-tool.ts");
-		_cachedHandleTeamTool = mod.handleTeamTool;
-	}
-	return _cachedHandleTeamTool(params, ctx);
+	// LAZY: avoid pulling team-tool.ts (and its entire runtime chain) into module load.
+	const mod = await import("./team-tool.ts");
+	return mod.handleTeamTool(params, ctx);
 }
 
 import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-session/live-control-realtime.ts";

package/src/extension/register.ts

@@ -18,6 +18,7 @@
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../config/config.ts";
+import { validateEnv } from "../config/migration-validator.ts";
 import { startRuntimeWarmup } from "../runtime/model/runtime-warmup.ts";
 import { primePeerDep } from "../runtime/peer-dep.ts";
 import { deployBundledThemes } from "../ui/deploy-bundled-themes.ts";
@@ -60,6 +61,18 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	// full crash chain — /crew-view mid-run crash).
 	installChildProcessAbortShield();
 
+	// WI-5.6 wiring (review remediation 2026-09-10): surface deprecated /
+	// removed / reverted PI_CREW_* env keys as ONE consolidated startup
+	// warning — warn, never fail (spec M5 acceptance). validateEnv is a pure
+	// scanner over the env-registry (env-vars.ts) and never throws.
+	const envWarnings = validateEnv(process.env);
+	if (envWarnings.warnings.length > 0) {
+		console.warn(
+			`[pi-crew] ${envWarnings.warnings.length} deprecated env var(s) in use:\n` +
+				envWarnings.warnings.map((w) => `  ${w.name}: ${w.message}`).join("\n"),
+		);
+	}
+
 	startRuntimeWarmup();
 	primePeerDep().catch(() => undefined);
 	deployBundledThemes();

package/src/extension/registration/lifecycle-handlers.ts

@@ -21,7 +21,7 @@ import { loadConfig } from "../../config/config.ts";
 import { DEFAULT_UI } from "../../config/defaults.ts";
 import { getCrewEnv } from "../../config/env-vars.ts";
 import { pruneFinishedRuns, pruneUserLevelRuns } from "../../extension/run-maintenance.ts";
-import { type BrokerSpawnCredentials, setActiveBrokerIssuer } from "../../runtime/broker/broker-issuer.ts";
+import { type BrokerSpawnCredentials, setActiveBrokerIssuer, setActiveBrokerRevoker } from "../../runtime/broker/broker-issuer.ts";
 import { CrewBroker } from "../../runtime/broker/crew-broker.ts";
 import { terminateActiveChildPiProcesses } from "../../runtime/child-pi/child-pi.ts";
 import { forgetDetachedRun, hasDetachedRuns, peekFinishedDetachedRunResults } from "../../runtime/detached-run-results.ts";
@@ -681,8 +681,13 @@ function setupRenderLoop(
 				// file just changed on disk, so force a fresh snapshot while keeping
 				// the entry populated — deleting it left a window where the widget's
 				// `get()` returned undefined and dropped the run to "(loading…)".
+				// PERF (2026-08-24): route through the coalesced ASYNC refresh —
+				// fs.watch can fire many times per second and the sync rebuild
+				// blocked the UI event loop. The entry stays populated until the
+				// async rebuild re-sets it in place; the render schedule below
+				// repaints while it lands.
 				try {
-					ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).refresh(runId);
+					ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).scheduleRefresh(runId);
 				} catch (error) {
 					logInternalError("register.runWatcher.refresh", error, runId);
 				}
@@ -930,8 +935,11 @@ function setupRenderLoop(
 		// FLICKER FIX: rebuild-in-place instead of deleting the entry (see
 		// onRunChange above). A hard delete left `get()` returning undefined for
 		// a frame, dropping the run to "(loading…)" and causing visible flicker.
+		// PERF (2026-08-24): coalesced ASYNC refresh — fs.watch can fire many
+		// times per second and the sync rebuild blocked the UI event loop; the
+		// render schedule below repaints while the rebuild lands.
 		try {
-			ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).refresh(runId);
+			ctx.getRunSnapshotCache(ctx.currentCtx?.cwd ?? process.cwd()).scheduleRefresh(runId);
 		} catch (error) {
 			logInternalError("register.crewRunWatcher.refresh", error, runId);
 		}
@@ -1077,10 +1085,11 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 					// config.broker.waitMethodsEnabled a dead knob and the ADR-0
 					// "then true" flip a silent no-op. Fail-closed when unset.
 					waitMethodsEnabled: cfg?.waitMethodsEnabled ?? false,
-					// T3/R5 (ADR-5 §10): governed-nesting capability gate — fail-closed
-					// default; production threads config.nesting (sensitive: user config
-					// only). Nested-slot sizing + admission-time model catalog (ADR-5 §7 —
-					// the production wiring MUST supply it) + workspace gate mirror.
+					// T3/R5 (ADR-5 §10): governed-nesting capability gate — default-on
+					// since D8 (loadConfig layers DEFAULT_NESTING.enabled=true; sensitive
+					// flag, so only USER config may flip it). Nested-slot sizing +
+					// admission-time model catalog (ADR-5 §7 — the production wiring
+					// MUST supply it) + workspace gate mirror.
 					nestingEnabled: nestingCfg?.nesting?.enabled ?? false,
 					...(nestingCfg?.nesting?.maxSlots !== undefined ? { nestingMaxSlots: nestingCfg.nesting.maxSlots } : {}),
 					...(nestingCfg?.nesting?.maxDepth !== undefined ? { nestingMaxDepth: nestingCfg.nesting.maxDepth } : {}),
@@ -1120,8 +1129,8 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 		if (!effectiveEnabled()) return undefined;
 		// ADR-5 §4 (governed nesting): tokens are minted ONLY for children that
 		// may themselves delegate — childDepth < resolved maxDepth. At the default
-		// maxDepth=2 a delegate-spawned depth-2 grandchild gets NO credentials
-		// (env containment: no PI_CREW_BROKER_SOCKET/TOKEN at depth 2; identity
+		// maxDepth=4 a delegate-spawned depth-4 grandchild gets NO credentials
+		// (env containment: no PI_CREW_BROKER_SOCKET/TOKEN at the cap depth; identity
 		// routing via PI_CREW_BROKER_RUN_ID/TASK_ID is threaded unconditionally
 		// elsewhere). Undefined childDepth = legacy worker spawn (depth 1).
 		if (childDepth !== undefined && childDepth >= resolveCrewMaxDepth(undefined)) return undefined;
@@ -1136,6 +1145,27 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 		}
 	};
 
+	// MuxSurface A1 (spec §7 D3 step 2): publish the revoker alongside the
+	// issuer — team-runner's degrade controller calls it when a pane is lost.
+	// Best-effort and self-gated: no broker bound (never started / session
+	// switched) means nothing to revoke; re-issue after respawn mints fresh (T10).
+	const revokeForTask = (taskId: string): void => {
+		if (!taskId || typeof taskId !== "string") return;
+		if (!isRootSession(process.env)) return;
+		if (!broker || brokerSessionId !== cachedSessionId) return;
+		try {
+			broker.revokeTaskToken(taskId);
+		} catch (error) {
+			logInternalError(
+				"broker.revoke-for-task",
+				error instanceof Error ? error : new Error(String(error)),
+				`taskId=${taskId}`,
+				"warn",
+			);
+		}
+	};
+	setActiveBrokerRevoker(revokeForTask);
+
 	// Publish this issuer as the process-local active issuer so runChildPi can
 	// default `brokerIssuer` without the registration context being threaded
 	// through every runner call site. The issuer self-gates (root + flag), so
@@ -1146,6 +1176,7 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 		issueForChild,
 		stop: async () => {
 			setActiveBrokerIssuer(undefined);
+			setActiveBrokerRevoker(undefined);
 			if (broker) {
 				try {
 					await broker.stop();

package/src/extension/registration/observability.ts

@@ -75,14 +75,10 @@ export interface ObservabilityDeps {
 	}>;
 }
 
-let _cachedOTLPExporter: OTLPExporterCtor | undefined;
 async function importOTLPExporter(): Promise<OTLPExporterCtor> {
-	if (!_cachedOTLPExporter) {
-		// LAZY: opt-in OTLP metric export — load only when otlp.enabled=true.
-		const mod = await import("../../observability/exporters/otlp-exporter.ts");
-		_cachedOTLPExporter = mod.OTLPExporter as unknown as OTLPExporterCtor;
-	}
-	return _cachedOTLPExporter;
+	// LAZY: opt-in OTLP metric export — load only when otlp.enabled=true.
+	const mod = await import("../../observability/exporters/otlp-exporter.ts");
+	return mod.OTLPExporter as unknown as OTLPExporterCtor;
 }
 
 /**

package/src/extension/registration/subagent-tools.ts

@@ -6,17 +6,13 @@ import { withSessionId } from "../team-tool/context.ts";
 // Lazy-loaded: team-tool.ts pulls in entire runtime chain.
 import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
 
-let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 async function handleTeamTool(
 	params: Parameters<typeof HandleTeamToolFn>[0],
 	ctx: Parameters<typeof HandleTeamToolFn>[1],
 ): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
-	if (!_cachedHandleTeamTool) {
-		// LAZY: team-tool.ts pulls in entire runtime chain.
-		const mod = await import("../team-tool.ts");
-		_cachedHandleTeamTool = mod.handleTeamTool;
-	}
-	return _cachedHandleTeamTool(params, ctx);
+	// LAZY: team-tool.ts pulls in entire runtime chain.
+	const mod = await import("../team-tool.ts");
+	return mod.handleTeamTool(params, ctx);
 }
 
 import { Text } from "@earendil-works/pi-tui";