pi-crew 0.5.5 → 0.5.7

package/src/runtime/chain-runner.ts

@@ -0,0 +1,507 @@
+/**
+ * ChainRunner - Execute sequential chains with `->` syntax support.
+ * 
+ * Based on pi-boomerang's parseChain pattern:
+ * - Parses "teamA -> teamB -> teamC" syntax
+ * - Supports per-step overrides for model, skill, thinking
+ * - Accumulates handoffs between steps
+ * - Executes steps sequentially with context passing
+ * 
+ * @see docs/pi-boomerang-integration-plan.md
+ */
+
+import type { HandoffSummary, HandoffManager, TaskPacket, TaskResult } from "./handoff-manager.ts";
+
+/**
+ * Single step in a chain.
+ */
+export interface ChainStep {
+	/** Step name/identifier */
+	name: string;
+	/** Team to execute (if using team reference) */
+	team?: string;
+	/** Workflow to execute (if using workflow reference) */
+	workflow?: string;
+	/** Template to execute (if using template reference) */
+	template?: string;
+	/** Inline goal text (for literal goals) */
+	inlineGoal?: string;
+
+	/** Per-step model override */
+	model?: string;
+	/** Per-step skill override */
+	skill?: string;
+	/** Thinking mode */
+	thinking?: "fast" | "standard" | "deep";
+
+	/** Step-specific context */
+	context?: Record<string, unknown>;
+	/** Step timeout in milliseconds */
+	timeout?: number;
+
+	/** Whether to continue chain on failure */
+	continueOnError?: boolean;
+}
+
+/**
+ * Parsed chain specification.
+ */
+export interface ChainSpec {
+	/** Ordered steps in the chain */
+	steps: ChainStep[];
+	/** Global arguments applied to all steps */
+	globalArgs?: Record<string, unknown>;
+	/** Global model override */
+	globalModel?: string;
+	/** Global skill override */
+	globalSkill?: string;
+	/** Global thinking mode */
+	globalThinking?: "fast" | "standard" | "deep";
+	/** Continue chain on step failure */
+	continueOnError?: boolean;
+}
+
+/**
+ * Result of a single chain step execution.
+ */
+export interface ChainStepResult {
+	step: number;
+	name: string;
+	outcome: "success" | "failure" | "skipped" | "partial";
+	result?: TaskResult;
+	handoff?: HandoffSummary;
+	duration: number;
+	error?: string;
+}
+
+/**
+ * Final chain execution result.
+ */
+export interface ChainResult {
+	steps: ChainStepResult[];
+	totalDuration: number;
+	success: boolean;
+	/** Total tokens used across all steps */
+	totalTokens?: number;
+	/** All handoffs generated during chain */
+	totalHandoffs: HandoffSummary[];
+}
+
+/**
+ * Task runner interface for chain execution.
+ */
+export interface ChainTaskRunner {
+	runTask(packet: TaskPacket): Promise<TaskResult>;
+}
+
+/**
+ * ChainRunner executes sequential chains with context passing.
+ */
+export class ChainRunner {
+	/** Maximum number of chain history entries to prevent memory leaks */
+	private static readonly MAX_CHAIN_HISTORY_SIZE = 100;
+
+	/** Maximum size per handoff entry to prevent memory issues from large artifacts */
+	private static readonly MAX_HANDOFF_ENTRY_SIZE = 5000; // bytes per entry
+
+	constructor(
+		private taskRunner: ChainTaskRunner,
+		private handoffManager: HandoffManager,
+	) {}
+
+	/**
+	 * Parse chain syntax: step1 -> step2 -> step3
+	 * 
+	 * Supports multiple syntaxes:
+	 * - Team reference: @teamName
+	 * - Workflow reference: workflow:name
+	 * - Template reference: template:name
+	 * - Inline goal: "goal description"
+	 * 
+	 * @example
+	 * parseChain("@research -> @implement -> @review")
+	 * parseChain('"Research AI trends" -> "Analyze findings"')
+	 * parseChain("@step1 --model claude-opus-3 -> @step2")
+	 * 
+	 * @param chainString - The chain string to parse
+	 * @returns Parsed chain specification
+	 */
+	parseChain(chainString: string): ChainSpec {
+		const stepStrings = chainString.split("->").map(s => s.trim());
+
+		const steps: ChainStep[] = stepStrings.map((step, index) => {
+			return this.parseStep(step, index);
+		});
+
+		// Extract global overrides
+		const globalModel = this.extractGlobalFlag(chainString, "global-model");
+		const globalSkill = this.extractGlobalFlag(chainString, "global-skill");
+		const globalThinking = this.extractGlobalFlag(chainString, "global-thinking") as "fast" | "standard" | "deep" | undefined;
+		const continueOnError = this.extractGlobalFlag(chainString, "continue-on-error") === "true";
+
+		return {
+			steps,
+			globalModel,
+			globalSkill,
+			globalThinking,
+			continueOnError,
+		};
+	}
+
+	/**
+	 * Execute chain sequentially.
+	 * Each step receives handoff from previous step.
+	 * 
+	 * @param spec - Parsed chain specification
+	 * @param initialContext - Initial context for the chain
+	 * @param eventsPath - Optional event log path for events
+	 * @returns Final chain result
+	 */
+	async runChain(
+		spec: ChainSpec,
+		initialContext: Record<string, unknown> = {},
+		eventsPath?: string
+	): Promise<ChainResult> {
+		const stepResults: ChainStepResult[] = [];
+		let accumulatedContext = { ...initialContext };
+		const startTime = Date.now();
+		let totalTokens = 0;
+		const allHandoffs: HandoffSummary[] = [];
+
+		for (let i = 0; i < spec.steps.length; i++) {
+			const step = spec.steps[i];
+			const stepStart = Date.now();
+
+			try {
+				// Resolve effective config (step overrides global)
+				const effectiveConfig = this.getEffectiveConfig(step, spec);
+
+				// Enrich context with previous handoffs
+				const stepContext = this.enrichContextFromHandoffs(
+					accumulatedContext,
+					stepResults
+				);
+
+				// Execute step
+				const result = await this.executeStep(effectiveConfig, stepContext);
+
+				// Track tokens
+				if (result.usage?.totalTokens) {
+					totalTokens += result.usage.totalTokens;
+				}
+
+				// Generate handoff for next step
+				const handoff = await this.handoffManager.generateSummary(
+					this.createMinimalPacket(step, i),
+					result
+				);
+
+				stepResults.push({
+					step: i + 1,
+					name: step.name,
+					outcome: result.outcome,
+					result,
+					handoff,
+					duration: Date.now() - stepStart,
+				});
+
+				if (handoff !== null) { allHandoffs.push(handoff); }
+
+				// Update accumulated context on success
+				if (result.outcome === "success") {
+					accumulatedContext = {
+						...accumulatedContext,
+						[`step_${i}_result`]: result,
+						[`step_${i}_handoff`]: handoff,
+					};
+				} else {
+					// Stop chain on step failure unless configured to continue
+					if (!spec.continueOnError && !step.continueOnError) {
+						break;
+					}
+				}
+
+				// Emit progress event if eventsPath provided
+				if (eventsPath) {
+					const { appendEventAsync } = await import("../state/event-log.ts");
+					await appendEventAsync(eventsPath, {
+						type: "chain.step_completed",
+						runId: "chain",
+						taskId: `step-${i + 1}`,
+						data: {
+							step: i + 1,
+							name: step.name,
+							outcome: result.outcome,
+							duration: Date.now() - stepStart,
+						},
+					});
+				}
+
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : String(error);
+
+				stepResults.push({
+					step: i + 1,
+					name: step.name,
+					outcome: "failure",
+					duration: Date.now() - stepStart,
+					error: errorMessage,
+				});
+
+				// Stop chain on failure unless configured to continue
+				if (!spec.continueOnError && !step.continueOnError) {
+					break;
+				}
+			}
+		}
+
+		return {
+			steps: stepResults,
+			totalDuration: Date.now() - startTime,
+			success: stepResults.every(s => s.outcome !== "failure"),
+			totalTokens: totalTokens > 0 ? totalTokens : undefined,
+			totalHandoffs: allHandoffs,
+		};
+	}
+
+	/**
+	 * Parse a single step from the chain string.
+	 * Includes type safety checks for ChainStep parsing (H3).
+	 */
+	private parseStep(step: string, index: number): ChainStep {
+		// Parse team reference: @teamName
+		const teamMatch = step.match(/^@([a-zA-Z][a-zA-Z0-9_]*)/);
+
+		// Parse workflow reference: workflow:name
+		const workflowMatch = step.match(/^workflow:([a-zA-Z][a-zA-Z0-9_]*)/);
+
+		// Parse template reference: template:name
+		const templateMatch = step.match(/^template:([a-zA-Z][a-zA-Z0-9_]*)/);
+
+		// Parse inline goal: "goal description" (can follow other patterns)
+		const inlineMatch = step.match(/"([^"]{1,10000})"/);
+
+		const nameParts = step.split(/\s+/);
+		const name = (nameParts[0] && nameParts[0].length > 0 && nameParts[0].length <= 100)
+			? nameParts[0]
+			: `step-${index}`;
+
+		const parsed: ChainStep = {
+			name,
+		};
+
+		// Set step type based on matching pattern with type safety
+		if (teamMatch && teamMatch[1]) {
+			parsed.team = this.sanitizeIdentifier(teamMatch[1]);
+		}
+		if (workflowMatch && workflowMatch[1]) {
+			parsed.workflow = this.sanitizeIdentifier(workflowMatch[1]);
+		}
+		if (templateMatch && templateMatch[1]) {
+			parsed.template = this.sanitizeIdentifier(templateMatch[1]);
+		}
+		if (inlineMatch && inlineMatch[1]) {
+			parsed.inlineGoal = this.sanitizeInlineGoal(inlineMatch[1]);
+		}
+
+		// Parse per-step overrides with type safety
+		const modelVal = this.extractFlag(step, "model");
+		if (modelVal && this.isValidModelName(modelVal)) {
+			parsed.model = modelVal;
+		}
+
+		const skillVal = this.extractFlag(step, "skill");
+		if (skillVal && this.isValidIdentifier(skillVal)) {
+			parsed.skill = skillVal;
+		}
+
+		const thinkingVal = this.extractFlag(step, "thinking");
+		if (thinkingVal && this.isValidThinkingMode(thinkingVal)) {
+			parsed.thinking = thinkingVal;
+		}
+
+		// Parse step timeout
+		const timeoutStr = this.extractFlag(step, "timeout");
+		if (timeoutStr) {
+			const timeoutMs = parseInt(timeoutStr, 10);
+			if (!isNaN(timeoutMs) && timeoutMs > 0 && timeoutMs <= 86400000) {
+				parsed.timeout = timeoutMs * 1000; // Convert seconds to ms
+			}
+		}
+
+		// Parse continueOnError for step
+		if (this.extractFlag(step, "continue-on-error") === "true") {
+			parsed.continueOnError = true;
+		}
+
+		return parsed;
+	}
+
+	/**
+	 * Sanitize identifier to prevent injection.
+	 */
+	private sanitizeIdentifier(value: string): string {
+		return value.replace(/[^a-zA-Z0-9_]/g, '_').substring(0, 100);
+	}
+
+	/**
+	 * Sanitize inline goal to prevent injection.
+	 */
+	private sanitizeInlineGoal(value: string): string {
+		// Remove control characters and limit length
+		return value.replace(/[\x00-\x1F\x7F]/g, '').substring(0, 10000);
+	}
+
+	/**
+	 * Validate model name format.
+	 */
+	private isValidModelName(value: string): boolean {
+		return /^[a-zA-Z][a-zA-Z0-9_-]{0,50}$/.test(value);
+	}
+
+	/**
+	 * Validate identifier format.
+	 */
+	private isValidIdentifier(value: string): boolean {
+		return /^[a-zA-Z][a-zA-Z0-9_]{0,50}$/.test(value);
+	}
+
+	/**
+	 * Validate thinking mode value.
+	 */
+	private isValidThinkingMode(value: string): value is "fast" | "standard" | "deep" {
+		return ["fast", "standard", "deep"].includes(value);
+	}
+
+	/**
+	 * Extract a flag from step string.
+	 * Uses escaped flag name to prevent regex injection.
+	 */
+	private extractFlag(input: string, flag: string): string | undefined {
+		// Escape regex special characters in flag name to prevent injection
+		const escapedFlag = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		const match = input.match(new RegExp(`--${escapedFlag}\\s+(\\S+)`));
+		return match?.[1];
+	}
+
+	/**
+	 * Extract a global flag from the chain string.
+	 * Global flags can appear anywhere in the chain string.
+	 * Uses escaped flag name to prevent regex injection.
+	 */
+	private extractGlobalFlag(input: string, flag: string): string | undefined {
+		// Escape regex special characters in flag name to prevent injection
+		const escapedFlag = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		const patternEq = '--' + escapedFlag + '=\\s*(\\S+)';
+		const match = input.match(new RegExp(patternEq, 'i'));
+		if (match) return match[1];
+
+		const patternNoEq = '--' + escapedFlag + '\\s+(\\S+)';
+		const matchNoEq = input.match(new RegExp(patternNoEq, 'i'));
+		if (matchNoEq) return matchNoEq[1];
+
+		return undefined;
+	}
+
+	/**
+	 * Get effective config with step overrides global.
+	 */
+	private getEffectiveConfig(step: ChainStep, spec: ChainSpec): ChainStep {
+		return {
+			...step,
+			model: step.model ?? spec.globalModel,
+			skill: step.skill ?? spec.globalSkill,
+			thinking: step.thinking ?? spec.globalThinking,
+		};
+	}
+
+	/**
+	 * Enrich context with previous handoffs.
+	 * Limits history size to prevent memory leaks.
+	 */
+	private enrichContextFromHandoffs(
+		context: Record<string, unknown>,
+		previousResults: ChainStepResult[]
+	): Record<string, unknown> {
+		const handoffs = previousResults
+			.filter(r => r.handoff)
+			.map(r => r.handoff!);
+
+		if (handoffs.length === 0) {
+			return context;
+		}
+
+		// Limit history size to prevent memory leak (H2)
+		const limitedHandoffs = handoffs.slice(-ChainRunner.MAX_CHAIN_HISTORY_SIZE);
+
+		// Limit per-entry size to prevent memory issues from large artifacts
+		const filteredHandoffs = limitedHandoffs.filter(h => {
+			const size = JSON.stringify(h).length;
+			return size <= ChainRunner.MAX_HANDOFF_ENTRY_SIZE;
+		});
+
+		return {
+			...context,
+			__chainHistory: filteredHandoffs.map(h => ({
+				step: h.taskId,
+				outcome: h.outcome,
+				filesCreated: h.filesCreated?.slice(0, 50), // Limit array size
+				filesModified: h.filesModified?.slice(0, 50), // Limit array size
+				decisions: h.decisions?.slice(0, 20), // Limit array size
+				nextSteps: h.nextSteps?.slice(0, 20), // Limit array size
+			})),
+		};
+	}
+
+	/**
+	 * Execute a single step.
+	 */
+	private async executeStep(
+		config: ChainStep,
+		context: Record<string, unknown>
+	): Promise<TaskResult> {
+		const packet: TaskPacket = {
+			taskId: `chain-${Date.now()}-${config.name}`,
+			runId: "chain",
+			goal: config.inlineGoal ?? config.name,
+			summarizeThreshold: 3000,
+			collapseContext: true,
+			context,
+		};
+
+		return this.taskRunner.runTask(packet);
+	}
+
+	/**
+	 * Create minimal packet for handoff generation.
+	 */
+	private createMinimalPacket(step: ChainStep, index: number): TaskPacket {
+		return {
+			taskId: `chain-step-${index}`,
+			runId: "chain",
+			sessionId: "chain",
+			goal: step.inlineGoal ?? step.name,
+		};
+	}
+}
+
+/**
+ * Create a ChainRunner with default dependencies.
+ */
+export function createChainRunner(
+	taskRunner: ChainTaskRunner,
+	handoffManager: HandoffManager
+): ChainRunner {
+	return new ChainRunner(taskRunner, handoffManager);
+}
+
+/**
+ * Parse chain from string shorthand.
+ */
+export function parseChainString(chainString: string): ChainSpec {
+	const runner = new ChainRunner(
+		{ runTask: () => Promise.reject(new Error("Not initialized")) } as ChainTaskRunner,
+		{} as HandoffManager
+	);
+	return runner.parseChain(chainString);
+}

package/src/runtime/child-pi.ts

@@ -8,7 +8,7 @@ import { getPiSpawnCommand } from "./pi-spawn.ts";
 import { DEFAULT_CHILD_PI } from "../config/defaults.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guard.ts";
-import { redactJsonLine, SECRET_KEY_PATTERN } from "../utils/redaction.ts";
+import { redactJsonLine, isSecretKey } from "../utils/redaction.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { registerChildProcess, unregisterChildProcess } from "../extension/crew-cleanup.ts";
 
@@ -206,11 +206,29 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 			"SHELL",
 			"TERM",
 			"LANG",
-			"LC_*",
-			"XDG_*",
-			"NVM_*",
-			"NODE_*",
-			"npm_*",
+			// FIX: Replaced broad wildcards (LC_*, XDG_*, NVM_*, NODE_*, npm_*) with
+			// specific names. Previously NPM_TOKEN, NODE_ENV=production, NVM_RC_VERSION
+			// all leaked through wildcards.
+			"LC_ALL",
+			"LC_COLLATE",
+			"LC_CTYPE",
+			"LC_MESSAGES",
+			"LC_MONETARY",
+			"LC_NUMERIC",
+			"LC_TIME",
+			"XDG_CONFIG_HOME",
+			"XDG_DATA_HOME",
+			"XDG_CACHE_HOME",
+			"XDG_RUNTIME_DIR",
+			"NVM_BIN",
+			"NVM_DIR",
+			"NVM_INC",
+			"NODE_PATH",
+			"NODE_DISABLE_COLORS",
+			"NODE_EXTRA_CA_CERTS",
+			"NPM_CONFIG_REGISTRY",
+			"NPM_CONFIG_USERCONFIG",
+			"NPM_CONFIG_GLOBALCONFIG",
 			"PI_*",
 			"PI_CREW_*",
 			"PI_TEAMS_*",

package/src/runtime/crash-recovery.ts

@@ -15,6 +15,7 @@ import { activeRunEntries, unregisterActiveRun, readActiveRunRegistry } from "..
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
 import { terminateLiveAgentsForRun } from "./live-agent-manager.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 
 export interface RecoveryPlan {
 	runId: string;
@@ -159,7 +160,7 @@ export function cancelOrphanedRuns(
 			cancelled.push(manifest.runId);
 			cancelledRun = true;
 		});
-		if (cancelledRun) void terminateLiveAgentsForRun(manifest.runId, "cancelled", appendEvent, loaded.manifest.eventsPath).catch(() => {});
+		if (cancelledRun) void terminateLiveAgentsForRun(manifest.runId, "cancelled", appendEvent, loaded.manifest.eventsPath).catch((error) => logInternalError("crash-recovery.orphan.terminate", error, `runId=${manifest.runId}`));
 	}
 
 	return { cancelled, skipped };
@@ -268,7 +269,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 							saveRunTasks(fullLoaded.manifest, repairedTasks);
 							for (const task of repairedTasks) { try { upsertCrewAgent(fullLoaded.manifest, recordFromTask(fullLoaded.manifest, task, "scaffold")); } catch { /* non-critical */ } }
 							updateRunStatus(fullLoaded.manifest, "cancelled", "Orphaned run: worker process dead and no recent activity");
-							void terminateLiveAgentsForRun(fullLoaded.manifest.runId, "cancelled", appendEvent, fullLoaded.manifest.eventsPath).catch(() => {});
+							void terminateLiveAgentsForRun(fullLoaded.manifest.runId, "cancelled", appendEvent, fullLoaded.manifest.eventsPath).catch((error) => logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`));
 						}
 					} catch {
 						// Best-effort manifest cleanup
@@ -299,7 +300,7 @@ export function purgeStaleActiveRunIndex(staleThresholdMs = 300_000, now = Date.
 						saveRunTasks(fullLoaded.manifest, repairedTasks);
 						for (const task of repairedTasks) { try { upsertCrewAgent(fullLoaded.manifest, recordFromTask(fullLoaded.manifest, task, "scaffold")); } catch { /* non-critical */ } }
 						updateRunStatus(fullLoaded.manifest, "cancelled", "Orphaned run: no async worker and no manifest update in over " + Math.round(staleThresholdMs / 60000) + " minutes");
-						void terminateLiveAgentsForRun(fullLoaded.manifest.runId, "cancelled", appendEvent, fullLoaded.manifest.eventsPath).catch(() => {});
+						void terminateLiveAgentsForRun(fullLoaded.manifest.runId, "cancelled", appendEvent, fullLoaded.manifest.eventsPath).catch((error) => logInternalError("crash-recovery.pid-dead.terminate", error, `runId=${fullLoaded.manifest.runId}`));
 					}
 				} catch {
 					// Best-effort
@@ -335,7 +336,7 @@ export function reconcileAllStaleRuns(cwd: string, manifestCache: ManifestCache,
 				for (const task of result.repairedTasks) { try { upsertCrewAgent(fresh.manifest, recordFromTask(fresh.manifest, task, "scaffold")); } catch { /* non-critical */ } }
 			}
 				updateRunStatus(fresh.manifest, "failed", `Stale run reconciled: ${result.detail}`);
-				void terminateLiveAgentsForRun(fresh.manifest.runId, "failed", appendEvent, fresh.manifest.eventsPath).catch(() => {});
+				void terminateLiveAgentsForRun(fresh.manifest.runId, "failed", appendEvent, fresh.manifest.eventsPath).catch((error) => logInternalError("crash-recovery.reconcile.terminate", error, `runId=${fresh.manifest.runId}`));
 				appendEvent(fresh.manifest.eventsPath, { type: "crew.run.reconciled_stale", runId: manifest.runId, message: result.detail, data: { verdict: result.verdict } });
 			}
 			if (result.verdict !== "healthy") {

package/src/runtime/crew-agent-records.ts

@@ -263,12 +263,41 @@ export function readCrewAgentStatus(manifest: TeamRunManifest, taskOrAgentId: st
 }
 
 const agentEventSeqCache = new Map<string, { size: number; mtimeMs: number; seq: number }>();
+const AGENT_EVENT_SEQ_SIDECAR = ".seq";
+
+function readSeqFromSidecar(filePath: string): number | undefined {
+	try {
+		const raw = fs.readFileSync(`${filePath}.${AGENT_EVENT_SEQ_SIDECAR}`, "utf-8");
+		const n = Number.parseInt(raw, 10);
+		return Number.isFinite(n) && n > 0 ? n : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function writeSeqToSidecar(filePath: string, seq: number): void {
+	try {
+		fs.writeFileSync(`${filePath}.${AGENT_EVENT_SEQ_SIDECAR}`, String(seq));
+	} catch (error) {
+		logInternalError("crew-agent-records.seq-sidecar", error, `filePath=${filePath}`);
+	}
+}
 
 function nextAgentEventSeq(filePath: string): number {
-	if (!fs.existsSync(filePath)) return 1;
+	if (!fs.existsSync(filePath)) {
+		// Clean up stale sidecar when main file is gone.
+		try { fs.unlinkSync(`${filePath}.${AGENT_EVENT_SEQ_SIDECAR}`); } catch {}
+		return 1;
+	}
 	const stat = fs.statSync(filePath);
 	const cached = agentEventSeqCache.get(filePath);
 	if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return cached.seq + 1;
+	// FIX: Try sidecar file for O(1) lookup before falling back to O(n) scan.
+	const sidecarSeq = readSeqFromSidecar(filePath);
+	if (sidecarSeq !== undefined) {
+		agentEventSeqCache.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs, seq: sidecarSeq });
+		return sidecarSeq + 1;
+	}
 	let max = 0;
 	for (const line of fs.readFileSync(filePath, "utf-8").split(/\r?\n/)) {
 		if (!line.trim()) continue;
@@ -281,6 +310,7 @@ function nextAgentEventSeq(filePath: string): number {
 		}
 	}
 	agentEventSeqCache.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs, seq: max });
+	writeSeqToSidecar(filePath, max);
 	return max + 1;
 }
 
@@ -292,6 +322,7 @@ export function appendCrewAgentEvent(manifest: TeamRunManifest, taskId: string,
 	try {
 		const stat = fs.statSync(filePath);
 		agentEventSeqCache.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs, seq });
+		writeSeqToSidecar(filePath, seq);
 	} catch (error) {
 		logInternalError("crew-agent-records.stat", error, `filePath=${filePath}`);
 	}

package/src/runtime/custom-tools/irc-tool.ts

@@ -44,6 +44,19 @@ const IrcParams = Type.Object({
 
 type IrcParams = Static<typeof IrcParams>;
 
+/**
+ * Output schema for the irc tool's `details` field.
+ * All fields are optional — only present when relevant to the operation.
+ *
+ * Schema:
+ *   op         — Always present. "send" | "list"
+ *   from       — Sender agent ID. Present on all responses.
+ *   to         — Recipient agent ID. Present on send responses.
+ *   delivered  — Array of agent IDs that received the message. Present on send.
+ *   notFound   — Array of agent IDs that were unknown or unavailable. Present on send.
+ *   peers      — Array of { id, status } for list operation.
+ *   error      — Human-readable error description. Present when the operation failed.
+ */
 interface IrcDetails {
 	op: "send" | "list";
 	from?: string;

package/src/runtime/custom-tools/submit-result-tool.ts

@@ -12,6 +12,7 @@
 import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "@sinclair/typebox";
 import type { YieldResult } from "../yield-handler.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
 
 const SubmitResultParams = Type.Object({
 	summary: Type.String({ description: "Summary of completed work." }),
@@ -81,8 +82,8 @@ export function createSubmitResultTool(
 			};
 			try {
 				onYield(result);
-			} catch {
-				// Yield handler failure should not prevent tool response
+			} catch (error) {
+				logInternalError("submit-result-tool.yield", error, toolCallId);
 			}
 			return response;
 		},