pi-crew 0.9.4 → 0.9.7

package/docs/troubleshooting.md

@@ -74,6 +74,32 @@ team action='cancel' runId=…    # cancel a truly-dead run
 
 The error message explains the heartbeat mechanism + remediation.
 
+### "Run not found" but `team list` shows it / scheduler appears frozen at 25%
+
+**Symptom:** an async `team action='run'` (e.g. a review) gets through the
+first task (e.g. explorer), then the scheduler appears to stop responding.
+`team action='status' runId=…` returns `Run not found`; the run's
+`stateRoot` (in `<project>/.crew/state/runs/<runId>/`) is missing. TUI
+progress shows the run stuck at the same task percentage forever, and the
+only workaround was killing the parent `pi` process.
+
+**This was the v0.9.4 symptom** caused by two coupled runtime bugs:
+
+- **Bug X** (proximate): `purgeStaleActiveRunIndex` destroyed the
+  `stateRoot` of long-running legitimate async runs based on a frozen
+  `entry.updatedAt` (set at registration, never refreshed).
+- **Bug Y** (root cause): the bg-runner crashed with an unhandled `EPIPE`
+  on the first `console.debug` after the parent detached its stdio pipes.
+
+**Fixed in v0.9.5** (see [CHANGELOG.md](../CHANGELOG.md#v095--fix-team-run-hangs-forever-at-25-2026-06-23)).
+With the fix, a long-running run is no longer falsely purged, and even if the
+bg-runner dies, the `stateRoot`, `background.log`, `events.jsonl`, and
+`heartbeat.json` survive — runs stay queryable and resumable.
+
+**Recovering a stuck run from v0.9.4 or earlier:** the `stateRoot` for
+those runs is already gone (Bug X nuked it). Re-dispatch the workflow. New
+runs on v0.9.5+ are fully protected.
+
 ## Model fallback exhausted
 
 **Symptom:** `All N candidates exhausted (tried: a → b → c)`.
@@ -129,3 +155,79 @@ code + a help hint inline. Common ones:
 - `team action='summary' runId=…` — includes common failure-pattern detection
   ("4 of 5 failures share 2 root causes").
 - `team action='events' runId=…` — full event timeline for forensics.
+
+## Stuck / orphaned sub-agent processes ("zombies")
+
+A pi-crew sub-agent whose parent crashed may linger as an orphaned process.
+**Do NOT kill `pi` processes by eye** (uptime/RSS heuristics will match your
+own interactive main session — that is unrecoverable). Use the safe scanner:
+
+```
+team action='doctor' focus='zombies'
+```
+
+This is **read-only**. It matches ONLY processes carrying the authoritative
+`PI_CREW_KIND=subagent` env marker (set by every child-pi spawn) whose
+`PI_CREW_PARENT_PID` is no longer alive. Your main session never carries the
+marker, so it can never appear in the list. (The marker is an env var, not an
+argv flag — pi's strict option parser rejects unknown flags, so we can't use
+a `--crew-subagent` CLI flag.)
+
+To kill a confirmed zombie: `kill <PID>` (the OS reaps it). The scanner never
+kills on your behalf.
+
+### Why the marker exists
+
+Before `PI_CREW_KIND`, a heuristic zombie "cleanup" killed a live main session
+by accident. The marker makes sub-agent identity authoritative rather than
+guessed. See `src/runtime/zombie-scanner.ts` and `.crew/knowledge.md`.
+
+## `ctx.agent({disableTools: true})` — historical `exit null` (FIXED)
+
+Previously, `ctx.agent({disableTools: true, maxTurns: 1})` could return
+`exit null` because the steer-injection code mis-treated normal Node stdin
+backpressure (`write() === false`) as a fatal failure and `killProcessTree`'d
+the worker mid-answer. **Fixed**: steer injection is now advisory — a
+backpressure return or non-writable stdin is logged, not fatal; the
+hard-abort at `maxTurns + graceTurns` remains the safety net for genuine
+runaways. The `disableTools` correlation was a red herring — the real trigger
+was `maxTurns:1` hitting on the first turn. See CHANGELOG "Real-world smoke
+testing findings" and `test/unit/child-pi-steer-backpressure.test.ts`.
+
+## Running the real-binary smoke suite (HB-004)
+
+The default `npm test` mocks child-pi (`PI_TEAMS_MOCK_CHILD_PI`), so it cannot
+catch bugs that only manifest against the real `pi` binary. The smoke suite
+shells out to real pi + makes real LLM calls, so it bills tokens and is gated
+behind `PI_CREW_SMOKE=1`.
+
+### Run locally
+
+```bash
+# All smoke tests (~5 tests, ~1 min, bills tokens):
+PI_CREW_SMOKE=1 npm run test:smoke
+
+# One smoke test in isolation:
+PI_CREW_SMOKE=1 npx tsx --test test/smoke/agent-disabletools.smoke.ts
+```
+
+Smoke tests live in `test/smoke/*.smoke.ts` and are NOT picked up by the default
+`npm test` glob (`test/unit/*` + `test/integration/*`). Each test self-skips
+unless `PI_CREW_SMOKE=1`.
+
+### What each covers
+
+| File | Feature family | Catches |
+|---|---|---|
+| `argv-flags.smoke.ts` | buildPiWorkerArgs argv | unknown-flag rejection (e.g. `--crew-subagent`) |
+| `agent-plain.smoke.ts` | ctx.agent() baseline | spawn-path breakage |
+| `agent-schema.smoke.ts` | ctx.agent({schema, systemPrompt}) | persona-leak / schema-validation failures |
+| `agent-disabletools.smoke.ts` | ctx.agent({disableTools, maxTurns:1}) ×5 | HB-003a steer-backpressure exit-null (flaky → 5×) |
+| `dwf-workflow.smoke.ts` | full DWF end-to-end | phase/log/args/budget/pipeline/agent/setResult integration |
+
+### Run in CI (manual dispatch)
+
+GitHub Actions → "Smoke (real-binary, manual)" → Run workflow → pick OS.
+Requires the `PI_AUTH_JSON` repo secret (the contents of `~/.pi/agent/auth.json`)
+so the spawned `pi` can authenticate with the model provider. If unset, the
+LLM-calling smoke tests fail with a clear auth error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.4",
+  "version": "0.9.7",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "docs/",
     "tsconfig.json",
     "schema.json",
+    "types/",
     "CHANGELOG.md",
     "LICENSE",
     "NOTICE.md"
@@ -52,6 +53,7 @@
     "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit test/unit/*.test.ts",
     "test:watch": "tsx --watch --test --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/*.test.ts",
     "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=120000 test/integration/*.test.ts",
+    "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
     "build:bundle": "node scripts/build-bundle.mjs",
     "bench": "node scripts/run-bench.mjs",
     "bench:check": "node scripts/bench-check.mjs",
@@ -63,7 +65,10 @@
     "smoke:release": "node scripts/release-smoke.mjs"
   },
   "exports": {
-    "./schema.json": "./schema.json"
+    "./schema.json": "./schema.json",
+    "./workflow": {
+      "types": "./types/dwf.d.ts"
+    }
   },
   "pi": {
     "extensions": [
@@ -81,6 +86,7 @@
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
+    "acorn": "^8.17.0",
     "ajv": "^8.20.0",
     "cli-highlight": "^2.1.11",
     "diff": "^5.2.0",

package/src/extension/command-completions.ts

@@ -67,6 +67,7 @@ export function suggestRunIds(_prefix: string, cwd?: string): AutocompleteItem[]
 export async function suggestTaskIds(runId: string, prefix: string, cwd?: string): Promise<AutocompleteItem[] | null> {
 	const resolvedCwd = cwd ?? process.cwd();
 	// Dynamic import to avoid pulling state-store into the hot command-registration path.
+		// LAZY: defer dynamic import of ../state/state-store.ts to its call site.
 	const { loadRunManifestById } = await import("../state/state-store.ts");
 	const loaded = loadRunManifestById(resolvedCwd, runId);
 	if (!loaded) return null;

package/src/extension/crew-shortcuts.ts

@@ -34,6 +34,7 @@ const CREW_SHORTCUTS: ReadonlyArray<ShortcutRegistration> = [
 		// (avoids pulling the full commands.ts dependency tree into every
 		// process that imports this module, e.g. the unit test).
 		handler: async (ctx) => {
+		// LAZY: defer dynamic import of ./registration/commands.ts to its call site.
 			const { openTeamSettingsOverlay } = await import("./registration/commands.ts");
 			await openTeamSettingsOverlay(ctx);
 		},

package/src/extension/register.ts

@@ -1129,6 +1129,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 				// LAZY: state-store only needed in hasRunning; avoid at startup.
 				// Use dynamic import to avoid CJS/ESM mixed module issues.
 				const { loadRunManifestById: loadRunForHasRunning } =
+		// LAZY: defer dynamic import of ../state/state-store.ts to its call site.
 					await import("../state/state-store.ts");
 				const loaded = loadRunForHasRunning(
 					currentCtx?.cwd ?? process.cwd(),
@@ -1494,6 +1495,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 								const cwd = ctx.cwd ?? process.cwd();
 								const loaded = loadRunManifestById(cwd, runId);
 								if (loaded) {
+		// LAZY: defer dynamic import of ../state/atomic-write.ts to its call site.
 									const { atomicWriteJson } = await import("../state/atomic-write.ts");
 									atomicWriteJson(loaded.manifest.stateRoot + "/manifest.json", {
 										...loaded.manifest,

package/src/extension/registration/commands.ts

@@ -202,11 +202,13 @@ export async function openTeamSettingsOverlay(ctx: ExtensionContext): Promise<vo
 						if (res.success) {
 							ctx.ui.notify(`Theme: ${value} (applied live)`, "info");
 						} else {
+		// LAZY: defer dynamic import of ../../ui/theme-discovery.ts to its call site.
 							const { setPiTheme } = await import("../../ui/theme-discovery.ts");
 							setPiTheme(value);
 							ctx.ui.notify(`Theme saved as '${value}' but failed to apply: ${res.error ?? "unknown"}. Restart Pi.`, "warning");
 						}
 					} else {
+		// LAZY: defer dynamic import of ../../ui/theme-discovery.ts to its call site.
 						const { setPiTheme } = await import("../../ui/theme-discovery.ts");
 						setPiTheme(value);
 						ctx.ui.notify(`Pi theme set to '${value}'. Restart Pi to apply.`, "info");
@@ -672,6 +674,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 	pi.registerCommand("crew-brief", {
 		description: "Toggle brief tool output mode: on | off | status",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
+		// LAZY: defer dynamic import of ../../ui/tool-renderers/brief-mode.ts to its call site.
 			const { isBrief, setBrief, BRIEF_ENTRY_TYPE, makeBriefEntry } = await import("../../ui/tool-renderers/brief-mode.ts");
 			const trimmed = args.trim();
 

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

@@ -10,6 +10,7 @@ import { DEFAULT_PATHS } from "../../config/defaults.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
 import { getRuntimeWarmupStatus } from "../../runtime/runtime-warmup.ts";
+import { scanZombieSubagents, formatZombieReport } from "../../runtime/zombie-scanner.ts";
 import { validateResources } from "../validate-resources.ts";
 import { detectDrift, formatDriftReport, type DriftReport } from "../../config/drift-detector.ts";
 import { TeamToolParams } from "../../schema/team-tool-schema.ts";
@@ -237,6 +238,19 @@ export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorR
 }
 
 export function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue = {}): PiTeamsToolResult {
+	// Sub-focus: zombie sub-agent scan. READ-ONLY — never kills. Returns a table of
+	// orphaned pi-crew sub-agents identified by the authoritative PI_CREW_KIND=subagent
+	// marker. The user's main session never carries that marker, so it can never appear.
+	if (params.focus === "zombies") {
+		const scan = scanZombieSubagents();
+		const text = formatZombieReport(scan);
+		return result(text, {
+			action: "doctor",
+			status: "ok",
+			data: { zombies: scan.zombies.length, live: scan.live.length, errors: scan.errors.length },
+		}, false);
+	}
+
 	const loadedConfig = loadConfig(ctx.cwd);
 	let smokeChildPi: { ok: boolean; detail: string } | undefined;
 	if (configRecord(params.config).smokeChildPi === true) {

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

@@ -269,6 +269,7 @@ async function handleStop(input: GoalSubActionInput): Promise<ReturnType<typeof
 	let cancelMsg = "";
 	if (updated.currentRunId) {
 		try {
+		// LAZY: defer dynamic import of ./cancel.ts to its call site.
 			const { handleCancel } = await import("./cancel.ts");
 			const cancelResult = await handleCancel({ action: "cancel", runId: updated.currentRunId, force: true, config: { intent: "user requested goal stop" } }, ctx);
 			cancelMsg = ` In-flight turn ${updated.currentRunId} cancel: ${(cancelResult.content[0] as { text?: string } | undefined)?.text ?? "ok"}.`;

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

@@ -34,6 +34,7 @@ import { expandParallelResearchWorkflow } from "../../runtime/parallel-research.
 /**
  * Module-scoped latch for the crew-init dynamic import.
  *
+		// LAZY: defer dynamic import of module to its call site.
  * `crew-init.ts` is dynamically `await import()`'d from `handleRun` below, which
  * N concurrent subagents hit simultaneously (every `team` tool call runs it).
  * Under the tsx/jiti loader, concurrent first-imports race module-record
@@ -280,6 +281,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		workspaceMode: params.workspaceMode,
 		ownerSessionId: ctx.sessionId,
 		runKind: params.runKind,
+		args: params.args,
 	});
 	const goalArtifact = writeArtifact(paths.artifactsRoot, {
 		kind: "prompt",
@@ -296,6 +298,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	// orchestrates subagents via ctx.agent(); only ctx.setResult() reaches the main context.
 	// Placed AFTER manifest creation so runId/paths/artifactsRoot are available.
 	if (!directAgent && (workflow as import("../../workflows/workflow-config.ts").DynamicWorkflowConfig).runtime === "dynamic") {
+		// LAZY: defer dynamic import of ../../runtime/dynamic-workflow-runner.ts to its call site.
 		const { runDynamicWorkflow } = await import("../../runtime/dynamic-workflow-runner.ts");
 		// Re-synthesize a dynamic-team (§0c C9) for role resolution.
 		const dwfTeam: import("../../teams/team-config.ts").TeamConfig = {
@@ -321,6 +324,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 					team: dwfTeam,
 					signal: ctx.signal ?? AbortSignal.timeout(3_600_000),
 					modelOverride: params.model,
+					tokenBudget: params.tokenBudget ?? (workflow as import("../../workflows/workflow-config.ts").DynamicWorkflowConfig).maxTokenBudget,
 				});
 			} catch (runnerError) {
 				// Round-11 runtime fix: persist manifest with status=failed when runner throws

package/src/runtime/background-runner.ts

@@ -323,11 +323,28 @@ async function main(): Promise<void> {
 			const origWrite =
 				(_prefix: string) =>
 				(data: unknown, ...args: unknown[]) => {
+					// FIX: Never let the in-process console redirect crash the background
+					// runner. If logFd is missing/invalid or the write fails, swallow the
+					// error silently — losing one debug line is far better than killing the
+					// scheduler (a previous version only redirected console.log/error, so
+					// console.debug/.warn still wrote to the original stdout/stderr pipe
+					// which is closed after the parent detaches, producing EPIPE → process
+					// crash mid-workflow → runs hang at 25% forever).
+					if (logFd === undefined) return;
 					const msg = [data, ...args].map(String).join(" ") + "\n";
-					fs.writeSync(logFd!, msg);
+					try {
+						fs.writeSync(logFd, msg);
+					} catch {
+						/* best-effort: never crash the scheduler over a log write */
+					}
 				};
 			console.log = origWrite("OUT");
 			console.error = origWrite("ERR");
+			// FIX: Also redirect console.debug and console.warn — otherwise they still
+			// hit the original stdout/stderr pipe, which is closed once the parent
+			// process detaches, causing EPIPE unhandled errors that kill the scheduler.
+			console.debug = origWrite("DBG");
+			console.warn = origWrite("WARN");
 			// FIX: Close logFd on process exit to prevent file descriptor leak
 			process.on("exit", () => {
 				try {
@@ -558,8 +575,11 @@ async function main(): Promise<void> {
 			debugLog(`[background-runner] short-circuiting ${manifest.runKind} (synthetic team/workflow)`,
 			);
 			if (manifest.runKind === "goal-loop") {
+		// LAZY: defer dynamic import of ./goal-loop-runner.ts to its call site.
 				const { runGoalLoop } = await import("./goal-loop-runner.ts");
+		// LAZY: defer dynamic import of ./goal-state-store.ts to its call site.
 				const { GoalStore } = await import("./goal-state-store.ts");
+		// LAZY: defer dynamic import of ../agents/discover-agents.ts to its call site.
 				const { discoverAgents, allAgents } = await import("../agents/discover-agents.ts");
 				const store = new GoalStore(manifest.cwd);
 				const goalState = store.load(manifest.runId);
@@ -576,11 +596,13 @@ async function main(): Promise<void> {
 				saveRunManifest(finalGoalManifest);
 				earlyResult = { manifest: finalGoalManifest, tasks: goalResult.tasks };
 			} else {
+		// LAZY: defer dynamic import of ./dynamic-workflow-runner.ts to its call site.
 				const { runDynamicWorkflow } = await import("./dynamic-workflow-runner.ts");
+		// LAZY: defer dynamic import of ../workflows/discover-workflows.ts to its call site.
 				const { allWorkflows, discoverWorkflows } = await import("../workflows/discover-workflows.ts");
 				const wf = allWorkflows(discoverWorkflows(manifest.cwd)).find((w) => w.name === manifest.workflow);
 				if (!wf || wf.runtime !== "dynamic" || !wf.dynamicScript) throw new Error(`runKind="dynamic-workflow" but workflow '${manifest.workflow}' is not dynamic (runId=${manifest.runId})`);
-				const dwfResult = await runDynamicWorkflow({ manifest, workflow: wf as import("../workflows/workflow-config.ts").DynamicWorkflowConfig, signal: abortController.signal });
+				const dwfResult = await runDynamicWorkflow({ manifest, workflow: wf as import("../workflows/workflow-config.ts").DynamicWorkflowConfig, signal: abortController.signal, tokenBudget: wf.maxTokenBudget });
 				saveRunManifest(dwfResult.manifest);
 				earlyResult = dwfResult;
 			}

package/src/runtime/chain-runner.ts

@@ -246,6 +246,7 @@ export class ChainRunner {
 
 				// Emit progress event if eventsPath provided
 				if (eventsPath) {
+		// LAZY: defer dynamic import of ../state/event-log.ts to its call site.
 					const { appendEventAsync } = await import("../state/event-log.ts");
 					await appendEventAsync(eventsPath, {
 						type: "chain.step_completed",

package/src/runtime/child-pi.ts

@@ -95,6 +95,17 @@ export function killProcessPid(pid: number): void {
 }
 
 function killProcessTree(pid: number | undefined, child?: ChildProcess): void {
+	// Phase-0 diagnostic (HB-003a): capture who invoked killProcessTree so the
+	// exit-null race has a provenance trail. .stack is best-effort (may be undefined
+	// under deep async), so we take a snapshot lazily.
+	try {
+		const callerStack = new Error("killProcessTree caller").stack ?? "(no stack)";
+		logInternalError(
+			"child-pi.kill-process-tree-invoked",
+			new Error(`pid=${pid} called from:\n${callerStack.split("\n").slice(0, 8).join("\n")}`),
+			`pid=${pid}`,
+		);
+	} catch { /* diagnostic best-effort */ }
 	if (!pid || !Number.isInteger(pid) || pid <= 0) return;
 	if (child && child.exitCode !== null) return;
 	killProcessPid(pid);
@@ -124,6 +135,18 @@ export interface ChildPiLifecycleEvent {
 	stderrExcerpt?: string;
 	/** Timestamp (ISO). */
 	ts: string;
+	/** Phase-0 diagnostic (HB-003a): the signal that killed the child (when
+	 *  available). Was previously discarded after building the error string. */
+	signal?: string;
+	/** Phase-0 diagnostic (HB-003a): final-drain race timing, present only on
+	 *  exit events where a drain timer was armed. Surfaces the exit-null race. */
+	diagnostic?: {
+		finalDrainArmed: boolean;
+		forcedFinalDrain: boolean;
+		finalDrainFiredMonotonicMs?: number;
+		finalAssistantEventMonotonicMs?: number;
+		exitMonotonicMs: number;
+	};
 }
 
 export interface ChildPiRunInput {
@@ -267,6 +290,9 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 			"PI_CREW_MAX_DEPTH",
 			"PI_CREW_INHERIT_PROJECT_CONTEXT",
 			"PI_CREW_INHERIT_SKILLS",
+			// PI_CREW_KIND marks this process as a crew sub-agent (vs the user's main session).
+			// doctor --zombies matches it to safely list orphaned sub-agents only.
+			"PI_CREW_KIND",
 			// PI_CREW_PARENT_PID is needed by child-pi's parent-guard (uses
 			// process.kill(pid, 0) liveness check). The PID is not a secret.
 			"PI_CREW_PARENT_PID",
@@ -577,6 +603,15 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			let noResponseTimer: NodeJS.Timeout | undefined;
 			const finalDrainMs = input.finalDrainMs ?? FINAL_DRAIN_MS;
 			const hardKillMs = input.hardKillMs ?? HARD_KILL_MS;
+			// Phase-0 diagnostic (HB-003a): track the final-drain race that produces
+			// `exit null` for ctx.agent({disableTools:true}). These vars are READ-ONLY
+			// instrumentation — no behavior change. finalDrainArmed lets the close
+			// handler know a drain timer existed even after clearFinalDrainTimers() ran;
+			// spawnMonotonicMs gives us relative timing to distinguish a race from a crash.
+			let finalDrainArmed = false;
+			let finalDrainFiredMonotonicMs: number | undefined;
+			const spawnMonotonicMs = performance.now();
+			let finalAssistantEventMonotonicMs: number | undefined;
 			// FIX (Round 14): Bound the env-controlled response timeout to
 			// [1_000ms, 3_600_000ms] (1s–1h) so a hostile or accidental value
 			// (e.g. 1, or 999_999_999) cannot disable the timeout or cause
@@ -680,20 +715,27 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 								if (maxTurns !== undefined && !softLimitReached && turnCount >= maxTurns) {
 									softLimitReached = true;
 									// Inject steer via stdin to tell child to wrap up.
-									// If stdin is not writable or the write fails (backpressure/closed),
-									// the steer cannot be injected and the agent could run indefinitely.
-									// Kill the process tree in that case to enforce the turn limit.
+									// Steer injection is ADVISORY: it asks the worker to wrap up. The real
+									// enforcement is the hard-abort at maxTurns + graceTurns (below). So a
+									// failed/non-writable stdin must NOT kill the worker — that destroys a
+									// valid answer already in stdout (Phase-0 root cause of the
+									// disableTools/maxTurns:1 exit-null bug). Just log + let the hard-abort
+									// path handle a genuinely runaway worker.
 									if (child.stdin?.writable) {
 										const steerPayload = JSON.stringify({ type: "steer", message: "You have reached your turn limit. Wrap up immediately — provide your final answer now." }) + "\n";
 										const writeSucceeded = child.stdin.write(steerPayload);
 										if (!writeSucceeded) {
-											logInternalError("child-pi.steer-backpressure", new Error("stdin write returned false during steer injection; buffer full"), `pid=${child.pid}`);
-											steerInjectionFailed = true;
-											killProcessTree(child.pid, child);
+											// Normal Node backpressure: the payload is buffered and will flush on
+											// 'drain'. NOT a failure — do NOT kill the worker. The steer is
+											// advisory; if the worker ignores it and runs past maxTurns +
+											// graceTurns, the hard-abort below terminates it.
+											logInternalError("child-pi.steer-backpressure", new Error("stdin write returned false (normal backpressure); steer buffered, worker NOT killed"), `pid=${child.pid}`);
 										}
 									} else {
-										logInternalError("child-pi.steer-not-writable", new Error("stdin not writable when attempting steer injection"), `pid=${child.pid}`);
-										killProcessTree(child.pid, child);
+										// stdin closed (worker already finished) or otherwise unwritable.
+										// Also advisory — the worker is done or nearly done; let it exit
+										// naturally. Hard-abort remains the safety net for true runaways.
+										logInternalError("child-pi.steer-not-writable", new Error("stdin not writable when attempting steer injection (worker may be done); worker NOT killed"), `pid=${child.pid}`);
 									}
 								} else if (maxTurns !== undefined && softLimitReached && turnCount >= maxTurns + (graceTurns ?? 5)) {
 									// Hard abort — terminate after grace turns
@@ -708,9 +750,12 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					}
 					input.onJsonEvent?.(event);
 					if (!isFinalAssistantEvent(event) || childExited || settled || finalDrainTimer) return;
+					finalAssistantEventMonotonicMs = performance.now();
+					finalDrainArmed = true; // Phase-0 diagnostic: track that a drain timer was created.
 					finalDrainTimer = setTimeout(() => {
 						if (settled || childExited) return;
 						forcedFinalDrain = true;
+						finalDrainFiredMonotonicMs = performance.now(); // Phase-0 diagnostic: race timing.
 						input.onLifecycleEvent?.({ type: "final_drain", pid: child.pid, ts: new Date().toISOString() });
 						try {
 							child.kill(process.platform === "win32" ? undefined : "SIGTERM");
@@ -765,7 +810,27 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				}
 				// Catch all errors from settle to prevent unhandled rejection from propagating
 				try {
-					resolve({ ...result, exitStatus: result.exitStatus ?? { exitCode: result.exitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
+					resolve({
+						...result,
+						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 })}`);
 				}
@@ -866,7 +931,30 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					rejectPendingOperations(exitError);
 				}
 				try {
-					input.onLifecycleEvent?.({ type: "exit", pid: child.pid, exitCode: code, ts: new Date().toISOString(), error: exitError?.message, stderrExcerpt: isUnexpectedExit ? stderr.slice(-1000) || undefined : undefined });
+					// Phase-0 diagnostic (HB-003a): capture signal + drain timing in the
+					// exit lifecycle event so the exit-null race is diagnosable instead of
+					// opaque. `signal` was previously discarded after building the error msg.
+					input.onLifecycleEvent?.({
+						type: "exit",
+						pid: child.pid,
+						exitCode: code,
+						ts: new Date().toISOString(),
+						error: exitError?.message,
+						stderrExcerpt: isUnexpectedExit ? stderr.slice(-1000) || undefined : undefined,
+						// Phase-0 diagnostic fields (kept optional — no type change required).
+						...(signal ? { signal } : {}),
+						...(finalDrainArmed || forcedFinalDrain
+							? {
+									diagnostic: {
+										finalDrainArmed,
+										forcedFinalDrain,
+										finalDrainFiredMonotonicMs,
+										finalAssistantEventMonotonicMs,
+										exitMonotonicMs: performance.now() - spawnMonotonicMs,
+									},
+							  }
+							: {}),
+					});
 				} catch (err) {
 					logInternalError("child-pi.on-lifecycle-event", err, `event=exit, pid=${child.pid}`);
 				}
@@ -902,6 +990,9 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			const finalExitCode = forcedFinalDrain && !timeoutError ? 0 : exitCode;
 				const wasGraceAborted = softLimitReached && turnCount >= (maxTurns ?? 0) + (graceTurns ?? 5);
 				const wasParentAborted = abortDueToParentSignal && !wasGraceAborted;
+				// steerInjectionFailed is now always false (Phase-1 fix: steer backpressure
+				// is logged, not fatal). The steerError branch is retained for safety in
+				// case a future change reintroduces a fatal steer path.
 				const steerError = steerInjectionFailed ? "Steer injection failed due to stdin backpressure; process killed" : undefined;
 				settle({ exitCode: finalExitCode, stdout, stderr, ...(timeoutError ? { error: timeoutError.error } : {}), ...(steerError ? { error: steerError } : {}), aborted: wasGraceAborted || wasParentAborted, steered: softLimitReached && !wasGraceAborted, exitStatus: { exitCode: finalExitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
 			});