@selesai/code 0.5.29 → 0.6.2

package/dist/extensions/pi-subagents/src/tui/render.ts

@@ -27,6 +27,32 @@ import { contextModeBadge, contextModePrefix } from "../runs/shared/context-mode
 
 type Theme = ExtensionContext["ui"]["theme"];
 
+/**
+ * UI-side output projection: completed terminal results strip `finalOutput`/
+ * `truncation` when an authoritative saved output path exists (see
+ * compactForegroundResult). The terminal renderer stays reference-first: it
+ * never re-reads the saved child output file. Settled file-only results show
+ * the saved-output reference (path/size/lines) instead of re-inlining child
+ * prose; explicit `outputMode: "inline"` results keep their full text via
+ * `finalOutput`. Legacy/foreign result data may carry `savedOutputPath` without
+ * an `outputReference`; a path-only reference is synthesized so the saved file
+ * stays discoverable without reading it.
+ */
+function formatPathOnlyOutputReference(savedOutputPath: string): string {
+	return `Output saved to: ${path.resolve(savedOutputPath)}. Read this file if needed.`;
+}
+
+function resultOutputForUi(r: Details["results"][number]): string {
+	// Explicit `outputMode: "inline"` is the sole legacy full-text opt-out:
+	// keep the inline text even when a saved output path also exists.
+	if (r.outputMode === "inline") return r.truncation?.text || getSingleResultOutput(r) || "";
+	// Settled file-backed results are reference-first: never re-read or re-inline
+	// the saved child output, even when foreign/legacy data still carries a text
+	// projection. Synthesize a path-only reference when none was persisted.
+	if (r.savedOutputPath) return r.outputReference?.message || formatPathOnlyOutputReference(r.savedOutputPath);
+	return r.truncation?.text || getSingleResultOutput(r) || "";
+}
+
 function liveDetailKeyText(): string {
 	return keyText("app.tools.expand");
 }
@@ -1308,7 +1334,7 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 }
 
 function renderSingleCompact(d: Details, r: Details["results"][number], theme: Theme, frame?: number): Component {
-	const output = r.truncation?.text || getSingleResultOutput(r);
+	const output = resultOutputForUi(r);
 	const progress = r.progress || r.progressSummary;
 	const isRunning = r.progress?.status === "running";
 	const contextBadge = contextModeBadge(theme, r.context ?? d.context);
@@ -1418,7 +1444,7 @@ function renderMultiCompact(d: Details, theme: Theme, frame?: number): Component
 			c.addChild(new Text(truncLine(theme.fg("dim", `  ◦ ${pendingLabel}: ${agentName} · pending`), width), 0, 0));
 			continue;
 		}
-		const output = getSingleResultOutput(r);
+		const output = resultOutputForUi(r);
 		const progressFromArray = d.progress?.find((p) => p.index === i) || d.progress?.find((p) => p.agent === r.agent && p.status === "running");
 		const rProg = r.progress || progressFromArray || r.progressSummary;
 		const rRunning = rProg && "status" in rProg && rProg.status === "running";
@@ -1500,7 +1526,7 @@ export function renderSubagentResult(
 					? theme.fg("success", "ok")
 					: theme.fg("error", "failed");
 		const contextBadge = contextModeBadge(theme, r.context ?? d.context);
-		const output = r.truncation?.text || getSingleResultOutput(r);
+		const output = resultOutputForUi(r);
 
 		const progressInfo = isRunning && r.progress
 			? ` | ${r.progress.toolCount} tools, ${formatTokens(r.progress.tokens)} tok, ${formatDuration(r.progress.durationMs)}`
@@ -1600,7 +1626,7 @@ export function renderSubagentResult(
 	const hasEmptyWithoutTarget = d.results.some((r) =>
 		r.exitCode === 0
 		&& r.progress?.status !== "running"
-		&& hasEmptyTextOutputWithoutOutputTarget(r.task, getSingleResultOutput(r)),
+		&& hasEmptyTextOutputWithoutOutputTarget(r.task, resultOutputForUi(r)),
 	);
 	const hasWorkflowFailure = workflowGraphHasStatus(d, ["failed"]);
 	const hasWorkflowStop = d.results.some((r) => r.stopped && r.progress?.status !== "running") || workflowGraphHasStatus(d, ["stopped"]);
@@ -1658,7 +1684,7 @@ export function renderSubagentResult(
 					const isComplete = result && result.exitCode === 0 && result.progress?.status !== "running";
 					const isEmptyWithoutTarget = Boolean(result)
 						&& Boolean(isComplete)
-						&& hasEmptyTextOutputWithoutOutputTarget(result.task, getSingleResultOutput(result));
+						&& hasEmptyTextOutputWithoutOutputTarget(result.task, resultOutputForUi(result));
 					const isCurrent = i === (d.currentStepIndex ?? d.results.length);
 					const stepIcon = isFailed
 						? theme.fg("error", "failed")
@@ -1729,7 +1755,7 @@ export function renderSubagentResult(
 		const rRunning = rProg?.status === "running";
 		const stepNumber = typeof rProg?.index === "number" ? rProg.index + 1 : i + 1;
 
-		const resultOutput = getSingleResultOutput(r);
+		const resultOutput = resultOutputForUi(r);
 		const statusIcon = rRunning
 			? theme.fg("warning", "running")
 			: r.exitCode !== 0

package/dist/extensions/pi-subagents/test/e2e/real-session-subagent.test.ts

@@ -13,6 +13,7 @@
 
 import { afterEach, describe, it } from "node:test";
 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 { tryImport } from "../support/helpers.ts";
@@ -23,6 +24,17 @@ const piAi = await tryImport<unknown>("@earendil-works/pi-ai");
 const available = Boolean(piCodingAgent && piAi);
 
 const CHILD_MARKER = "CHILD_REAL_SESSION_OK";
+
+/**
+ * Reference-first tool results: completion content carries "Output saved to:
+ * <path> (…)". Read the durable file to inspect the full child output.
+ */
+function readSavedOutput(text: string): string {
+	const rest = text.split("Output saved to: ")[1];
+	assert.ok(rest, `expected a saved-output reference in: ${text.slice(0, 160)}`);
+	const outputPath = rest.split(" (")[0]!;
+	return fs.readFileSync(outputPath, "utf-8");
+}
 // Env vars the runner must clear so a parent that was itself spawned as a
 // subagent child can still launch fresh children. The values are deliberately
 // bogus sentinels (nonexistent paths) so a leaked value would break spawning.
@@ -122,10 +134,14 @@ Use the available tools.`;
 		const chainDetails = JSON.stringify((toolMessages[1] as { details?: unknown } | undefined)?.details);
 		const structuredDetails = JSON.stringify((toolMessages[2] as { details?: unknown } | undefined)?.details);
 		assert.equal(results.length, 4);
-		assert.match(results[0] ?? "", /ACTIVE_TOOLS:[^\n]*fixture_search/);
-		assert.match(results[0] ?? "", /ACTIVE_TOOLS:[^\n]*read/);
-		assert.match(chainDetails, /ACTIVE_TOOLS:[^\n]*fixture_search/);
-		assert.match(chainDetails, /ACTIVE_TOOLS:[^\n]*read/);
+		const directOutput = readSavedOutput(results[0] ?? "");
+		assert.match(directOutput, /ACTIVE_TOOLS:[^\n]*fixture_search/);
+		assert.match(directOutput, /ACTIVE_TOOLS:[^\n]*read/);
+		const chainFirstChild = (toolMessages[1] as { details?: { results?: Array<{ savedOutputPath?: string }> } } | undefined)?.details?.results?.[0];
+		assert.ok(chainFirstChild?.savedOutputPath, "chain details should carry the saved output path");
+		const chainOutput = fs.readFileSync(chainFirstChild.savedOutputPath, "utf-8");
+		assert.match(chainOutput, /ACTIVE_TOOLS:[^\n]*fixture_search/);
+		assert.match(chainOutput, /ACTIVE_TOOLS:[^\n]*read/);
 		assert.match(structuredDetails, /STRUCTURED_OUTPUT_OK/);
 		assert.match(results[3] ?? "", /requested unavailable child tools: missing_search/);
 		assert.match(results[3] ?? "", /subagentOnlyExtensions/);
@@ -172,7 +188,8 @@ Report active tools.`;
 
 		const results = subagentToolResults(run.parentSession);
 		assert.equal(results.length, 1);
-		assert.match(results[0] ?? "", /ACTIVE_TOOLS:[^\n]*fixture_async_search/);
+		const asyncOutput = readSavedOutput(results[0] ?? "");
+		assert.match(asyncOutput, /ACTIVE_TOOLS:[^\n]*fixture_async_search/);
 		assert.doesNotMatch(results[0] ?? "", /requested unavailable child tools/);
 	});
 
@@ -206,7 +223,7 @@ Report active tools.`;
 
 			const toolResults = subagentToolResults(run.parentSession);
 			assert.equal(toolResults.length, 1);
-			assert.match(toolResults[0]!, new RegExp(CHILD_MARKER));
+			assert.match(readSavedOutput(toolResults[0]!), new RegExp(CHILD_MARKER));
 			assert.match(run.responseText, new RegExp(CHILD_MARKER));
 			assert.doesNotMatch(run.responseText, /CHILD_MISSING/);
 			assert.ok(run.modelCalls >= 2, `expected parent tool-call and final turns, got ${run.modelCalls}`);
@@ -219,4 +236,92 @@ Report active tools.`;
 			}
 		}
 	});
+
+	function latestSubagentToolResultText(messages: Array<{ role?: string; toolName?: string; content?: unknown }>): string | undefined {
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const message = messages[i]!;
+			if (message.role === "toolResult" && message.toolName === "subagent") {
+				return Array.isArray(message.content)
+					? message.content
+						.map((part) => part && typeof part === "object" && (part as { type?: unknown }).type === "text"
+							? String((part as { text?: unknown }).text ?? "")
+							: "")
+						.join("")
+					: "";
+			}
+		}
+		return undefined;
+	}
+
+	it("lists then delegates to a non-bundled discovered writer in a broad-mutation request", async () => {
+		const { runRealSubagentSession, subagentCall, subagentToolResults } = await import("../support/real-session-runner.ts");
+		const writerAgent = `---
+name: fixture-writer
+description: Scoped mutation-capable fixture writer
+aliases: fw
+tools: read, grep, find, ls, bash, edit, write
+acceptanceRole: writer
+defaultContext: fork
+completionGuard: false
+---
+Implement the scoped fixture change and return the marker.`;
+
+		run = await runRealSubagentSession({
+			prompt: "Implement the fixture change across the codebase.",
+			childText: CHILD_MARKER,
+			projectFiles: {
+				".selesai/agents/fixture-writer.md": writerAgent,
+			},
+			respond(context) {
+				const messages = context.messages as Array<{ role?: string; toolName?: string; content?: unknown; details?: unknown }>;
+				const subagentResults = messages.filter((message) => message.role === "toolResult" && message.toolName === "subagent");
+				if (subagentResults.length === 0) {
+					return subagentCall({ action: "list", agentScope: "project" }, "call-list-writer");
+				}
+				if (subagentResults.length === 1) {
+					const listText = latestSubagentToolResultText(messages) ?? "";
+					assert.match(
+						listText,
+						/- fixture-writer \(project, context: fork, role: writer, aliases: fw, tools: read, grep, find, ls, bash, edit, write\)/,
+						"catalog must expose the custom writer with its runtime metadata",
+					);
+					const listedDetails = JSON.stringify(subagentResults.at(-1)?.details ?? {});
+					assert.match(listedDetails, /"catalog"/);
+					assert.match(listedDetails, /"fixture-writer"/);
+					assert.match(listedDetails, /"acceptanceRole":"writer"/);
+					return subagentCall(
+						{ agent: "fixture-writer", task: "Implement the change and return the marker.", context: "fresh", agentScope: "project" },
+						"call-fixture-writer",
+					);
+				}
+				return "Broad mutation work complete.";
+			},
+			timeoutMs: 60_000,
+		});
+
+		const results = subagentToolResults(run.parentSession);
+		assert.equal(results.length, 2);
+		assert.match(results[0] ?? "", /fixture-writer \(project, context: fork, role: writer/);
+		assert.match(readSavedOutput(results[1] ?? ""), new RegExp(CHILD_MARKER));
+	});
+
+	it("keeps tiny targeted reads local without a subagent call", async () => {
+		const { runRealSubagentSession, subagentToolResults } = await import("../support/real-session-runner.ts");
+		run = await runRealSubagentSession({
+			prompt: "What does the README say about subagents?",
+			childText: CHILD_MARKER,
+			projectFiles: {
+				"README.md": "Subagents are delegated workers.",
+			},
+			respond() {
+				return "The README says: Subagents are delegated workers.";
+			},
+			timeoutMs: 60_000,
+		});
+
+		const results = subagentToolResults(run.parentSession);
+		assert.equal(results.length, 0);
+		assert.match(run.responseText, /Subagents are delegated workers/);
+		assert.ok(run.modelCalls >= 1, `expected at least one parent turn, got ${run.modelCalls}`);
+	});
 });

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

@@ -80,7 +80,7 @@ interface AsyncResultPayload {
 	totalCost?: { inputTokens: number; outputTokens: number; costUsd: number };
 	usageBudget?: UsageBudgetState;
 	checkpoint?: { name?: string; status?: string };
-	results: Array<{ agent?: 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; 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 }; structuredOutput?: unknown; agentContract?: { version: 1 }; execution?: { status?: string; success?: boolean; exitCode?: number }; effects?: { fileMutation?: { status?: string; expected?: boolean; attempted?: 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 }; capabilityCeiling?: { version?: number; allowedTools?: string[]; denyExtensions?: boolean; sources?: string[] }; capabilityAudit?: { effectiveTools?: string[]; removedTools?: string[]; extensionsDenied?: boolean } }>;
+	results: Array<{ agent?: string; launchContractDigest?: string; launchResolvedExtensions?: LaunchResolvedExtensions; runtimeAcknowledgedExtensions?: RuntimeAcknowledgedExtensions; output?: string; outputPath?: string; outputState?: "present" | "absent" | "unknown"; success?: boolean; error?: string; protocolError?: { code?: string; stream?: string; limitBytes?: number; observedBytes?: number }; timedOut?: boolean; 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 }; structuredOutput?: unknown; agentContract?: { version: 1 }; execution?: { status?: string; success?: boolean; exitCode?: number }; effects?: { fileMutation?: { status?: string; expected?: boolean; attempted?: 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 }; 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 };
@@ -453,6 +453,18 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		return JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 	}
 
+	/**
+	 * Reference-first async child assertion: the result payload carries the
+	 * saved-output reference; the full text is read from the durable output path.
+	 */
+	function assertAsyncChildOutput(payload: AsyncResultPayload, index: number, expected: string): void {
+		const child = payload.results[index];
+		assert.ok(child, `expected async child ${index}`);
+		assert.match(child.output ?? "", /Output saved to: /);
+		assert.ok(child.outputPath, `expected a durable output path for child ${index}`);
+		assert.equal(fs.readFileSync(child.outputPath, "utf-8"), expected);
+	}
+
 	function launchProtocolTest(id: string): void {
 		executeAsyncSingle(id, {
 			agent: "worker",
@@ -480,7 +492,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		launchProtocolTest(id);
 		const payload = await readAsyncPayload(id);
 		assert.equal(payload.success, true);
-		assert.equal(payload.results[0]?.output, "你好 from fragmented async JSON");
+		assertAsyncChildOutput(payload, 0, "你好 from fragmented async JSON");
 	});
 
 	it("persists absent output provenance when async lifecycle text is synthetic", { skip: !isAsyncAvailable() ? "jiti not available" : undefined }, async () => {
@@ -500,7 +512,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		const payload = await readAsyncPayload(id);
 		assert.equal(payload.success, false);
 		assert.equal(payload.results[0]?.outputState, "present");
-		assert.equal(payload.results[0]?.output, "usable partial answer");
+		assertAsyncChildOutput(payload, 0, "usable partial answer");
 	});
 
 	it("matches preflight launch digest in equivalent foreground and async execution", { skip: !isAsyncAvailable() ? "jiti not available" : undefined }, async () => {
@@ -512,11 +524,14 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		fs.writeFileSync(agentPath, `---\nname: ${agentName}\ndescription: Contract comparison worker\n---\n`, "utf-8");
 		const discovered = discoverAgents(tempDir).agents.find((agent) => agent.name === agentName);
 		assert.ok(discovered, "expected temporary agent definition to be discovered");
-		const preflight = await resolveSubagentLaunchContract({ agent: agentName, cwd: tempDir, task, turnBudget, runId: "contract-preflight" });
+		// Stable explicit output keeps the preflight launch contract equivalent to
+		// both execution paths (generated per-run paths would differ by design).
+		const contractOutputPath = path.join(tempDir, "contract-output.md");
+		const preflight = await resolveSubagentLaunchContract({ agent: agentName, cwd: tempDir, task, turnBudget, runId: "contract-preflight", output: contractOutputPath });
 		assert.equal(preflight.ok, true);
 
 		mockPi.onCall({ output: "foreground contract comparison" });
-		const foreground = await runSync(tempDir, [discovered], agentName, task, { runId: "contract-foreground", acceptance: false, turnBudget });
+		const foreground = await runSync(tempDir, [discovered], agentName, task, { runId: "contract-foreground", acceptance: false, turnBudget, outputPath: contractOutputPath });
 		assert.equal(foreground.exitCode, 0);
 		assert.equal(foreground.launchContractDigest, preflight.contract.launchContractDigest);
 
@@ -525,6 +540,8 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		const launch = executeAsyncSingle(asyncId, {
 			agent: agentName,
 			task,
+			output: contractOutputPath,
+			outputMode: "inline",
 			agentConfig: discovered,
 			ctx: { pi: { events: { emit() {} } }, cwd: tempDir, currentSessionId: "session-1" },
 			artifactConfig: { enabled: false, includeInput: false, includeOutput: false, includeJsonl: false, includeMetadata: false, cleanupDays: 7 },
@@ -721,7 +738,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 
 		const launch = await executor.execute(
 			"async-session-artifact-dir",
-			{ agent: "worker", task: "Write async session artifacts", async: true, runId: "async-session-artifacts", acceptance: false },
+			{ agent: "worker", task: "Write async session artifacts", async: true, runId: "async-session-artifacts", acceptance: false, artifacts: true },
 			new AbortController().signal,
 			undefined,
 			ctx,
@@ -829,7 +846,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		launchProtocolTest(id);
 		const payload = await readAsyncPayload(id);
 		assert.equal(payload.success, true);
-		assert.equal(payload.results[0]?.output, "settled async response");
+		assertAsyncChildOutput(payload, 0, "settled async response");
 		assert.ok(Date.now() - startedAt >= 1200, "background runner must not terminate during the retry delay");
 	});
 
@@ -841,7 +858,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		const payload = await readAsyncPayload(id);
 		assert.equal(payload.success, true);
 		assert.equal(payload.results[0]?.error, undefined);
-		assert.equal(payload.results[0]?.output, "settled async without a terminal assistant stop");
+		assertAsyncChildOutput(payload, 0, "settled async without a terminal assistant stop");
 		assert.ok(Date.now() - startedAt < 4000, "agent_settled should trigger bounded child cleanup");
 	});
 
@@ -872,7 +889,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.match(call.args.at(-1) ?? "", /\{outputs\.name\}/);
 		const payload = await readAsyncPayload(id);
 		assert.equal(payload.success, true);
-		assert.equal(payload.results[0]?.output, "OK");
+		assertAsyncChildOutput(payload, 0, "OK");
 	});
 
 	it("spawns the async runner with node when process.execPath is not node", { skip: !isAsyncAvailable() ? "jiti not available" : undefined }, async () => {
@@ -903,7 +920,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			const resultPath = await waitForAsyncResultFile(id, 30_000);
 			const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 			assert.equal(payload.success, true);
-			assert.equal(payload.results[0]?.output, "non-node exec async done");
+			assertAsyncChildOutput(payload, 0, "non-node exec async done");
 		} finally {
 			process.execPath = originalExecPath;
 		}
@@ -937,7 +954,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			const resultPath = await waitForAsyncResultFile(id, 10_000);
 			const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 			assert.equal(payload.success, true);
-			assert.equal(payload.results[0]?.output, "stale node exec async done");
+			assertAsyncChildOutput(payload, 0, "stale node exec async done");
 		} finally {
 			process.execPath = originalExecPath;
 		}
@@ -1178,8 +1195,11 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.turnBudget?.turnCount, 2);
 		assert.equal(payload.results[0]?.wrapUpRequested, true);
 		assert.equal(payload.results[0]?.turnBudget?.turnCount, 2);
-		assert.match(payload.results[0]?.output ?? "", /Turn budget wrap-up was requested after 1 assistant turn/);
-		assert.match(payload.results[0]?.output ?? "", /final wrapped output/);
+		// Reference-first delivery: the saved-output reference replaces inline prose;
+		// the wrap-up note and raw output stay visible through status/result fields
+		// and the persisted result file.
+		assert.match(payload.results[0]?.output ?? "", /Output saved to: /);
+		assertAsyncChildOutput(payload, 0, "final wrapped output");
 		assert.equal(status.wrapUpRequested, true);
 		assert.equal(status.turnBudgetExceeded, undefined);
 		assert.equal(status.steps?.[0]?.wrapUpRequested, true);
@@ -1218,8 +1238,9 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.turnBudget?.turnCount, 3);
 		assert.equal(payload.turnBudget?.exceededAtTurn, 3);
 		assert.equal(payload.results[0]?.turnBudgetExceeded, true);
-		assert.match(payload.results[0]?.output ?? "", /Partial output before turn-budget abort:/);
-		assert.match(payload.results[0]?.output ?? "", /safe assistant boundary after tool work/);
+		assert.match(payload.error ?? "", /Subagent exceeded turn budget|turn budget/i);
+		assert.match(payload.results[0]?.output ?? "", /Output saved to: /);
+		assertAsyncChildOutput(payload, 0, "safe assistant boundary after tool work");
 		assert.equal(status.state, "failed");
 		assert.equal(status.turnBudgetExceeded, true);
 		assert.equal(status.steps?.[0]?.turnBudgetExceeded, true);
@@ -1272,7 +1293,8 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.turnBudget?.outcome, "exceeded");
 		assert.equal(payload.turnBudget?.turnCount, 2);
 		assert.equal(payload.results[0]?.turnBudgetExceeded, true);
-		assert.match(payload.results[0]?.output ?? "", /safe assistant boundary reached/);
+		assert.match(payload.results[0]?.output ?? "", /Output saved to: /);
+		assertAsyncChildOutput(payload, 0, "safe assistant boundary reached");
 		assert.equal(status.state, "failed");
 		assert.equal(status.turnBudgetExceeded, true);
 		assert.equal(status.steps?.[0]?.turnBudget?.outcome, "exceeded");
@@ -1564,6 +1586,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 				tasks: [{ agent: "builder", task: "Do async work", output: "async-top-output.md", reads: ["input.md"] }],
 				async: true,
 				clarify: false,
+				artifacts: true,
 			},
 			new AbortController().signal,
 			undefined,
@@ -1622,7 +1645,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			];
 			const launch = await executor.execute(
 				`async-inherited-output-${outputOverride === true ? "true" : "omitted"}`,
-				{ tasks, async: true, clarify: false },
+				{ tasks, async: true, clarify: false, artifacts: true },
 				new AbortController().signal,
 				undefined,
 				makeMinimalCtx(tempDir),
@@ -1631,8 +1654,8 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			assert.equal(launch.isError, undefined);
 			const payload = await readAsyncPayload(launch.details?.asyncId as string);
 			assert.equal(payload.success, true);
-			assert.equal(payload.results[0]?.output?.split("\n\nOutput saved to:")[0], "first async report");
-			assert.equal(payload.results[1]?.output?.split("\n\nOutput saved to:")[0], "second async report");
+			assertAsyncChildOutput(payload, 0, "first async report");
+			assertAsyncChildOutput(payload, 1, "second async report");
 			const outputDir = path.join(tempDir, ".pi-subagents", "artifacts", "outputs", launch.details?.asyncId as string);
 			const authoritativePaths = [
 				path.join(outputDir, "parallel-0", "0-worker", "context.md"),
@@ -1694,6 +1717,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 				],
 				async: true,
 				clarify: false,
+				artifacts: true,
 			},
 			new AbortController().signal,
 			undefined,
@@ -1932,13 +1956,13 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 		const status = JSON.parse(fs.readFileSync(path.join(ASYNC_DIR, id, "status.json"), "utf-8")) as AsyncStatusPayload;
 		assert.equal(payload.success, true);
-		assert.deepEqual(payload.results.map((entry) => entry.output), [
-			"Scout A async findings",
-			"Scout B async findings",
-			"Async funnel synthesis",
-			"Async reviewer A done",
-			"Async reviewer B done",
-		]);
+		// Reference-first chain delivery: every child result carries the saved-output
+		// reference; full text is read from each durable output path.
+		assertAsyncChildOutput(payload, 0, "Scout A async findings");
+		assertAsyncChildOutput(payload, 1, "Scout B async findings");
+		assertAsyncChildOutput(payload, 2, "Async funnel synthesis");
+		assertAsyncChildOutput(payload, 3, "Async reviewer A done");
+		assertAsyncChildOutput(payload, 4, "Async reviewer B done");
 		assert.deepEqual(status.steps?.map((step) => step.status), ["complete", "complete", "complete", "complete", "complete"]);
 		assert.deepEqual(status.parallelGroups, [
 			{ start: 0, count: 2, stepIndex: 0 },
@@ -1946,11 +1970,14 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		]);
 		const funnelTask = readMockPiArgsMatching(mockPi, "Synthesize:").at(-1) ?? "";
 		assert.match(funnelTask, /=== Parallel Task 1 \(scout-a\) ===/);
-		assert.match(funnelTask, /Scout A async findings/);
 		assert.match(funnelTask, /=== Parallel Task 2 \(scout-b\) ===/);
-		assert.match(funnelTask, /Scout B async findings/);
-		assert.match(readMockPiArgsMatching(mockPi, "Review funnel A:").at(-1) ?? "", /Review funnel A:\nAsync funnel synthesis/);
-		assert.match(readMockPiArgsMatching(mockPi, "Review funnel B:").at(-1) ?? "", /Review funnel B:\nAsync funnel synthesis/);
+		// Chain handoff stays reference-first: the funnel consumes the saved-output
+		// references and reads the named paths instead of re-inlined child prose.
+		assert.match(funnelTask, /Output saved to: /);
+		assert.doesNotMatch(funnelTask, /Scout A async findings/);
+		assert.doesNotMatch(funnelTask, /Scout B async findings/);
+		assert.match(readMockPiArgsMatching(mockPi, "Review funnel A:").at(-1) ?? "", /Review funnel A:\nOutput saved to: /);
+		assert.match(readMockPiArgsMatching(mockPi, "Review funnel B:").at(-1) ?? "", /Review funnel B:\nOutput saved to: /);
 		assert.equal(payload.workflowGraph?.nodes?.[0]?.kind, "parallel-group");
 		assert.equal(payload.workflowGraph?.nodes?.[0]?.status, "completed");
 		assert.equal(payload.workflowGraph?.nodes?.[1]?.kind, "step");
@@ -2341,7 +2368,10 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		const expectedConsumerTarget = `subagent-consumer-${id}-4`;
 		assert.equal(payload.success, true);
 		assert.equal(payload.results[3]?.intercomTarget, expectedConsumerTarget);
-		assert.deepEqual(JSON.parse(payload.results[3]?.output ?? "{}"), { SELESAI_SUBAGENT_INTERCOM_SESSION_NAME: expectedConsumerTarget });
+		const consumerChild = payload.results[3];
+		assert.ok(consumerChild?.outputPath, "expected a durable output path for the consumer child");
+		assert.match(consumerChild.output ?? "", /Output saved to: /);
+		assert.deepEqual(JSON.parse(fs.readFileSync(consumerChild.outputPath, "utf-8")), { SELESAI_SUBAGENT_INTERCOM_SESSION_NAME: expectedConsumerTarget });
 	});
 
 	it("async dynamic pre-spawn failures persist failed graph status and error", { skip: !isAsyncAvailable() ? "jiti not available" : undefined }, async () => {
@@ -2428,6 +2458,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 					async: true,
 					clarify: false,
 					worktree: true,
+					artifacts: true,
 				},
 				new AbortController().signal,
 				undefined,
@@ -2632,7 +2663,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.results[0]?.model, "openai/gpt-5-mini:high");
 		assert.deepEqual(payload.results[0]?.attemptedModels, ["openai/gpt-5-mini:high"]);
 		assert.deepEqual(payload.results[0]?.modelAttempts?.map((attempt) => attempt.success), [false, true]);
-		assert.match(payload.results[0]?.output ?? "", /\[startup-retry\].*Recovered asynchronously after startup race/s);
+		assertAsyncChildOutput(payload, 0, "Recovered asynchronously after startup race");
 		assert.equal(mockPi.callCount(), 2);
 	});
 
@@ -2679,7 +2710,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		const payload = JSON.parse(fs.readFileSync(await waitForAsyncResultFile(id), "utf-8"));
 		assert.equal(payload.success, true);
 		assert.deepEqual(payload.results[0].attemptedModels, ["openai/gpt-5-mini:high", "anthropic/claude-sonnet-4:low"]);
-		assert.match(payload.results[0].output ?? "", /Recovered after stream failure/);
+		assertAsyncChildOutput(payload, 0, "Recovered after stream failure");
 		assert.equal(mockPi.callCount(), 2);
 	});
 
@@ -2820,7 +2851,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 		assert.equal(payload.success, true);
 		assert.equal(payload.results[0]?.model, "anthropic/claude-sonnet-4");
-		assert.match(payload.results[0]?.output ?? "", /Recovered asynchronously from empty output/);
+		assertAsyncChildOutput(payload, 0, "Recovered asynchronously from empty output");
 		assert.match(payload.results[0]?.modelAttempts?.[0]?.error ?? "", /no output/i);
 		assert.deepEqual(payload.results[0]?.modelAttempts?.map((attempt) => attempt.success), [false, true]);
 		assert.equal(mockPi.callCount(), 2);
@@ -2960,7 +2991,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.exitCode, 0);
 		assert.equal(payload.results[0]?.success, true);
 		assert.equal(payload.results[0]?.error, undefined);
-		assert.equal(payload.results[0]?.output, "Recovered asynchronously");
+		assertAsyncChildOutput(payload, 0, "Recovered asynchronously");
 		const statusPayload = JSON.parse(fs.readFileSync(path.join(asyncDir, "status.json"), "utf-8")) as AsyncStatusPayload;
 		assert.equal(statusPayload.state, "complete");
 		assert.equal(statusPayload.steps?.[0]?.status, "complete");
@@ -3364,7 +3395,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.success, true);
 		assert.equal(payload.exitCode, 0);
 		assert.equal(payload.results[0].success, true);
-		assert.equal(payload.results[0].output, "cold start test after patch");
+		assertAsyncChildOutput(payload, 0, "cold start test after patch");
 
 		const eventsPath = path.join(ASYNC_DIR, id, "events.jsonl");
 		const eventsText = fs.readFileSync(eventsPath, "utf-8");
@@ -4070,7 +4101,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 			assert.ok(elapsed < 6000, `unconfigured watchdog status should not delay async final drain, took ${elapsed}ms`);
 			assert.equal(payload.success, true);
-			assert.equal(payload.results[0]?.output, "async-done-without-watchdog-config");
+			assertAsyncChildOutput(payload, 0, "async-done-without-watchdog-config");
 			assert.equal((payload.results[0] as { watchdog?: unknown }).watchdog, undefined);
 		});
 	});
@@ -4105,7 +4136,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			assert.ok(elapsed >= 1200, `watchdog settlement should delay async final drain, took ${elapsed}ms`);
 			assert.ok(elapsed < 9000, `settled watchdog should still allow async cleanup, took ${elapsed}ms`);
 			assert.equal(payload.success, true);
-			assert.equal(payload.results[0]?.output, "async-done-before-watchdog");
+			assertAsyncChildOutput(payload, 0, "async-done-before-watchdog");
 			assert.equal((payload.results[0] as { watchdog?: { phase?: string } }).watchdog?.phase, "idle");
 		});
 	});
@@ -4136,7 +4167,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 			assert.ok(elapsed < 6000, `watchdog tail fallback should not hang async final drain, took ${elapsed}ms`);
 			assert.equal(payload.success, true);
-			assert.equal(payload.results[0]?.output, "async-done-before-watchdog-timeout");
+			assertAsyncChildOutput(payload, 0, "async-done-before-watchdog-timeout");
 			const watchdog = (payload.results[0] as { watchdog?: { phase?: string; timedOut?: boolean } }).watchdog;
 			assert.equal(watchdog?.phase, "stale");
 			assert.equal(watchdog?.timedOut, true);
@@ -4187,7 +4218,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.success, true);
 		assert.equal(payload.exitCode, 0);
 		assert.equal(payload.results[0].success, true);
-		assert.equal(payload.results[0].output, "async-done-before-drain");
+		assertAsyncChildOutput(payload, 0, "async-done-before-drain");
 	});
 
 	it("background forced drain after empty terminal assistant output is cleanup success", { skip: !isAsyncAvailable() ? "jiti not available" : undefined }, async () => {
@@ -4223,7 +4254,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 		assert.equal(payload.success, true);
 		assert.equal(payload.exitCode, 0);
 		assert.equal(payload.results[0].success, true);
-		assert.equal(payload.results[0].output, "");
+		assert.match(payload.results[0].output ?? "", /Output saved to: /);
 	});
 
 	it("background final-drain cleanup preserves explicit assistant errors", { skip: !isAsyncAvailable() ? "jiti not available" : undefined }, async () => {
@@ -4596,7 +4627,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 			const resultPath = await waitForAsyncResultFile(id, 10_000);
 			const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultPayload;
 			assert.equal(payload.success, true);
-			assert.equal(payload.results[0]?.output, "Done after noisy stream");
+			assertAsyncChildOutput(payload, 0, "Done after noisy stream");
 
 			const eventsText = fs.readFileSync(path.join(asyncDir, "events.jsonl"), "utf-8");
 			assert.doesNotMatch(eventsText, /"type":"message_update"/);
@@ -4675,7 +4706,7 @@ describe("async execution utilities", { skip: !available ? "pi packages not avai
 
 		const payload = JSON.parse(fs.readFileSync(resultPath, "utf-8"));
 		assert.equal(payload.success, true);
-		assert.equal(payload.results[0].output, "Done streaming");
+		assertAsyncChildOutput(payload, 0, "Done streaming");
 
 		const status = JSON.parse(fs.readFileSync(path.join(asyncDir, "status.json"), "utf-8"));
 		assert.deepEqual(status.steps[0].recentTools.map((tool: { tool: string; args: string }) => ({ tool: tool.tool, args: tool.args })), [{ tool: "bash", args: "ls" }]);