@selesai/code 0.5.29 → 0.6.1

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" }]);

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

@@ -367,8 +367,9 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 		assert.doesNotMatch(firstTaskArg, /\[Write to:|Write your findings to exactly this path/);
 		assert.ok(result.details.results[0]?.savedOutputPath);
 		assert.equal(fs.readFileSync(result.details.results[0].savedOutputPath, "utf-8"), "full chain output\nwith details");
-		assert.match(result.details.results[0]?.finalOutput ?? "", /Output saved to:/);
-		assert.doesNotMatch(result.details.results[0]?.finalOutput ?? "", /full chain output/);
+		assert.equal(result.details.results[0]?.finalOutput, undefined);
+		assert.match(result.details.results[0]?.outputReference?.message ?? "", /Output saved to:/);
+		assert.doesNotMatch(result.details.results[0]?.outputReference?.message ?? "", /full chain output/);
 		const secondTaskArg = readCallArgs(1).at(-1) ?? "";
 		assert.match(secondTaskArg, /Output saved to:/);
 		assert.match(secondTaskArg, /2 lines/);
@@ -404,7 +405,8 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 		);
 
 		assert.ok(!result.isError, `chain should succeed: ${JSON.stringify(result.content)}`);
-		assert.match(result.details.results[0]?.finalOutput ?? "", /Output saved to:/);
+		assert.equal(result.details.results[0]?.finalOutput, undefined);
+		assert.match(result.details.results[0]?.outputReference?.message ?? "", /Output saved to:/);
 		assert.equal(result.details.results[0]?.acceptance?.status, "checked");
 		assert.ok(result.details.results[0]?.acceptance?.childReport);
 
@@ -630,10 +632,13 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 
 		assert.ok(!result.isError);
 		const step2Task = result.details.results[1].task;
+		// Reference-first handoff: {previous} carries the saved-output reference and
+		// the step reads the named path instead of re-inlined prose.
 		assert.ok(
-			step2Task.includes("MARKER_ABC_123"),
-			`step 2 task should contain step 1 output via {previous}: ${step2Task.slice(0, 200)}`,
+			step2Task.includes("Output saved to:"),
+			`step 2 task should contain the saved-output reference via {previous}: ${step2Task.slice(0, 200)}`,
 		);
+		assert.doesNotMatch(step2Task, /MARKER_ABC_123/);
 	});
 
 	it("passes named sequential outputs through {outputs.name}", async () => {
@@ -652,7 +657,8 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 		);
 
 		assert.ok(!result.isError);
-		assert.match(readCallArgs(1).at(-1) ?? "", /CTX_123/);
+		assert.match(readCallArgs(1).at(-1) ?? "", /Output saved to: /);
+		assert.doesNotMatch(readCallArgs(1).at(-1) ?? "", /CTX_123/);
 		assert.equal(result.details.workflowGraph?.nodes[0]?.outputName, "contextOutput");
 	});
 
@@ -692,9 +698,10 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 		assert.match(readCallArgs(1).at(-1) ?? "", /Review src\/a\.ts/);
 		assert.match(readCallArgs(2).at(-1) ?? "", /Review src\/b\.ts/);
 		assert.match(readCallArgs(3).at(-1) ?? "", /"key":"src\/a\.ts"/);
-		const collected = result.details.outputs?.reviews?.structured as Array<{ key: string; structured: unknown }>;
-		assert.deepEqual(collected.map((item) => item.key), ["src/a.ts", "src/b.ts"]);
-		assert.deepEqual(collected.map((item) => item.structured), [{ ok: "a" }, { ok: "b" }]);
+		// Terminal details strip chain outputs text/structured; bindings remain
+		// reference-first via {outputs.name} and the workflow graph keeps item keys.
+		assert.equal(result.details.outputs?.reviews?.text, "");
+		assert.equal(result.details.outputs?.reviews?.structured, undefined);
 		const dynamicNode = result.details.workflowGraph?.nodes[1];
 		assert.equal(dynamicNode?.kind, "dynamic-parallel-group");
 		assert.deepEqual(dynamicNode?.children?.map((child) => child.itemKey), ["src/a.ts", "src/b.ts"]);
@@ -868,7 +875,7 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 					{ agent: "scout", task: "Return targets", as: "targets", outputSchema: { type: "object" } },
 					{
 						expand: { from: { output: "targets", path: "/items" }, key: "/path", maxItems: 4 },
-						parallel: { agent: "reviewer", task: "Review {item.path}", outputMode: "file-only" },
+						parallel: { agent: "reviewer", task: "Review {item.path}", output: false, outputMode: "file-only" },
 						collect: { as: "reviews" },
 					},
 				],
@@ -906,7 +913,8 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 
 		assert.ok(!result.isError, `chain should succeed: ${JSON.stringify(result.content)}`);
 		assert.equal(mockPi.callCount(), 2);
-		assert.deepEqual(result.details.outputs?.reviews?.structured, []);
+		assert.equal(result.details.outputs?.reviews?.text, "");
+		assert.equal(result.details.outputs?.reviews?.structured, undefined);
 		assert.equal(result.details.workflowGraph?.nodes[1]?.status, "completed");
 		assert.deepEqual(result.details.workflowGraph?.nodes[1]?.children, []);
 	});
@@ -1123,7 +1131,9 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 		assert.equal(result.details.results.length, 2);
 		assert.equal(result.details.results[0]?.acceptance?.status, "rejected");
 		assert.equal(result.details.results[0]?.exitCode, 0);
-		assert.match(result.details.results[1]?.finalOutput ?? "", /Step 2 ran/);
+		assert.equal(result.details.results[1]?.finalOutput, undefined);
+		assert.ok(result.details.results[1]?.savedOutputPath);
+		assert.equal(fs.readFileSync(result.details.results[1]!.savedOutputPath!, "utf-8"), "Step 2 ran");
 	});
 
 	it("agent contract v1 chain can gate progression on acceptance", async () => {
@@ -1195,7 +1205,8 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 		);
 
 		const finalTaskArg = readCallArgs(chainLength - 1).at(-1) ?? "";
-		assert.match(finalTaskArg, /step-38-output/);
+		assert.match(finalTaskArg, /Output saved to: /);
+		assert.doesNotMatch(finalTaskArg, /step-38-output/);
 		assert.doesNotMatch(finalTaskArg, /step-37-output/);
 		assert.match(result.content[0]?.text ?? "", /40 steps/);
 	});
@@ -1284,7 +1295,9 @@ describe("chain execution — sequential", { skip: !available ? "pi packages not
 			);
 
 			assert.ok(!result.isError);
-			assert.deepEqual(JSON.parse(result.details.results[0].finalOutput ?? "{}"), {
+			const depthChild = result.details.results[0];
+			assert.ok(depthChild.savedOutputPath);
+			assert.deepEqual(JSON.parse(fs.readFileSync(depthChild.savedOutputPath, "utf-8")), {
 				SELESAI_SUBAGENT_DEPTH: "1",
 				SELESAI_SUBAGENT_MAX_DEPTH: "1",
 			});
@@ -1474,8 +1487,9 @@ describe("chain execution — parallel steps", { skip: !available ? "pi packages
 
 		assert.ok(!result.isError);
 		const finalTask = readCallArgs(2).at(-1) ?? "";
-		assert.match(finalTask, /Alpha named output/);
-		assert.match(finalTask, /Beta named output/);
+		assert.match(finalTask, /Output saved to: /);
+		assert.doesNotMatch(finalTask, /Alpha named output/);
+		assert.doesNotMatch(finalTask, /Beta named output/);
 	});
 
 	it("funnels an initial parallel step through one agent, then fans the funnel output back out", async () => {
@@ -1512,13 +1526,14 @@ describe("chain execution — parallel steps", { skip: !available ? "pi packages
 		assert.equal(result.details.totalSteps, 3);
 		const funnelTask = readCallArgsMatching("Synthesize:").at(-1) ?? "";
 		assert.match(funnelTask, /=== Parallel Task 1 \(scout-a\) ===/);
-		assert.match(funnelTask, /Scout A findings/);
 		assert.match(funnelTask, /=== Parallel Task 2 \(scout-b\) ===/);
-		assert.match(funnelTask, /Scout B findings/);
+		assert.match(funnelTask, /Output saved to: /);
+		assert.doesNotMatch(funnelTask, /Scout A findings/);
+		assert.doesNotMatch(funnelTask, /Scout B findings/);
 		const fanoutTaskA = readCallArgsMatching("Review funnel A:").at(-1) ?? "";
 		const fanoutTaskB = readCallArgsMatching("Review funnel B:").at(-1) ?? "";
-		assert.match(fanoutTaskA, /Review funnel A:\nFunnel synthesis/);
-		assert.match(fanoutTaskB, /Review funnel B:\nFunnel synthesis/);
+		assert.match(fanoutTaskA, /Review funnel A:\nOutput saved to: /);
+		assert.match(fanoutTaskB, /Review funnel B:\nOutput saved to: /);
 		assert.equal(result.details.workflowGraph?.nodes[0]?.kind, "parallel-group");
 		assert.equal(result.details.workflowGraph?.nodes[1]?.kind, "step");
 		assert.equal(result.details.workflowGraph?.nodes[2]?.kind, "parallel-group");
@@ -1560,7 +1575,7 @@ describe("chain execution — parallel steps", { skip: !available ? "pi packages
 			makeChainParams(
 				[{
 					parallel: [
-						{ agent: "reviewer-a", task: "Review A", outputMode: "file-only" },
+						{ agent: "reviewer-a", task: "Review A", output: false, outputMode: "file-only" },
 						{ agent: "reviewer-b", task: "Review B", output: "b.md" },
 					],
 				}],

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

@@ -310,7 +310,8 @@ describe("fork context execution wiring", { skip: !available ? "subagent executo
 
 		assert.equal(result.isError, undefined);
 		const args = readCallArgs();
-		assert.ok((args.at(-1) ?? "").startsWith("Task: \n\n## Acceptance Contract"));
+		assert.ok((args.at(-1) ?? "").startsWith("Task: \n\n---\n**Output:**"));
+		assert.match(args.at(-1) ?? "", /## Acceptance Contract/);
 	});
 
 	it("does not treat top-level agent as single mode when tasks are present", async () => {
@@ -327,7 +328,8 @@ describe("fork context execution wiring", { skip: !available ? "subagent executo
 
 		assert.equal(result.isError, undefined);
 		const args = readCallArgs();
-		assert.ok((args.at(-1) ?? "").startsWith("Task: parallel task\n\n## Acceptance Contract"));
+		assert.ok((args.at(-1) ?? "").startsWith("Task: parallel task\n\n---\n**Output:**"));
+		assert.match(args.at(-1) ?? "", /## Acceptance Contract/);
 	});
 
 	it("uses agent defaultContext fork when launch context is omitted", async () => {
@@ -1827,7 +1829,7 @@ describe("fork context execution wiring", { skip: !available ? "subagent executo
 		);
 
 		assert.equal(result.isError, undefined);
-		const args = readAllCallArgs().find((callArgs) => (callArgs.at(-1) ?? "").startsWith(`Task: ${task}\n\n## Acceptance Contract`));
+		const args = readAllCallArgs().find((callArgs) => (callArgs.at(-1) ?? "").startsWith(`Task: ${task}\n\n---\n**Output:**`));
 		assert.ok(args, "expected a recorded mock pi call for this test task");
 		const modelIndex = args.indexOf("--model");
 		assert.notEqual(modelIndex, -1);

package/dist/extensions/pi-subagents/test/integration/intercom-result-delivery.test.ts

@@ -227,10 +227,13 @@ describe("intercom result delivery cutover", { skip: !available ? "executor not
 		assert.match(result.content[0]?.text ?? "", /Delivered single subagent result via intercom\./);
 		assert.doesNotMatch(result.content[0]?.text ?? "", /Full child output from worker/);
 		assert.equal(result.details?.results?.[0]?.finalOutput, undefined);
-		assert.match(String(payload.message ?? ""), /Full child output from worker/);
+		// Reference-first intercom delivery: the child summary is the saved-output
+		// reference (error/status first for failed children), never raw child prose.
+		assert.match(String(payload.message ?? ""), /Output saved to: /);
+		assert.doesNotMatch(String(payload.message ?? ""), /Full child output from worker/);
 	});
 
-	it("falls back to legacy foreground output when the bridge is inactive", async () => {
+	it("returns the native saved-output receipt when the bridge is inactive", async () => {
 		mockPi.onCall({ output: "Legacy foreground output" });
 		const { executor, events } = makeExecutor({ bridgeMode: "off" });
 
@@ -243,10 +246,14 @@ describe("intercom result delivery cutover", { skip: !available ? "executor not
 		);
 
 		assert.equal(events.emitted.some((entry) => entry.channel === "subagent:result-intercom"), false);
-		assert.match(result.content[0]?.text ?? "", /Legacy foreground output/);
+		assert.match(result.content[0]?.text ?? "", /Output saved to: /);
+		assert.doesNotMatch(result.content[0]?.text ?? "", /Legacy foreground output/);
+		const runId = result.details?.runId;
+		assert.ok(runId);
+		assert.equal(fs.readFileSync(path.join(tempDir, ".pi-subagents", "artifacts", "outputs", runId, "result.md"), "utf-8"), "Legacy foreground output");
 	});
 
-	it("keeps native foreground output without attempting external grouped delivery when disabled", async () => {
+	it("keeps the native saved-output receipt without attempting external grouped delivery when disabled", async () => {
 		mockPi.onCall({ output: "Native foreground output" });
 		const { executor, events } = makeExecutor({ resultDelivery: false });
 
@@ -259,10 +266,11 @@ describe("intercom result delivery cutover", { skip: !available ? "executor not
 		);
 
 		assert.equal(events.emitted.some((entry) => entry.channel === "subagent:result-intercom"), false);
-		assert.match(result.content[0]?.text ?? "", /Native foreground output/);
+		assert.match(result.content[0]?.text ?? "", /Output saved to: /);
+		assert.doesNotMatch(result.content[0]?.text ?? "", /Native foreground output/);
 	});
 
-	it("falls back to legacy foreground output when grouped delivery is not acknowledged", async () => {
+	it("falls back to the compact native saved-output receipt when grouped delivery is not acknowledged", async () => {
 		mockPi.onCall({ output: "Unacknowledged foreground output" });
 		const { executor, events } = makeExecutor({ acknowledgeResults: false });
 
@@ -275,7 +283,8 @@ describe("intercom result delivery cutover", { skip: !available ? "executor not
 		);
 
 		assert.equal(events.emitted.some((entry) => entry.channel === "subagent:result-intercom"), true);
-		assert.match(result.content[0]?.text ?? "", /Unacknowledged foreground output/);
+		assert.match(result.content[0]?.text ?? "", /Output saved to: /);
+		assert.doesNotMatch(result.content[0]?.text ?? "", /Unacknowledged foreground output/);
 	});
 
 	it("top-level parallel runs emit one grouped event containing all children", async () => {
@@ -1250,7 +1259,10 @@ describe("intercom result delivery cutover", { skip: !available ? "executor not
 		const payload = completion.payload as { success?: boolean; summary?: string };
 		assert.equal(payload.success, false);
 		assert.match(payload.summary ?? "", /Acceptance rejected/);
-		assert.match(payload.summary ?? "", /final answer with rejected acceptance evidence/);
+		// Reference-first foreground completion: the recovery summary carries the
+		// saved-output reference (with error/status), never raw child prose.
+		assert.match(payload.summary ?? "", /Output saved to: /);
+		assert.doesNotMatch(payload.summary ?? "", /final answer with rejected acceptance evidence/);
 
 		const status = await executor.execute(
 			"foreground-detached-failed-status",