pi-crew 0.9.4 → 0.9.7

package/src/runtime/goal-loop-runner.ts

@@ -121,6 +121,7 @@ export const realGoalEvaluator = async (
 		}
 		if (!verificationCompromised) {
 			try {
+		// LAZY: defer dynamic import of ./verification-gates.ts to its call site.
 				const { executeVerificationCommands } = await import("./verification-gates.ts");
 				const contract = { requiredGreenLevel: "none" as const, commands: goal.verification.commands, allowManualEvidence: goal.verification.allowManualEvidence ?? false };
 				// Phase 1.5 #2 (RFC 16): run verification in a pristine git worktree at
@@ -131,6 +132,7 @@ export const realGoalEvaluator = async (
 				let worktreeCwd: string | undefined;
 				let worktreeCleanup: (() => void) | undefined;
 				try {
+		// LAZY: defer dynamic import of ./verification-worktree.ts to its call site.
 					const { checkWorktreeSandboxAvailable, prepareVerificationWorktree } = await import("./verification-worktree.ts");
 					const availability = checkWorktreeSandboxAvailable(goal.cwd);
 					if (availability.available) {

package/src/runtime/live-session-runtime.ts

@@ -36,6 +36,7 @@ import { listLiveAgents } from "./live-agent-manager.ts";
  * Module-scoped latch for the optional peer dependency import. When N
  * in-process live-session subagents spawn CONCURRENTLY (e.g. several
  * `Agent({run_in_background:true})` started at once), each used to call
+		// LAZY: defer dynamic import of @earendil-works/pi-coding-agent to its call site.
  * `await import("@earendil-works/pi-coding-agent")` independently. Under the
  * tsx loader (registering load/resolve hooks), concurrent first-imports can
  * each enter the loader and race module-record instantiation, yielding

package/src/runtime/model-scope.ts

@@ -128,6 +128,7 @@ export async function readEnabledModelsPatterns(cwd: string, agentDir?: string):
 		// SDK. SettingsManager is dynamically imported because the module
 		// shape differs across pi versions; the create() factory is the
 		// canonical, version-stable entry point.
+		// LAZY: defer dynamic import of @earendil-works/pi-coding-agent to its call site.
 		const mod = await import("@earendil-works/pi-coding-agent" as string).catch(() => null);
 		if (!mod) return [];
 		const SettingsManagerCtor = (mod as { SettingsManager?: { create?: (cwd: string, agentDir?: string) => { getEnabledModels?: () => string[] | undefined } } }).SettingsManager;

package/src/runtime/peer-dep.ts

@@ -239,6 +239,7 @@ export function primePeerDep(): Promise<PeerDepModule> {
 		if (!resolved) {
 			throw new Error(buildMissingMessage());
 		}
+		// LAZY: defer dynamic import of module to its call site.
 		cachedModule = (await import(resolved.mainUrl)) as PeerDepModule;
 		return cachedModule;
 	})();

package/src/runtime/pi-args.ts

@@ -243,6 +243,12 @@ export function createSafeTempDir(base: string, prefix: string): string {
 }
 
 export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerArgsResult {
+	// NOTE: do NOT add an argv flag like `--crew-subagent` here. Pi uses a strict
+	// option parser and REJECTS unknown flags with a non-zero exit, which would
+	// break every ctx.agent() call. The authoritative sub-agent identity signal
+	// is the PI_CREW_KIND=subagent ENV var (set below) — the zombie scanner and
+	// doctor --zombies read it from /proc/<pid>/environ. The user's main session
+	// never sets it, so it can never be matched as a sub-agent.
 	const args = ["--mode", "json", "-p"];
 	if (input.sessionEnabled === false) args.push("--no-session");
 
@@ -327,6 +333,11 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	return {
 		args,
 		env: {
+			// PI_CREW_KIND is the authoritative machine-readable sub-agent marker. It is always
+		// present on a child-pi process and NEVER present on a user's interactive main session.
+			// doctor --zombies uses it to safely list orphaned sub-agents without ever matching a
+		// main session (the lesson from an accidental `kill` of a live main session).
+			PI_CREW_KIND: "subagent",
 			PI_CREW_INHERIT_PROJECT_CONTEXT: input.agent.inheritProjectContext ? "1" : "0",
 			PI_CREW_INHERIT_SKILLS: input.agent.inheritSkills ? "1" : "0",
 			PI_CREW_DEPTH: String(parentDepth + 1),

package/src/runtime/resilient-edit.ts

@@ -133,6 +133,7 @@ export function wrapEditWithResilientReplace(pi: ExtensionAPI, tools?: { edit: T
 			throw new Error("old_string not found (and resilient retry skipped: missing path/old/new)");
 		}
 
+		// LAZY: defer dynamic import of node:fs/promises to its call site.
 		const fs = await import("node:fs/promises");
 		let content: string;
 		try {

package/src/runtime/result-extractor.ts

@@ -1,11 +1,19 @@
 /**
  * Structured Result Extractor — attempts to extract structured data from worker output.
  * Tries multiple extraction strategies before falling back to raw text.
+ *
+ * Round-13 P0-3: optional `schema` (TypeBox `TSchema`) — when provided, extracted
+ * data is validated against the schema via `Value.Check`. On mismatch, the result
+ * is `structured:false` with an explanatory `error`. Backward compatible: when
+ * schema is undefined, behavior is identical to the previous regex-based extractor.
  */
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
 export interface ExtractedResult {
 	/** Whether structured data was successfully extracted */
 	structured: boolean;
-	/** Parsed structured data (if structured=true) */
+	/** Parsed structured data (if structured=true AND validated against schema if provided) */
 	data: unknown;
 	/** Raw text output (always available) */
 	rawText: string;
@@ -15,9 +23,13 @@ export interface ExtractedResult {
 
 /**
  * Extract structured result from raw worker output text.
- * Tries strategies in order: direct JSON, fenced JSON, key-value markers.
+ * Tries strategies in order: direct JSON, fenced JSON, key-value markers, scan.
+ *
+ * @param raw - the raw text output from a worker
+ * @param schema - optional TypeBox schema. When provided, the extracted value is
+ *                 validated; mismatch produces `{structured:false, error:...}`.
  */
-export function extractStructuredResult(raw: string, _schema?: Record<string, unknown>): ExtractedResult {
+export function extractStructuredResult(raw: string, schema?: TSchema): ExtractedResult {
 	const trimmed = raw.trim();
 	if (!trimmed) {
 		return { structured: false, data: null, rawText: raw };
@@ -26,19 +38,19 @@ export function extractStructuredResult(raw: string, _schema?: Record<string, un
 	// Strategy 1: Direct JSON parse (entire output is JSON)
 	const directResult = tryDirectJson(trimmed);
 	if (directResult !== undefined) {
-		return { structured: true, data: directResult, rawText: raw };
+		return finalize(directResult, raw, schema);
 	}
 
 	// Strategy 2: Extract from ```json ... ``` fence
 	const fencedResult = tryFencedJson(trimmed);
 	if (fencedResult !== undefined) {
-		return { structured: true, data: fencedResult, rawText: raw };
+		return finalize(fencedResult, raw, schema);
 	}
 
 	// Strategy 3: Extract from markers like "RESULT:" or "OUTPUT:"
 	const markerResult = tryMarkerExtraction(trimmed);
 	if (markerResult !== undefined) {
-		return { structured: true, data: markerResult, rawText: raw };
+		return finalize(markerResult, raw, schema);
 	}
 
 	// Strategy 4: Scan for the first JSON object/array anywhere in text.
@@ -46,12 +58,65 @@ export function extractStructuredResult(raw: string, _schema?: Record<string, un
 	// around the JSON. This catches JSON embedded in sentences, lists, or prose.
 	const scannedResult = tryScanJson(trimmed);
 	if (scannedResult !== undefined) {
-		return { structured: true, data: scannedResult, rawText: raw };
+		return finalize(scannedResult, raw, schema);
 	}
 
 	return { structured: false, data: null, rawText: raw };
 }
 
+/**
+ * After extracting a candidate object, validate it against the optional TypeBox schema.
+ * When no schema is given, behavior is the legacy "structured:true" path.
+ * When a schema is given and validation fails, return structured:false with a
+ * clear error message (caller can surface this in the AgentResult).
+ *
+ * NOTE: TypeBox 0.34.49's `Value.Check` returns a boolean and does not expose
+ * per-error paths in its public API. We use the boolean + a fallback "type mismatch"
+ * description. Scripts that need detailed diagnostics can wrap their own validator.
+ */
+function finalize(candidate: unknown, raw: string, schema: TSchema | undefined): ExtractedResult {
+	if (!schema) {
+		return { structured: true, data: candidate, rawText: raw };
+	}
+	const ok = Value.Check(schema, candidate);
+	if (ok) {
+		return { structured: true, data: candidate, rawText: raw };
+	}
+	return {
+		structured: false,
+		data: null,
+		rawText: raw,
+		error: `structured output does not match schema: expected shape ${describeSchemaShape(schema)}, got ${describeValue(candidate)}`,
+	};
+}
+
+function describeValue(value: unknown): string {
+	try {
+		const json = JSON.stringify(value);
+		return json.length > 200 ? `${json.slice(0, 200)}…` : json;
+	} catch {
+		return typeof value;
+	}
+}
+
+function describeSchemaShape(schema: unknown): string {
+	if (!schema || typeof schema !== "object") return "any";
+	const obj = schema as Record<string, unknown>;
+	const kind = obj.kind as string | undefined;
+	const type = obj.type as string | undefined;
+	if (kind === "object" || type === "object") {
+		const properties = obj.properties;
+		if (!properties || typeof properties !== "object") return "object";
+		return `object<${Object.keys(properties as Record<string, unknown>).join(",")}>`;
+	}
+	if (kind === "array" || type === "array") return "array";
+	if (type === "string") return "string";
+	if (type === "number" || type === "integer") return "number";
+	if (type === "boolean") return "boolean";
+	if (Array.isArray(obj.anyOf) || Array.isArray(obj.oneOf)) return "union";
+	return "any";
+}
+
 function tryDirectJson(text: string): unknown | undefined {
 	if (!text.startsWith("{") && !text.startsWith("[")) return undefined;
 	try {

package/src/runtime/task-runner.ts

@@ -289,6 +289,7 @@ export async function runTeamTask(
 			// follow it and execute a script outside cwd. Throws on escape.
 			resolveRealContainedPath(manifest.cwd, input.step.preStepScript);
 			try {
+		// LAZY: defer dynamic import of node:child_process to its call site.
 				const { execFileSync } = await import("node:child_process");
 				preStepOutput = execFileSync(input.step.preStepScript, scriptArgs, {
 					timeout: scriptTimeout,

package/src/runtime/team-runner.ts

@@ -63,16 +63,21 @@ builtInRegistry.register(VitePlugin);
  * executing. The team-runner has no periodic heartbeat today, so any
  * team run lasting >5min is at risk.
  */
-function startTeamRunHeartbeat(stateRoot: string, runId: string, lastTaskUpdateAt?: string): () => void {
+function startTeamRunHeartbeat(stateRoot: string, runId: string): () => void {
 	const heartbeatPath = path.join(stateRoot, "heartbeat.json");
 	const writeHeartbeat = (): void => {
 		try {
+			// lastTaskUpdateAt is written fresh on each tick so the heartbeat
+			// never carries a stale creation-time timestamp. Previously this
+			// captured manifest.updatedAt once at startup, making the value
+			// permanently stale throughout the run.
+			const now = new Date().toISOString();
 			fs.writeFileSync(heartbeatPath, JSON.stringify({
 				pid: process.pid,
 				at: Date.now(),
 				runId,
 				kind: "team-runner",
-				lastTaskUpdateAt,
+				lastTaskUpdateAt: now,
 			}), { encoding: "utf-8", mode: 0o600 });
 		} catch {
 			// best-effort
@@ -439,7 +444,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 	// (NO_PID_HEARTBEAT_STALE_MS). Previously only sub-task runners wrote
 	// heartbeats; the team-level run had no heartbeat, so any multi-phase
 	// workflow lasting >5min was marked stale and cancelled.
-	const stopTeamHeartbeat = startTeamRunHeartbeat(manifest.stateRoot, manifest.runId, manifest.updatedAt);
+	const stopTeamHeartbeat = startTeamRunHeartbeat(manifest.stateRoot, manifest.runId);
 
 	const cleanupUsage = (): void => {
 		for (const task of input.tasks) clearTrackedTaskUsage(task.id);

package/src/runtime/zombie-scanner.ts

@@ -0,0 +1,297 @@
+/**
+ * zombie-scanner.ts — safely detect orphaned pi-crew sub-agent processes.
+ *
+ * LESSON (learned the hard way): a heuristic like "old `pi` process + high RSS +
+ * orphaned (ppid=1/bash)" will match a user's interactive MAIN session just as
+ * readily as a real zombie. The result is a live main session being killed by
+ * accident. This module replaces that heuristic with an authoritative signal.
+ *
+ * Authoritative marker (set by buildPiWorkerArgs on every child-pi spawn):
+ *   - argv:   `--crew-subagent` is the first positional arg
+ *   - env:    `PI_CREW_KIND=subagent` is the machine-readable signal
+ *
+ * A process is a "pi-crew sub-agent" ONLY IF it carries `PI_CREW_KIND=subagent`
+ * in its environment. The user's main `pi` session NEVER has this var, so it can
+ * never be matched here — by construction.
+ *
+ * A sub-agent is a "zombie" ONLY IF its `PI_CREW_PARENT_PID` points at a PID that
+ * is no longer alive (parent crashed/exited without reaping the child). A sub-agent
+ * whose parent is still running is NOT a zombie — it's a legitimate in-flight task.
+ *
+ * This module is READ-ONLY. It never kills anything. The caller (doctor --zombies)
+ * prints the list and asks for explicit confirmation before any kill.
+ */
+
+import * as fs from "node:fs";
+
+export interface ZombieSubagent {
+	pid: number;
+	ppid: number;
+	/** PID recorded in PI_CREW_PARENT_PID (may differ from ppid if re-parented to init/bash). */
+	crewParentPid: number;
+	/** Whether the recorded crew parent PID is still alive. */
+	parentAlive: boolean;
+	role: string | undefined;
+	rssKb: number;
+	elapsedSec: number | undefined;
+	cmd: string;
+}
+
+export interface ZombieScanResult {
+	zombies: ZombieSubagent[];
+	/** Sub-agents whose parent is still alive — shown for transparency, never killed. */
+	live: ZombieSubagent[];
+	/** Errors encountered while scanning (per-pid). Never aborts the whole scan. */
+	errors: string[];
+}
+
+/** Read /proc/<pid>/environ as a key=value record. Returns {} if unreadable. */
+function readProcEnviron(pid: number): Record<string, string> {
+	try {
+		// /proc/<pid>/environ is NUL-separated key=value pairs.
+		const raw = fs.readFileSync(`/proc/${pid}/environ`, "utf-8");
+		const out: Record<string, string> = {};
+		for (const entry of raw.split("\0")) {
+			const eq = entry.indexOf("=");
+			if (eq > 0) out[entry.slice(0, eq)] = entry.slice(eq + 1);
+		}
+		return out;
+	} catch {
+		return {};
+	}
+}
+
+/** Read /proc/<pid>/stat to get ppid + elapsed. Returns undefined if unreadable. */
+function readProcStat(pid: number): { ppid: number; elapsedSec: number | undefined } | undefined {
+	try {
+		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+		// stat format: pid (comm) state ppid ... starttime ...
+		// comm may contain spaces/parens, so parse from the LAST ')' backwards.
+		const closeParen = stat.lastIndexOf(")");
+		if (closeParen < 0) return undefined;
+		const rest = stat.slice(closeParen + 2).trim().split(/\s+/);
+		// rest[0] = state, rest[1] = ppid
+		const ppid = Number.parseInt(rest[1] ?? "", 10);
+		// starttime (clock ticks since boot) is field 22 in the full stat → index 19 in `rest`
+		const starttimeTicksRaw = Number.parseInt(rest[19] ?? "", 10);
+		const starttimeTicks = Number.isFinite(starttimeTicksRaw) ? starttimeTicksRaw : undefined;
+		const elapsedSec = computeElapsedSec(starttimeTicks);
+		return { ppid: Number.isFinite(ppid) ? ppid : 0, elapsedSec };
+	} catch {
+		return undefined;
+	}
+}
+
+function computeElapsedSec(starttimeTicks: number | undefined): number | undefined {
+	if (starttimeTicks === undefined || !Number.isFinite(starttimeTicks)) return undefined;
+	try {
+		// Linux CLK_TCK is virtually always 100 (sysconf(_SC_CLK_TCK)). Reading it
+		// portably from Node requires a native addon; hardcoding 100 matches every
+		// mainstream Linux distro and keeps this dependency-free.
+		const ticksPerSec = 100;
+		// /proc/uptime: first field is seconds since boot.
+		const uptimeRaw = fs.readFileSync("/proc/uptime", "utf-8");
+		const uptimeSec = Number.parseFloat(uptimeRaw.split(" ")[0] ?? "");
+		if (!Number.isFinite(uptimeSec)) return undefined;
+		// starttime (ticks since boot) → process age in seconds = uptime - starttime/ticksPerSec.
+		const startAgeSec = starttimeTicks / ticksPerSec;
+		return Math.max(0, uptimeSec - startAgeSec);
+	} catch {
+		return undefined;
+	}
+}
+
+function isPidAlive(pid: number): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		// process.kill(pid, 0) throws if the pid is not alive (or not ours).
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function readProcCmdline(pid: number): string {
+	try {
+		// /proc/<pid>/cmdline is NUL-separated argv.
+		const raw = fs.readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+		return raw.split("\0").filter(Boolean).join(" ").trim() || `pid ${pid}`;
+	} catch {
+		return `pid ${pid}`;
+	}
+}
+
+function readProcRssKb(pid: number): number {
+	try {
+		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const match = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
+		return match ? Number.parseInt(match[1] ?? "", 10) : 0;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Enumerate candidate pi-crew sub-agent PIDs under the current uid.
+ *
+ * Reads /proc directly (Linux only) — no shelling out to pgrep/ps, so the
+ * result is deterministic and unaffected by shell quoting or locale. On
+ * non-Linux platforms the scanner returns an empty result with a note in
+ * `errors` (zombie detection is best-effort; the doctor report still renders).
+ */
+function listCandidatePids(): number[] {
+	if (process.platform !== "linux") return [];
+	const pids: number[] = [];
+	try {
+		for (const entry of fs.readdirSync("/proc")) {
+			if (/^\d+$/.test(entry)) pids.push(Number.parseInt(entry, 10));
+		}
+	} catch {
+		// /proc unreadable (e.g. sandboxed). Caller surfaces via errors[].
+	}
+	return pids;
+}
+
+/**
+ * Scan for orphaned pi-crew sub-agent processes. READ-ONLY — never kills.
+ *
+ * Returns the full picture: zombies (parent dead), live (parent alive), and
+ * any scan errors. Callers decide what to do with the result; this module
+ * has no side effects.
+ */
+export function scanZombieSubagents(): ZombieScanResult {
+	const result: ZombieScanResult = { zombies: [], live: [], errors: [] };
+	if (process.platform !== "linux") {
+		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + process.platform);
+		return result;
+	}
+
+	const myUid = tryGetUid();
+	for (const pid of listCandidatePids()) {
+		try {
+			// Cheap rejection first: only inspect processes we own (avoid scanning system procs).
+			if (myUid !== undefined && getProcUid(pid) !== myUid) continue;
+
+			const environ = readProcEnviron(pid);
+			// AUTHORITATIVE GATE: a process is a pi-crew sub-agent ONLY if it carries
+			// PI_CREW_KIND=subagent. The user's main session never sets this, so it can
+			// never be matched — this is the fix for accidentally killing main sessions.
+			if (environ.PI_CREW_KIND !== "subagent") continue;
+
+			const crewParentPid = Number.parseInt(environ.PI_CREW_PARENT_PID ?? "", 10);
+			const stat = readProcStat(pid);
+			const entry: ZombieSubagent = {
+				pid,
+				ppid: stat?.ppid ?? 0,
+				crewParentPid: Number.isFinite(crewParentPid) ? crewParentPid : 0,
+				parentAlive: Number.isFinite(crewParentPid) && isPidAlive(crewParentPid),
+				role: environ.PI_CREW_ROLE,
+				rssKb: readProcRssKb(pid),
+				elapsedSec: stat?.elapsedSec,
+				cmd: readProcCmdline(pid),
+			};
+
+			if (entry.parentAlive) {
+				result.live.push(entry);
+			} else {
+				result.zombies.push(entry);
+			}
+		} catch (error) {
+			// Race: process may have exited between readdir and read. Don't abort the scan.
+			result.errors.push(`pid ${pid}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	// Sort: zombies first by descending RSS (biggest leaks first), live by pid.
+	result.zombies.sort((a, b) => b.rssKb - a.rssKb);
+	result.live.sort((a, b) => a.pid - b.pid);
+	return result;
+}
+
+function tryGetUid(): number | undefined {
+	try {
+		return process.getuid?.();
+	} catch {
+		return undefined;
+	}
+}
+
+function getProcUid(pid: number): number | undefined {
+	try {
+		// /proc/<pid>/status has Uid: <real> <eff> <sav> <fs>
+		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const match = status.match(/^Uid:\s+(\d+)/m);
+		return match ? Number.parseInt(match[1] ?? "", 10) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Render a ZombieScanResult as human-readable text for the doctor report.
+ * Explicitly labels main-session safety and never suggests killing live parents.
+ */
+export function formatZombieReport(scan: ZombieScanResult): string {
+	const lines: string[] = [];
+	lines.push("## Zombie sub-agent scan (read-only — nothing killed)");
+	lines.push("");
+	lines.push(
+		`Sub-agents identified by PI_CREW_KIND=subagent marker. Main sessions (no marker) are never listed.`,
+	);
+	lines.push("");
+
+	if (scan.zombies.length === 0 && scan.live.length === 0) {
+		lines.push("No pi-crew sub-agent processes found.");
+		if (scan.errors.length > 0) {
+			lines.push("");
+			lines.push(`Scan notes (${scan.errors.length}):`);
+			for (const err of scan.errors.slice(0, 5)) lines.push(`  - ${err}`);
+		}
+		return lines.join("\n");
+	}
+
+	if (scan.zombies.length > 0) {
+		lines.push(`### Zombies — parent dead (${scan.zombies.length})`);
+		lines.push("These sub-agents are orphaned. Safe to kill after review:");
+		lines.push("");
+		lines.push("  PID       PARENT  RSS       ROLE          CMD");
+		for (const z of scan.zombies) {
+			lines.push(
+				`  ${String(z.pid).padEnd(9)}${String(z.crewParentPid).padEnd(8)}${formatRss(z.rssKb).padEnd(10)}${(z.role ?? "?").padEnd(14)}${z.cmd.slice(0, 60)}`,
+			);
+		}
+		lines.push("");
+	}
+
+	if (scan.live.length > 0) {
+		lines.push(`### Live — parent still running (${scan.live.length})`);
+		lines.push("NOT zombies. Do not kill (parent PID is alive and may still reap them).");
+		lines.push("");
+		lines.push("  PID       PARENT  RSS       ROLE          CMD");
+		for (const l of scan.live) {
+			lines.push(
+				`  ${String(l.pid).padEnd(9)}${String(l.crewParentPid).padEnd(8)}${formatRss(l.rssKb).padEnd(10)}${(l.role ?? "?").padEnd(14)}${l.cmd.slice(0, 60)}`,
+			);
+		}
+		lines.push("");
+	}
+
+	if (scan.errors.length > 0) {
+		lines.push(`Scan errors (${scan.errors.length}, first 5 shown):`);
+		for (const err of scan.errors.slice(0, 5)) lines.push(`  - ${err}`);
+		lines.push("");
+	}
+
+	lines.push("To kill a zombie: `kill <PID>` (the OS will reap it). This tool never kills.");
+	return lines.join("\n");
+}
+
+function formatRss(kb: number): string {
+	if (kb >= 1024 * 1024) return `${(kb / 1024 / 1024).toFixed(1)}G`;
+	if (kb >= 1024) return `${(kb / 1024).toFixed(0)}M`;
+	return `${kb}K`;
+}
+
+// Re-export for tests + callers that want to inspect proc helpers in isolation.
+export const __test = { readProcEnviron, isPidAlive, computeElapsedSec };

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

@@ -289,6 +289,26 @@ export const TeamToolParams = Type.Object({
 			},
 		),
 	),
+	tokenBudget: Type.Optional(
+		Type.Number({
+			description:
+				"Per-workflow token budget for dynamic-workflow runs. When set, ctx.agent() auto-rejects with ok:false once exhausted. Accumulated from each agent run's reported usage. Overrides workflow.maxTokenBudget.",
+			minimum: 0,
+		}),
+	),
+	args: Type.Optional(
+		// round-14 P1-5: typed workflow arguments. Type.Any() generates an empty {} schema
+		// (matches any JSON value) which is strict-provider friendly — no array type union.
+		// Description lives in the JSDoc / TeamToolParamsValue below to avoid the
+		// "description-only schema" strict-provider check.
+		Type.Any(),
+	),
+	focus: Type.Optional(
+		Type.String({
+			description:
+				"Sub-focus for the doctor action. 'zombies' runs a READ-ONLY scan for orphaned pi-crew sub-agent processes (identified by PI_CREW_KIND=subagent); it never kills and never matches the user's interactive main session.",
+		}),
+	),
 });
 
 export interface TeamToolParamsValue {
@@ -365,6 +385,10 @@ export interface TeamToolParamsValue {
 	skill?: string | string[] | boolean;
 	scope?: "user" | "project" | "both";
 	config?: Record<string, unknown>;
+	/** Sub-focus for the `doctor` action. `"zombies"` runs a READ-ONLY scan for
+	 *  orphaned pi-crew sub-agent processes (identified by PI_CREW_KIND=subagent);
+	 *  it never kills and never matches the user's interactive main session. */
+	focus?: string;
 	dryRun?: boolean;
 	confirm?: boolean;
 	force?: boolean;
@@ -393,4 +417,8 @@ export interface TeamToolParamsValue {
 	budgetAbort?: number;
 	/** Background dispatch discriminator. Default "team-run". "goal-loop"/"dynamic-workflow" dispatch to their runners (P0/P2). */
 	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
+	/** Per-workflow token budget for dynamic-workflow runs (round-14 P1-2). */
+	tokenBudget?: number;
+	/** Typed workflow arguments for .dwf.ts scripts, accessible via ctx.args<T>() (round-14 P1-5). */
+	args?: unknown;
 }

package/src/state/contracts.ts

@@ -91,6 +91,7 @@ const TEAM_EVENT_TYPES = [
 	"dwf.phase_completed",
 	"dwf.completed",
 	"dwf.failed",
+	"dwf.log",
 ] as const;
 export type TeamEventType = typeof TEAM_EVENT_TYPES[number];
 

package/src/state/hook-instinct-bridge.ts

@@ -11,7 +11,9 @@ let pathsInstance: typeof import("../utils/paths.js") | null = null;
 
 async function getStore() {
 	if (!storeInstance) {
+		// LAZY: defer dynamic import of ./instinct-store.js to its call site.
 		const { InstinctStore } = await import("./instinct-store.js");
+		// LAZY: defer dynamic import of ../utils/paths.js to its call site.
 		const paths = await import("../utils/paths.js");
 		storeInstance = new InstinctStore(paths.projectCrewRoot(process.cwd()));
 	}
@@ -20,6 +22,7 @@ async function getStore() {
 
 async function getPaths() {
 	if (!pathsInstance) {
+		// LAZY: defer dynamic import of ../utils/paths.js to its call site.
 		pathsInstance = await import("../utils/paths.js");
 	}
 	return pathsInstance;

package/src/state/state-store.ts

@@ -228,6 +228,8 @@ export function createRunManifest(params: {
 	workspaceMode?: "single" | "worktree";
 	ownerSessionId?: string;
 	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
+	/** round-14 P1-5: typed workflow arguments for .dwf.ts scripts (ctx.args<T>()). */
+	args?: unknown;
 }): { manifest: TeamRunManifest; tasks: TeamTaskState[]; paths: RunPaths } {
 	const paths = createRunPaths(params.cwd);
 	const now = new Date().toISOString();
@@ -251,6 +253,7 @@ export function createRunManifest(params: {
 		artifacts: [],
 		...(params.ownerSessionId ? { ownerSessionId: params.ownerSessionId } : {}),
 		runKind: params.runKind ?? "team-run",
+		...(params.args !== undefined ? { args: params.args } : {}),
 	};
 	fs.mkdirSync(paths.stateRoot, { recursive: true });
 	fs.mkdirSync(paths.artifactsRoot, { recursive: true });

package/src/state/types.ts

@@ -116,6 +116,13 @@ export interface WorkerExitStatus {
 	signal?: string;
 	cleanupErrors: string[];
 	finalDrainMs: number;
+	/** Phase-0 diagnostic (HB-003a): final-drain race state for the exit-null
+	 *  disableTools bug. Optional + read-only — absent when no drain timer was
+	 *  ever armed. Phase 1 will use `finalDrainArmed` to decide whether a
+	 *  signal-death (exitCode=null) should be treated as a forced final drain. */
+	finalDrainArmed?: boolean;
+	forcedFinalDrain?: boolean;
+	finalDrainFiredMonotonicMs?: number;
 }
 
 export interface OperationTerminalEvidence {
@@ -185,6 +192,8 @@ export interface TeamRunManifest {
 	runConfig?: unknown;
 	/** Background dispatch discriminator. Default "team-run" runs executeTeamRun; "goal-loop" / "dynamic-workflow" dispatch to their respective runners. Absent = "team-run" for backward compatibility. */
 	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
+	/** round-14 P1-5: typed workflow arguments accessible in .dwf.ts scripts via ctx.args<T>(). Any JSON value; default {} when unset. */
+	args?: unknown;
 	summary?: string;
 	policyDecisions?: PolicyDecision[];
 }