@gavin-hu/my-pi-agent 0.13.0 → 0.14.0

package/extensions/plan/README.md

@@ -311,6 +311,18 @@ agent file that overrides it.
 - `readOnly` is also a normal `subagent` parameter; outside plan mode a caller
   may set it to run any agent read-only on purpose.
 
+## Review screen
+
+<img src="../../assets/plan.png" alt="The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints" width="100%">
+
+`exit_plan_mode` opens this screen on the plan file it just wrote. The body is
+Pi's Markdown renderer with the active theme, so headings, lists, code, and
+links read as they do in the transcript; the checkboxes in `Steps` use the
+shared `◼`/`◻` vocabulary. A plan taller than the terminal scrolls under a gauge
+that names the section at the top of the viewport and the line range it shows,
+and the footer lists only the keys that apply. `Esc` keeps planning, `a` approves
+and runs, `r` refines inline, and `w` opens the browser review below.
+
 ## Browser review
 
 <img src="../../assets/plan-review.png" alt="The browser-based plan review: a sticky header with the plan title, a status chip, and the Approve & run, Save feedback, and Back to Pi actions, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail and an inline review thread" width="100%">

package/extensions/subagent/README.md

@@ -29,6 +29,10 @@ How the `subagent` call and its result look in the transcript — the call line
 - **Streaming.** Tool calls and progress update live in the transcript while the
   subagent runs; the `app.tools.expand` key (`ctrl+o` by default) expands the
   full task, tool calls, Markdown output, and usage.
+- **Bounded runs.** A per-run deadline kills a child that hangs, and reports it
+  as a failed run instead of rejecting the whole call.
+- **Optional transcripts.** Opt-in per-run stream under `.pi/subagents/`,
+  written by the parent and pruned by age and count.
 - **Inherited model.** Subagents use the dispatching session's model and thinking
   level unless an agent overrides them (none do).
 
@@ -88,6 +92,42 @@ at most 8 steps (like the parallel task cap).
 }
 ```
 
+## Configuration
+
+Read from the shared `bytefly.json` section `subagent` (global then project),
+once per session. Keys and bounds live in the
+[configuration reference](../../docs/references/bytefly-config.md#subagent--delegated-runs);
+the behaviour is here.
+
+- **`timeoutMs`** (default ten minutes, `0` disables) bounds one child run. The
+  limit is per run, not per call, so a chain is bounded step by step and a
+  parallel batch bounds each task separately. On expiry the child gets the same
+  `SIGTERM`, then `SIGKILL` after 5 s, as a user abort — but the run fails
+  instead of throwing: a chain stops at that step, a parallel call counts a
+  failure, and the model sees `Timed out after 10m00s`.
+- **`transcripts`** (`off`, `failed`, or `all`; default `off`) keeps finished
+  runs on disk, all of them or only the failed ones.
+- **`retentionDays`** (default 14) and **`maxRuns`** (default 100) bound the
+  store. It is pruned at `session_start`, and only while transcripts are on.
+
+### Transcripts
+
+```
+.pi/subagents/20261015-143012-a1b2c3/
+  meta.json     agent, task, cwd, model, timings, exit, status, usage
+  events.jsonl  the child's raw stdout lines, verbatim
+  stderr.log    only when the child wrote any
+```
+
+The store is resolved against the **session** cwd, so inside a worktree it lands
+in the main checkout's `.pi/` and outlives that worktree — the anchoring the
+`job` registry uses. Outside a repository it falls back to
+`<agent-dir>/subagents`. The parent writes it and the child never learns it
+exists, so `readOnly`, the `--tools` allowlist, and the project-agent trust gate
+are unchanged. Writing is best-effort: an unwritable checkout records the failure
+in the result and never fails a run. The stream is buffered in the parent up to
+32 MiB, then truncated with a marker rather than silently dropped.
+
 ## Security
 
 A subagent is a real `pi` process and shares Pi's OS permissions. The built-in
@@ -206,7 +246,10 @@ Markdown, and per-step/per-task usage with a total.
 
 A failed or aborted result always shows its `errorMessage`, falling back to the
 subprocess `stderr`, in both the collapsed and expanded views, in every mode. A
-failure with neither falls back to `Error: Subprocess exited with code N.` and an
+run that exceeded its deadline reports `Timed out after …` the same way, and the
+expanded view adds the transcript path, the truncation marker, or why the
+transcript could not be written. A failure with neither falls back to
+`Error: Subprocess exited with code N.` and an
 `[exit N]` bracket, so a non-zero exit is never silent. A child terminated by a
 signal (an OOM kill, a crash) has no exit code, so it is recorded as
 `Terminated by <signal>` and reported as a failure. Parallel and chain
@@ -232,8 +275,10 @@ step's `Output`.
   does not reimplement tool execution or model streaming.
 - **No pinned models.** Built-in agents set no `model`, so a subprocess inherits
   the dispatching session's provider/model and thinking level.
-- **No persistence.** Subagent transcripts live only in the tool result details;
-  they are not written to the parent session.
+- **No persistence by default.** A run's transcript lives in the tool result
+  details; keeping it on disk is opt-in, parent-written, and bounded by age and
+  count. It is an audit and handoff record, not a resume point: replaying a run
+  whose writes already landed is not attempted.
 - **No cost attribution to the parent session.** A subagent's tokens and cost are
   captured in the tool result and shown in the transcript, but they belong to a
   separate process and are not added to the dispatching session's totals. Instead,
@@ -253,8 +298,8 @@ step's `Output`.
 | Annotations | `readOnlyHint: false`, `openWorldHint: true` |
 | Output schema | none; the full result lives in tool-result `details` |
 | Execution | spawns `pi --mode json` subprocesses; external agents discovered from `<agent-dir>/agents` and `.pi/agents` |
-| State storage | tool-result `details` only (no session persistence) |
-| Lifecycle | none; the tool is stateless and spawns per call |
+| State storage | tool-result `details`; optional per-run transcripts under `.pi/subagents/`, never the session |
+| Lifecycle | `session_start` loads the config and prunes expired transcripts; the tool itself is stateless |
 
 ## Design notes
 
@@ -284,6 +329,14 @@ step's `Output`.
   results arrive as `message_end` (messages, usage, model, stop reason) and
   failures as `tool_execution_end`. A tool error does not by itself fail the run,
   because the agent may recover.
+- **A deadline reuses the abort kill path but not its outcome.** One kill
+  closure serves both triggers, so the SIGTERM → 5 s SIGKILL escalation is
+  identical; only the reporting differs, because a deadline must leave the
+  finished steps in `details` while a user abort rejects the call.
+- **The transcript is the parent's.** Teeing the child's stdout and stderr in
+  `spawnAndCollect` and flushing in `runSingleAgent`'s `finally` means the
+  artifact exists even on the abort path, and the child needs no tool, no prompt
+  line, and no writable store.
 - **Bounded parallel output.** Parallel mode runs at most 4 of up to 8 tasks at
   once and caps each model-facing section at 50 KiB, appending an omission notice
   pointing at the tool details. The full results stay in `details` for rendering.
@@ -318,6 +371,8 @@ step's `Output`.
 | `schema.ts` | TypeBox params, limits, and `resolveMode`. |
 | `invocation.ts` | `pi` subprocess invocation and argument construction. |
 | `stream.ts` | JSON-event parsing, usage accounting, output helpers (pure). |
+| `transcripts.ts` | Per-run transcript buffer, run ids, the store directory, and pruning. |
+| `config.ts` | The `subagent` section of `bytefly.json`: deadline, transcripts, retention. |
 | `run.ts` | Runs one subagent process and captures its result. |
 | `format.ts` | Token/usage/tool-call formatting (pure). |
 | `render.ts` | `renderCall` / `renderResult` transcript rendering. |

package/extensions/subagent/config.ts

@@ -0,0 +1,58 @@
+/**
+ * Config-file support for subagent runs.
+ *
+ * The `subagent` section of the shared `bytefly.json` (global then project,
+ * project wins). Only the container is configurable — a run's deadline and
+ * whether it keeps a transcript on disk — never an agent's prompt or tools.
+ */
+
+import { clampInteger, loadConfigSection } from "../../lib/config.ts";
+
+/** Which finished runs keep a transcript on disk. */
+export const TRANSCRIPT_MODES = ["off", "failed", "all"] as const;
+
+/** One of {@link TRANSCRIPT_MODES}. */
+export type TranscriptMode = (typeof TRANSCRIPT_MODES)[number];
+
+export interface SubagentConfig {
+	/** Wall-clock limit for one child run in ms; `0` disables it. */
+	timeoutMs: number;
+	/** Which runs write a transcript under `.pi/subagents/`. */
+	transcripts: TranscriptMode;
+	/** Age in days after which a run directory is pruned at session start. */
+	retentionDays: number;
+	/** Most run directories kept, oldest pruned first. */
+	maxRuns: number;
+}
+
+export const DEFAULT_SUBAGENT_CONFIG: SubagentConfig = {
+	timeoutMs: 600_000,
+	transcripts: "off",
+	retentionDays: 14,
+	maxRuns: 100,
+};
+
+/** An unknown value read as one of {@link TRANSCRIPT_MODES}, or `fallback`. */
+function asTranscriptMode(value: unknown, fallback: TranscriptMode): TranscriptMode {
+	if (typeof value !== "string") return fallback;
+	return TRANSCRIPT_MODES.find((mode) => mode === value) ?? fallback;
+}
+
+/** Validate a raw config object over `base`. */
+export function normalizeSubagentConfig(
+	raw: Record<string, unknown> | undefined,
+	base: SubagentConfig,
+): SubagentConfig {
+	if (!raw) return base;
+	return {
+		timeoutMs: clampInteger(raw.timeoutMs, base.timeoutMs, 0, 3_600_000),
+		transcripts: asTranscriptMode(raw.transcripts, base.transcripts),
+		retentionDays: clampInteger(raw.retentionDays, base.retentionDays, 1, 3650),
+		maxRuns: clampInteger(raw.maxRuns, base.maxRuns, 1, 1000),
+	};
+}
+
+/** Effective subagent config from the shared `subagent` section. */
+export function loadSubagentConfig(cwd: string): SubagentConfig {
+	return loadConfigSection(cwd, "subagent", DEFAULT_SUBAGENT_CONFIG, normalizeSubagentConfig);
+}

package/extensions/subagent/index.ts

@@ -15,7 +15,7 @@
  * Load with:  pi --extension ./extensions/subagent
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled, resolveEffectiveCwd } from "../../lib/env.ts";
 import {
 	type AgentConfig,
@@ -25,8 +25,10 @@ import {
 	formatAgentList,
 	formatAgentNames,
 } from "./agents.ts";
+import { loadSubagentConfig, type SubagentConfig } from "./config.ts";
 import { runChainMode, runParallelMode, runSingleMode, type ModeContext } from "./orchestrate.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
+import { pruneTranscripts, transcriptsDirFor } from "./transcripts.ts";
 import { SUBAGENT_FINISHED_CHANNEL } from "../../lib/events.ts";
 import { finishedEvent } from "./accounting.ts";
 import { runSingleAgent, type RunOptions } from "./run.ts";
@@ -68,6 +70,21 @@ function requestedAgentNames(args: SubagentArgs): string[] {
 export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): void {
 	if (!isExtensionEnabled("subagent")) return;
 	const runner = deps.run ?? runSingleAgent;
+	// Read once per session; a call that arrives before `session_start` reads the
+	// same files lazily, so the two paths cannot disagree.
+	let settings: SubagentConfig | undefined;
+
+	const startSession = async (ctx: ExtensionContext): Promise<void> => {
+		settings = loadSubagentConfig(ctx.cwd);
+		if (settings.transcripts === "off") return;
+		try {
+			pruneTranscripts(await transcriptsDirFor(pi, ctx.cwd), settings);
+		} catch {
+			// Retention is housekeeping: an unreadable store must not fail a session.
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => startSession(ctx));
 
 	/**
 	 * Account for each finished child, then hand the result on unchanged.
@@ -127,6 +144,13 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 			const discovery = discoverAgents(root, agentScope);
 			const agents = discovery.agents;
 			const requestedTotal = args.chain?.length ?? args.tasks?.length ?? 1;
+			const config = settings ?? loadSubagentConfig(ctx.cwd);
+			// Resolved against the session cwd, not the active root: a run's record outlives
+			// the worktree it ran in, the way the `job` registry does.
+			const transcripts =
+				config.transcripts === "off"
+					? undefined
+					: { dir: await transcriptsDirFor(pi, ctx.cwd), mode: config.transcripts };
 			const makeDetails = (results: SingleResult[]): SubagentDetails => ({
 				mode,
 				results,
@@ -180,6 +204,8 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 				onUpdate,
 				makeDetails,
 				agents,
+				timeoutMs: config.timeoutMs,
+				transcripts,
 			};
 
 			if (mode === "chain" && args.chain) return runChainMode(context);

package/extensions/subagent/orchestrate.ts

@@ -6,6 +6,7 @@
 
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { AgentConfig } from "./agents.ts";
+import type { TranscriptMode } from "./config.ts";
 import type { RunOptions } from "./run.ts";
 import { MAX_CONCURRENCY, PER_TASK_OUTPUT_CAP, type SubagentArgs } from "./schema.ts";
 import {
@@ -30,11 +31,15 @@ export interface ModeContext {
 	onUpdate?: OnUpdateCallback;
 	/** Builds the details payload for this mode from the current results. */
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
+	/** Per-run wall-clock limit in ms; `0` or absent disables it. */
+	timeoutMs?: number;
+	/** Where and when a finished run writes a transcript. */
+	transcripts?: { dir: string; mode: Exclude<TranscriptMode, "off"> };
 }
 
 /** Sequential chain: each step's `{previous}` is the prior step's final output. */
 export async function runChainMode(ctx: ModeContext): Promise<AgentToolResult<SubagentDetails>> {
-	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents } = ctx;
+	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents, timeoutMs, transcripts } = ctx;
 	const chain = args.chain ?? [];
 	const results: SingleResult[] = [];
 	let previous = "";
@@ -62,6 +67,8 @@ export async function runChainMode(ctx: ModeContext): Promise<AgentToolResult<Su
 			signal,
 			onUpdate: chainUpdate,
 			makeDetails,
+			timeoutMs,
+			transcripts,
 		});
 		results.push(result);
 
@@ -89,7 +96,7 @@ export async function runChainMode(ctx: ModeContext): Promise<AgentToolResult<Su
 
 /** Independent tasks with bounded concurrency, reporting running/done progress. */
 export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult<SubagentDetails>> {
-	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents } = ctx;
+	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents, timeoutMs, transcripts } = ctx;
 	const tasks = args.tasks ?? [];
 	const allResults: SingleResult[] = tasks.map((task) => createResult(task.agent, task.task));
 
@@ -113,6 +120,10 @@ export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult
 			cwd: task.cwd,
 			readOnly: args.readOnly,
 			signal,
+			// Elapsed time is per run, so a deadline is too: one timer around the mode
+			// would bound the batch rather than each child.
+			timeoutMs,
+			transcripts,
 			onUpdate: (partial) => {
 				const current = partial.details?.results[0];
 				if (!current) return;
@@ -148,7 +159,7 @@ export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult
 
 /** One agent + task. */
 export async function runSingleMode(ctx: ModeContext): Promise<AgentToolResult<SubagentDetails>> {
-	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents } = ctx;
+	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents, timeoutMs, transcripts } = ctx;
 	const result = await run({
 		defaultCwd,
 		defaults,
@@ -160,6 +171,8 @@ export async function runSingleMode(ctx: ModeContext): Promise<AgentToolResult<S
 		signal,
 		onUpdate,
 		makeDetails,
+		timeoutMs,
+		transcripts,
 	});
 
 	if (isFailedResult(result)) {

package/extensions/subagent/render.ts

@@ -296,6 +296,16 @@ function callText(args: StreamedSubagentArgs, theme: Theme, context?: { cwd?: st
 	return text;
 }
 
+/** The transcript this run kept, or why it could not be written. */
+function transcriptLine(result: SingleResult, theme: Theme): string | undefined {
+	if (result.artifactError) {
+		return paint(theme, "warn", `transcript failed: ${sanitizeLine(result.artifactError)}`);
+	}
+	if (!result.artifactPath) return undefined;
+	const cut = result.artifactTruncated ? paint(theme, "warn", " (truncated)") : "";
+	return paint(theme, "faint", `transcript: ${sanitizeLine(result.artifactPath)}${cut}`);
+}
+
 /** Append one result's expanded block: header, error, task, output, usage. */
 function addExpandedResult(
 	container: Container,
@@ -353,6 +363,8 @@ function addExpandedResult(
 		container.addChild(new Spacer(1));
 		container.addChild(new Text(paint(theme, "faint", usage), 0, 0));
 	}
+	const transcript = transcriptLine(result, theme);
+	if (transcript) container.addChild(new Text(transcript, 0, 0));
 }
 
 /** The collapsed single result: header, a word, body, expand hint, and usage. */

package/extensions/subagent/run.ts

@@ -2,8 +2,9 @@
  * Running one subagent subprocess.
  *
  * Spawns `pi --mode json`, folds the JSON event stream into a `SingleResult`,
- * streams partial updates, and cleans up the temporary system-prompt file. The
- * process factory is injectable so tests can drive a scripted child.
+ * enforces the run's deadline, optionally records the raw stream, streams partial
+ * updates, and cleans up the temporary system-prompt file. The process factory and
+ * the transcript store are injectable so tests can drive a scripted child.
  */
 
 import { spawn as nodeSpawn } from "node:child_process";
@@ -11,9 +12,12 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { formatDuration } from "../../lib/format.ts";
 import { BUILTIN_AGENTS, formatAgentList, type AgentConfig } from "./agents.ts";
+import type { TranscriptMode } from "./config.ts";
 import { buildAgentArgs, getPiInvocation, READ_ONLY_NOTE } from "./invocation.ts";
-import { applyEvent, createResult, parseJsonLine } from "./stream.ts";
+import { applyEvent, createResult, isFailedResult, parseJsonLine } from "./stream.ts";
+import { createTranscript, type Transcript } from "./transcripts.ts";
 import type { DispatchDefaults, OnUpdateCallback, SingleResult, SpawnFn, SubagentDetails } from "./types.ts";
 
 export interface RunOptions {
@@ -38,6 +42,10 @@ export interface RunOptions {
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
 	/** Process factory; defaults to `node:child_process.spawn`. */
 	spawn?: SpawnFn;
+	/** Per-run wall-clock limit in ms; `0` or absent disables it. */
+	timeoutMs?: number;
+	/** Where and when a finished run writes a transcript. */
+	transcripts?: { dir: string; mode: Exclude<TranscriptMode, "off"> };
 }
 
 async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
@@ -53,46 +61,79 @@ async function writePromptToTempFile(agentName: string, prompt: string): Promise
 interface SpawnOutcome {
 	exitCode: number;
 	aborted: boolean;
+	timedOut: boolean;
+}
+
+/** How long a killed child has to exit before it is killed again, hard. */
+const KILL_ESCALATION_MS = 5000;
+
+/** Why a child is being killed; a timeout fails the run, an abort rejects the call. */
+type KillReason = "abort" | "timeout";
+
+interface SpawnContext {
+	command: string;
+	args: string[];
+	cwd: string;
+	/** Per-run wall-clock limit in ms; `0` disables it. */
+	timeoutMs: number;
+	signal?: AbortSignal;
+	result: SingleResult;
+	onEvent: () => void;
+	transcript?: Transcript;
+	spawn: SpawnFn;
 }
 
 /** Spawn the child, parse stdout line-by-line, and resolve when it closes. */
-function spawnAndCollect(
-	command: string,
-	args: string[],
-	cwd: string,
-	signal: AbortSignal | undefined,
-	result: SingleResult,
-	onEvent: () => void,
-	spawn: SpawnFn,
-): Promise<SpawnOutcome> {
+function spawnAndCollect(context: SpawnContext): Promise<SpawnOutcome> {
+	const { command, args, cwd, timeoutMs, signal, result, onEvent, transcript, spawn } = context;
 	return new Promise<SpawnOutcome>((resolve) => {
 		const proc = spawn(command, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
 		let buffer = "";
 		let settled = false;
-		let aborted = false;
+		let abortRequested = false;
+		let timedOut = false;
 
-		let kill: (() => void) | undefined;
 		let killTimer: ReturnType<typeof setTimeout> | undefined;
+		let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+
+		const kill = (reason: KillReason) => {
+			if (settled) return;
+			if (reason === "abort") abortRequested = true;
+			else {
+				timedOut = true;
+				result.timedOut = true;
+			}
+			proc.kill("SIGTERM");
+			killTimer = setTimeout(() => {
+				if (!proc.killed) proc.kill("SIGKILL");
+			}, KILL_ESCALATION_MS);
+			killTimer.unref();
+		};
+		const onAbort = () => kill("abort");
 
 		const finish = (exitCode: number) => {
 			if (settled) return;
 			settled = true;
-			if (kill && signal) signal.removeEventListener("abort", kill);
+			if (signal) signal.removeEventListener("abort", onAbort);
 			if (killTimer) clearTimeout(killTimer);
+			if (timeoutTimer) clearTimeout(timeoutTimer);
 			if (buffer.trim()) {
+				transcript?.line(buffer);
 				const event = parseJsonLine(buffer);
 				if (event && applyEvent(result, event)) onEvent();
 			}
-			resolve({ exitCode, aborted });
+			resolve({ exitCode, aborted: abortRequested, timedOut });
 		};
 
 		const processLine = (line: string) => {
+			transcript?.line(line);
 			const event = parseJsonLine(line);
 			if (event && applyEvent(result, event)) onEvent();
 		};
 
 		proc.stdout?.on("data", (chunk) => {
-			buffer += chunk.toString();
+			const text = chunk.toString();
+			buffer += text;
 			// Keep the final partial line in the buffer for the close handler.
 			let newline = buffer.indexOf("\n");
 			while (newline !== -1) {
@@ -103,7 +144,9 @@ function spawnAndCollect(
 		});
 
 		proc.stderr?.on("data", (chunk) => {
-			result.stderr += chunk.toString();
+			const text = chunk.toString();
+			result.stderr += text;
+			transcript?.stderr(text);
 		});
 
 		proc.on("close", (code, signal) => {
@@ -122,16 +165,12 @@ function spawnAndCollect(
 		});
 
 		if (signal) {
-			kill = () => {
-				aborted = true;
-				proc.kill("SIGTERM");
-				killTimer = setTimeout(() => {
-					if (!proc.killed) proc.kill("SIGKILL");
-				}, 5000);
-				killTimer.unref();
-			};
-			if (signal.aborted) kill();
-			else signal.addEventListener("abort", kill, { once: true });
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+		if (timeoutMs > 0) {
+			timeoutTimer = setTimeout(() => kill("timeout"), timeoutMs);
+			timeoutTimer.unref();
 		}
 	});
 }
@@ -163,6 +202,12 @@ export async function runSingleAgent(options: RunOptions): Promise<SingleResult>
 
 	const emit = () => options.onUpdate?.({ content: [], details: options.makeDetails([result]) });
 
+	const timeoutMs = options.timeoutMs ?? 0;
+	if (timeoutMs > 0) result.timeoutMs = timeoutMs;
+	const transcripts = options.transcripts;
+	const transcript = transcripts ? createTranscript() : undefined;
+	let runCwd = options.defaultCwd;
+
 	let tempDir: string | null = null;
 	let tempPath: string | null = null;
 
@@ -178,22 +223,40 @@ export async function runSingleAgent(options: RunOptions): Promise<SingleResult>
 
 		const args = buildAgentArgs(agent, options.task, options.defaults, tempPath, options.readOnly === true);
 		const invocation = getPiInvocation(args);
-		const runCwd = options.cwd ? path.resolve(options.defaultCwd, options.cwd) : options.defaultCwd;
-		const outcome = await spawnAndCollect(
-			invocation.command,
-			invocation.args,
-			runCwd,
-			options.signal,
+		runCwd = options.cwd ? path.resolve(options.defaultCwd, options.cwd) : options.defaultCwd;
+		const outcome = await spawnAndCollect({
+			command: invocation.command,
+			args: invocation.args,
+			cwd: runCwd,
+			timeoutMs,
+			signal: options.signal,
 			result,
-			emit,
+			onEvent: emit,
+			transcript,
 			spawn,
-		);
+		});
 
-		result.exitCode = outcome.exitCode;
+		result.exitCode = outcome.timedOut ? 1 : outcome.exitCode;
 		result.finishedAt = Date.now();
+		// A deadline fails the run rather than rejecting it: a chain then stops at
+		// this step and reports why, instead of discarding the steps already done.
+		if (outcome.timedOut) result.errorMessage = `Timed out after ${formatDuration(timeoutMs)}`;
 		if (outcome.aborted) throw new Error("Subagent was aborted");
 		return result;
 	} finally {
+		// Flushed here, not after the call: the abort path throws past every caller.
+		if (transcript && transcripts && (transcripts.mode === "all" || isFailedResult(result))) {
+			const written = transcript.write(transcripts.dir, result, {
+				cwd: runCwd,
+				readOnly: options.readOnly === true,
+			});
+			if (written.path) {
+				result.artifactPath = written.path;
+				result.artifactBytes = written.bytes;
+				if (written.truncated) result.artifactTruncated = true;
+			}
+			if (written.error) result.artifactError = written.error;
+		}
 		if (tempPath) {
 			try {
 				fs.unlinkSync(tempPath);