@selesai/code 0.5.28 → 0.6.1

package/dist/extensions/pi-subagents/test/unit/runtime-acknowledged-extensions.test.ts

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+import { MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_FILE_BYTES, isRuntimeAcknowledgedExtensionId, projectRuntimeAcknowledgedExtensions, readRuntimeAcknowledgedExtensions, sanitizeRuntimeAcknowledgedExtensions } from "../../src/runs/shared/runtime-acknowledged-extensions.ts";
+
+describe("runtime acknowledged extension projection", () => {
+	it("validates opaque ids without path-like content", () => {
+		assert.equal(isRuntimeAcknowledgedExtensionId("com.example-extension:v1"), true);
+		assert.equal(isRuntimeAcknowledgedExtensionId(""), false);
+		assert.equal(isRuntimeAcknowledgedExtensionId("has space"), false);
+		assert.equal(isRuntimeAcknowledgedExtensionId("../secret"), false);
+		assert.equal(isRuntimeAcknowledgedExtensionId("path/to/ext"), false);
+		assert.equal(isRuntimeAcknowledgedExtensionId("path\\to\\ext"), false);
+		assert.equal(isRuntimeAcknowledgedExtensionId("x".repeat(129)), false);
+	});
+
+	it("deduplicates, caps ids, and counts omitted valid ids", () => {
+		const ids = ["dup", "dup", ...Array.from({ length: 35 }, (_, index) => `ext-${index}`), "bad id"];
+		const projected = projectRuntimeAcknowledgedExtensions(ids);
+
+		assert.equal(projected?.source, "child-runtime");
+		assert.equal(projected?.ids.length, 32);
+		assert.equal(projected?.ids[0], "dup");
+		assert.equal(projected?.omitted, 4);
+		assert.equal(projected?.ids.includes("bad id"), false);
+	});
+
+	it("sanitizes persisted projections and rejects invalid shapes", () => {
+		assert.deepEqual(sanitizeRuntimeAcknowledgedExtensions({ version: 1, source: "child-runtime", ids: ["ok", "ok", "bad/path"], omitted: 2 }), {
+			version: 1,
+			source: "child-runtime",
+			ids: ["ok"],
+			omitted: 2,
+		});
+		assert.equal(sanitizeRuntimeAcknowledgedExtensions({ version: 1, source: "launch-resolved", ids: ["ok"] }), undefined);
+		assert.equal(sanitizeRuntimeAcknowledgedExtensions({ version: 1, source: "child-runtime", ids: ["bad/path"] }), undefined);
+	});
+
+	it("rejects oversized capture files without reading them", (t) => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "runtime-ack-"));
+		t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+		const filePath = path.join(dir, "ack.json");
+
+		fs.writeFileSync(filePath, "x".repeat(MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_FILE_BYTES + 1));
+		assert.equal(readRuntimeAcknowledgedExtensions(filePath), undefined);
+
+		fs.writeFileSync(filePath, JSON.stringify({ version: 1, source: "child-runtime", ids: ["ok"], omitted: 0 }));
+		assert.deepEqual(readRuntimeAcknowledgedExtensions(filePath), { version: 1, source: "child-runtime", ids: ["ok"], omitted: 0 });
+	});
+});

package/dist/extensions/pi-subagents/test/unit/schemas.test.ts

@@ -38,6 +38,13 @@ interface SubagentParamsSchema {
 				graceTurns?: { minimum?: number };
 			};
 		};
+		usageBudget?: {
+			properties?: {
+				tokens?: { properties?: { soft?: { exclusiveMinimum?: number }; hard?: { exclusiveMinimum?: number } } };
+				costUsd?: { properties?: { soft?: { exclusiveMinimum?: number }; hard?: { exclusiveMinimum?: number } } };
+			};
+			description?: string;
+		};
 		id?: {
 			type?: string;
 			description?: string;
@@ -187,6 +194,18 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.doesNotMatch(description, /orchestration\./);
 	});
 
+	it("documents list task as an optional advisory intent and keeps action a free string", () => {
+		const taskSchema = (SubagentParams?.properties as Record<string, JsonSchemaNode> | undefined)?.task;
+		assert.ok(taskSchema, "task schema should exist");
+		const description = String(taskSchema?.description ?? "");
+		assert.match(description, /action:'list'/);
+		assert.match(description, /never launches/);
+		assert.match(description, /explicitly call subagent/);
+		const actionSchema = SubagentParams?.properties?.action;
+		assert.equal(actionSchema?.type, "string");
+		assert.equal(actionSchema?.enum, undefined);
+	});
+
 	it("includes foreground timeout aliases and turn budget", () => {
 		const timeoutSchema = SubagentParams?.properties?.timeoutMs;
 		const maxRuntimeSchema = SubagentParams?.properties?.maxRuntimeMs;
@@ -206,6 +225,19 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.equal(toolBudgetSchema?.properties?.hard?.minimum, 1);
 	});
 
+	it("includes root-only reported usage budget", () => {
+		const usageBudgetSchema = SubagentParams?.properties?.usageBudget;
+		assert.ok(usageBudgetSchema, "usageBudget schema should exist");
+		assert.equal(usageBudgetSchema.properties?.tokens?.properties?.soft?.exclusiveMinimum, 0);
+		assert.equal(usageBudgetSchema.properties?.tokens?.properties?.hard?.exclusiveMinimum, 0);
+		assert.equal(usageBudgetSchema.properties?.costUsd?.properties?.soft?.exclusiveMinimum, 0);
+		assert.equal(usageBudgetSchema.properties?.costUsd?.properties?.hard?.exclusiveMinimum, 0);
+		assert.match(String(usageBudgetSchema.description ?? ""), /root-only/);
+		assert.match(String(usageBudgetSchema.description ?? ""), /running children are not stopped/i);
+		assert.equal(getPropertySchema(SubagentParams?.properties?.tasks?.items as JsonSchemaNode | undefined, ["usageBudget"]), undefined);
+		assert.equal(getPropertySchema(SubagentParams?.properties?.chain?.items as JsonSchemaNode | undefined, ["usageBudget"]), undefined);
+	});
+
 	it("includes subagent control fields", () => {
 		const idSchema = SubagentParams?.properties?.id;
 		assert.ok(idSchema, "id schema should exist");
@@ -214,6 +246,12 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.match(String(idSchema.description ?? ""), /interrupt/i);
 		assert.match(String(idSchema.description ?? ""), /steer/i);
 		assert.match(String(idSchema.description ?? ""), /append-step/i);
+		assert.match(String(idSchema.description ?? ""), /approve-checkpoint/i);
+		assert.match(String(idSchema.description ?? ""), /reject-checkpoint/i);
+
+		const chainItemSchema = SubagentParams?.properties?.chain?.items;
+		assert.equal(chainItemSchema?.properties?.checkpoint?.type, "string");
+		assert.equal(chainItemSchema?.properties?.message?.type, "string");
 
 		const runIdSchema = SubagentParams?.properties?.runId;
 		assert.ok(runIdSchema, "runId schema should exist");
@@ -318,12 +356,18 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.ok(SubagentParams, "SubagentParams schema should exist");
 		const schema = SubagentParams as unknown as JsonSchemaNode;
 		const serialized = JSON.stringify(schema);
-		assert.ok(serialized.length < 15_000, `expected compact schema under 15k chars, got ${serialized.length}`);
+		assert.ok(serialized.length < 16_000, `expected compact schema under 16k chars, got ${serialized.length}`);
 		assert.equal(serialized.includes('"$ref"'), false);
 		assert.equal(serialized.includes('"$defs"'), false);
 		assert.equal(serialized.split("Optional acceptance policy.").length - 1, 1);
 		assert.match(String((schema.properties as Record<string, JsonSchemaNode> | undefined)?.agent?.description ?? ""), /SINGLE mode/);
-		assert.match(String((schema.properties as Record<string, JsonSchemaNode> | undefined)?.acceptance?.description ?? ""), /acceptance policy/);
+		const acceptanceDescription = String((schema.properties as Record<string, JsonSchemaNode> | undefined)?.acceptance?.description ?? "");
+		assert.match(acceptanceDescription, /acceptance policy/);
+		assert.match(acceptanceDescription, /Supported evidence kinds:/);
+		assert.match(acceptanceDescription, /commands-run/);
+		assert.match(acceptanceDescription, /changed-files/);
+		assert.match(acceptanceDescription, /manual-notes/);
+		assert.match(acceptanceDescription, /\{ level: "checked", evidence: \["commands-run", "changed-files"\] \}/);
 
 		const nestedDescriptionPaths: string[] = [];
 		const stack: Array<{ path: string; value: unknown }> = [{ path: "SubagentParams", value: schema }];

package/dist/extensions/pi-subagents/test/unit/single-output.test.ts

@@ -6,8 +6,10 @@ import * as path from "node:path";
 import type { Message, Usage } from "@earendil-works/pi-ai";
 import {
 	captureSingleOutputSnapshot,
+	CONTEXT_FALLBACK_LIMIT,
 	extractChildWrittenOutput,
 	finalizeSingleOutput,
+	formatBoundedPersistenceFallback,
 	formatSavedOutputReference,
 	injectOutputPathSystemPrompt,
 	injectSingleOutputInstruction,
@@ -269,6 +271,49 @@ describe("validateFileOnlyOutputMode", () => {
 	});
 });
 
+describe("CONTEXT_FALLBACK_LIMIT and formatBoundedPersistenceFallback", () => {
+	it("exports the fixed internal 80-line/4-KiB context fallback cap", () => {
+		assert.equal(CONTEXT_FALLBACK_LIMIT.lines, 80);
+		assert.equal(CONTEXT_FALLBACK_LIMIT.bytes, 4096);
+	});
+
+	it("includes error, process status, intended path, and a bounded slice", () => {
+		const fallback = formatBoundedPersistenceFallback({
+			error: "EACCES: permission denied",
+			outputPath: "/tmp/report.md",
+			fullOutput: "line one\nline two",
+			exitCode: 1,
+			processError: "boom",
+		});
+		assert.match(fallback, /\[Full output unavailable\] EACCES: permission denied/);
+		assert.match(fallback, /Process status: boom/);
+		assert.match(fallback, /Intended output path: \/tmp\/report\.md/);
+		assert.match(fallback, /Full output is unavailable; showing a bounded excerpt \(first 80 lines \/ 4 KiB\)\./);
+		assert.match(fallback, /line one\nline two/);
+		assert.doesNotMatch(fallback, /Output saved to:/);
+	});
+
+	it("never returns unbounded output when the source exceeds the cap", () => {
+		const longOutput = Array.from({ length: 500 }, (_, i) => `line ${i} ${`x`.repeat(50)}`).join("\n");
+		const fallback = formatBoundedPersistenceFallback({
+			error: "disk full",
+			fullOutput: longOutput,
+			exitCode: 0,
+		});
+		const body = fallback.split("\n").filter((line) => /^line \d+/.test(line)).length;
+		assert.ok(body <= 80, `fallback kept ${body} lines, expected at most 80`);
+		assert.ok(Buffer.byteLength(fallback, "utf-8") <= 12 * 1024, "fallback header plus 4-KiB slice stays bounded");
+		assert.doesNotMatch(fallback, /line 400/);
+	});
+
+	it("states completed status for exit code 0 and failed status otherwise", () => {
+		const completed = formatBoundedPersistenceFallback({ error: "read failed", fullOutput: "x", exitCode: 0 });
+		assert.match(completed, /Process status: completed/);
+		const failed = formatBoundedPersistenceFallback({ error: "read failed", fullOutput: "x", exitCode: 2 });
+		assert.match(failed, /Process status: failed \(exit 2\)/);
+	});
+});
+
 describe("finalizeSingleOutput", () => {
 	it("formats saved-path messaging around the already-resolved output", () => {
 		const result = finalizeSingleOutput({
@@ -298,13 +343,58 @@ describe("finalizeSingleOutput", () => {
 		assert.match(result.displayOutput, /3 lines/);
 	});
 
-	it("does not add save messaging on failed runs", () => {
+	it("returns error/status plus the saved-output reference on failed runs with a persisted result", () => {
 		const result = finalizeSingleOutput({
 			fullOutput: "full output",
 			truncatedOutput: "truncated output",
 			outputPath: "/tmp/review.md",
 			savedPath: "/tmp/review.md",
 			exitCode: 1,
+			error: "exploded",
+		});
+
+		assert.match(result.displayOutput, /^exploded\n\nOutput saved to: \/tmp\/review\.md/);
+		assert.doesNotMatch(result.displayOutput, /truncated output/);
+		assert.equal(result.savedPath, "/tmp/review.md");
+		assert.ok(result.outputReference);
+	});
+
+	it("returns only the bounded persistence-failure fallback when saving failed", () => {
+		const result = finalizeSingleOutput({
+			fullOutput: "full output text",
+			truncatedOutput: "truncated output",
+			outputPath: "/tmp/review.md",
+			exitCode: 0,
+			saveError: "EACCES: permission denied",
+		});
+
+		assert.match(result.displayOutput, /\[Full output unavailable\]/);
+		assert.match(result.displayOutput, /Intended output path: \/tmp\/review\.md/);
+		assert.match(result.displayOutput, /full output text/);
+		assert.doesNotMatch(result.displayOutput, /Output saved to:/);
+		assert.equal(result.savedPath, undefined);
+		assert.equal(result.saveError, "EACCES: permission denied");
+	});
+
+	it("returns only the bounded persistence-failure fallback on failed runs with a save error", () => {
+		const result = finalizeSingleOutput({
+			fullOutput: "partial child output",
+			outputPath: "/tmp/review.md",
+			exitCode: 1,
+			saveError: "Failed to read changed output file: boom",
+			error: "step failed",
+		});
+
+		assert.match(result.displayOutput, /\[Full output unavailable\] Failed to read changed output file: boom/);
+		assert.match(result.displayOutput, /Process status: step failed/);
+		assert.doesNotMatch(result.displayOutput, /Output saved to:/);
+	});
+
+	it("keeps the legacy full inline output for successful inline runs without a saved path", () => {
+		const result = finalizeSingleOutput({
+			fullOutput: "legacy inline output",
+			truncatedOutput: "truncated output",
+			exitCode: 0,
 		});
 
 		assert.equal(result.displayOutput, "truncated output");

package/dist/extensions/pi-subagents/test/unit/skills-fallback.test.ts

@@ -340,7 +340,7 @@ describe("skills filesystem fallback", () => {
 		`;
 		execFileSync(
 			process.execPath,
-			["--experimental-transform-types", "--import", "./test/support/register-loader.mjs", "--input-type=module", "--eval", script],
+			["--experimental-strip-types", "--import", "./test/support/register-loader.mjs", "--input-type=module", "--eval", script],
 			{
 				cwd: projectRoot,
 				env: {

package/dist/extensions/pi-subagents/test/unit/steering-action.test.ts

@@ -60,7 +60,7 @@ function projectRequest(status: AsyncStatus, request: SteerRequest, states: Stee
 	}
 }
 
-async function waitUntil<T>(read: () => T | undefined, timeoutMs = 1_000): Promise<T> {
+async function waitUntil<T>(read: () => T | undefined, timeoutMs = 30_000): Promise<T> {
 	const deadline = Date.now() + timeoutMs;
 	while (true) {
 		const value = read();

package/dist/extensions/pi-subagents/test/unit/streamed-progress-bounds.test.ts

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import { Buffer } from "node:buffer";
+import { describe, it } from "node:test";
+import {
+	boundStreamedRecentOutput,
+	boundStreamedRecentTools,
+	boundStreamedToolCalls,
+	MAX_STREAMED_OUTPUT_LINE_CHARS,
+	MAX_STREAMED_RECENT_TOOLS,
+	MAX_STREAMED_TOOL_CALLS,
+} from "../../src/shared/utils.ts";
+
+describe("streamed progress snapshot bounds", () => {
+	it("keeps only the most recent tool-history entries and clones them", () => {
+		const recentTools = Array.from({ length: MAX_STREAMED_RECENT_TOOLS + 40 }, (_, i) => ({
+			tool: "read",
+			args: `file-${i}.ts`,
+			endMs: i,
+		}));
+		const bounded = boundStreamedRecentTools(recentTools);
+		assert.equal(bounded.length, MAX_STREAMED_RECENT_TOOLS);
+		// most-recent retained (chronological)
+		assert.equal(bounded.at(-1)?.endMs, recentTools.at(-1)?.endMs);
+		assert.equal(bounded[0]?.endMs, recentTools.at(-MAX_STREAMED_RECENT_TOOLS)?.endMs);
+		// cloned, not aliased
+		bounded[0]!.args = "mutated";
+		assert.notEqual(recentTools.at(-MAX_STREAMED_RECENT_TOOLS)?.args, "mutated");
+	});
+
+	it("truncates long recent-output lines but leaves short lines intact", () => {
+		const shortLine = "ok";
+		const longLine = "x".repeat(MAX_STREAMED_OUTPUT_LINE_CHARS + 5000);
+		const bounded = boundStreamedRecentOutput([shortLine, longLine]);
+		assert.equal(bounded[0], shortLine);
+		assert.ok(bounded[1]!.length < longLine.length);
+		assert.ok(bounded[1]!.startsWith("x".repeat(MAX_STREAMED_OUTPUT_LINE_CHARS)));
+		assert.match(bounded[1]!, /\[truncated\]$/);
+	});
+
+	it("prefers an existing toolCalls summary and caps it", () => {
+		const toolCalls = Array.from({ length: MAX_STREAMED_TOOL_CALLS + 20 }, (_, i) => ({
+			text: `read(${i})`,
+			expandedText: `read(file-${i}.ts)`,
+		}));
+		const bounded = boundStreamedToolCalls({ toolCalls, messages: undefined });
+		assert.equal(bounded?.length, MAX_STREAMED_TOOL_CALLS);
+		assert.equal(bounded?.at(-1)?.text, toolCalls.at(-1)?.text);
+	});
+
+	it("derives tool-call summaries from messages when none are present", () => {
+		const messages = [
+			{ role: "assistant", content: [{ type: "toolCall", name: "read", arguments: { path: "a.ts" } }] },
+			{ role: "assistant", content: [{ type: "toolCall", name: "grep", arguments: { pattern: "foo" } }] },
+			{ role: "user", content: [{ type: "text", text: "ignored" }] },
+		] as never;
+		const bounded = boundStreamedToolCalls({ toolCalls: undefined, messages });
+		assert.equal(bounded?.length, 2);
+		assert.match(bounded![0]!.text, /read/);
+		assert.match(bounded![1]!.text, /grep/);
+	});
+
+	it("returns undefined when there are no tool calls", () => {
+		assert.equal(boundStreamedToolCalls({ toolCalls: [], messages: [] as never }), undefined);
+		assert.equal(boundStreamedToolCalls({ toolCalls: undefined, messages: undefined }), undefined);
+	});
+
+	it("bounds a pathological running snapshot well under the child-stdout protocol cap", () => {
+		// Simulates a long, deep nested fan-out: many tool calls + long output lines.
+		const recentTools = Array.from({ length: 5000 }, (_, i) => ({ tool: "read", args: `services/pkg/file-${i}.ts`, endMs: i }));
+		const recentOutput = Array.from({ length: 50 }, () => "y".repeat(60_000));
+		const snapshot = {
+			recentTools: boundStreamedRecentTools(recentTools),
+			recentOutput: boundStreamedRecentOutput(recentOutput),
+		};
+		const bytes = Buffer.byteLength(JSON.stringify(snapshot), "utf8");
+		assert.ok(bytes < 256 * 1024, `bounded snapshot should be small, was ${bytes} bytes`);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/subagent-prompt-runtime.test.ts

@@ -16,6 +16,7 @@ import {
 	SUBAGENT_STEER_INBOX_ENV,
 	SUBAGENT_SUPERVISOR_CHANNEL_DIR_ENV,
 } from "../../src/runs/shared/pi-args.ts";
+import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV } from "../../src/runs/shared/runtime-acknowledged-extensions.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "../../src/runs/shared/structured-output.ts";
 import { TOOL_BUDGET_ENV } from "../../src/runs/shared/tool-budget.ts";
 import { CHILD_TOOL_DIAGNOSTIC_PATH_ENV, formatChildToolDiagnostic, MCP_DIRECT_CHILD_TOOLS_ENV, readChildToolDiagnostic, REQUIRED_CHILD_TOOLS_ENV } from "../../src/runs/shared/tool-availability.ts";
@@ -128,6 +129,42 @@ function setSupervisorEnv(): void {
 }
 
 describe("subagent prompt runtime", () => {
+	it("collects runtime extension acknowledgements until terminal serialization", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "subagent-runtime-ack-"));
+		try {
+			const outputPath = path.join(dir, "acks.json");
+			process.env[RUNTIME_EXTENSION_ACK_PATH_ENV] = outputPath;
+			const runtimeHandlers = new Map<string, Array<(payload?: unknown) => unknown>>();
+			const extensionHandlers = new Map<string, Array<(payload?: unknown) => unknown>>();
+			const pushHandler = (target: Map<string, Array<(payload?: unknown) => unknown>>, event: string, handler: (payload?: unknown) => unknown): void => {
+				target.set(event, [...(target.get(event) ?? []), handler]);
+			};
+			const emitAll = (target: Map<string, Array<(payload?: unknown) => unknown>>, event: string, payload?: unknown): void => {
+				for (const handler of target.get(event) ?? []) handler(payload);
+			};
+
+			registerSubagentPromptRuntime({
+				events: { on(event: string, handler: (payload?: unknown) => unknown) { pushHandler(extensionHandlers, event, handler); } },
+				on(event: string, handler: (payload?: unknown) => unknown) { pushHandler(runtimeHandlers, event, handler); },
+			} as never);
+
+			emitAll(extensionHandlers, RUNTIME_EXTENSION_ACK_EVENT, { id: "ext.one" });
+			emitAll(extensionHandlers, RUNTIME_EXTENSION_ACK_EVENT, { id: "ext.one" });
+			emitAll(extensionHandlers, RUNTIME_EXTENSION_ACK_EVENT, { id: "bad/path" });
+			runtimeHandlers.get("agent_end")?.[0]?.({});
+			emitAll(extensionHandlers, RUNTIME_EXTENSION_ACK_EVENT, { id: "late" });
+
+			assert.deepEqual(JSON.parse(fs.readFileSync(outputPath, "utf-8")), {
+				version: 1,
+				source: "child-runtime",
+				ids: ["ext.one"],
+				omitted: 0,
+			});
+		} finally {
+			fs.rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
 	it("nudges after the tool budget soft limit and blocks configured tools after hard", () => {
 		const handlers = new Map<string, (payload: { toolName?: string }) => unknown>();
 		const sent: string[] = [];
@@ -299,6 +336,10 @@ describe("subagent prompt runtime", () => {
 	});
 
 	it("registers child watchdog lifecycle handlers only when enabled by env", () => {
+		delete process.env[CHILD_WATCHDOG_CONFIG_ENV];
+		// Clear the ack capture env explicitly: when this test suite itself runs inside a
+		// pi-subagents child, the runner sets it and an extra agent_end handler registers.
+		delete process.env[RUNTIME_EXTENSION_ACK_PATH_ENV];
 		const handlersWithout = new Map<string, unknown[]>();
 		registerSubagentPromptRuntime({
 			on(event: string, handler: unknown) {

package/dist/extensions/pi-subagents/test/unit/subagent-startup-retry.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Usage } from "../../src/shared/types.ts";
+import {
+	MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS,
+	SUBAGENT_STARTUP_RETRY_DELAYS_MS,
+	formatSubagentStartupRetryExhaustedError,
+	formatSubagentStartupRetryNote,
+	isRetryableSubagentStartupFailure,
+	waitForSubagentStartupRetry,
+	type SubagentStartupFailureEvidence,
+} from "../../src/runs/shared/subagent-startup-retry.ts";
+
+function emptyUsage(): Usage {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+}
+
+function startupFailure(overrides: Partial<SubagentStartupFailureEvidence> = {}): SubagentStartupFailureEvidence {
+	return {
+		exitCode: 1,
+		messageCount: 0,
+		toolCount: 0,
+		usage: emptyUsage(),
+		durationMs: 20,
+		...overrides,
+	};
+}
+
+describe("subagent startup retry", () => {
+	it("uses a bounded retry schedule", () => {
+		assert.deepEqual(SUBAGENT_STARTUP_RETRY_DELAYS_MS, [250, 750, 1500]);
+	});
+
+	it("classifies a short non-zero exit with no child activity", () => {
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure()), true);
+	});
+
+	it("rejects successful, long-running, and diagnosed exits", () => {
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ exitCode: 0 })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ durationMs: MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS + 1 })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ error: "authentication failed" })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ finalOutput: "partial response" })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ protocolError: { code: "protocol_output_limit" } })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ processSignal: "SIGKILL" })), false);
+	});
+
+	it("rejects any model, tool, usage, mutation, or lifecycle activity", () => {
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ messageCount: 1 })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ toolCount: 1 })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ usage: { ...emptyUsage(), input: 1 } })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ usage: { ...emptyUsage(), turns: 1 } })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ observedMutationAttempt: true })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ detached: true })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ interrupted: true })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ timedOut: true })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ stopped: true })), false);
+		assert.equal(isRetryableSubagentStartupFailure(startupFailure({ turnBudgetExceeded: true })), false);
+	});
+
+	it("formats retry and exhaustion diagnostics without task content", () => {
+		assert.equal(
+			formatSubagentStartupRetryNote({ model: "openai/test", attempt: 1, maxAttempts: 4, delayMs: 250 }),
+			"[startup-retry] openai/test exited before model or tool activity (attempt 1/4). Retrying the same model in 250ms.",
+		);
+		assert.match(
+			formatSubagentStartupRetryExhaustedError({ model: "openai/test", attempts: 4 }),
+			/failed to start after 4 attempts.*concurrent Pi startup race.*lower subagent concurrency/i,
+		);
+	});
+
+	it("cancels a pending retry delay", async () => {
+		const controller = new AbortController();
+		const wait = waitForSubagentStartupRetry(5000, [controller.signal]);
+		controller.abort();
+		assert.equal(await wait, false);
+	});
+});