@selesai/code 0.5.29 → 0.6.2

package/dist/extensions/pi-subagents/src/runs/foreground/subagent-executor.ts

@@ -25,7 +25,6 @@ import { handleWatchdogToolAction, WATCHDOG_TOOL_ACTIONS } from "../../watchdog/
 import type { MainWatchdogRuntime } from "../../watchdog/runtime.ts";
 import { buildModelCandidates, normalizeParentModel, resolveEffectiveSubagentModel, resolveModelCandidate, type ParentModel } from "../shared/model-fallback.ts";
 import type { ModelScopeConfig } from "../shared/model-scope.ts";
-import { aggregateParallelOutputs } from "../shared/parallel-utils.ts";
 import { recordRun } from "../shared/run-history.ts";
 import {
 	buildChainInstructions,
@@ -57,7 +56,7 @@ import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
 import { usageBudgetExceededMessage, usageBudgetState, validateUsageBudgetConfig } from "../shared/usage-budget.ts";
 import { intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
 import { isAgentContractV1 } from "../shared/agent-contract.ts";
-import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { finalizeSingleOutput, formatBoundedPersistenceFallback, formatSavedOutputReference, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { cleanupStructuredOutputRuntime, createStructuredOutputRuntime } from "../shared/structured-output.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd, sumResultsCost, sumResultsUsage } from "../../shared/utils.ts";
 import { DEFAULT_GLOBAL_CONCURRENCY_LIMIT, Semaphore } from "../shared/parallel-utils.ts";
@@ -521,7 +520,12 @@ function updateRememberedForegroundChild(state: SubagentState, input: { runId: s
 		updatedAt,
 		...(input.result.exitCode !== undefined ? { exitCode: input.result.exitCode } : {}),
 		...(input.result.error ? { error: input.result.error } : {}),
-		...(input.result.finalOutput ? { finalOutput: input.result.finalOutput } : {}),
+		// Reference-first remembered state: when an authoritative saved output path
+		// exists, do not retain the full final output in memory; status/transcript
+		// views recover it from `savedOutputPath` via `rememberedForegroundChildOutput`
+		// (runs/background/run-status.ts) and the TUI via `resultOutputForUi`
+		// (tui/render.ts).
+		...(input.result.finalOutput && !input.result.savedOutputPath ? { finalOutput: input.result.finalOutput } : {}),
 		outputState: input.result.outputState,
 		outputMode: input.result.outputMode,
 		savedOutputPath: input.result.savedOutputPath,
@@ -541,10 +545,11 @@ function updateRememberedForegroundChild(state: SubagentState, input: { runId: s
 		...(input.result.capabilityAudit ? { capabilityAudit: input.result.capabilityAudit } : {}),
 	};
 	trimRememberedForegroundRuns(state);
-	const output = getSingleResultOutput(input.result).trim();
+	const reference = input.result.outputReference?.message;
+	const output = reference ?? getSingleResultOutput(input.result).trim();
 	const success = terminalStatus === "completed";
 	const summary = !success && input.result.error
-		? `${input.result.error}${output ? `\n\nOutput:\n${output}` : ""}`
+		? `${input.result.error}${output ? `\n\n${output}` : ""}`
 		: output || input.result.error || "Detached child exited without final output.";
 	// A detached callback may outlive its extension runtime. Stale sessions are
 	// intentionally dropped rather than routed through a replacement runtime.
@@ -1288,7 +1293,7 @@ async function resumeAsyncRun(input: {
 			};
 		}
 		const runId = randomUUID().slice(0, 8);
-		const artifactConfig: ArtifactConfig = { ...DEFAULT_ARTIFACT_CONFIG, enabled: input.params.artifacts !== false, dir: input.deps.config.artifactDir ?? DEFAULT_ARTIFACT_CONFIG.dir };
+		const artifactConfig: ArtifactConfig = { ...DEFAULT_ARTIFACT_CONFIG, enabled: input.params.artifacts === true, dir: input.deps.config.artifactDir ?? DEFAULT_ARTIFACT_CONFIG.dir };
 		const availableModels = input.ctx.modelRegistry.getAvailable().map(toModelInfo);
 		const contextPolicy = resolveExplicitContextPolicy(input.params);
 		const workflowTask = (input.params.task ?? followUp) || undefined;
@@ -1354,7 +1359,7 @@ async function resumeAsyncRun(input: {
 
 	const runId = randomUUID().slice(0, 8);
 	const recoveryAgentConfig = recoveryDescriptor ? applySteeringRecoveryAgentConfig(agentConfig, recoveryDescriptor) : agentConfig;
-	const artifactConfig: ArtifactConfig = recoveryDescriptor?.artifactConfig ?? { ...DEFAULT_ARTIFACT_CONFIG, enabled: input.params.artifacts !== false, dir: input.deps.config.artifactDir ?? DEFAULT_ARTIFACT_CONFIG.dir };
+	const artifactConfig: ArtifactConfig = recoveryDescriptor?.artifactConfig ?? { ...DEFAULT_ARTIFACT_CONFIG, enabled: input.params.artifacts === true, dir: input.deps.config.artifactDir ?? DEFAULT_ARTIFACT_CONFIG.dir };
 	const artifactsDir = recoveryDescriptor?.artifactsDir ?? getArtifactsDir(parentSessionFile, effectiveCwd, artifactConfig.dir);
 	const availableModels = input.ctx.modelRegistry.getAvailable().map(toModelInfo);
 	const parentModel = input.parentModel;
@@ -1435,14 +1440,82 @@ async function resumeAsyncRun(input: {
 }
 
 function resultSummaryForIntercom(result: SingleResult): string {
-	const output = getSingleResultOutput(result);
-	if (result.exitCode !== 0 && result.error) {
-		return output ? `${result.error}\n\nOutput:\n${output}` : result.error;
+	const reference = result.outputReference?.message;
+	if (reference) {
+		return result.exitCode !== 0 && result.error ? `${result.error}\n\n${reference}` : reference;
 	}
-	return output || result.error || "(no output)";
+	if (result.savedOutputPath) {
+		try {
+			const ref = formatSavedOutputReference(result.savedOutputPath, fs.readFileSync(result.savedOutputPath, "utf-8"));
+			return result.exitCode !== 0 && result.error ? `${result.error}\n\n${ref.message}` : ref.message;
+		} catch (error) {
+			const fallback = formatBoundedPersistenceFallback({
+				error: `Failed to read saved output: ${error instanceof Error ? error.message : String(error)}`,
+				outputPath: result.savedOutputPath,
+				fullOutput: getSingleResultOutput(result),
+				exitCode: result.exitCode,
+				processError: result.error,
+			});
+			return result.exitCode !== 0 && result.error ? `${result.error}\n\n${fallback}` : fallback;
+		}
+	}
+	if (result.outputSaveError) {
+		return formatBoundedPersistenceFallback({
+			error: result.outputSaveError,
+			outputPath: result.savedOutputPath,
+			fullOutput: getSingleResultOutput(result),
+			exitCode: result.exitCode,
+			processError: result.error,
+		});
+	}
+	// Legacy / `output: false` child without a durable saved path: bounded fallback
+	// only, never the raw full output.
+	return formatBoundedPersistenceFallback({
+		error: "No saved output path is available for this child.",
+		fullOutput: getSingleResultOutput(result),
+		exitCode: result.exitCode,
+		processError: result.error,
+	});
+}
+
+/**
+ * Compact terminal per-child line for bridge-off foreground parallel content:
+ * status plus either the saved-output reference (default/file-only), the legacy
+ * inline full output when explicitly requested, or the bounded fallback.
+ */
+function formatParallelChildResult(result: SingleResult, index: number): string {
+	const status = resolveSubagentResultStatus({
+		exitCode: result.exitCode,
+		interrupted: result.interrupted,
+		detached: result.detached,
+		processSignal: result.processSignal,
+		timedOut: result.timedOut,
+		stopped: result.stopped,
+		turnBudgetExceeded: result.turnBudgetExceeded,
+	});
+	const header = `=== Task ${index + 1}: ${result.agent} [${status}] ===`;
+	if (result.outputMode === "inline") {
+		const output = getSingleResultOutput(result).trim();
+		return `${header}\n${output || "(no output)"}`;
+	}
+	const reference = result.outputReference?.message;
+	if (reference) {
+		const body = result.exitCode !== 0 && result.error ? `${result.error}\n${reference}` : reference;
+		return `${header}\n${body}`;
+	}
+	return `${header}\n${formatBoundedPersistenceFallback({
+		error: result.outputSaveError ?? "No saved output path is available for this child.",
+		outputPath: result.savedOutputPath,
+		fullOutput: getSingleResultOutput(result),
+		exitCode: result.exitCode,
+		processError: result.error,
+	})}`;
 }
 
 function formatFailedSingleRunOutput(result: SingleResult, displayOutput: string): string {
+	// Reference-first and persistence-failure fallbacks already carry error/status
+	// and must not be re-wrapped as raw "Output:" text.
+	if (result.savedOutputPath || result.outputSaveError) return displayOutput;
 	const error = result.error || "Failed";
 	const output = displayOutput.trim();
 	const lines = [error];
@@ -2287,7 +2360,6 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		}
 		const rawOutput = params.output !== undefined ? params.output : a.output;
 		const effectiveOutput = normalizeSingleOutputOverride(rawOutput, a.output);
-		const effectiveOutputMode = params.outputMode ?? "inline";
 		const normalizedSkills = normalizeSkillInput(params.skill);
 		const skills = normalizedSkills === false ? [] : normalizedSkills;
 		const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, a.maxSubagentDepth);
@@ -2309,7 +2381,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			context: contextPolicy.contextForAgent(params.agent!),
 			skills,
 			output: effectiveOutput,
-			outputMode: effectiveOutputMode,
+			outputMode: params.outputMode,
 			outputBaseDir: resolveSingleRunOutputBaseDir(deps, artifactsDir, id),
 			modelOverride,
 			thinkingOverride: thinkingOverrideForTask(params.agent!, 0, modelOverride),
@@ -2610,6 +2682,19 @@ function resolveSingleRunOutputBaseDir(deps: ExecutorDeps, artifactsDir: string,
 		: path.join(artifactsDir, "outputs", runId);
 }
 
+/**
+ * Generated per-run durable output path for foreground single runs when the
+ * caller omits `output` (and does not set `output: false`):
+ * `<singleRunOutputBaseDir>/<runId>/result.md`. The base is the configured
+ * `singleRunOutputBaseDir` when present, otherwise `{artifactsDir}/outputs`.
+ */
+function resolveGeneratedSingleOutputPath(deps: ExecutorDeps, artifactsDir: string, runId: string): string {
+	const base = deps.config.singleRunOutputBaseDir
+		? path.resolve(deps.expandTilde(deps.config.singleRunOutputBaseDir))
+		: path.join(artifactsDir, "outputs");
+	return path.join(base, runId, "result.md");
+}
+
 function buildChainWorktreeTaskCwdError(chain: ChainStep[], sharedCwd: string): string | undefined {
 	for (let stepIndex = 0; stepIndex < chain.length; stepIndex++) {
 		const step = chain[stepIndex]!;
@@ -3068,8 +3153,19 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 
 	const behaviors = tasks.map((task, index) => {
 		let behavior = suppressProgressForReadOnlyTask(resolveStepBehavior(agentConfigs[index]!, behaviorOverrides[index]!), taskTexts[index]);
-		if (behaviorOverrides[index]?.output === undefined && typeof behavior.output === "string" && !path.isAbsolute(behavior.output)) {
-			behavior = { ...behavior, output: path.join("parallel-0", `${index}-${task.agent}`, behavior.output) };
+		if (behaviorOverrides[index]?.output === undefined) {
+			if (typeof behavior.output === "string" && !path.isAbsolute(behavior.output)) {
+				behavior = { ...behavior, output: path.join("parallel-0", `${index}-${task.agent}`, behavior.output) };
+			} else if (behavior.output === false && behaviorOverrides[index]?.output !== false && behaviorOverrides[index]?.output !== "false") {
+				// Omitted output: generate a collision-safe per-task durable path in the
+				// existing per-task namespace (parallel-0/<index>-<agent>/result.md).
+				behavior = { ...behavior, output: path.join("parallel-0", `${index}-${task.agent}`, "result.md") };
+			}
+		}
+		// Omitted outputMode resolves to file-only whenever an output path is active;
+		// explicit `outputMode: "inline"` is preserved exactly.
+		if (behaviorOverrides[index]?.outputMode === undefined && typeof behavior.output === "string") {
+			behavior = { ...behavior, outputMode: "file-only" };
 		}
 		return behavior;
 	});
@@ -3235,21 +3331,12 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		const worktreeSuffix = handoff?.suffix ?? "";
 		const ok = results.filter((result) => result.exitCode === 0).length;
 		const downgradeNote = backgroundRequestedWhileClarifying ? " (background requested, but clarify kept this run foreground)" : "";
-		const aggregatedOutput = aggregateParallelOutputs(
-			results.map((result) => ({
-				agent: result.agent,
-				output: result.truncation?.text || getSingleResultOutput(result),
-				exitCode: result.exitCode,
-				error: result.error,
-				timedOut: result.timedOut,
-			})),
-			(i, agent) => `=== Task ${i + 1}: ${agent} ===`,
-		);
+		const perChildResults = results.map((result, i) => formatParallelChildResult(result, i)).join("\n\n");
 
 		const summary = `${ok}/${results.length} succeeded${downgradeNote}`;
 		const fullContent = worktreeSuffix
-			? `${summary}\n\n${aggregatedOutput}\n\n${worktreeSuffix}`
-			: `${summary}\n\n${aggregatedOutput}`;
+			? `${summary}\n\n${perChildResults}\n\n${worktreeSuffix}`
+			: `${summary}\n\n${perChildResults}`;
 
 		return {
 			content: [{ type: "text", text: fullContent }],
@@ -3309,7 +3396,6 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	let skillOverride: string[] | false | undefined = normalizeSkillInput(params.skill);
 	const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
 	let effectiveOutput = normalizeSingleOutputOverride(rawOutput, agentConfig.output);
-	const effectiveOutputMode = params.outputMode ?? "inline";
 	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
 	const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, agentConfig.maxSubagentDepth);
 
@@ -3381,7 +3467,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				context: contextPolicy.contextForAgent(params.agent!),
 				skills: skillOverride === false ? [] : skillOverride,
 				output: effectiveOutput,
-				outputMode: effectiveOutputMode,
+				outputMode: params.outputMode,
 				outputBaseDir: resolveSingleRunOutputBaseDir(deps, artifactsDir, id),
 				modelOverride,
 				thinkingOverride: thinkingOverrideForTask(params.agent!, 0, modelOverride),
@@ -3410,7 +3496,16 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		task = wrapForkTask(task);
 	}
 	const cleanTask = task;
-	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, effectiveCwd, resolveSingleRunOutputBaseDir(deps, artifactsDir, runId));
+	// Omitted output resolves to a generated per-run durable path
+	// (`<singleRunOutputBaseDir>/<runId>/result.md`); omitted outputMode resolves to
+	// file-only whenever an output path is active. Explicit paths, `output: false`,
+	// and explicit `outputMode: "inline"` are preserved exactly.
+	const outputPath = typeof effectiveOutput === "string"
+		? resolveSingleOutputPath(effectiveOutput, ctx.cwd, effectiveCwd, resolveSingleRunOutputBaseDir(deps, artifactsDir, runId))
+		: effectiveOutput === false
+			? undefined
+			: resolveGeneratedSingleOutputPath(deps, artifactsDir, runId);
+	const effectiveOutputMode = params.outputMode ?? (outputPath ? "file-only" : "inline");
 	const validationError = validateFileOnlyOutputMode(effectiveOutputMode, outputPath, `Single run (${params.agent})`);
 	if (validationError) {
 		return { content: [{ type: "text", text: validationError }], isError: true, details: { mode: "single", results: [] } };
@@ -3549,6 +3644,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		savedPath: r.savedOutputPath,
 		outputReference: r.outputReference,
 		saveError: r.outputSaveError,
+		error: r.error,
 	});
 	if (foregroundControl) {
 		updateForegroundNestedProjection(foregroundControl);
@@ -4225,7 +4321,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 
 		const artifactConfig: ArtifactConfig = {
 			...DEFAULT_ARTIFACT_CONFIG,
-			enabled: effectiveParams.artifacts !== false,
+			enabled: effectiveParams.artifacts === true,
 			dir: deps.config.artifactDir ?? DEFAULT_ARTIFACT_CONFIG.dir,
 		};
 		const artifactsDir = getArtifactsDir(parentSessionFile, effectiveCwd, artifactConfig.dir);

package/dist/extensions/pi-subagents/src/runs/shared/acceptance.ts

@@ -22,7 +22,7 @@ import type {
 	SubagentRunMode,
 } from "../../shared/types.ts";
 import { isAgentContractV1 } from "./agent-contract.ts";
-import { classifyTaskMutationIntent, taskMayMutate } from "./task-intent.ts";
+import { classifyTaskMutationIntent, resolveAgentRoutingRole, taskMayMutate } from "./task-intent.ts";
 
 const LEVEL_RANK: Record<Exclude<AcceptanceLevel, "auto">, number> = {
 	none: 0,
@@ -82,7 +82,6 @@ function inferLevel(input: {
 	dynamic?: boolean;
 	dynamicGroup?: boolean;
 }): { level: Exclude<AcceptanceLevel, "auto">; reasons: string[]; criteria: string[]; evidence: AcceptanceEvidenceKind[]; review?: { agent?: string; required?: boolean } } {
-	const agent = input.agentName.toLowerCase();
 	const task = input.task?.toLowerCase() ?? "";
 	const reasons: string[] = [];
 	// Declared roles replace name heuristics, so use the full writer grammar to detect explicit mutation independently of the actual agent name.
@@ -94,11 +93,10 @@ function inferLevel(input: {
 		&& !/\b(?:do not|don't|must not)\s+patch\b/.test(task)
 		&& /\bpatch\s+(?:(?:\.{0,2}[\\/])?(?:[\w.-]+[\\/])+[\w.-]+|[\w.-]+\.[a-z0-9]+\b|(?:the\s+)?parser\b)/.test(task);
 	const taskMayWrite = readOnlyTask ? false : taskMayMutate(input.task ?? "") || intent.kind === "implementation" || rolePatchTask;
-	const readOnlyAgent = input.acceptanceRole === "read-only"
-		|| (input.acceptanceRole === undefined && /\b(?:architect|commentator|explorer|recapper|researcher|analyst)\b/.test(agent));
+	const routingRole = resolveAgentRoutingRole(input.agentName, input.acceptanceRole);
+	const readOnlyAgent = routingRole === "read-only";
 	const writeTask = taskMayWrite
-		|| (input.acceptanceRole === "writer" && !readOnlyTask)
-		|| (input.acceptanceRole === undefined && /\bbuilder\b/.test(agent) && !readOnlyTask);
+		|| (routingRole === "writer" && !readOnlyTask);
 	const inferredReadOnly = readOnlyTask || (input.acceptanceRole === "read-only" && !taskMayWrite);
 	const roleResolvesReadOnly = input.acceptanceRole !== undefined && inferredReadOnly;
 	const keywordRiskReadOnly = input.acceptanceRole === undefined ? intent.kind === "read-only" : inferredReadOnly;

package/dist/extensions/pi-subagents/src/runs/shared/single-output.ts

@@ -1,9 +1,19 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
-import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+import type { MaxOutputConfig, OutputMode, SavedOutputReference } from "../../shared/types.ts";
+import { truncateOutput } from "../../shared/types.ts";
 import { hasMutationToolCapability } from "./completion-guard.ts";
 
+/**
+ * Fixed internal context-fallback cap used when persisted output is unavailable
+ * (persistence/read failure, `output: false`, or legacy results without a saved
+ * path). Deliberately not exposed as a public parameter; reuse `truncateOutput()`
+ * so the excerpt is bounded by both lines and bytes and never falls back to
+ * unbounded output.
+ */
+export const CONTEXT_FALLBACK_LIMIT: Required<MaxOutputConfig> = { bytes: 4096, lines: 80 };
+
 export interface SingleOutputSnapshot {
 	exists: boolean;
 	mtimeMs?: number;
@@ -125,6 +135,34 @@ function formatByteSize(bytes: number): string {
 	return `${value.toFixed(1)} ${units[unitIndex]}`;
 }
 
+/**
+ * Bounded fallback for deliveries where the durable full output cannot be
+ * referenced: persistence/write errors, unreadable saved paths, or no saved
+ * path at all (legacy/`output: false`). Contains process status, the intended
+ * output path, the concrete error, and a bounded 80-line/4-KiB excerpt of the
+ * available output. Never claims a full artifact exists.
+ */
+export function formatBoundedPersistenceFallback(input: {
+	error: string;
+	outputPath?: string;
+	fullOutput: string;
+	exitCode: number;
+	processError?: string;
+}): string {
+	const status = input.processError?.trim()
+		? `Process status: ${input.processError}`
+		: `Process status: ${input.exitCode === 0 ? "completed" : `failed (exit ${input.exitCode})`}`;
+	const bounded = truncateOutput(input.fullOutput, CONTEXT_FALLBACK_LIMIT);
+	const lines = [
+		`[Full output unavailable] ${input.error}`,
+		status,
+		...(input.outputPath ? [`Intended output path: ${input.outputPath}`] : []),
+		"Full output is unavailable; showing a bounded excerpt (first 80 lines / 4 KiB).",
+		bounded.text,
+	];
+	return lines.join("\n");
+}
+
 export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
 	const absolutePath = path.resolve(savedPath);
 	const bytes = Buffer.byteLength(fullOutput, "utf-8");
@@ -217,19 +255,35 @@ export function finalizeSingleOutput(params: {
 	savedPath?: string;
 	outputReference?: SavedOutputReference;
 	saveError?: string;
+	error?: string;
 }): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
-	let displayOutput = params.truncatedOutput || params.fullOutput;
-	if (params.exitCode === 0 && params.savedPath) {
+	if (params.savedPath) {
 		const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
-		if (params.outputMode === "file-only") {
+		if (params.exitCode === 0 && params.outputMode === "file-only") {
 			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
 		}
-		displayOutput += `\n\n${outputReference.message}`;
+		if (params.exitCode !== 0) {
+			// Failed runs with a successfully persisted result surface the error/status
+			// plus the saved-output reference, never raw child output.
+			const status = params.error?.trim() || `Subagent failed with exit code ${params.exitCode}`;
+			return { displayOutput: `${status}\n\n${outputReference.message}`, savedPath: params.savedPath, outputReference };
+		}
+		const displayOutput = `${params.truncatedOutput || params.fullOutput}\n\n${outputReference.message}`;
 		return { displayOutput, savedPath: params.savedPath, outputReference };
 	}
-	if (params.exitCode === 0 && params.saveError && params.outputPath) {
-		displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
-		return { displayOutput, saveError: params.saveError };
+	if (params.saveError && params.outputPath) {
+		// Persistence/read failure: only the bounded fallback is delivered. It must
+		// not claim a full artifact exists.
+		return {
+			displayOutput: formatBoundedPersistenceFallback({
+				error: params.saveError,
+				outputPath: params.outputPath,
+				fullOutput: params.fullOutput,
+				exitCode: params.exitCode,
+				processError: params.error,
+			}),
+			saveError: params.saveError,
+		};
 	}
-	return { displayOutput };
+	return { displayOutput: params.truncatedOutput || params.fullOutput };
 }

package/dist/extensions/pi-subagents/src/runs/shared/task-intent.ts

@@ -1,3 +1,5 @@
+import type { AcceptanceRole } from "../../shared/types.ts";
+
 /**
  * Shared task mutation-intent classifier.
  *
@@ -139,6 +141,25 @@ function isReviewerStyleAgent(agent: string): boolean {
 	return /\b(?:architect|commentator|explorer|recapper|researcher)\b/i.test(agent);
 }
 
+/**
+ * Resolve an agent's acceptance routing role: a declared `acceptanceRole`
+ * always wins; otherwise the established name heuristics apply (builder-named
+ * agents are writers; architect/commentator/explorer/recapper/researcher/
+ * analyst-named agents are read-only). This is the single shared source of
+ * truth for acceptance inference and task-aware advisory routing so the two
+ * cannot drift. Alias values are never role signals.
+ */
+export function resolveAgentRoutingRole(
+	agentName: string,
+	acceptanceRole?: AcceptanceRole,
+): "writer" | "read-only" | undefined {
+	if (acceptanceRole !== undefined) return acceptanceRole;
+	const agent = agentName.toLowerCase();
+	if (/\bbuilder\b/.test(agent)) return "writer";
+	if (/\b(?:architect|commentator|explorer|recapper|researcher|analyst)\b/.test(agent)) return "read-only";
+	return undefined;
+}
+
 function hasImplementationIntent(agent: string, taskText: string): boolean {
 	if (isReviewerStyleAgent(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
 	if (agent === "builder") return WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));

package/dist/extensions/pi-subagents/src/shared/types.ts

@@ -5,7 +5,7 @@
 import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
-import type { AgentConfig } from "../agents/agents.ts";
+import type { AgentConfig, AgentSource } from "../agents/agents.ts";
 import type { FSWatcher } from "node:fs";
 import type { ExtensionContext } from "@selesai/code";
 import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
@@ -912,12 +912,51 @@ export interface SpawnBudgetSnapshot {
 	grantHistory: SpawnBudgetGrant[];
 }
 
+// ============================================================================
+// Runtime catalog (action:list machine metadata)
+// ============================================================================
+
+/** Machine-readable catalog entry for one visible runtime agent. */
+export interface CatalogAgentMetadata {
+	name: string;
+	source: AgentSource;
+	description: string;
+	/** false for capability-ceiling-restricted agents (still visible, not launchable). */
+	executable: boolean;
+	/** Present only when the agent is capability-ceiling-restricted. */
+	restrictionSources?: string[];
+	aliases?: string[];
+	/** Normalized to explicit "fresh" when the agent has no defaultContext. */
+	defaultContext: "fresh" | "fork";
+	acceptanceRole?: AcceptanceRole;
+	/** Effective declared tools: normal tools plus mcp:-prefixed direct MCP tools. */
+	tools?: string[];
+}
+
+/** Machine-readable catalog entry for one visible chain. */
+export interface CatalogChainMetadata {
+	name: string;
+	source: AgentSource;
+	description: string;
+}
+
+/** Versioned action:list catalog mirroring the human list output. */
+export interface CatalogMetadataV1 {
+	version: 1;
+	agents: CatalogAgentMetadata[];
+	chains: CatalogChainMetadata[];
+	/** Present only when a capability ceiling restricted visible agents. */
+	capabilityCeilingSources?: string[];
+}
+
 export interface Details {
 	mode: SubagentRunMode | "management";
 	runId?: string;
 	/** Run-level context summary. "mixed" when children resolved to different modes. */
 	context?: "fresh" | "fork" | "mixed";
 	results: SingleResult[];
+	/** Runtime-resolved human+machine catalog for { action: "list" } results. */
+	catalog?: CatalogMetadataV1;
 	controlEvents?: ControlEvent[];
 	steering?: SteerActionResult;
 	asyncId?: string;
@@ -1645,7 +1684,7 @@ export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
 };
 
 export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
-	enabled: true,
+	enabled: false,
 	dir: "project",
 	includeInput: true,
 	includeOutput: true,

package/dist/extensions/pi-subagents/src/shared/utils.ts

@@ -7,7 +7,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import { formatToolCall } from "./formatters.ts";
-import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, NestedRunSummary, SingleResult, ToolCallSummary, Usage } from "./types.ts";
+import type { AgentProgress, AsyncStatus, ChainOutputMap, Details, DisplayItem, ErrorInfo, NestedRunSummary, SingleResult, ToolCallSummary, Usage } from "./types.ts";
 
 // ============================================================================
 // File System Utilities
@@ -414,12 +414,40 @@ export function compactForegroundResult(result: SingleResult): SingleResult {
 		messages: undefined,
 		progress: undefined,
 		toolCalls: toolCalls.length ? toolCalls : undefined,
+		// Reference-first terminal details: once an authoritative saved output path
+		// exists, drop the raw final output and truncation marker from the model-
+		// visible projection; consumers recover the file from `savedOutputPath`.
+		// Explicit `outputMode: "inline"` is the sole legacy full-text opt-out and
+		// keeps its final output in the terminal projection (e.g. delegation v1
+		// `response.output` stays populated).
+		finalOutput: result.savedOutputPath && result.outputMode !== "inline" ? undefined : result.finalOutput,
+		truncation: result.savedOutputPath && result.outputMode !== "inline" ? undefined : result.truncation,
 	};
 }
 
+/**
+ * Strip chain `details.outputs` text/structured payloads from the terminal
+ * projection while retaining the output names and step metadata. Chain output
+ * bindings themselves remain reference-first in the completion content and
+ * `{outputs.name}` interpolation (see outputEntryFromResult).
+ */
+function compactChainOutputs(outputs: ChainOutputMap | undefined): ChainOutputMap | undefined {
+	if (!outputs) return undefined;
+	const compact: ChainOutputMap = {};
+	for (const [name, entry] of Object.entries(outputs)) {
+		compact[name] = {
+			agent: entry.agent,
+			stepIndex: entry.stepIndex,
+			text: "",
+		};
+	}
+	return compact;
+}
+
 export function compactForegroundDetails(details: Details): Details {
 	return {
 		...details,
+		outputs: compactChainOutputs(details.outputs),
 		results: details.results.map(compactForegroundResult),
 		progress: details.progress
 			? details.progress.map(compactCompletedProgress)

package/dist/extensions/pi-subagents/src/slash/delegation-adapters.ts

@@ -375,7 +375,11 @@ export function toSubagentDelegationExecutionParams(request: SubagentDelegationR
 		toolBudget: request.toolBudget,
 		skill: request.skill,
 		output: request.output,
-		outputMode: request.outputMode,
+		// v1 has no default for outputMode: preserve the legacy full-text contract by
+		// resolving an omitted outputMode to explicit inline (response.output stays
+		// populated). The model-facing tool's mode-dependent reference-first default
+		// (omitted outputMode -> file-only) is intentionally NOT applied here.
+		outputMode: request.outputMode ?? "inline",
 		outputSchema: request.outputSchema,
 		agentContract: request.agentContract,
 		acceptance: request.acceptance,