pi-crew 0.9.34 → 0.9.35

package/src/extension/team-tool/handle-schedule.ts

@@ -10,6 +10,11 @@ const CREW_SCHEDULER_KEY = Symbol.for("pi-crew:scheduler");
 type SchedulerRef = {
 	add(job: import("../../runtime/scheduler.ts").ScheduledJob): void;
 	list(): import("../../runtime/scheduler.ts").ScheduledJob[];
+	remove(id: string): boolean;
+	update(
+		id: string,
+		patch: Partial<import("../../runtime/scheduler.ts").ScheduledJob>,
+	): import("../../runtime/scheduler.ts").ScheduledJob | undefined;
 };
 
 function getCrewScheduler(): SchedulerRef | undefined {
@@ -65,7 +70,27 @@ function buildScheduleSpec(params: ScheduleParams): {
 	throw new Error("schedule requires one of: cron, interval, or once.");
 }
 
+function getSubAction(params: TeamToolParamsValue): string | undefined {
+	const raw = params.subAction ?? (params.config as { subAction?: unknown } | undefined)?.subAction;
+	return typeof raw === "string" ? raw.toLowerCase() : undefined;
+}
+
+function getJobIdParam(params: TeamToolParamsValue): string {
+	const fromTop = typeof params.jobId === "string" ? params.jobId : "";
+	const fromConfig = ((params.config as { jobId?: unknown } | undefined)?.jobId as string | undefined) ?? "";
+	return (fromTop || fromConfig).trim();
+}
+
 export function handleSchedule(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	// Route subactions FIRST so remove/disable/enable don't require a goal.
+	const subAction = getSubAction(params);
+	if (subAction === "remove" || subAction === "delete") {
+		return handleRemoveScheduled(params, ctx);
+	}
+	if (subAction === "disable" || subAction === "enable" || subAction === "update") {
+		return handleUpdateScheduled(params, ctx);
+	}
+
 	const team = params.team ?? "default";
 	const goal = params.goal ?? params.task ?? "";
 	if (!goal) return result("Schedule requires goal or task.", { action: "schedule", status: "error" }, true);
@@ -239,3 +264,80 @@ export function handleListScheduled(_params: TeamToolParamsValue, ctx: TeamConte
 	}
 	return result(lines.join("\n"), { action: "scheduled", status: "ok" });
 }
+
+/**
+ * Remove a scheduled job. Mirrors the `cancel` action for runs.
+ *
+ * Usage:
+ *   team action='schedule' subAction='remove' jobId='<uuid>'
+ *   team action='schedule' subAction='delete' jobId='<uuid>'
+ */
+export function handleRemoveScheduled(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const jobId = getJobIdParam(params);
+	if (!jobId) {
+		return result(
+			"subAction=remove requires jobId. Usage: team action='schedule' subAction='remove' jobId='<uuid>'",
+			{ action: "schedule", status: "error" },
+			true,
+		);
+	}
+	const scheduler = getCrewScheduler();
+	if (!scheduler) {
+		return result("Scheduler not running.", { action: "schedule", status: "error" }, true);
+	}
+	const removed = scheduler.remove(jobId);
+	persistScheduledJobRemove(ctx.cwd, jobId);
+	if (!removed) {
+		return result(`No scheduled job with id '${jobId}'.`, { action: "schedule", status: "error" }, true);
+	}
+	return result([`Scheduled job removed.`, `  Job ID: ${jobId}`].join("\n"), {
+		action: "schedule",
+		status: "ok",
+		data: { jobId, removed: true },
+	});
+}
+
+/**
+ * Update a scheduled job — toggle enabled flag or apply patches.
+ *
+ * Usage:
+ *   team action='schedule' subAction='disable' jobId='<uuid>'
+ *   team action='schedule' subAction='enable'  jobId='<uuid>'
+ *   team action='schedule' subAction='update'  jobId='<uuid>' cron='0 9 * * *'
+ */
+export function handleUpdateScheduled(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const jobId = getJobIdParam(params);
+	if (!jobId) {
+		return result(
+			"subAction=update requires jobId. Usage: team action='schedule' subAction='update|enable|disable' jobId='<uuid>'",
+			{ action: "schedule", status: "error" },
+			true,
+		);
+	}
+	const subAction = typeof params.subAction === "string" ? params.subAction.toLowerCase() : "update";
+	const scheduler = getCrewScheduler();
+	if (!scheduler) {
+		return result("Scheduler not running.", { action: "schedule", status: "error" }, true);
+	}
+
+	const patch: Partial<import("../../runtime/scheduler.ts").ScheduledJob> = {};
+	if (subAction === "disable") patch.enabled = false;
+	if (subAction === "enable") patch.enabled = true;
+	// For generic "update", allow patch of cron / interval / goal.
+	if (subAction === "update") {
+		if (typeof params.cron === "string") patch.schedule = params.cron;
+		if (typeof params.goal === "string" || typeof params.task === "string") {
+			patch.description = typeof params.task === "string" ? params.task : params.goal;
+		}
+	}
+
+	const updated = scheduler.update(jobId, patch);
+	if (!updated) {
+		return result(`No scheduled job with id '${jobId}'.`, { action: "schedule", status: "error" }, true);
+	}
+	persistScheduledJobUpdate(ctx.cwd, updated);
+	return result(
+		[`Scheduled job updated.`, `  Job ID: ${jobId}`, `  Enabled: ${updated.enabled}`, `  Schedule: ${updated.schedule}`].join("\n"),
+		{ action: "schedule", status: "ok", data: { jobId, enabled: updated.enabled, schedule: updated.schedule } },
+	);
+}

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

@@ -1,6 +1,5 @@
 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";
@@ -374,47 +373,6 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		}
 	}
 
-	// Check if this is a pipeline workflow - special handling for multi-stage execution
-	const isPipelineWorkflow = workflowName === "pipeline" && !directAgent;
-	if (isPipelineWorkflow) {
-		// For pipeline workflows, use PipelineRunner for execution
-		const pipelineRunner = new PipelineRunner();
-		const pipelineWorkflow: PipelineWorkflow = {
-			name: workflow.name,
-			description: workflow.description,
-			goal,
-			stages: workflow.steps.map((step) => ({
-				name: step.id,
-				team: step.role,
-				inputs: step.task,
-				usePreviousResults: step.dependsOn && step.dependsOn.length > 0,
-			})),
-			stopOnError: true,
-			defaultMaxConcurrency: workflow.maxConcurrency ?? 5,
-		};
-
-		// For now, show pipeline workflow info - full integration would require
-		// connecting PipelineRunner to the actual team execution system
-		const stageInfo = pipelineWorkflow.stages.map((s) => `- ${s.name} (${s.team})`).join("\n");
-		return result(
-			[
-				`Pipeline workflow '${workflow.name}' is not yet wired into the team execution system.`,
-				`Goal: ${goal}`,
-				`Defined stages (${pipelineWorkflow.stages.length}):`,
-				stageInfo,
-				"",
-				"To actually run work right now, use a supported workflow instead:",
-				"  - action='run' workflow='default'  (explore → plan → execute → verify)",
-				"  - action='run' workflow='implementation'  (adaptive, parallel specialists)",
-				"  - action='run' workflow='research'  (explore → analyze → write)",
-				"",
-				"Run action='list' resource='workflow' to see all available workflows.",
-			].join("\n"),
-			{ action: "run", status: "ok" },
-			false,
-		);
-	}
-
 	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { validateWorkflowForTeam }` above (issue #28, RFC 17).
 	const { validateWorkflowForTeam: validateWorkflow } = await import("../../workflows/validate-workflow.ts");
 	const validationErrors = validateWorkflow(workflow, team);

package/src/extension/team-tool.ts

@@ -11,7 +11,7 @@ import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEvent, appendEventFireAndForget } from "../state/event-log.ts";
 import { withRunLock } from "../state/locks.ts";
 import { replayPendingMailboxMessages } from "../state/mailbox.ts";
-import { loadRunManifestById, saveRunManifest, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
+import { loadRunManifestById, saveRunManifestAsync, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { assertSafePathId } from "../utils/safe-paths.ts";
@@ -59,7 +59,7 @@ async function handleRun(...args: Parameters<HandleRunFn>): Promise<Awaited<Retu
 
 import { FileCheckpointStore } from "../runtime/checkpoint.ts";
 import { waitForRun } from "../runtime/run-tracker.ts";
-import { normalizeSkillOverride } from "../runtime/skill-instructions.ts";
+import { getSkillCacheStats, normalizeSkillOverride } from "../runtime/skill-instructions.ts";
 import { computeRunCacheKey, getCachedRun, getCacheStats } from "../state/run-cache.ts";
 import { listRunGraphs, loadRunGraph } from "../state/run-graph.ts";
 import { searchAgents, searchTeams } from "../utils/bm25-search.ts";
@@ -223,10 +223,10 @@ function artifactKey(artifact: ArtifactDescriptor): string {
 	return `${artifact.kind}:${artifact.path}`;
 }
 
-function recoverCheckpointedTasks(
+async function recoverCheckpointedTasks(
 	manifest: TeamRunManifest,
 	tasks: TeamTaskState[],
-): { manifest: TeamRunManifest; tasks: TeamTaskState[]; recovered: string[] } {
+): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[]; recovered: string[] }> {
 	const recovered: string[] = [];
 	let nextManifest = manifest;
 	const nextTasks = tasks.map((task) => {
@@ -302,7 +302,7 @@ function recoverCheckpointedTasks(
 			artifacts: [...artifacts.values()],
 			updatedAt: new Date().toISOString(),
 		};
-		saveRunManifest(nextManifest);
+		await saveRunManifestAsync(nextManifest);
 		saveRunTasks(nextManifest, nextTasks);
 	}
 	return { manifest: nextManifest, tasks: nextTasks, recovered };
@@ -346,7 +346,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		const lockedManifest = fresh?.manifest ?? loaded.manifest;
 		const lockedTasks = fresh?.tasks ?? loaded.tasks;
 		const loadedConfig = loadConfig(ctx.cwd);
-		const recovered = recoverCheckpointedTasks(lockedManifest, lockedTasks);
+		const recovered = await recoverCheckpointedTasks(lockedManifest, lockedTasks);
 		const resumeManifest = recovered.manifest;
 		const executedConfig = {
 			...effectiveRunConfig(loadedConfig.config, params.config),
@@ -372,7 +372,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 			runtimeResolution,
 			updatedAt: new Date().toISOString(),
 		};
-		saveRunManifest(runtimeManifest);
+		await saveRunManifestAsync(runtimeManifest);
 		appendEvent(runtimeManifest.eventsPath, {
 			type: "runtime.resolved",
 			runId: runtimeManifest.runId,
@@ -974,7 +974,12 @@ export async function handleTeamTool(params: TeamToolParamsValue, ctx: TeamConte
 				});
 			}
 			const stats = getCacheStats(ctx.cwd);
-			return result(`Cache stats: ${stats.entries} entries, ${stats.sizeBytes} bytes`, { action: "cache", status: "ok" });
+			const skillStats = getSkillCacheStats();
+			return result(
+				`Run cache: ${stats.entries} entries, ${stats.sizeBytes} bytes\n` +
+					`Skill cache: ${skillStats.hits} hits, ${skillStats.misses} misses (${(skillStats.hitRate * 100).toFixed(1)}% hit rate), ${skillStats.currentSize}/${skillStats.maxEntries} entries, ${skillStats.evictions} evictions`,
+				{ action: "cache", status: "ok" },
+			);
 		}
 		case "checkpoint": {
 			if (!params.runId || !params.taskId) {

package/src/runtime/adaptive-plan.ts

@@ -17,7 +17,7 @@
 import * as fs from "node:fs";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEvent } from "../state/event-log.ts";
-import { saveRunManifest } from "../state/state-store.ts";
+import { saveRunManifestAsync } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import type { TeamConfig } from "../teams/team-config.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
@@ -369,7 +369,7 @@ export interface InjectAdaptivePlanResult {
 	missingPlan: boolean;
 }
 
-export function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput): InjectAdaptivePlanResult {
+export async function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput): Promise<InjectAdaptivePlanResult> {
 	if (input.workflow.name !== "implementation")
 		return {
 			tasks: input.tasks,
@@ -442,7 +442,7 @@ export function injectAdaptivePlanIfReady(input: InjectAdaptivePlanInput): Injec
 				producer: assessTask.id,
 				content: `${JSON.stringify({ reason: repair.reason, phases: repair.plan.phases.map((phase) => ({ name: phase.name, count: phase.tasks.length, roles: phase.tasks.map((task) => task.role) })) }, null, 2)}\n`,
 			});
-			saveRunManifest({
+			await saveRunManifestAsync({
 				...input.manifest,
 				updatedAt: new Date().toISOString(),
 				artifacts: [...input.manifest.artifacts, repairArtifact],

package/src/runtime/background-runner.ts

@@ -4,7 +4,7 @@ import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
 import { loadConfig } from "../config/config.ts";
 import { appendEvent } from "../state/event-log.ts";
 import { withRunLockSync } from "../state/locks.ts";
-import { createRunPaths, loadRunManifestById, saveRunManifest, updateRunStatus } from "../state/state-store.ts";
+import { createRunPaths, loadRunManifestById, saveRunManifestAsync, updateRunStatus } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
@@ -621,7 +621,7 @@ async function main(): Promise<void> {
 					status: runStatus,
 					updatedAt: new Date().toISOString(),
 				};
-				saveRunManifest(finalGoalManifest);
+				await saveRunManifestAsync(finalGoalManifest);
 				earlyResult = {
 					manifest: finalGoalManifest,
 					tasks: goalResult.tasks,
@@ -642,7 +642,7 @@ async function main(): Promise<void> {
 					signal: abortController.signal,
 					tokenBudget: wf.maxTokenBudget,
 				});
-				saveRunManifest(dwfResult.manifest);
+				await saveRunManifestAsync(dwfResult.manifest);
 				earlyResult = dwfResult;
 			}
 			console.log(`[background-runner] ${manifest.runKind} returned, status=${earlyResult.manifest.status}`);
@@ -687,7 +687,7 @@ async function main(): Promise<void> {
 				runConfig,
 				updatedAt: new Date().toISOString(),
 			};
-			saveRunManifest(manifest);
+			await saveRunManifestAsync(manifest);
 			appendEvent(manifest.eventsPath, {
 				type: "runtime.resolved",
 				runId: manifest.runId,

package/src/runtime/child-pi.ts

@@ -435,11 +435,75 @@ function appendTranscript(input: ChildPiRunInput, line: string): void {
 	// We skip mkdirSync here for security — adding it would create parent
 	// directories during validation, contradicting the original design where
 	// resolveRealContainedPath validates a pre-existing path.
-	const fd = fs.openSync(safePath, fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW | fs.constants.O_CREAT | fs.constants.O_APPEND, 0o600);
+	// Async optimization: use fire-and-forget async write to avoid blocking the event loop.
+	// The caller does not need to await this — transcript writes are best-effort telemetry.
+	// OPT-06 follow-up: we still track the write promise in a module-scoped Set so
+	// lifecycle boundaries (ChildPiLineObserver.flush, runChildPi settle) can drain
+	// them before returning. Without that drain, callers that immediately read the
+	// transcript file post-flush (e.g. integration tests at phase3-runtime:50 and
+	// phase4-runtime:37/:68/:103) would see ENOENT or empty content because the
+	// async file handle had not yet been opened / flushed.
+	trackTranscriptWrite(safePath, line);
+}
+
+/** Async version of appendTranscript — fire-and-forget for non-blocking writes. */
+async function appendTranscriptAsync(safePath: string, line: string): Promise<void> {
+	const content = `${redactJsonLine(line)}\n`;
 	try {
-		fs.writeSync(fd, `${redactJsonLine(line)}\n`, undefined, "utf-8");
-	} finally {
-		fs.closeSync(fd);
+		// Use async file handle for better performance when many writes occur.
+		// O_NOFOLLOW | O_CREAT | O_APPEND ensures security and atomicity.
+		const fd = await fs.promises.open(
+			safePath,
+			fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW | fs.constants.O_CREAT | fs.constants.O_APPEND,
+			0o600,
+		);
+		try {
+			await fd.write(content, undefined, "utf-8");
+		} finally {
+			await fd.close();
+		}
+	} catch (error) {
+		logInternalError("child-pi.transcript-write-failed", error as Error, `path=${safePath}`);
+	}
+}
+
+/**
+ * Module-scoped set of in-flight transcript-write promises. Each call to
+ * {@link trackTranscriptWrite} registers its promise here; the promise
+ * removes itself on completion via `.finally`. Lifecycle boundaries
+ * (ChildPiLineObserver.flush, runChildPi settle) call
+ * {@link flushPendingTranscriptWrites} before returning so callers that
+ * immediately read the transcript file after `runChildPi` / `observer.flush()`
+ * await see the full content (and a non-ENOENT file).
+ *
+ * Module-scoped rather than per-input because all transcript writes for a
+ * given run share the same Node fs event loop and serialise through a single
+ * fs handle per path; one drain per lifecycle boundary is sufficient.
+ */
+const pendingTranscriptWrites: Set<Promise<void>> = new Set();
+
+function trackTranscriptWrite(safePath: string, line: string): void {
+	const p = appendTranscriptAsync(safePath, line).finally(() => {
+		pendingTranscriptWrites.delete(p);
+	});
+	pendingTranscriptWrites.add(p);
+}
+
+/**
+ * Drain all currently-pending transcript writes. Awaits every promise in the
+ * set; if new writes are scheduled during the drain (i.e. the `.finally`
+ * callback has not yet removed them), the loop re-checks `size > 0` and
+ * awaits them too. Idempotent and safe to call concurrently / reentrantly —
+ * each pending promise is tracked exactly once.
+ *
+ * Exported so external callers (e.g. integration tests that construct a
+ * ChildPiLineObserver directly) can drain explicitly if they need to read
+ * the transcript file outside of the observer's lifecycle.
+ */
+export async function flushPendingTranscriptWrites(): Promise<void> {
+	while (pendingTranscriptWrites.size > 0) {
+		const drained = [...pendingTranscriptWrites];
+		await Promise.allSettled(drained);
 	}
 }
 
@@ -632,11 +696,18 @@ export class ChildPiLineObserver {
 		for (const line of lines) this.emitLine(line);
 	}
 
-	flush(): void {
-		if (!this.buffer) return;
-		const line = this.buffer;
-		this.buffer = "";
-		this.emitLine(line);
+	flush(): Promise<void> {
+		if (this.buffer) {
+			const line = this.buffer;
+			this.buffer = "";
+			this.emitLine(line);
+		}
+		// OPT-06 follow-up: appendTranscript is fire-and-forget async, so the file
+		// may not exist on disk by the time this returns. Drain the module-scoped
+		// pending-write set before resolving so callers that immediately read the
+		// transcript file (e.g. integration tests at phase4-runtime:37/:68/:103
+		// after `await observer.flush()`) see the full content.
+		return flushPendingTranscriptWrites();
 	}
 
 	/** Last non-empty RAW assistant text (mirrors {@link parsePiJsonOutput}'s
@@ -715,11 +786,15 @@ export class ChildPiLineObserver {
 	}
 }
 
-/** Mock-only path — real code path reuses a single observer. */
-function observeStdoutChunk(input: ChildPiRunInput, text: string): void {
+/** Mock-only path — real code path reuses a single observer.
+ *  OPT-06 follow-up: returns a Promise so callers can await the transcript
+ *  drain before resolving runChildPi. Without this, mock-mode callers that
+ *  read the transcript file post-run see ENOENT (the async file handle had
+ *  not yet been opened). */
+async function observeStdoutChunk(input: ChildPiRunInput, text: string): Promise<void> {
 	const observer = new ChildPiLineObserver(input);
 	observer.observe(text);
-	observer.flush();
+	await observer.flush();
 }
 
 function asRecord(value: unknown): Record<string, unknown> | undefined {
@@ -779,7 +854,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 		logInternalError("child-pi.mock", new Error(`Mock mode active: ${mock}`), "NOT running real agents");
 		if (mock === "success") {
 			const stdout = `[MOCK] Success for ${input.agent.name}\n`;
-			observeStdoutChunk(input, stdout);
+			await observeStdoutChunk(input, stdout);
 			return { exitCode: 0, stdout, stderr: "" };
 		}
 		if (mock === "json-success" || mock === "adaptive-plan") {
@@ -834,7 +909,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						})}\nADAPTIVE_PLAN_JSON_END`
 					: `[MOCK] JSON success for ${input.agent.name}`;
 			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
-			observeStdoutChunk(input, stdout);
+			await observeStdoutChunk(input, stdout);
 			return { exitCode: 0, stdout, stderr: "" };
 		}
 		if (mock === "retryable-failure")
@@ -882,14 +957,14 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					},
 				};
 				const stdout = `${JSON.stringify(failureEvent)}\n`;
-				observeStdoutChunk(input, stdout);
+				await observeStdoutChunk(input, stdout);
 				return { exitCode: 0, stdout, stderr: "" };
 			}
 			// Subsequent invocations: delegate to json-success shape so the
 			// fallback chain's second attempt succeeds and the run completes.
 			const text = `[MOCK] JSON success for ${input.agent.name}`;
 			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
-			observeStdoutChunk(input, stdout);
+			await observeStdoutChunk(input, stdout);
 			return { exitCode: 0, stdout, stderr: "" };
 		}
 		return { exitCode: 1, stdout: "", stderr: `[MOCK] failure: ${mock}` };
@@ -1107,7 +1182,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 							process.kill(child.pid!, 0);
 							// Child still alive — force settle with timeout error.
 							const timeoutErr = `Child Pi produced no new output for ${responseTimeoutMs}ms; killed but did not exit within ${SAFETY_SETTLE_MS}ms (possible zombie).`;
-							settle({
+							void settle({
 								exitCode: null,
 								stdout,
 								stderr,
@@ -1320,46 +1395,106 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				clearPostExitGuard();
 			};
 
-			const settle = (result: ChildPiRunResult): void => {
-				if (settled) return;
+			const settle = (result: ChildPiRunResult): Promise<void> => {
+				if (settled) return Promise.resolve();
 				settled = true;
 				clearChildPiTimeouts();
-				lineObserver.flush();
-				input.signal?.removeEventListener("abort", abort);
-				input.signal?.removeEventListener("abort", onParentAbort);
-				try {
-					cleanupTempDir(built.tempDir);
-				} catch (error) {
-					cleanupErrors.push(error instanceof Error ? error.message : String(error));
-				}
-				// Catch all errors from settle to prevent unhandled rejection from propagating
-				try {
-					resolve({
-						...result,
-						rawFinalText: lineObserver.getRawFinalText(),
-						intermediateFindings: lineObserver.getIntermediateFindings(),
-						exitStatus: result.exitStatus ?? {
-							exitCode: result.exitCode,
-							cancelled: abortRequested,
-							timedOut: responseTimeoutHit,
-							killed: hardKilled,
-							// Phase-0 diagnostic (HB-003a): surface the final-drain race state.
-							// finalDrainArmed lets Phase 1 decide whether a signal-death (exitCode=null)
-							// should be treated as a forced final drain. READ-ONLY for now.
-							...(finalDrainArmed || forcedFinalDrain
-								? {
-										finalDrainArmed,
-										forcedFinalDrain,
-										finalDrainFiredMonotonicMs,
-									}
-								: {}),
-							cleanupErrors,
-							finalDrainMs,
-						},
+				// OPT-06 follow-up: lineObserver.flush() is now async (returns
+				// Promise<void>) and drains the module-scoped pending-write set
+				// before resolving. We must await it before calling `resolve()`
+				// below so callers that read the transcript file post-`runChildPi`
+				// see all written lines. Caller invocations of `settle` from
+				// sync event handlers (`child.on('close'|'exit'|'error')`,
+				// safety timer) use `void settle(...)` — errors are caught and
+				// logged inside, and `resolve()` only fires after the drain
+				// completes, so runChildPi's outer Promise resolves with a
+				// durable transcript on disk.
+				return lineObserver
+					.flush()
+					.then(() => {
+						input.signal?.removeEventListener("abort", abort);
+						input.signal?.removeEventListener("abort", onParentAbort);
+						try {
+							cleanupTempDir(built.tempDir);
+						} catch (error) {
+							cleanupErrors.push(error instanceof Error ? error.message : String(error));
+						}
+						// Catch all errors from settle to prevent unhandled rejection from propagating
+						try {
+							resolve({
+								...result,
+								rawFinalText: lineObserver.getRawFinalText(),
+								intermediateFindings: lineObserver.getIntermediateFindings(),
+								exitStatus: result.exitStatus ?? {
+									exitCode: result.exitCode,
+									cancelled: abortRequested,
+									timedOut: responseTimeoutHit,
+									killed: hardKilled,
+									// Phase-0 diagnostic (HB-003a): surface the final-drain race state.
+									// finalDrainArmed lets Phase 1 decide whether a signal-death (exitCode=null)
+									// should be treated as a forced final drain. READ-ONLY for now.
+									...(finalDrainArmed || forcedFinalDrain
+										? {
+												finalDrainArmed,
+												forcedFinalDrain,
+												finalDrainFiredMonotonicMs,
+											}
+										: {}),
+									cleanupErrors,
+									finalDrainMs,
+								},
+							});
+						} catch (resolveError) {
+							logInternalError(
+								"child-pi.settle-resolve",
+								resolveError,
+								`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+							);
+						}
+					})
+					.catch((flushError) => {
+						// Drain failed — log and still resolve so runChildPi doesn't hang.
+						logInternalError(
+							"child-pi.settle-flush-failed",
+							flushError,
+							`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+						);
+						input.signal?.removeEventListener("abort", abort);
+						input.signal?.removeEventListener("abort", onParentAbort);
+						try {
+							cleanupTempDir(built.tempDir);
+						} catch (error) {
+							cleanupErrors.push(error instanceof Error ? error.message : String(error));
+						}
+						try {
+							resolve({
+								...result,
+								rawFinalText: lineObserver.getRawFinalText(),
+								intermediateFindings: lineObserver.getIntermediateFindings(),
+								exitStatus: result.exitStatus ?? {
+									exitCode: result.exitCode,
+									cancelled: abortRequested,
+									timedOut: responseTimeoutHit,
+									killed: hardKilled,
+									...(finalDrainArmed || forcedFinalDrain
+										? {
+												finalDrainArmed,
+												forcedFinalDrain,
+												finalDrainFiredMonotonicMs,
+											}
+										: {}),
+									cleanupErrors,
+									finalDrainMs,
+								},
+							});
+						} catch (resolveError) {
+							logInternalError(
+								"child-pi.settle-resolve",
+								resolveError,
+								`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+							);
+						}
 					});
-				} catch (resolveError) {
-					logInternalError("child-pi.settle-resolve", resolveError, `result=${JSON.stringify({ exitCode: result.exitCode })}`);
-				}
 			};
 
 			const abort = (): void => {
@@ -1446,7 +1581,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				} catch (err) {
 					logInternalError("child-pi.on-lifecycle-event", err, `event=error, pid=${child.pid}`);
 				}
-				settle({
+				void settle({
 					exitCode: null,
 					stdout,
 					stderr,
@@ -1585,7 +1720,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					spawnError: undefined,
 					stderrSnippet: stderr ? redactStderrExcerpt(stderr, 1000) : undefined,
 				});
-				settle({
+				void settle({
 					exitCode: finalExitCode,
 					stdout,
 					stderr,