@selesai/code 0.13.2 → 0.13.4

package/dist/extensions/pi-subagents/src/watchdog/change-signature.ts

@@ -1,12 +1,14 @@
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { PROJECT_SUBAGENTS_RELATIVE_DIR } from "../shared/artifacts.ts";
 
 const IGNORED_CHANGE_PREFIXES = [`${PROJECT_SUBAGENTS_RELATIVE_DIR}/`, "tmp/", "node_modules/"];
 const IGNORED_CHANGE_PATHS = new Set([PROJECT_SUBAGENTS_RELATIVE_DIR, "tmp", "node_modules"]);
 const IGNORED_CHANGE_SEGMENTS = new Set([".git", "node_modules"]);
+const TRACKED_ENTRY_PROBE_MAX_BYTES = 1_024;
 
 const DEFAULT_MAX_HASH_FILE_BYTES = 64 * 1024 * 1024;
 const DEFAULT_MAX_HASH_TOTAL_BYTES = 64 * 1024 * 1024;
@@ -43,6 +45,37 @@ function git(cwd: string, args: string[]): string | undefined {
 	return result.stdout;
 }
 
+function comparablePath(value: string): string {
+	let resolved = path.resolve(value);
+	try {
+		resolved = fs.realpathSync.native(resolved);
+	} catch {
+		// Keep the lexical path when canonicalization is unavailable.
+	}
+	return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function isHomeRepoRoot(root: string): boolean {
+	return comparablePath(root) === comparablePath(os.homedir());
+}
+
+/**
+ * Probe the index without asking Git to inspect the working tree. The output
+ * cap keeps this check bounded even for repositories with a very large index;
+ * an ENOBUFS result still proves that at least one tracked path exists.
+ */
+function hasTrackedEntries(root: string): boolean | undefined {
+	const result = spawnSync("git", ["-C", root, "ls-files", "--cached", "--error-unmatch", "--", "."], {
+		encoding: "utf-8",
+		maxBuffer: TRACKED_ENTRY_PROBE_MAX_BYTES,
+		windowsHide: true,
+	});
+	const errorCode = (result.error as NodeJS.ErrnoException | undefined)?.code;
+	if (result.status === 0 || errorCode === "ENOBUFS") return true;
+	if (result.status === 1) return false;
+	return undefined;
+}
+
 function normalizeRelPath(value: string): string {
 	return value.replaceAll(path.sep, "/").replace(/^\.\//, "");
 }
@@ -181,7 +214,13 @@ function buildRepoChangeSignature(root: string, statusOutput: string): WatchdogR
 export function computeWatchdogRepoChangeSignature(cwd: string): WatchdogRepoChangeSignature | undefined {
 	const root = git(cwd, ["rev-parse", "--show-toplevel"])?.trim();
 	if (!root) return undefined;
-	const statusOutput = git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+	const skipUntracked = isHomeRepoRoot(root) || hasTrackedEntries(root) === false;
+	const statusOutput = git(root, [
+		"status",
+		"--porcelain=v1",
+		"-z",
+		`--untracked-files=${skipUntracked ? "no" : "all"}`,
+	]);
 	if (statusOutput === undefined) return undefined;
 	try {
 		return buildRepoChangeSignature(root, statusOutput);

package/dist/extensions/pi-subagents/src/workflows/host-command.ts

@@ -53,7 +53,12 @@ export function normalizeWorkflowHostCommandParams(value: unknown, label = "runs
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
 	const params = value as Record<string, unknown>;
 	const unknownFields = Object.keys(params).filter((field) => !["kind", "command", "timeoutMs", "output", "role", "provider"].includes(field));
-	if (unknownFields.length) throw new Error(`${label} has unsupported fields: ${unknownFields.join(", ")}.`);
+	if (unknownFields.length) {
+		const cwdHint = unknownFields.includes("cwd")
+			? " The host step does not accept per-step cwd; commands and relative output paths use the workflow cwd. Set cwd on the outer subagent request, or put a trusted directory change in command (for example, 'cd /path/to/worktree && npm test')."
+			: "";
+		throw new Error(`${label} has unsupported fields: ${unknownFields.join(", ")}.${cwdHint}`);
+	}
 	if (params.kind !== "command") throw new Error(`${label}.kind must be 'command'.`);
 	if (typeof params.command !== "string" || !params.command.trim()) throw new Error(`${label}.command must be a non-empty string.`);
 	const command = params.command.trim();

package/dist/extensions/pi-subagents/src/workflows/scripted-workflow.ts

@@ -500,8 +500,26 @@ function runLane(lane, firstResult, observe) {
   return visit(0, firstResult);
 }
 
+function workflowPlanStringMetadata(params) {
+  return {
+    ...(typeof params.phase === "string" && params.phase.trim() ? { phase: params.phase.trim() } : {}),
+    ...(typeof params.label === "string" && params.label.trim() ? { label: params.label.trim() } : {}),
+    ...(typeof params.agent === "string" && params.agent.trim() ? { agent: params.agent.trim() } : {}),
+  };
+}
+
 function runLanes(laneSpecs) {
   const lanes = validateLaneSpecs(laneSpecs);
+  parentPort.postMessage({ type: "lanePlan", lanes: lanes.map((lane) => ({
+    key: lane.key,
+    stages: lane.stages.map((stage) => ({
+      key: stage.key,
+      generatedKey: stage.generatedKey,
+      ...workflowPlanStringMetadata(stage.params),
+      ...(typeof stage.params.as === "string" && stage.params.as.trim() ? { outputName: stage.params.as.trim() } : {}),
+      ...(stage.params.outputSchema !== undefined ? { structured: true } : {}),
+    })),
+  })) });
   const firstItems = lanes.map((lane) => {
     const first = lane.stages[0];
     return { key: first.generatedKey, ...first.params };
@@ -624,7 +642,12 @@ function validateHostCommand(key, params) {
   if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error("runs.host('" + key + "') params must be an object.");
   const allowed = new Set(["kind", "command", "timeoutMs", "output", "role", "provider"]);
   const unknown = Object.keys(params).filter((field) => !allowed.has(field));
-  if (unknown.length) throw new Error("runs.host('" + key + "') params have unsupported fields: " + unknown.join(", ") + ".");
+  if (unknown.length) {
+    const cwdHint = unknown.includes("cwd")
+      ? " The host step does not accept per-step cwd; commands and relative output paths use the workflow cwd. Set cwd on the outer subagent request, or put a trusted directory change in command (for example, 'cd /path/to/worktree && npm test')."
+      : "";
+    throw new Error("runs.host('" + key + "') params have unsupported fields: " + unknown.join(", ") + "." + cwdHint);
+  }
   if (params.kind !== "command") throw new Error("runs.host('" + key + "') kind must be 'command'.");
   if (typeof params.command !== "string" || !params.command.trim() || params.command.includes("\u0000") || new TextEncoder().encode(params.command.trim()).byteLength > 16384) throw new Error("runs.host('" + key + "') command must be a non-empty string of at most 16384 bytes without NUL.");
   if (!Number.isInteger(params.timeoutMs) || params.timeoutMs < 1 || params.timeoutMs > 86400000) throw new Error("runs.host('" + key + "') timeoutMs must be an integer from 1 to 86400000.");
@@ -977,6 +1000,22 @@ export interface WorkflowScriptTraceEntry {
 	warning?: string;
 }
 
+/** Bounded plan metadata emitted when a workflow materializes a runs.lanes graph. */
+export interface WorkflowLanePlanStage {
+	key: string;
+	generatedKey: string;
+	agent?: string;
+	phase?: string;
+	label?: string;
+	outputName?: string;
+	structured?: boolean;
+}
+
+export interface WorkflowLanePlan {
+	key: string;
+	stages: WorkflowLanePlanStage[];
+}
+
 export interface WorkflowSteerOptions {
 	mode?: "steer" | "follow_up" | "auto";
 	index?: number;
@@ -1044,6 +1083,7 @@ export interface RunWorkflowScriptOptions {
 	};
 	registerStopChild?: (stop: ((key: string, message?: string) => boolean) | undefined) => void;
 	onTrace?: (trace: WorkflowScriptTraceEntry[]) => void;
+	onLanePlan?: (lanes: WorkflowLanePlan[]) => void;
 	onEmit?: (emits: unknown[]) => void;
 }
 
@@ -1227,7 +1267,7 @@ function validateStaticHostCall(call: AstNode): WorkflowScriptValidationError[]
 	for (const property of params.properties) {
 		if (!astNode(property)) continue;
 		const name = staticPropertyKey(property);
-		if (name !== undefined && !allowed.has(name)) errors.push({ message: `runs.host params contain unsupported field '${name}'.`, ...nodeLocation(property) });
+		if (name !== undefined && !allowed.has(name)) errors.push({ message: name === "cwd" ? "runs.host params contain unsupported field 'cwd'. The host step does not accept per-step cwd; commands and relative output paths use the workflow cwd. Set cwd on the outer subagent request, or put a trusted directory change in command (for example, 'cd /path/to/worktree && npm test')." : `runs.host params contain unsupported field '${name}'.`, ...nodeLocation(property) });
 	}
 	const kindNode = directObjectPropertyValue(params, "kind");
 	const commandNode = directObjectPropertyValue(params, "command");
@@ -1524,6 +1564,13 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			console.error("Workflow onTrace callback failed:", error);
 		}
 	};
+	const lanePlanChanged = (lanes: WorkflowLanePlan[]) => {
+		try {
+			options.onLanePlan?.(lanes);
+		} catch (error) {
+			console.error("Workflow onLanePlan callback failed:", error);
+		}
+	};
 	const hostStepChanged = (hostStep: HostStepNodeV1) => {
 		try {
 			options.onHostStep?.(hostStep);
@@ -1626,6 +1673,10 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 		});
 		worker.on("message", (message: Record<string, unknown>) => {
 			if (settled) return;
+			if (message.type === "lanePlan" && Array.isArray(message.lanes)) {
+				lanePlanChanged(message.lanes as WorkflowLanePlan[]);
+				return;
+			}
 			if (message.type === "emit") {
 				try {
 					assertWorkflowJsonValue(message.value, "emit");

package/dist/extensions/pi-subagents/test/integration/async-execution.test.ts

@@ -26,6 +26,7 @@ import { resolveSubagentLaunchContract } from "../../src/api/preflight.ts";
 import { discoverAgents } from "../../src/agents/agents.ts";
 import { runSync } from "../../src/runs/foreground/execution.ts";
 import { ACTIVE_ASYNC_CAPACITY_DIR, acquireActiveAsyncCapacity, activeAsyncCapacitySessionKey } from "../../src/runs/background/active-async-capacity.ts";
+import { deriveForkPromptCacheKey, SUBAGENT_FORK_CACHE_KEY_ENV } from "../../src/runs/shared/pi-args.ts";
 
 interface LaunchResolvedExtensions {
 	version?: number;
@@ -80,7 +81,7 @@ interface AsyncResultPayload {
 	totalTokens?: { input: number; output: number; total: number };
 	totalCost?: { inputTokens: number; outputTokens: number; costUsd: number };
 	usageBudget?: UsageBudgetState;
-	results: Array<{ agent?: string; sessionName?: string; launchContractDigest?: string; launchResolvedExtensions?: LaunchResolvedExtensions; runtimeAcknowledgedExtensions?: RuntimeAcknowledgedExtensions; output?: string; outputState?: "present" | "absent" | "unknown"; success?: boolean; error?: string; protocolError?: { code?: string; stream?: string; limitBytes?: number; observedBytes?: number }; timedOut?: boolean; timeoutRecovery?: { changedFiles?: string[]; message?: string; warning?: string }; stopped?: boolean; turnBudget?: { maxTurns: number; graceTurns: number; outcome: string; turnCount: number; wrapUpRequestedAtTurn?: number; terminationDeferredAtTurn?: number; exceededAtTurn?: number }; turnBudgetExceeded?: boolean; wrapUpRequested?: boolean; model?: string; attemptedModels?: string[]; modelAttempts?: Array<{ success?: boolean; error?: string }>; totalCost?: { inputTokens: number; outputTokens: number; costUsd: number }; usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number; turns: number }; structuredOutput?: unknown; agentContract?: { version: 1 }; execution?: { status?: string; success?: boolean; exitCode?: number }; effects?: { fileMutation?: { status?: string; expected?: boolean; attempted?: boolean; message?: string }; settlementDiagnostic?: { finalTextPresent?: boolean; mutation?: { expected?: boolean; attempted?: boolean; observed?: boolean }; requiredOutput?: { kind?: string; path?: string; missing?: boolean }; afterCompactionSettlement?: boolean } }; intercomTarget?: string; acceptance?: { status?: string; effectiveAcceptance?: { level?: string }; childReport?: unknown; runtimeChecks?: Array<{ id?: string; status?: string; message?: string }> }; artifactPaths?: { outputPath?: string; inputPath?: string; metadataPath?: string; transcriptPath?: string }; outputSaveError?: string; metadataSaveError?: string; capabilityCeiling?: { version?: number; allowedTools?: string[]; denyExtensions?: boolean; sources?: string[] }; capabilityAudit?: { effectiveTools?: string[]; removedTools?: string[]; extensionsDenied?: boolean } }>;
+	results: Array<{ agent?: string; sessionName?: string; launchContractDigest?: string; launchResolvedExtensions?: LaunchResolvedExtensions; runtimeAcknowledgedExtensions?: RuntimeAcknowledgedExtensions; output?: string; outputState?: "present" | "absent" | "unknown"; success?: boolean; error?: string; protocolError?: { code?: string; stream?: string; limitBytes?: number; observedBytes?: number }; timedOut?: boolean; timeoutRecovery?: { changedFiles?: string[]; message?: string; warning?: string; recoveryNeeded?: boolean; reason?: string; reportStatus?: string }; stopped?: boolean; turnBudget?: { maxTurns: number; graceTurns: number; outcome: string; turnCount: number; wrapUpRequestedAtTurn?: number; terminationDeferredAtTurn?: number; exceededAtTurn?: number }; turnBudgetExceeded?: boolean; wrapUpRequested?: boolean; model?: string; attemptedModels?: string[]; modelAttempts?: Array<{ success?: boolean; error?: string }>; totalCost?: { inputTokens: number; outputTokens: number; costUsd: number }; usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number; turns: number }; structuredOutput?: unknown; agentContract?: { version: 1 }; execution?: { status?: string; success?: boolean; exitCode?: number }; effects?: { fileMutation?: { status?: string; expected?: boolean; attempted?: boolean; message?: string }; settlementDiagnostic?: { finalTextPresent?: boolean; mutation?: { expected?: boolean; attempted?: boolean; observed?: boolean }; requiredOutput?: { kind?: string; path?: string; missing?: boolean }; afterCompactionSettlement?: boolean } }; intercomTarget?: string; acceptance?: { status?: string; effectiveAcceptance?: { level?: string }; childReport?: unknown; runtimeChecks?: Array<{ id?: string; status?: string; message?: string }> }; artifactPaths?: { outputPath?: string; inputPath?: string; metadataPath?: string; transcriptPath?: string }; outputSaveError?: string; metadataSaveError?: string; capabilityCeiling?: { version?: number; allowedTools?: string[]; denyExtensions?: boolean; sources?: string[] }; capabilityAudit?: { effectiveTools?: string[]; removedTools?: string[]; extensionsDenied?: boolean } }>;
 	outputs?: Record<string, { text?: string; structured?: unknown }>;
 	workflowGraph?: { nodes?: Array<{ kind?: string; label?: string; phase?: string; status?: string; acceptanceStatus?: string; error?: string; outputName?: string; structured?: boolean; children?: Array<{ label?: string; outputName?: string; itemKey?: string; status?: string; acceptanceStatus?: string; error?: string }> }> };
 	parallelHandoff?: { version?: number; path?: string; groupCount?: number; childCount?: number; changedPatches?: number; cleanupState?: string };
@@ -128,7 +129,7 @@ interface AsyncStatusPayload {
 		status?: string;
 		exitCode?: number;
 		timedOut?: boolean;
-		timeoutRecovery?: { changedFiles?: string[]; message?: string; warning?: string };
+		timeoutRecovery?: { changedFiles?: string[]; message?: string; warning?: string; recoveryNeeded?: boolean; reason?: string; reportStatus?: string };
 		error?: string;
 		model?: string;
 		thinking?: string;
@@ -1551,14 +1552,15 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.results[0]?.error, "Subagent timed out after 150ms.");
 	});
 
-	it("preserves async timeout recovery summaries in final results", { skip: !isAsyncAvailable() ? "jiti not available" : process.platform === "win32" ? "timeout signal delivery intermittent on Windows CI" : undefined }, async () => {
+	it("classifies a timed-out dirty child with a missing requested report as recovery-needed", { skip: !isAsyncAvailable() ? "jiti not available" : process.platform === "win32" ? "timeout signal delivery intermittent on Windows CI" : undefined }, async () => {
 		mockPi.onCall({ delay: 5_000, output: "too late" });
 		const repo = createRepo("pi-subagents-timeout-recovery-");
 		try {
 			const id = `async-timeout-recovery-${Date.now().toString(36)}`;
+			const outputPath = path.join(repo, "missing-report.md");
 			executeAsyncChain(id, {
-				chain: [{ agent: "slow", task: "Wait" }],
-				agents: [makeAgent("slow")],
+				chain: [{ agent: "slow", task: "Write the requested report" }],
+				agents: [makeAgent("slow", { output: outputPath, outputMode: "file-only" })],
 				ctx: { pi: { events: { emit() {} } }, cwd: repo, currentSessionId: "session-1" },
 				artifactConfig: {
 					enabled: true,
@@ -1578,12 +1580,27 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			const payload = await readAsyncPayload(id);
 			const status = await waitForAsyncState(id, (candidate) => candidate.state === "failed");
 			const result = payload.results[0];
+			const recovery = result?.timeoutRecovery;
+			const statusRecovery = status.steps?.[0]?.timeoutRecovery;
+			assert.equal(payload.success, false);
+			assert.equal(payload.state, "failed");
 			assert.equal(result?.timedOut, true);
+			assert.equal(result?.success, false);
+			assert.equal(fs.existsSync(outputPath), false);
 			assert.deepEqual(result?.timeoutRecovery?.changedFiles, ["input.md"]);
+			assert.equal(recovery?.recoveryNeeded, true);
+			assert.equal(recovery?.reason, "timed-out-with-dirty-worktree");
+			assert.equal(recovery?.reportStatus, "missing");
 			assert.match(result?.timeoutRecovery?.message ?? "", /changed tracked files: input\.md/);
+			assert.match(recovery?.message ?? "", /requested report: missing/i);
+			assert.match(result?.output ?? "", /review (?:the )?diff and artifacts before resuming.*dependent stages/i);
 			assert.match(result?.output ?? "", /Recovery summary:/);
 			assert.match(result?.output ?? "", /Warning: Inspect partial changes before retrying/);
-			assert.deepEqual(status.steps?.[0]?.timeoutRecovery?.changedFiles, ["input.md"]);
+			assert.equal(status.state, "failed");
+			assert.equal(status.steps?.[0]?.status, "failed");
+			assert.deepEqual(statusRecovery?.changedFiles, ["input.md"]);
+			assert.equal(statusRecovery?.recoveryNeeded, true);
+			assert.equal(statusRecovery?.reportStatus, "missing");
 		} finally {
 			fs.rmSync(repo, { recursive: true, force: true });
 		}
@@ -4652,6 +4669,38 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.results[0]?.model, "gateway/parent-model");
 	});
 
+	it("background forked runs receive the derived fork cache key", { skip: !isAsyncAvailable() || !createSubagentExecutor ? "jiti or executor not available" : undefined }, async () => {
+		mockPi.onCall({ echoEnv: [SUBAGENT_FORK_CACHE_KEY_ENV] });
+		const parentSessionFile = path.join(tempDir, "parent-cache.jsonl");
+		const forkedSessionFile = path.join(tempDir, "forked-cache.jsonl");
+		const sessionHeader = JSON.stringify({ type: "session", cwd: fs.realpathSync(tempDir) });
+		fs.writeFileSync(parentSessionFile, `${sessionHeader}\n`, "utf-8");
+		fs.writeFileSync(forkedSessionFile, `${sessionHeader}\n`, "utf-8");
+		const ctx = {
+			...makeMinimalCtx(tempDir),
+			sessionManager: {
+				getSessionId: () => "session-cache-parent",
+				getSessionFile: () => parentSessionFile,
+				getLeafId: () => "leaf-current",
+				openSession: () => ({ createBranchedSession: () => forkedSessionFile }),
+			},
+		};
+
+		const launch = await makeAsyncExecutor([makeAgent("worker", { completionGuard: false })]).execute(
+			"forked-cache-key",
+			{ agent: "worker", task: "Inspect cache affinity", async: true, context: "fork" },
+			new AbortController().signal,
+			undefined,
+			ctx,
+		) as AsyncExecutionResult;
+		assert.ok(!launch.isError, launch.content[0]?.text);
+		assert.ok(launch.details.asyncId);
+
+		const payload = await readAsyncPayload(launch.details.asyncId);
+		const childEnv = JSON.parse(payload.results[0]?.output ?? "{}") as Record<string, string | null>;
+		assert.equal(childEnv[SUBAGENT_FORK_CACHE_KEY_ENV], deriveForkPromptCacheKey("session-cache-parent"));
+	});
+
 	it("revives an inherited parent model outside the current registry", { skip: !isAsyncAvailable() || !createSubagentExecutor ? "jiti or executor not available" : undefined }, async () => {
 		mockPi.onCall({ output: "Initial async work" });
 		const sourceId = `async-revive-parent-model-${Date.now().toString(36)}`;

package/dist/extensions/pi-subagents/test/integration/async-status.test.ts

@@ -4,7 +4,7 @@ import { syncBuiltinESMExports } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
 import { describe, it } from "node:test";
-import { formatAsyncRunList, listAsyncRuns } from "../../src/runs/background/async-status.ts";
+import { formatAsyncRunList, formatWorkflowStageLine, listAsyncRuns } from "../../src/runs/background/async-status.ts";
 import { ACTIVE_RUN_INDEX_DIR, DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS, updateActiveRunIndex } from "../../src/runs/background/active-run-index.ts";
 import { encodeIndexSegment } from "../../src/runs/background/index-segment.ts";
 import { TERMINAL_RUN_INDEX_DIR } from "../../src/runs/background/terminal-run-index.ts";
@@ -19,7 +19,43 @@ function createAsyncDir(root: string, id: string, status: Record<string, unknown
 	return dir;
 }
 
+const stagedLaneKeys = ["scope-scout", "red-tests", "label-helpers", "summary-title", "detail-row", "tiers-noise", "validation", "minimality-challenge", "fresh-review"];
+
+function stagedLaneStatusGraph(runId: string): Record<string, unknown> {
+	const nodeIds = stagedLaneKeys.map((key) => `${runId}.${key}`);
+	return {
+		runId,
+		mode: "workflow",
+		phases: [{ title: `${runId} staged lane`, nodeIds }],
+		nodes: stagedLaneKeys.map((key, index) => ({
+			id: nodeIds[index],
+			kind: "step",
+			agent: index === 0 ? "scout" : index === 7 ? "simplifier" : "worker",
+			label: key,
+			status: index === 0 ? "running" : "pending",
+			flatIndex: index,
+			stepIndex: index,
+		})),
+		currentNodeId: nodeIds[0],
+	};
+}
+
 describe("async status helpers", () => {
+	it("bounds workflow stage text from persisted status", () => {
+		const line = formatWorkflowStageLine({
+			id: `${"stage".repeat(80)}\u001b[31m`,
+			kind: "step",
+			label: `${"label".repeat(80)}\nsecond line`,
+			agent: "worker".repeat(40),
+			status: "failed",
+			error: `${"boom".repeat(100)}\nwith details`,
+		}, 0, 1);
+
+		assert.equal(line.includes("\u001b"), false);
+		assert.equal(line.includes("\n"), false);
+		assert.ok(line.length < 700, line);
+	});
+
 	it("lists only requested states and includes flattened step summaries", () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-async-status-"));
 		let budgetDirectory: string | undefined;
@@ -73,6 +109,80 @@ describe("async status helpers", () => {
 			if (budgetDirectory) fs.rmSync(budgetDirectory, { recursive: true, force: true });
 		}
 	});
+
+	it("forwards bounded timeout recovery evidence and formats the recovery route", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-async-status-recovery-"));
+		try {
+			const changedFiles = Array.from({ length: 25 }, (_, index) => `src/file-${String(index + 1).padStart(2, "0")}.ts`);
+			createAsyncDir(root, "run-recovery", {
+				runId: "run-recovery",
+				mode: "single",
+				state: "failed",
+				startedAt: 100,
+				lastUpdate: 200,
+				steps: [{
+					agent: "worker",
+					status: "failed",
+					timedOut: true,
+					timeoutRecovery: {
+						termination: "timed-out",
+						changedFiles,
+						truncated: true,
+						recoveryNeeded: true,
+						reason: "timed-out-with-dirty-worktree",
+						reportStatus: "missing",
+						message: "raw recovery message must not cross the projection",
+						effects: { settlementDiagnostic: { finalTextPresent: true } },
+					},
+				}],
+			});
+
+			const run = listAsyncRuns(root, { states: ["failed"], reconcile: false })[0]!;
+			assert.deepEqual(run.steps[0]?.timeoutRecovery, {
+				termination: "timed-out",
+				changedFiles: changedFiles.slice(0, 20),
+				truncated: true,
+				recoveryNeeded: true,
+				reason: "timed-out-with-dirty-worktree",
+				reportStatus: "missing",
+			});
+			assert.doesNotMatch(JSON.stringify(run), /raw recovery message|settlementDiagnostic/);
+			const text = formatAsyncRunList([run], "Failed async runs");
+			assert.match(text, /Recovery needed: review the diff and artifacts before resuming or launching dependent stages\./);
+			assert.match(text, /requested report: missing/);
+			assert.match(text, /changed tracked files: src\/file-01\.ts, src\/file-02\.ts/);
+			assert.match(text, /file-20\.ts, …/);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("reports the planned runs.lanes stage count while the first child is running", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-async-status-staged-lane-"));
+		try {
+			const runId = "run-staged-lane";
+			createAsyncDir(root, runId, {
+				runId,
+				mode: "workflow",
+				state: "running",
+				startedAt: 100,
+				lastUpdate: 200,
+				currentStep: 0,
+				steps: [{ agent: "scout", workflowKey: `${runId}.scope-scout`, label: "scope-scout", status: "running" }],
+				workflowGraph: stagedLaneStatusGraph(runId),
+			});
+
+			const runs = listAsyncRuns(root, { states: ["running"], reconcile: false });
+			const text = formatAsyncRunList(runs);
+			assert.match(text, /stage\s+1\/9/i);
+			assert.doesNotMatch(text, /step\s+1\/1/i);
+			assert.match(text, /scope-scout/);
+			assert.match(text, /stage\s+9\/9:.*fresh-review.*pending/i);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
 	it("loads typed host monitor nodes from workflow status without child identity", () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-async-host-step-"));
 		try {