pi-crew 0.9.17 → 0.9.19

package/src/config/config.ts

@@ -66,6 +66,108 @@ import type {
 	UpdateConfigOptions,
 } from "./types.ts";
 
+// (F16) loadConfig was called 1 Hz idle / 6 Hz active with 0 cache — added 2s TTL+mtime cache following the manifestCache pattern in state-store.ts:75-130.
+const CONFIG_CACHE_TTL_MS = 2000;
+
+interface ConfigCacheEntry {
+	value: LoadedPiTeamsConfig;
+	mtimes: Record<string, number>;
+	cachedAt: number;
+}
+
+interface ConfigCacheKeyParts {
+	filePath: string;
+	legacyPath: string;
+	projectPath: string;
+	projectPiCrewJsonPath: string;
+	cwd: string | null;
+}
+
+const configCache = new Map<string, ConfigCacheEntry>();
+
+/** @internal — TTL override for unit tests (matches __test__setManifestCache pattern in state-store.ts:82). */
+export function __test__setConfigCacheTtlMs(ttlMs: number): void {
+	configCacheTtlMsOverride = ttlMs;
+}
+
+/** @internal — read the effective TTL in use by the cache. */
+export function __test__getConfigCacheTtlMs(): number {
+	return configCacheTtlMsOverride ?? CONFIG_CACHE_TTL_MS;
+}
+
+/** @internal — peek at the cached entry for a given key shape. */
+export function __test__getConfigCacheEntry(parts: ConfigCacheKeyParts): ConfigCacheEntry | undefined {
+	return configCache.get(buildConfigCacheKey(parts));
+}
+
+/** @internal — number of cached entries (for tests/diagnostics). */
+export function __test__configCacheSize(): number {
+	return configCache.size;
+}
+
+let configCacheTtlMsOverride: number | null = null;
+
+function buildConfigCacheKey(parts: ConfigCacheKeyParts): string {
+	return JSON.stringify([parts.filePath, parts.legacyPath, parts.projectPath, parts.projectPiCrewJsonPath, parts.cwd]);
+}
+
+function statMtimeMs(filePath: string): number | undefined {
+	try {
+		return fs.statSync(filePath).mtimeMs;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function readCachedConfigParts(filePath: string, legacyPath: string, cwd: string | undefined): ConfigCacheKeyParts {
+	const projectPath = cwd ? projectConfigPath(cwd) : "";
+	const piCrewJsonPath = cwd ? projectPiCrewJsonPath(cwd) : "";
+	return {
+		filePath,
+		legacyPath,
+		projectPath,
+		projectPiCrewJsonPath: piCrewJsonPath,
+		cwd: cwd ?? null,
+	};
+}
+
+function readCacheMtimes(parts: ConfigCacheKeyParts): Record<string, number> {
+	const mtimes: Record<string, number> = {};
+	for (const p of [parts.filePath, parts.legacyPath, parts.projectPath, parts.projectPiCrewJsonPath]) {
+		if (!p) continue; // skip empty (cwd-undefined project paths)
+		const m = statMtimeMs(p);
+		if (m !== undefined) mtimes[p] = m;
+	}
+	return mtimes;
+}
+
+function matchesCachedMtimes(cached: Record<string, number>, current: Record<string, number>): boolean {
+	const cachedKeys = Object.keys(cached);
+	const currentKeys = Object.keys(current);
+	if (cachedKeys.length !== currentKeys.length) return false;
+	for (const key of cachedKeys) {
+		if (current[key] !== cached[key]) return false;
+	}
+	return true;
+}
+
+function setConfigCache(key: string, value: LoadedPiTeamsConfig, mtimes: Record<string, number>): void {
+	if (configCache.has(key)) configCache.delete(key);
+	configCache.set(key, { value, mtimes, cachedAt: Date.now() });
+	const ttlMs = configCacheTtlMsOverride ?? CONFIG_CACHE_TTL_MS;
+	// TTL eviction on insert (mirrors manifestCache eviction in state-store.ts:108-117)
+	const now = Date.now();
+	for (const [k, entry] of configCache.entries()) {
+		if (now - entry.cachedAt > ttlMs) configCache.delete(k);
+	}
+}
+
+/** Drop all cached loadConfig results. Call after config writes or from tests. */
+export function invalidateConfigCache(): void {
+	configCache.clear();
+}
+
 function resolveHomeDir(): string {
 	const envValue = process.env.PI_TEAMS_HOME?.trim();
 	const defaultHome = os.homedir();
@@ -972,6 +1074,27 @@ function readOptionalConfig(filePath: string): {
 export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 	const filePath = configPath();
 	const legacyPath = legacyConfigPath();
+
+	// (F16) Quick-win cache: skip the expensive full-reparse on hot paths
+	// (preload tick 1 Hz, per-write validation, subagent completion) when the
+	// on-disk config files are unchanged. See CONFIG_CACHE_TTL_MS at the
+	// top of this file for the rationale and the manifestCache pattern in
+	// state-store.ts:75-130 for the canonical implementation we mirror.
+	const cacheParts = readCachedConfigParts(filePath, legacyPath, cwd);
+	const cacheKey = buildConfigCacheKey(cacheParts);
+	const cached = configCache.get(cacheKey);
+	const ttlMs = configCacheTtlMsOverride ?? CONFIG_CACHE_TTL_MS;
+	if (cached && Date.now() - cached.cachedAt <= ttlMs) {
+		const currentMtimes = readCacheMtimes(cacheParts);
+		if (matchesCachedMtimes(cached.mtimes, currentMtimes)) {
+			// Refresh insertion order so a frequently-accessed key isn't
+			// evicted from the Map on the next eviction sweep.
+			configCache.delete(cacheKey);
+			configCache.set(cacheKey, cached);
+			return cached.value;
+		}
+	}
+
 	const paths = cwd ? [filePath, projectConfigPath(cwd)] : [filePath];
 	const warnings: string[] = [];
 	const legacyConfig = readOptionalConfig(legacyPath);
@@ -1015,12 +1138,20 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 			paths.push(piCrewJsonPath);
 		}
 	}
-	return {
+	const result: LoadedPiTeamsConfig = {
 		path: filePath,
 		paths,
 		config,
 		warnings: warnings.length > 0 ? warnings : undefined,
 	};
+	// 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));
+	}
+	return result;
 }
 
 export function updateConfig(patch: PiTeamsConfig, options: UpdateConfigOptions = {}): SavedPiTeamsConfig {
@@ -1042,6 +1173,9 @@ export function updateConfig(patch: PiTeamsConfig, options: UpdateConfigOptions
 		}
 		fs.mkdirSync(path.dirname(filePath), { recursive: true });
 		atomicWriteFile(filePath, `${JSON.stringify(merged, null, 2)}\n`);
+		// (F16) Invalidate the loadConfig cache after a write — the next
+		// caller must see the new value, not a 0-2s stale snapshot.
+		invalidateConfigCache();
 		return { path: filePath, config: merged };
 	});
 }
@@ -1063,6 +1197,8 @@ export function updateAutonomousConfig(patch: PiTeamsAutonomousConfig): SavedPiT
 				: {};
 		current.autonomous = { ...currentAutonomous, ...patch };
 		atomicWriteFile(filePath, `${JSON.stringify(current, null, 2)}\n`);
+		// (F16) Invalidate the loadConfig cache after a write — see updateConfig.
+		invalidateConfigCache();
 		return { path: filePath, config: parseConfig(current) };
 	});
 }

package/src/extension/register.ts

@@ -67,7 +67,7 @@ import { registerCrewShortcuts } from "./crew-shortcuts.ts";
 import { type PiCrewRpcHandle, registerPiCrewRpc } from "./cross-extension-rpc.ts";
 import { registerKnowledgeInjection } from "./knowledge-injection.ts";
 import { registerCrewMessageRenderers } from "./message-renderers.ts";
-import { type NotificationDescriptor } from "./notification-router.ts";
+import type { NotificationDescriptor } from "./notification-router.ts";
 import { runArtifactCleanup } from "./registration/artifact-cleanup.ts";
 import { registerTeamCommands } from "./registration/commands.ts";
 import { registerCompactionGuard } from "./registration/compaction-guard.ts";

package/src/extension/team-onboard.ts

@@ -67,9 +67,7 @@ function loadRunSummaries(cwd: string, options: OnboardingOptions = {}): RunSumm
 				completedAt: raw.completedAt ?? raw.updatedAt,
 				taskCount: 0, // tasks stored separately, not in manifest
 			});
-		} catch {
-			continue;
-		}
+		} catch {}
 	}
 
 	return summaries;

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

@@ -3,7 +3,7 @@
  * Provides set/clear/status commands for anchor points.
  */
 
-import { AnchorManager, AnchorNotFoundError, createAnchorManager, NoHandoffsError } from "../../runtime/anchor-manager.ts";
+import { type AnchorManager, AnchorNotFoundError, 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";

package/src/extension/team-tool/auto-summarize.ts

@@ -3,7 +3,7 @@
  * Provides on/off/status commands for auto-summarization.
  */
 
-import { AutoSummarizeService, createAutoSummarizeService, DEFAULT_AUTO_SUMMARIZE_CONFIG } from "../../runtime/auto-summarize.ts";
+import { type AutoSummarizeService, createAutoSummarizeService, DEFAULT_AUTO_SUMMARIZE_CONFIG } from "../../runtime/auto-summarize.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";

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

@@ -1,6 +1,7 @@
 import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
 import { loadConfig } from "../../config/config.ts";
 import { PipelineRunner, type PipelineWorkflow } from "../../runtime/pipeline-runner.ts";
+import { sanitizeTaskText } from "../../runtime/task-packet.ts";
 // Heavy runtime — lazy-loaded to avoid 1.4s import cost at extension registration.
 import type { executeTeamRun as ExecuteTeamRunFn } from "../../runtime/team-runner.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
@@ -17,7 +18,7 @@ import { assertCleanLeader, findGitRoot } from "../../worktree/worktree-manager.
 const _typeCheck: typeof ExecuteTeamRunFn = null as never as typeof ExecuteTeamRunFn;
 
 import { logInternalError } from "../../utils/internal-error.ts";
-import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { resolveContainedPath, resolveRealContainedPath } from "../../utils/safe-paths.ts";
 
 let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
 async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
@@ -127,6 +128,76 @@ function scheduleBackgroundEarlyExitGuard(cwd: string, runId: string, pid: numbe
 	timer.unref();
 }
 
+/**
+ * Max analysis size in bytes — matches the `maxLength: 100_000` schema cap on
+ * the inline `analysis` param, so the file channel can't smuggle in a larger
+ * payload than the inline channel allows (prompt-size blowup guard).
+ */
+const MAX_ANALYSIS_BYTES = 100_000;
+
+/**
+ * Resolve the analysis channel (round-X Y1): inline `analysis` or `analysisPath` file.
+ *
+ * Called BEFORE `createRunManifest` so validation failures fail-fast and no orphan
+ * run state is left on disk. Sanitizes the parsed content with the same
+ * {@link sanitizeTaskText} machinery used in `buildTaskPacket` (SEC-007), since the
+ * resulting text is injected into worker prompts via standard sharedReads.
+ *
+ * Mutual exclusivity mirrors the `budgetTotal`/`budgetUnlimited` pattern in
+ * `goal.ts` — a cold-review #2 blocking fix pattern.
+ */
+function resolveAnalysisText(
+	params: TeamToolParamsValue,
+	cwd: string,
+): { text?: string; error?: string; source: "inline" | "path" | "none" } {
+	const hasInline = typeof params.analysis === "string" && params.analysis.length > 0;
+	const hasPath = typeof params.analysisPath === "string" && params.analysisPath.length > 0;
+
+	if (hasInline && hasPath) {
+		return {
+			error: "`analysis` and `analysisPath` are mutually exclusive. Set exactly one.",
+			source: "none",
+		};
+	}
+	if (!hasInline && !hasPath) return { source: "none" };
+
+	if (hasPath) {
+		let resolved: string;
+		try {
+			resolved = resolveContainedPath(cwd, params.analysisPath as string);
+		} catch {
+			return {
+				error: `analysisPath must be within project directory: ${params.analysisPath}`,
+				source: "none",
+			};
+		}
+		if (!fs.existsSync(resolved)) {
+			return {
+				error: `Analysis file not found: ${resolved}`,
+				source: "none",
+			};
+		}
+		// Size cap BEFORE reading: mirror the inline schema cap (maxLength 100_000)
+		// so a large file can't blow up worker prompts via the sharedReads channel.
+		const { size } = fs.statSync(resolved);
+		if (size > MAX_ANALYSIS_BYTES) {
+			return {
+				error: `Analysis file too large: ${size} bytes (max ${MAX_ANALYSIS_BYTES}). Trim the analysis or pass a summary inline.`,
+				source: "none",
+			};
+		}
+		const raw = fs.readFileSync(resolved, "utf-8");
+		const sanitized = sanitizeTaskText(raw);
+		if (!sanitized) return { source: "none" };
+		return { text: sanitized, source: "path" };
+	}
+
+	// hasInline
+	const sanitized = sanitizeTaskText(params.analysis as string);
+	if (!sanitized) return { source: "none" };
+	return { text: sanitized, source: "inline" };
+}
+
 export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	// CHAIN DISPATCH: runs before goal validation since a chain has no top-level
 	// goal. The injected handleRun reference breaks the run.ts ↔ chain-dispatch.ts
@@ -234,11 +305,18 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 						role: params.role ?? "agent",
 						task: "{goal}",
 						model: params.model,
+						reads: params.analysis || params.analysisPath ? ["analysis.md"] : undefined,
 					},
 				],
 			}
 		: workflows.find((item) => item.name === workflowName);
 	if (!baseWorkflow) return result(`Workflow '${workflowName}' not found.`, { action: "run", status: "error" }, true);
+
+	// ANALYSIS CHANNEL (round-X Y1): resolve analysis text from inline or file BEFORE
+	// createRunManifest so validation errors fail-fast (no orphan run state).
+	const analysisParam = resolveAnalysisText(params, resolvedCtx.cwd);
+	if (analysisParam.error) return result(analysisParam.error, { action: "run", status: "error" }, true);
+
 	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { expandParallelResearchWorkflow }` above (issue #28, RFC 17). At call time the module body has fully evaluated, so the dynamic import returns a live binding. Multi-line form breaks scripts/check-lazy-imports.mjs (which does `lines[lineNum - 2]`), so keep destructuring + await import on one line.
 	const { expandParallelResearchWorkflow: expandParallelResearch } = await import("../../runtime/parallel-research.ts");
 	const workflow = directAgent ? baseWorkflow : expandParallelResearch(baseWorkflow, resolvedCtx.cwd);
@@ -276,6 +354,11 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	if (!directAgent && workflow.source === "builtin" && isGoalWrapEnabled(resolvedCtx.cwd, workflow.name)) {
 		const decision = shouldGoalWrap(resolvedCtx.cwd, workflow);
 		if (decision.enabled) {
+			if (analysisParam.text) {
+				console.warn(
+					`[team-tool.run] analysis param is ignored by goal-wrapped run (workflow=${workflow.name}). The analysis artifact will not be written.`,
+				);
+			}
 			return await startGoalWrappedRun(params, ctx, workflow, goal);
 		}
 		// goal-wrap disabled for this workflow — fall through silently to normal
@@ -364,10 +447,23 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		content: `${goal}\n`,
 		producer: "team-tool",
 	});
+	// ANALYSIS CHANNEL (round-X Y1): if analysis was provided, persist as a shared artifact
+	// so workflow steps declaring reads: analysis.md receive it via the standard
+	// dependency-context injection (collectDependencyOutputContext → renderDependencyOutputContext).
+	const analysisArtifacts = analysisParam.text
+		? [
+				writeArtifact(paths.artifactsRoot, {
+					kind: "prompt",
+					relativePath: "shared/analysis.md",
+					content: `${analysisParam.text}\n`,
+					producer: "team-tool",
+				}),
+			]
+		: [];
 	const updatedManifest = {
 		...manifest,
 		...(skillOverride !== undefined ? { skillOverride } : {}),
-		artifacts: [goalArtifact],
+		artifacts: [goalArtifact, ...analysisArtifacts],
 		summary: "Run manifest created; worker execution is not implemented yet.",
 	};
 	atomicWriteJson(paths.manifestPath, updatedManifest);

package/src/runtime/async-runner.ts

@@ -8,6 +8,7 @@ import type { TeamRunManifest } from "../state/types.ts";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { packageRoot } from "../utils/paths.ts";
 import { registerWorker, unregisterWorker } from "./orphan-worker-registry.ts";
 import { PEER_DEP_DIR_ENV, resolvePeerDepDir } from "./peer-dep.ts";
 
@@ -223,7 +224,17 @@ export const BACKGROUND_RUNNER_ENV_ALLOWLIST: string[] = [
 ];
 
 export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise<SpawnBackgroundTeamRunResult> {
-	const runnerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "background-runner.ts");
+	// FIX (2026-07-02, perf review F-critical): use packageRoot() instead of
+	// import.meta.url-relative path. The previous path.resolve walks
+	// <bundleDir>/background-runner.ts, which is correct in src/ but BROKEN
+	// in the bundle: esbuild's __esm helper does not preserve per-module
+	// import.meta.url, so the resolve lands at <pi-crew>/background-runner.ts
+	// (missing `src/runtime/`). The background-runner then ENOENTs at spawn
+	// and 3 explorer agents failed during the verification run. packageRoot()
+	// walks up to find pi-crew's package.json and works correctly from both
+	// src/ and dist/ entry points. Mirrors the fix in pi-args.ts:10 (commit
+	// 0dd93e0).
+	const runnerPath = path.join(packageRoot(), "src", "runtime", "background-runner.ts");
 	const logPath = path.join(manifest.stateRoot, "background.log");
 	fs.mkdirSync(manifest.stateRoot, { recursive: true });
 

package/src/runtime/child-pi.ts

@@ -993,7 +993,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			};
 
 			let softLimitReached = false;
-			let steerInjectionFailed = false;
+			const steerInjectionFailed = false;
 			const maxTurns = input.maxTurns;
 			// FIX (Issue #1): Bound graceTurns to prevent the hard abort condition from
 			// never triggering when an arbitrarily large value is passed.

package/src/runtime/coalesce-tasks.ts

@@ -27,9 +27,9 @@
  *     grouping many micro-tasks into one worker prompt.
  */
 
-import { permissionForRole } from "./role-permission.ts";
 import type { TeamTaskState } from "../state/types.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+import { permissionForRole } from "./role-permission.ts";
 
 /** Default cap on group size to prevent context-budget overflow. */
 export const DEFAULT_MAX_GROUP_SIZE = 5;

package/src/runtime/dynamic-workflow-context.ts

@@ -254,7 +254,7 @@ export function makeWorkflowCtx(manifest: TeamRunManifest, opts: MakeWorkflowCtx
 	// round-12 P0-1: in-memory phase state, exposed via non-enumerable getter like __finalResult.
 	// The events log is the durable source of truth for phase boundaries.
 	// round-18 P2-3: hydrate phaseState from a resumed checkpoint (backward compatible when unset).
-	let phaseState: { currentPhase: string | undefined; phases: string[] } = opts.resumedState
+	const phaseState: { currentPhase: string | undefined; phases: string[] } = opts.resumedState
 		? {
 				currentPhase: opts.resumedState.currentPhase,
 				phases: [...opts.resumedState.phases],

package/src/runtime/hidden-handoff.ts

@@ -172,7 +172,7 @@ export class HiddenHandoffService {
 
 		const priority = options.priority ?? this.inferPriority(summary);
 		const content = this.buildContent(summary);
-		let recipient = options.to ?? this.getParentAgentId();
+		const recipient = options.to ?? this.getParentAgentId();
 
 		if (!recipient) {
 			// No parent to send to, but we still emit the event

package/src/runtime/mcp-proxy.ts

@@ -16,8 +16,8 @@
  * when proxying from the parent.
  */
 
-import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { type Static, type TSchema } from "@sinclair/typebox";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "@sinclair/typebox";
 
 export interface McpProxyConfig {
 	/** Whether to enable MCP in the child session. */

package/src/runtime/result-extractor.ts

@@ -152,10 +152,7 @@ function tryScanJson(text: string): unknown | undefined {
 		const candidate = rest.slice(0, end);
 		try {
 			return JSON.parse(candidate);
-		} catch {
-			// Not valid JSON at this position; keep scanning for the next '{'/'['.
-			continue;
-		}
+		} catch {}
 	}
 	return undefined;
 }

package/src/runtime/retry-runner.ts

@@ -278,7 +278,7 @@ export class RetryRunner {
 	 * Calculate backoff delay with optional capping.
 	 */
 	private calculateBackoff(baseMs: number, attempt: number, multiplier: number, maxBackoffMs?: number): number {
-		let delay = baseMs * Math.pow(multiplier, attempt - 1);
+		let delay = baseMs * multiplier ** (attempt - 1);
 		if (maxBackoffMs !== undefined) {
 			delay = Math.min(delay, maxBackoffMs);
 		}

package/src/runtime/run-coalesced-task-group.ts

@@ -11,19 +11,19 @@
 
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
-import { permissionForRole } from "./role-permission.ts";
-import { runChildPi } from "./child-pi.ts";
-import { splitCoalescedOutput } from "./task-runner/output-splitter.ts";
-import { buildWorkspaceTree } from "./workspace-tree.ts";
-import { saveRunTasks, updateRunStatus } from "../state/state-store.ts";
+import type { AgentConfig } from "../agents/agent-config.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEventAsync } from "../state/event-log.ts";
-import { createWorkerHeartbeat, touchWorkerHeartbeat } from "./worker-heartbeat.ts";
-import type { AgentConfig } from "../agents/agent-config.ts";
-import type { CrewRuntimeMode } from "./runtime-resolver.ts";
+import { saveRunTasks, updateRunStatus } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
+import { runChildPi } from "./child-pi.ts";
+import { permissionForRole } from "./role-permission.ts";
+import type { CrewRuntimeMode } from "./runtime-resolver.ts";
+import { splitCoalescedOutput } from "./task-runner/output-splitter.ts";
 import { mergeArtifacts } from "./team-runner-artifacts.ts";
+import { createWorkerHeartbeat, touchWorkerHeartbeat } from "./worker-heartbeat.ts";
+import { buildWorkspaceTree } from "./workspace-tree.ts";
 
 export interface CoalescedTaskGroupInput {
 	manifest: TeamRunManifest;

package/src/runtime/task-id.ts

@@ -58,7 +58,7 @@ export function hashToBase36(content: string, length: number): string {
  */
 export function calculateAdaptiveLength(existingCount: number, config: AdaptiveIDConfig = DEFAULT_CONFIG): number {
 	for (let length = config.minLength; length <= config.maxLength; length++) {
-		const totalPossibilities = Math.pow(36, length);
+		const totalPossibilities = 36 ** length;
 		const probability = 1 - Math.exp(-(existingCount * existingCount) / (2 * totalPossibilities));
 		if (probability <= config.maxCollisionProbability) {
 			return length;

package/src/runtime/task-runner/state-helpers.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
+import { flushPendingAtomicWrites } from "../../state/atomic-write.ts";
 import { withRunLockSync } from "../../state/locks.ts";
-import { loadRunManifestById, saveRunTasks } from "../../state/state-store.ts";
+import { loadRunManifestById, saveRunTasksCoalesced } from "../../state/state-store.ts";
 import type { TaskCheckpointState, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { recordFromTask, upsertCrewAgent } from "../crew-agent-records.ts";
@@ -54,7 +55,16 @@ export function persistSingleTaskUpdate(
 
 	try {
 		return withRunLockSync(manifest, () => {
-			retryLoop: for (let attempt = 0; attempt < 100; attempt++) {
+			for (let attempt = 0; attempt < 100; attempt++) {
+				// F4: persistSingleTaskUpdate now uses saveRunTasksCoalesced below
+				// (50ms debounce window). Read-modify-write loops are unsafe under
+				// coalescing — a parallel writer's buffered write is invisible to
+				// loadRunManifestById until it actually lands. Force any pending
+				// coalesced writes to flush first so this read sees the latest
+				// durable state. Without this guard, a parallel writer could
+				// overwrite our buffered write between our load and our (async)
+				// fsync, silently losing the intermediate update.
+				flushPendingAtomicWrites();
 				const latest = loadRunManifestById(manifest.cwd, manifest.runId)?.tasks ?? fallbackTasks;
 				merged = updateTask(latest, taskWithCheckpoint);
 
@@ -69,7 +79,7 @@ export function persistSingleTaskUpdate(
 				if (currentMtime !== baseMtime) {
 					// Another writer committed — their update is in latest, re-merge on top
 					baseMtime = currentMtime;
-					continue retryLoop;
+					continue;
 				}
 
 				// No concurrent writer — check that our merged result is based on the
@@ -83,7 +93,7 @@ export function persistSingleTaskUpdate(
 				}
 				if (recheckMtime !== baseMtime) {
 					baseMtime = recheckMtime;
-					continue retryLoop;
+					continue;
 				}
 
 				// Final pre-write mtime check to catch any concurrent writer that completed
@@ -97,10 +107,10 @@ export function persistSingleTaskUpdate(
 				if (preWriteMtime !== baseMtime) {
 					// Another writer committed — retry
 					baseMtime = preWriteMtime;
-					continue retryLoop;
+					continue;
 				}
 
-				break retryLoop;
+				break;
 			}
 
 			if (merged === undefined) {
@@ -109,7 +119,12 @@ export function persistSingleTaskUpdate(
 			}
 
 			try {
-				saveRunTasks(manifest, merged);
+				// F4: coalesced write inside the withRunLockSync critical section.
+				// The mtime CAS retry loop above still guards against concurrent
+				// non-coalesced writers; the flushPendingAtomicWrites() guard at
+				// the top of the retry loop ensures reads see any other coalesced
+				// writer's flushed-before-this-call state.
+				saveRunTasksCoalesced(manifest, merged);
 			} catch (err) {
 				logInternalError("persistSingleTaskUpdate", err);
 				throw err;

package/src/runtime/team-runner.ts

@@ -18,10 +18,8 @@ import type { TeamConfig } from "../teams/team-config.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
 import { checkBranchFreshness } from "../worktree/branch-freshness.ts";
-import { mergeArtifacts } from "./team-runner-artifacts.ts";
 import { buildSyntheticTerminalEvidence, CrewCancellationError, cancellationReasonFromSignal } from "./cancellation.ts";
-import { planCoalescedGroups, buildDispatchUnits } from "./coalesce-tasks.ts";
-import { runCoalescedTaskGroup } from "./run-coalesced-task-group.ts";
+import { buildDispatchUnits, planCoalescedGroups } from "./coalesce-tasks.ts";
 import { resolveBatchConcurrency } from "./concurrency.ts";
 import { readCrewAgents, saveCrewAgents } from "./crew-agent-records.ts";
 import type { CrewRuntimeKind } from "./crew-agent-runtime.ts";
@@ -37,6 +35,7 @@ import { evaluateCrewPolicy, summarizePolicyDecisions } from "./policy-engine.ts
 import { buildRecoveryLedger, shouldRerunFailedTask } from "./recovery-recipes.ts";
 import { DEFAULT_RETRY_POLICY, executeWithRetry, type RetryPolicy } from "./retry-executor.ts";
 import { permissionForRole } from "./role-permission.ts";
+import { runCoalescedTaskGroup } from "./run-coalesced-task-group.ts";
 import { registerRunPromise, rejectRunPromise, resolveRunPromise } from "./run-tracker.ts";
 import { resolveTaskRuntimeKind } from "./runtime-policy.ts";
 import type { CrewRuntimeCapabilities } from "./runtime-resolver.ts";
@@ -45,6 +44,7 @@ import { buildExecutionPlan as buildDagExecutionPlan, getReadyTasks as getDagRea
 import { buildTaskGraphIndex, refreshTaskGraphQueues, taskGraphSnapshot } from "./task-graph-scheduler.ts";
 import { aggregateTaskOutputs } from "./task-output-context.ts";
 import { runTeamTask } from "./task-runner.ts";
+import { mergeArtifacts } from "./team-runner-artifacts.ts";
 import { clearTrackedTaskUsage } from "./usage-tracker.ts";
 import {
 	createWorkflowStateMachine,

package/src/runtime/verification-integrity.ts

@@ -71,9 +71,7 @@ export function snapshotManifests(cwd: string): Record<string, string> {
 		try {
 			const content = fs.readFileSync(abs);
 			snapshot[rel] = createHash("sha256").update(content).digest("hex");
-		} catch {
-			continue; // unreadable (permissions/race) — skip gracefully
-		}
+		} catch {}
 	}
 	return snapshot;
 }

package/src/schema/team-tool-schema.ts

@@ -264,6 +264,19 @@ export const TeamToolParams = Type.Object({
 		// "description-only schema" strict-provider check.
 		Type.Any(),
 	),
+	analysis: Type.Optional(
+		Type.String({
+			maxLength: 100_000,
+			description:
+				"Inline analysis/context notes from the calling session. Persisted to artifacts/{runId}/shared/analysis.md (audit trail) and auto-injected into any workflow step declaring reads: analysis.md (e.g. builtin 'plan-execute'). Mutually exclusive with analysisPath. Ignored by goal-wrapped runs and chain dispatch in v1.",
+		}),
+	),
+	analysisPath: Type.Optional(
+		Type.String({
+			description:
+				"Path to an existing markdown analysis file (resolved within cwd). Copied into shared/analysis.md. Mutually exclusive with analysis.",
+		}),
+	),
 	focus: Type.Optional(
 		Type.String({
 			description:
@@ -385,4 +398,12 @@ export interface TeamToolParamsValue {
 	tokenBudget?: number;
 	/** Typed workflow arguments for .dwf.ts scripts, accessible via ctx.args<T>() (round-14 P1-5). */
 	args?: unknown;
+	/** Inline analysis/context notes from the calling session. Persisted to
+	 *  artifacts/{runId}/shared/analysis.md (audit trail) and auto-injected into
+	 *  any workflow step declaring reads: analysis.md (e.g. builtin 'plan-execute').
+	 *  Mutually exclusive with `analysisPath`. */
+	analysis?: string;
+	/** Path to an existing analysis file resolved within `cwd`. Copied into
+	 *  shared/analysis.md. Mutually exclusive with `analysis`. */
+	analysisPath?: string;
 }