@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/runs/background/runner-prepare-step.ts

@@ -0,0 +1,128 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ReadonlyDeep } from "type-fest";
+import type { ArtifactPaths, RunnerSubagentStep } from "../../shared/types.ts";
+import { getArtifactPaths } from "../../shared/artifacts.ts";
+import {
+  createStructuredOutputRuntime,
+  type StructuredOutputRuntime,
+} from "../shared/structured-output.ts";
+import { formatAcceptancePrompt } from "../shared/acceptance.ts";
+import { saveQuestionContract } from "../shared/supervisor-questions.ts";
+import type { SingleStepContext } from "./runner-contract.ts";
+
+export interface PreparedRunnerStep {
+  readonly step: RunnerSubagentStep;
+  readonly task: string;
+  readonly artifactPaths?: ArtifactPaths;
+  readonly interruptSignal: AbortSignal;
+  readonly verificationSignal: AbortSignal;
+  readonly structuredRuntime?: StructuredOutputRuntime;
+  readonly sessionEnabled: boolean;
+  readonly sessionDir?: string;
+}
+
+function saveStepContract(step: RunnerSubagentStep, ctx: ReadonlyDeep<SingleStepContext>): void {
+  saveQuestionContract(ctx.id, ctx.flatIndex, {
+    task: step.task,
+    label: step.label,
+    effectiveAcceptance: step.effectiveAcceptance,
+    output: step.outputPath ?? false,
+    outputMode: step.outputMode,
+    outputSchema: step.structuredOutputSchema ?? step.structuredOutput?.schema,
+    launch: step.launch
+      ? {
+          ...step.launch,
+          cwd: step.cwd ?? ctx.cwd,
+          output: step.outputPath ?? false,
+          outputMode: step.outputMode ?? "inline",
+          outputSchema: step.structuredOutputSchema ?? step.structuredOutput?.schema,
+          model: step.model,
+          thinking: step.thinking,
+        }
+      : undefined,
+    sessionFile: step.sessionFile,
+  });
+}
+
+function prepareArtifacts(
+  step: RunnerSubagentStep,
+  task: string,
+  ctx: Readonly<Pick<SingleStepContext, "artifactsDir" | "id" | "flatStepCount" | "flatIndex">>,
+): ArtifactPaths | undefined {
+  const directory = ctx.artifactsDir;
+  if (directory === undefined || directory.length === 0) {
+    return;
+  }
+  const index = ctx.flatStepCount > 1 ? ctx.flatIndex : undefined;
+  const paths = getArtifactPaths(directory, ctx.id, step.agent, index);
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(paths.inputPath, `# Task for ${step.agent}\n\n${task}`, "utf-8");
+  return paths;
+}
+
+function continuationStep(
+  input: RunnerSubagentStep,
+  ctx: Readonly<Pick<SingleStepContext, "nativeFinalization" | "outputFile" | "flatIndex">>,
+): RunnerSubagentStep {
+  if (ctx.nativeFinalization !== true || input.effectiveAcceptance?.explicit !== true) {
+    return input;
+  }
+  if (input.sessionFile !== undefined && input.sessionFile.length > 0) {
+    return input;
+  }
+  return {
+    ...input,
+    sessionFile: path.join(path.dirname(ctx.outputFile), `session-${ctx.flatIndex}.jsonl`),
+  };
+}
+
+function structuredRuntime(
+  step: RunnerSubagentStep,
+  outputFile: string,
+): StructuredOutputRuntime | undefined {
+  if (step.structuredOutput) {
+    return step.structuredOutput;
+  }
+  if (step.structuredOutputSchema === undefined) {
+    return;
+  }
+  return createStructuredOutputRuntime(
+    step.structuredOutputSchema,
+    path.join(path.dirname(outputFile), "structured-output"),
+  );
+}
+
+/** Establishes continuation persistence, acceptance prompt and owned interrupt signal before execution. */
+export function prepareRunnerStep(
+  input: RunnerSubagentStep,
+  ctx: ReadonlyDeep<SingleStepContext>,
+): PreparedRunnerStep {
+  const step = continuationStep(input, ctx);
+  saveStepContract(step, ctx);
+  const interrupt = new AbortController();
+  ctx.registerInterrupt?.(() => {
+    interrupt.abort();
+  });
+  const interruptSignal = AbortSignal.any(
+    [ctx.interruptSignal, interrupt.signal].filter((signal) => signal !== undefined),
+  );
+  const verificationSignal = AbortSignal.any(
+    [ctx.signal, interruptSignal].filter((signal) => signal !== undefined),
+  );
+  const runtime = structuredRuntime(step, ctx.outputFile);
+  const prompt = step.effectiveAcceptance ? formatAcceptancePrompt(step.effectiveAcceptance) : "";
+  const task = prompt.length > 0 ? `${step.task}\n${prompt}` : step.task;
+  const artifactPaths = prepareArtifacts(step, task, ctx);
+  const hasSession = step.sessionFile !== undefined && step.sessionFile.length > 0;
+  return {
+    step,
+    task,
+    artifactPaths,
+    interruptSignal,
+    verificationSignal,
+    structuredRuntime: runtime,
+    sessionEnabled: hasSession || ctx.sessionEnabled,
+    sessionDir: hasSession ? undefined : ctx.sessionDir,
+  };
+}

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

@@ -0,0 +1,192 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { inspect } from "node:util";
+import type { ReadonlyDeep } from "type-fest";
+import { findLatestSessionFile } from "../../shared/utils.ts";
+import { PI_CODING_AGENT_PACKAGE, resolveInstalledPiPackageRoot } from "../shared/pi-spawn.ts";
+import type { SubagentRunMode } from "../../shared/types.ts";
+import type { SubagentRunConfig } from "./runner-contract.ts";
+
+export function runnerErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return typeof error === "string" ? error : inspect(error);
+}
+
+function resolvePiPackageRootFallback(): string {
+  const root = resolveInstalledPiPackageRoot();
+  if (root !== undefined && root.length > 0) {
+    return root;
+  }
+  throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
+}
+
+export async function exportSessionHtml(
+  sessionFile: string,
+  outputDir: string,
+  piPackageRoot?: string,
+): Promise<string> {
+  const pkgRoot = piPackageRoot ?? resolvePiPackageRootFallback();
+  const exportModulePath = path.join(pkgRoot, "dist", "core", "export-html", "index.js");
+  const moduleUrl = pathToFileURL(exportModulePath).href;
+  const mod: unknown = await import(moduleUrl);
+  if (
+    typeof mod !== "object" ||
+    mod === null ||
+    !("exportFromFile" in mod) ||
+    typeof mod.exportFromFile !== "function"
+  ) {
+    throw new Error("exportFromFile not available");
+  }
+  const outputPath = path.join(outputDir, `${path.basename(sessionFile, ".jsonl")}.html`);
+  const exported: unknown = await Reflect.apply(mod.exportFromFile, mod, [
+    sessionFile,
+    { outputPath },
+  ]);
+  if (typeof exported !== "string") {
+    throw new Error("exportFromFile returned an invalid output path");
+  }
+  return exported;
+}
+
+export function createShareLink(
+  htmlPath: string,
+): { shareUrl: string; gistUrl: string } | { error: string } {
+  try {
+    const auth = spawnSync("gh", ["auth", "status"], { encoding: "utf-8" });
+    if (auth.status !== 0) {
+      return { error: "GitHub CLI is not logged in. Run 'gh auth login' first." };
+    }
+  } catch {
+    return { error: "GitHub CLI (gh) is not installed." };
+  }
+
+  try {
+    const result = spawnSync("gh", ["gist", "create", htmlPath], { encoding: "utf-8" });
+    if (result.status !== 0) {
+      const stderr = result.stderr.trim();
+      const err = stderr.length > 0 ? stderr : "Failed to create gist.";
+      return { error: err };
+    }
+    const gistUrl = result.stdout.trim();
+    const gistId = gistUrl.split("/").pop();
+    if (gistId === undefined || gistId.length === 0) {
+      return { error: "Failed to parse gist ID." };
+    }
+    const shareUrl = `https://shittycodingagent.ai/session/?${gistId}`;
+    return { shareUrl, gistUrl };
+  } catch (err) {
+    return { error: runnerErrorMessage(err) };
+  }
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  if (ms < 60000) {
+    return `${(ms / 1000).toFixed(1)}s`;
+  }
+  const minutes = Math.floor(ms / 60000);
+  const seconds = Math.floor((ms % 60000) / 1000);
+  return `${minutes}m${seconds}s`;
+}
+
+export function writeRunLog(
+  logPath: string,
+  input: ReadonlyDeep<{
+    id: string;
+    mode: SubagentRunMode;
+    cwd: string;
+    startedAt: number;
+    endedAt: number;
+    steps: Array<{
+      agent: string;
+      status: string;
+      durationMs?: number;
+    }>;
+    summary: string;
+    truncated: boolean;
+    artifactsDir?: string;
+    sessionFile?: string;
+    shareUrl?: string;
+    shareError?: string;
+  }>,
+): void {
+  const lines: string[] = [];
+  lines.push(`# Subagent run ${input.id}`);
+  lines.push("");
+  lines.push(`- **Mode:** ${input.mode}`);
+  lines.push(`- **Launch cwd:** ${input.cwd}`);
+  lines.push(`- **Started:** ${new Date(input.startedAt).toISOString()}`);
+  lines.push(`- **Ended:** ${new Date(input.endedAt).toISOString()}`);
+  lines.push(`- **Duration:** ${formatDuration(input.endedAt - input.startedAt)}`);
+  const references = [
+    { label: "Session", value: input.sessionFile },
+    { label: "Share", value: input.shareUrl },
+    { label: "Share error", value: input.shareError },
+    { label: "Artifacts", value: input.artifactsDir },
+  ];
+  for (const reference of references) {
+    if (reference.value !== undefined && reference.value.length > 0) {
+      lines.push(`- **${reference.label}:** ${reference.value}`);
+    }
+  }
+  lines.push("");
+  lines.push("## Steps");
+  lines.push("| Step | Agent | Status | Duration |");
+  lines.push("| --- | --- | --- | --- |");
+  input.steps.forEach((step, i) => {
+    const duration = step.durationMs !== undefined ? formatDuration(step.durationMs) : "-";
+    lines.push(`| ${i + 1} | ${step.agent} | ${step.status} | ${duration} |`);
+  });
+  lines.push("");
+  lines.push("## Summary");
+  if (input.truncated) {
+    lines.push("_Output truncated_");
+    lines.push("");
+  }
+  const summary = input.summary.trim();
+  lines.push(summary.length > 0 ? summary : "(no output)");
+  lines.push("");
+  fs.writeFileSync(logPath, lines.join("\n"), "utf-8");
+}
+
+interface SessionShare {
+  readonly sessionFile?: string;
+  readonly shareUrl?: string;
+  readonly gistUrl?: string;
+  readonly shareError?: string;
+}
+
+export async function shareRunnerSession(
+  config: ReadonlyDeep<SubagentRunConfig>,
+  latestSessionFile: string | undefined,
+): Promise<SessionShare> {
+  if (config.share !== true) {
+    return { sessionFile: latestSessionFile };
+  }
+  const discovered =
+    config.sessionDir === undefined || config.sessionDir.length === 0
+      ? undefined
+      : findLatestSessionFile(config.sessionDir);
+  const sessionFile = discovered ?? latestSessionFile;
+  if (sessionFile === undefined || sessionFile.length === 0) {
+    return { sessionFile: latestSessionFile, shareError: "Session file not found." };
+  }
+  try {
+    const exportDir = config.sessionDir ?? path.dirname(sessionFile);
+    fs.mkdirSync(exportDir, { recursive: true });
+    const htmlPath = await exportSessionHtml(sessionFile, exportDir, config.piPackageRoot);
+    const share = createShareLink(htmlPath);
+    if ("error" in share) {
+      return { sessionFile, shareError: share.error };
+    }
+    return { sessionFile, ...share };
+  } catch (error) {
+    return { sessionFile, shareError: runnerErrorMessage(error) };
+  }
+}

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

@@ -0,0 +1,220 @@
+import * as path from "node:path";
+import type { ReadonlyDeep } from "type-fest";
+import { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import type {
+  RunnerSubagentStep,
+  AsyncStatus,
+  ModelAttempt,
+  TokenUsage,
+} from "../../shared/types.ts";
+import type { RunSingleStepResult } from "./runner-contract.ts";
+
+export function pendingRunnerStep(task: ReadonlyDeep<RunnerSubagentStep>): RunnerStatusStep {
+  return {
+    agent: task.agent,
+    phase: task.phase,
+    label: task.label,
+    outputName: task.outputName,
+    structured: task.structured,
+    status: "pending",
+    ...(task.sessionFile !== undefined && task.sessionFile.length > 0
+      ? { sessionFile: task.sessionFile }
+      : {}),
+    skills: task.skills?.slice(),
+    model: task.model,
+    thinking: task.thinking,
+    attemptedModels: pendingModelCandidates(task),
+    recentTools: [],
+    recentOutput: [],
+  };
+}
+
+function pendingModelCandidates(task: ReadonlyDeep<RunnerSubagentStep>): string[] | undefined {
+  const candidates = task.modelCandidates;
+  if (candidates !== undefined && candidates.length > 0) {
+    return [...candidates];
+  }
+  if (task.model !== undefined && task.model.length > 0) {
+    return [task.model];
+  }
+  return;
+}
+
+export function tokenUsageFromAttempts(
+  attempts: readonly ReadonlyDeep<ModelAttempt>[] | undefined,
+): TokenUsage | null {
+  if (!attempts || attempts.length === 0) {
+    return null;
+  }
+  let input = 0;
+  let output = 0;
+  for (const attempt of attempts) {
+    input += attempt.usage?.input ?? 0;
+    output += attempt.usage?.output ?? 0;
+  }
+  const total = input + output;
+  return total > 0 ? { input, output, total } : null;
+}
+
+export function appendRecentStepOutput(step: RunnerStatusStep, lines: readonly string[]): void {
+  const nonEmpty = lines.filter((line) => line.trim().length > 0);
+  if (nonEmpty.length === 0) {
+    return;
+  }
+  step.recentOutput ??= [];
+  step.recentOutput.push(...nonEmpty);
+  if (step.recentOutput.length > 50) {
+    step.recentOutput.splice(0, step.recentOutput.length - 50);
+  }
+}
+
+export function clearStepCurrentActivity(step: RunnerStatusStep): void {
+  step.currentTool = undefined;
+  step.currentToolArgs = undefined;
+  step.currentToolStartedAt = undefined;
+  step.currentPath = undefined;
+}
+
+export function resetStepLiveDetail(step: RunnerStatusStep): void {
+  clearStepCurrentActivity(step);
+  step.recentTools = [];
+  step.recentOutput = [];
+}
+
+export function markStepPaused(step: RunnerStatusStep, now: number): void {
+  step.status = "paused";
+  step.activityState = undefined;
+  clearStepCurrentActivity(step);
+  step.startedAt ??= now;
+  step.endedAt = now;
+  step.durationMs = now - step.startedAt;
+  step.lastActivityAt = now;
+  step.exitCode = 0;
+}
+
+export type RunnerStatusStep = Omit<
+  NonNullable<AsyncStatus["steps"]>[number],
+  "recentTools" | "recentOutput"
+> & {
+  exitCode?: number | null;
+  recentTools?: Array<{ readonly tool: string; readonly args: string; readonly endMs: number }>;
+  recentOutput?: string[];
+};
+
+export type RunnerStatusPayload = Omit<
+  AsyncStatus,
+  "steps" | "parallelGroups" | "pid" | "cwd" | "currentStep" | "chainStepCount" | "lastUpdate"
+> & {
+  pid: number;
+  cwd: string;
+  currentStep: number;
+  chainStepCount: number;
+  parallelGroups: Array<{ start: number; count: number; stepIndex: number }>;
+  steps: RunnerStatusStep[];
+  lastUpdate: number;
+  artifactsDir?: string;
+  shareUrl?: string;
+  gistUrl?: string;
+  shareError?: string;
+};
+
+export function runnerResultStatus(
+  result: ReadonlyDeep<RunSingleStepResult>,
+): RunnerStatusStep["status"] {
+  if (result.interrupted === true) {
+    return "paused";
+  }
+  if (result.exitCode !== 0) {
+    return "failed";
+  }
+  return result.acceptance?.status === "blocked" ? "blocked" : "complete";
+}
+
+export function runnerResultEvent(result: ReadonlyDeep<RunSingleStepResult>): string {
+  const status = runnerResultStatus(result);
+  return status === "complete" ? "subagent.step.completed" : `subagent.step.${status}`;
+}
+
+interface StepStart {
+  readonly asyncDir: string;
+  readonly sequential?: boolean;
+  readonly resetTiming?: boolean;
+  readonly index: number;
+}
+
+/** Mutates only the live step owned by this status boundary; callers publish after transition. */
+export function startRunnerStep(
+  statusPayload: RunnerStatusPayload,
+  task: ReadonlyDeep<RunnerSubagentStep>,
+  input: StepStart,
+): number {
+  const startedAt = Date.now();
+  const step = statusPayload.steps[input.index];
+  statusPayload.currentStep = input.index;
+  step.status = "running";
+  step.activityState = undefined;
+  resetStepLiveDetail(step);
+  step.startedAt = startedAt;
+  if (input.sequential === true) {
+    statusPayload.activityState = undefined;
+    step.skills = task.skills?.slice();
+  } else {
+    step.error = undefined;
+  }
+  if (input.resetTiming === true) {
+    step.endedAt = undefined;
+    step.durationMs = undefined;
+  }
+  step.lastActivityAt = startedAt;
+  statusPayload.outputFile = path.join(input.asyncDir, `output-${input.index}.log`);
+  statusPayload.lastActivityAt = startedAt;
+  statusPayload.lastUpdate = startedAt;
+  return startedAt;
+}
+
+interface StepFinish {
+  readonly startedAt: number;
+  readonly sequential?: boolean;
+  readonly index: number;
+}
+
+export function finishRunnerStep(
+  statusPayload: RunnerStatusPayload,
+  result: ReadonlyDeep<RunSingleStepResult>,
+  input: StepFinish,
+): number {
+  const endedAt = Date.now();
+  const step = statusPayload.steps[input.index];
+  Object.assign(step, {
+    status: runnerResultStatus(result),
+    endedAt,
+    durationMs: endedAt - input.startedAt,
+    exitCode: result.exitCode,
+    agentProcessExit: result.agentProcessExit,
+    model: result.model,
+    thinking: resolveEffectiveThinking(result.model, step.thinking),
+    attemptedModels: result.attemptedModels,
+    modelAttempts: result.modelAttempts,
+    error: result.error,
+    structuredOutput: result.structuredOutput,
+    structuredOutputPath: result.structuredOutputPath,
+    structuredOutputSchemaPath: result.structuredOutputSchemaPath,
+    acceptance: result.acceptance,
+    resourceLimitExceeded: result.resourceLimitExceeded,
+  });
+  clearStepCurrentActivity(step);
+  const tokens = tokenUsageFromAttempts(result.modelAttempts);
+  if (tokens !== null || input.sequential !== true) {
+    step.tokens = tokens ?? undefined;
+    statusPayload.totalTokens = statusPayload.steps.reduce(
+      (total, candidate) => ({
+        input: total.input + (candidate.tokens?.input ?? 0),
+        output: total.output + (candidate.tokens?.output ?? 0),
+        total: total.total + (candidate.tokens?.total ?? 0),
+      }),
+      { input: 0, output: 0, total: 0 },
+    );
+  }
+  statusPayload.lastUpdate = endedAt;
+  return endedAt;
+}

package/src/runs/background/runner-step-output.ts

@@ -0,0 +1,158 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ReadonlyDeep } from "type-fest";
+import type { AcceptanceLedger, RunnerSubagentStep } from "../../shared/types.ts";
+import {
+  cleanupSingleOutputFile,
+  finalizeSingleOutput,
+  formatConsumedOutputReference,
+  formatSavedOutputReference,
+  type resolveSingleOutput,
+} from "../shared/single-output.ts";
+import {
+  formatUnconfirmedFinalizationOutput,
+  type resolveExecutionOutcome,
+} from "../shared/acceptance.ts";
+import type { RunSingleStepResult, SingleStepContext } from "./runner-contract.ts";
+
+interface OutputState {
+  readonly output: string;
+  readonly acceptance?: AcceptanceLedger;
+  readonly resolvedOutput: ReturnType<typeof resolveSingleOutput>;
+  readonly outcome: ReturnType<typeof resolveExecutionOutcome>;
+  readonly attemptNotes: readonly string[];
+}
+
+function decorateOutput(input: ReadonlyDeep<OutputState>): string {
+  let output = input.output;
+  const { acceptance, resolvedOutput, outcome } = input;
+  if (acceptance?.unconfirmedOutput !== undefined) {
+    const saved = resolvedOutput.savedPath;
+    const auditOutput =
+      saved !== undefined && saved.length > 0 && !resolvedOutput.writtenSnapshot
+        ? output
+        : acceptance.unconfirmedOutput;
+    output = formatUnconfirmedFinalizationOutput(auditOutput);
+  }
+  if (outcome.timedOut === true) {
+    const reason = outcome.error ?? "Timed out.";
+    const partial = output.trim();
+    output =
+      partial.length > 0 && partial !== reason
+        ? `${reason}\n\nPartial output before timeout:\n${partial}`
+        : reason;
+  }
+  return output;
+}
+
+function relocateOutput(
+  ctx: ReadonlyDeep<SingleStepContext>,
+  savedPath: string | undefined,
+  cleanup: ReadonlyDeep<ReturnType<typeof cleanupSingleOutputFile>>,
+): string | undefined {
+  const worktree = ctx.worktreePath;
+  if (
+    worktree === undefined ||
+    worktree.length === 0 ||
+    savedPath === undefined ||
+    savedPath.length === 0 ||
+    (cleanup !== undefined && cleanup.action !== "skipped")
+  ) {
+    return savedPath;
+  }
+  const relative = path.relative(worktree, savedPath);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    return savedPath;
+  }
+  const destination = path.join(
+    path.dirname(ctx.outputFile),
+    "outputs",
+    String(ctx.flatIndex),
+    path.basename(savedPath),
+  );
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(savedPath, destination);
+  return destination;
+}
+
+function outputReference(
+  savedPath: string | undefined,
+  output: string,
+  cleanup: ReturnType<typeof cleanupSingleOutputFile>,
+): ReturnType<typeof formatSavedOutputReference> | undefined {
+  if (savedPath === undefined || savedPath.length === 0) {
+    return;
+  }
+  return cleanup
+    ? formatConsumedOutputReference(savedPath, output, cleanup)
+    : formatSavedOutputReference(savedPath, output);
+}
+
+/** Consumes eligible default output or preserves it outside a worktree before that worktree is removed. */
+export function publishStepOutput(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  ctx: ReadonlyDeep<SingleStepContext>,
+  state: ReadonlyDeep<OutputState>,
+): Readonly<{
+  output: string;
+  displayOutput: string;
+  savedPath?: string;
+  cleanup: ReturnType<typeof cleanupSingleOutputFile>;
+  reference: ReturnType<typeof formatSavedOutputReference> | undefined;
+}> {
+  const output = decorateOutput(state);
+  const exitCode = state.outcome.exitCode ?? 1;
+  const originalPath = state.resolvedOutput.savedPath;
+  const shouldConsume =
+    exitCode === 0 &&
+    state.outcome.interrupted !== true &&
+    originalPath !== undefined &&
+    originalPath.length > 0 &&
+    step.outputMode !== "file-only" &&
+    step.outputPathFromAgentDefault === true;
+  const cleanup = shouldConsume
+    ? cleanupSingleOutputFile(originalPath, output, undefined)
+    : undefined;
+  const savedPath = relocateOutput(ctx, originalPath, cleanup);
+  const reference = outputReference(savedPath, state.resolvedOutput.fullOutput, cleanup);
+  const displayOutput = finalizeSingleOutput({
+    fullOutput:
+      state.attemptNotes.length > 0
+        ? `${state.attemptNotes.join("\n")}\n\n${output}`.trim()
+        : output,
+    outputPath: step.outputPath,
+    outputMode: step.outputMode,
+    exitCode,
+    savedPath,
+    outputReference: reference,
+    saveError: state.resolvedOutput.saveError,
+    cleanup,
+  }).displayOutput;
+  return { output, displayOutput, savedPath, cleanup, reference };
+}
+
+export function stepOutputFields(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  published: ReadonlyDeep<ReturnType<typeof publishStepOutput>>,
+  input: ReadonlyDeep<{ acceptance?: AcceptanceLedger; initialOutput: string; saveError?: string }>,
+): Pick<
+  RunSingleStepResult,
+  | "finalOutput"
+  | "initialOutput"
+  | "outputMode"
+  | "outputReference"
+  | "outputCleanup"
+  | "outputSaveError"
+  | "savedOutputPath"
+> {
+  const cleanup = published.cleanup;
+  return {
+    finalOutput: step.outputMode === "file-only" ? published.displayOutput : published.output,
+    initialOutput: input.acceptance?.finalization ? input.initialOutput : undefined,
+    outputMode: step.outputMode ?? "inline",
+    outputReference: published.reference,
+    outputCleanup: cleanup,
+    outputSaveError: input.saveError,
+    savedOutputPath: cleanup && cleanup.action !== "skipped" ? undefined : published.savedPath,
+  };
+}