pi-cohort 7.4.0 → 7.4.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [7.4.1] - 2026-10-19
+
+### Fixed
+- Non-BLOCKED file-only failures and save errors return an artifact pointer or an explicit not-preserved reason instead of the child reply inline; BLOCKED handoffs and inline mode are unchanged. (#24)
+
 ## [7.4.0] - 2026-10-19
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.4.0",
+  "version": "7.4.1",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/runs/background/subagent-runner.ts

@@ -7,7 +7,7 @@ import type { Message } from "@earendil-works/pi-ai";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { appendJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
 import { getPiSpawnCommand, parsePiRuntime, PiRuntimeLaunchError, type PiRuntimeIdentity } from "../shared/pi-spawn.ts";
-import { captureSingleOutputSnapshot, finalizeSingleOutput, formatSavedOutputReference, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, finalizeSingleOutput, formatFileOnlyFailure, formatSavedOutputReference, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	type ActivityState,
 	type ArtifactConfig,
@@ -1007,6 +1007,8 @@ export async function runSingleStep(
 	let acceptanceCanFailRun = false;
 	let effectiveFinalExitCode = resolvedOutput.saveError ? 1 : finalResult?.exitCode ?? 1;
 	let effectiveFinalError = finalResult?.error;
+	let preservedAt: string | undefined;
+	let notPreservedReason = "artifact output disabled";
 	if (resolvedOutput.saveError) {
 		effectiveFinalError = effectiveFinalError
 			? `${effectiveFinalError}\n${resolvedOutput.saveError}`
@@ -1037,7 +1039,14 @@ export async function runSingleStep(
 
 	if (artifactPaths && ctx.artifactConfig?.enabled !== false) {
 		if (ctx.artifactConfig?.includeOutput !== false) {
-			fs.writeFileSync(artifactPaths.outputPath, output, "utf-8");
+			try {
+				fs.writeFileSync(artifactPaths.outputPath, output, "utf-8");
+				preservedAt = artifactPaths.outputPath;
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				notPreservedReason = `artifact write failed: ${message}`;
+				throw error;
+			}
 		}
 		if (ctx.artifactConfig?.includeMetadata !== false) {
 			fs.writeFileSync(
@@ -1063,11 +1072,14 @@ export async function runSingleStep(
 		effectiveFinalError = effectiveFinalError ? `${effectiveFinalError}\n${message}` : message;
 	}
 
+	const outputBeforeExternalFinalization = outputForSummary;
+	let externalOutputPersisted = false;
 	// Native runs have runPiStreaming write outputFile live; external runs persist it
 	// before their surface can be destructively closed as delivered.
 	if (externalOwner) {
 		try {
 			fs.writeFileSync(ctx.outputFile, outputForSummary, "utf-8");
+			externalOutputPersisted = true;
 		} catch (error) {
 			const message = safeExternalFailure("output persistence", error);
 			effectiveFinalExitCode = 1;
@@ -1090,6 +1102,30 @@ export async function runSingleStep(
 		executionSurface = { handle: finishResult.handle, retained: finishResult.retained };
 	}
 
+	if (step.outputMode === "file-only"
+		&& (effectiveFinalExitCode !== 0 || resolvedOutput.saveError)
+		&& !blockedLine(effectiveFinalError ?? "")) {
+		const pointer = formatFileOnlyFailure({
+			outputPath: step.outputPath,
+			saveError: resolvedOutput.saveError,
+			...(preservedAt !== undefined ? { preservedAt } : { notPreservedReason }),
+		});
+		outputForSummary = attemptNotes.length > 0
+			? `${attemptNotes.join("\n")}\n\n${pointer}`
+			: pointer;
+	}
+
+	// finish can turn a saved success into a failure after the pre-close log write.
+	if (externalOutputPersisted && outputForSummary !== outputBeforeExternalFinalization) {
+		try {
+			fs.writeFileSync(ctx.outputFile, outputForSummary, "utf-8");
+		} catch (error) {
+			const message = safeExternalFailure("output persistence", error);
+			effectiveFinalExitCode = 1;
+			effectiveFinalError = effectiveFinalError ? `${effectiveFinalError}\n${message}` : message;
+		}
+	}
+
 	return {
 		agent: step.agent,
 		output: outputForSummary,

package/src/runs/foreground/execution.ts

@@ -46,7 +46,7 @@ import { PINNED_AGENT_DIR_OVERRIDE } from "../../shared/agent-dir.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
-import { captureSingleOutputSnapshot, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, formatFileOnlyFailure, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import {
 	buildModelCandidates,
 	formatModelAttemptNote,
@@ -815,6 +815,8 @@ export async function runSync(
 	} satisfies SingleResult;
 
 	let postLoopError: unknown;
+	let preservedAt: string | undefined;
+	let notPreservedReason = "artifact output disabled";
 	try {
 		result.usage = aggregateUsage;
 		result.attemptedModels = attemptedModels.length > 0 ? attemptedModels : undefined;
@@ -834,7 +836,14 @@ export async function runSync(
 		if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
 			result.artifactPaths = artifactPathsResult;
 			if (options.artifactConfig?.includeOutput !== false) {
-				writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
+				try {
+					writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
+					preservedAt = artifactPathsResult.outputPath;
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					notPreservedReason = `artifact write failed: ${message}`;
+					throw error;
+				}
 			}
 			if (options.artifactConfig?.includeMetadata !== false) {
 				writeMetadata(artifactPathsResult.metadataPath, {
@@ -912,9 +921,19 @@ export async function runSync(
 				: safeMessage;
 			result.executionSurface ??= { handle: externalOwner.surface, retained: true };
 		}
-	} else if (postLoopError) {
-		throw postLoopError;
 	}
 
+	if (options.outputMode === "file-only"
+		&& (result.exitCode !== 0 || result.outputSaveError)
+		&& !blockedLine(result.error ?? "")) {
+		result.finalOutput = formatFileOnlyFailure({
+			outputPath: options.outputPath,
+			saveError: result.outputSaveError,
+			...(preservedAt !== undefined ? { preservedAt } : { notPreservedReason }),
+		});
+		result.truncation = undefined;
+	}
+	if (!externalOwner && postLoopError) throw postLoopError;
+
 	return result;
 }

package/src/runs/foreground/subagent-executor.ts

@@ -39,6 +39,7 @@ import { createForkContextResolver } from "../../shared/fork-context.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeTopLevelOutput, resolveParallelTaskOutputPath, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { blockedLine } from "../shared/completion-guard.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd } from "../../shared/utils.ts";
 import { resolveSubagentResultStatus } from "../shared/result-children.ts";
 import { buildRevivedAsyncTask, resolveAsyncResumeTarget } from "../background/async-resume.ts";
@@ -2064,7 +2065,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
 
 	const fullOutput = getSingleResultOutput(r);
-	const finalizedOutput = finalizeSingleOutput({
+	const displayOutput = r.outputMode === "file-only" ? r.finalOutput : finalizeSingleOutput({
 		fullOutput,
 		truncatedOutput: r.truncation?.text,
 		outputPath,
@@ -2073,7 +2074,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		savedPath: r.savedOutputPath,
 		outputReference: r.outputReference,
 		saveError: r.outputSaveError,
-	});
+	}).displayOutput;
 	const details = compactForegroundDetails({
 		mode: "single",
 		runId,
@@ -2096,14 +2097,14 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		};
 	}
 
-	if (r.exitCode !== 0)
-		return {
-			content: [{ type: "text", text: r.error || "Failed" }],
-			details,
-			isError: true,
-		};
+	if (r.exitCode !== 0) {
+		const text = r.outputMode === "file-only" && !blockedLine(r.error ?? "")
+			? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}\n\n${r.finalOutput ?? ""}`
+			: r.error || "Failed";
+		return { content: [{ type: "text", text }], details, isError: true };
+	}
 	return {
-		content: [{ type: "text", text: finalizedOutput.displayOutput || "(no output)" }],
+		content: [{ type: "text", text: displayOutput || "(no output)" }],
 		details,
 	};
 }

package/src/runs/shared/single-output.ts

@@ -106,6 +106,16 @@ export function formatSavedOutputReference(savedPath: string, fullOutput: string
 	};
 }
 
+export function formatFileOnlyFailure(params: {
+	outputPath?: string;
+	saveError?: string;
+} & ({ preservedAt: string; notPreservedReason?: never } | { preservedAt?: never; notPreservedReason: string })): string {
+	const pointer = params.preservedAt !== undefined
+		? `Full reply preserved at ${params.preservedAt}`
+		: `Full reply not preserved (${params.notPreservedReason})`;
+	return params.saveError ? `Output file error: ${params.outputPath}\n${params.saveError}\n\n${pointer}` : pointer;
+}
+
 export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
 	if (outputMode === "file-only" && !outputPath) {
 		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;