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

package/extensions/bytefly/separator/component.ts

@@ -1,27 +1,28 @@
 /**
  * The transcript component that draws one separator entry.
  *
- * It is stateless: the line is derived from the stored turn number and the
- * width passed to `render`, so there is nothing to invalidate.
+ * It is stateless: the line is derived from the stored entry data and the width
+ * passed to `render`, so there is nothing to invalidate.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
 import { separatorLine } from "./format.ts";
+import type { TurnSeparatorData } from "./types.ts";
 
-/** Renders one separator entry; `turn` comes from the stored entry data. */
+/** Renders one separator entry; the data comes from the stored entry. */
 export class SeparatorComponent implements Component {
 	constructor(
-		private readonly turn: number,
+		private readonly data: TurnSeparatorData,
 		private readonly theme: Theme,
 		private readonly pad = 0,
 	) {}
 
 	invalidate(): void {
-		// Stateless: the line is derived from `turn` and the width passed to render.
+		// Stateless: the line is derived from the data and the width passed to render.
 	}
 
 	render(width: number): string[] {
-		return separatorLine(this.turn, width, this.theme, this.pad);
+		return separatorLine(this.data, width, this.theme, this.pad);
 	}
 }

package/extensions/bytefly/separator/config.ts

@@ -22,6 +22,16 @@ export const CONFIG = {
 	dashRole: "ruleStrong",
 	/** Role for the label. */
 	labelRole: "meta",
+	/** Role for a turn with a failed tool. */
+	failureRole: "bad",
+	/** Role for an aborted turn; escape is a warning, not an error. */
+	abortedRole: "warn",
+	/** Smallest run duration printed on the receipt; shorter turns keep the label quiet. */
+	minDurationMs: 1000,
+	/** Word appended when the run was aborted. */
+	abortedLabel: "aborted",
+	/** Glyph before a failed tool count. */
+	failureGlyph: GLYPHS.cross,
 } as const satisfies {
 	customType: string;
 	glyph: string;
@@ -29,4 +39,9 @@ export const CONFIG = {
 	pad: number;
 	dashRole: TuiRole;
 	labelRole: TuiRole;
+	failureRole: TuiRole;
+	abortedRole: TuiRole;
+	minDurationMs: number;
+	abortedLabel: string;
+	failureGlyph: string;
 };

package/extensions/bytefly/separator/format.ts

@@ -1,14 +1,67 @@
 /**
  * Pure formatting for bytefly's turn separator line.
  *
- * The centered `╌╌╌ turn N ╌╌╌` layout comes from the design system's
- * `centeredRule`, so this module only names the turn; the shared rule owns the
- * centering, the degradation, and the colors.
+ * The line is a receipt for the settled run: the turn number, then as much of
+ * the duration, the top-level tool count, and the outcome as the width can
+ * carry. The centered `╌╌╌ turn N ╌╌╌` layout comes from the design system's
+ * `centeredRule`, so this module only builds the label and picks its role; the
+ * shared rule owns the centering and the dashes.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { formatDuration, formatToolCount } from "../../../lib/format.ts";
+import { SEPARATORS } from "../../../lib/tui/glyphs.ts";
 import { centeredRule } from "../../../lib/tui/rules.ts";
+import type { TuiRole } from "../../../lib/tui/tokens.ts";
 import { CONFIG } from "./config.ts";
+import type { TurnSeparatorData } from "./types.ts";
+
+/** Whether the label and `centeredRule`'s two pads leave room for a dash. */
+function fits(label: string, width: number): boolean {
+	return visibleWidth(label) + CONFIG.pad * 2 < width;
+}
+
+/**
+ * The widest receipt that fits, shed one field at a time.
+ *
+ * The tool count goes first, then the duration; the outcome stays beside the
+ * turn as long as it fits, because a failed or aborted run is the part the rule
+ * should not hide. The turn number itself is never dropped here — a terminal
+ * too narrow even for that falls back to `centeredRule`'s plain dashed rule.
+ */
+export function receiptLabel(data: TurnSeparatorData, width: number): string {
+	const turn = `${CONFIG.labelPrefix} ${data.turn}`;
+	const duration =
+		data.durationMs !== undefined && data.durationMs >= CONFIG.minDurationMs
+			? formatDuration(data.durationMs)
+			: undefined;
+	const tools = data.tools !== undefined && data.tools > 0 ? formatToolCount(data.tools) : undefined;
+	const outcome = data.aborted
+		? CONFIG.abortedLabel
+		: data.failures !== undefined && data.failures > 0
+			? `${CONFIG.failureGlyph}${data.failures}`
+			: undefined;
+
+	const steps: Array<Array<string | undefined>> = [
+		[turn, duration, tools, outcome],
+		[turn, duration, outcome],
+		[turn, outcome],
+		[turn],
+	];
+	for (const parts of steps) {
+		const label = parts.filter((part): part is string => part !== undefined).join(SEPARATORS.item);
+		if (fits(label, width)) return label;
+	}
+	return turn;
+}
+
+/** The label's role: an aborted turn warns, a failed tool is an error. */
+export function receiptRole(data: TurnSeparatorData): TuiRole {
+	if (data.aborted) return CONFIG.abortedRole;
+	if (data.failures !== undefined && data.failures > 0) return CONFIG.failureRole;
+	return CONFIG.labelRole;
+}
 
 /**
  * One rendered line: the centered turn rule, colored by role.
@@ -17,14 +70,15 @@ import { CONFIG } from "./config.ts";
  * component raw, so the rule insets itself symmetrically by that many columns,
  * keeping its left edge on the transcript's margin.
  */
-export function separatorLine(turn: number, width: number, theme: Theme, pad = 0): string[] {
+export function separatorLine(data: TurnSeparatorData, width: number, theme: Theme, pad = 0): string[] {
 	const w = Math.max(1, Math.floor(width));
 	const inset = Math.max(0, Math.min(Math.floor(pad), Math.floor((w - 1) / 2)));
-	const line = centeredRule(theme, Math.max(1, w - inset * 2), `${CONFIG.labelPrefix} ${turn}`, {
+	const ruleWidth = Math.max(1, w - inset * 2);
+	const line = centeredRule(theme, ruleWidth, receiptLabel(data, ruleWidth), {
 		glyph: CONFIG.glyph,
 		pad: CONFIG.pad,
 		fillRole: CONFIG.dashRole,
-		labelRole: CONFIG.labelRole,
+		labelRole: receiptRole(data),
 	});
 	return [`${" ".repeat(inset)}${line}`];
 }

package/extensions/bytefly/separator/register.ts

@@ -4,11 +4,15 @@
  * Pi has no built-in turn separator. On every fully settled agent run
  * (`agent_settled`, one per user turn) this appends an inert custom entry that
  * is excluded from LLM context, and a registered entry renderer draws it as a
- * centered `╌╌╌ turn N ╌╌╌` rule in the interactive transcript.
+ * centered `╌╌╌ turn N ╌╌╌` rule in the interactive transcript. The entry also
+ * carries the run's receipt — duration, top-level tool count, failed tools, and
+ * whether the user aborted it — so the rule can read as a flight log.
  *
  * `agent_settled` is deliberate: `turn_end` fires once per assistant message,
  * so tool-calling rounds would each get a line, while a settled run is exactly
- * one user turn.
+ * one user turn. The run's first `agent_start` opens the receipt and later
+ * starts (a retry or a continuation) stay in it, so the duration covers the
+ * whole settled run rather than one attempt.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -17,6 +21,12 @@ import { SeparatorComponent } from "./component.ts";
 import { CONFIG } from "./config.ts";
 import type { TurnSeparatorData } from "./types.ts";
 
+/** Host seams, injected by tests so the duration is deterministic. */
+export interface SeparatorDeps {
+	/** The clock the duration is read from. */
+	now?: () => number;
+}
+
 /** Count separators already on the branch, so numbering survives resume and fork. */
 function countSeparators(entries: readonly { type: string; customType?: string }[]): number {
 	let count = 0;
@@ -27,17 +37,66 @@ function countSeparators(entries: readonly { type: string; customType?: string }
 }
 
 /** Register the separator renderer and append one on every settled turn. */
-export function registerTurnSeparator(pi: ExtensionAPI, pad: PadSource = createPadStore()): void {
+export function registerTurnSeparator(
+	pi: ExtensionAPI,
+	pad: PadSource = createPadStore(),
+	deps: SeparatorDeps = {},
+): void {
+	const now = deps.now ?? (() => Date.now());
+	// The current run's receipt. `startedAt` is the first `agent_start`; the
+	// counters span every top-level tool in the settled run.
+	let startedAt: number | undefined;
+	let tools = 0;
+	let failures = 0;
+
+	const reset = (): void => {
+		startedAt = undefined;
+		tools = 0;
+		failures = 0;
+	};
+
 	pi.registerEntryRenderer<TurnSeparatorData>(CONFIG.customType, (entry, _options, theme) => {
-		const turn = entry.data?.turn;
-		if (typeof turn !== "number" || !Number.isFinite(turn)) return undefined;
-		return new SeparatorComponent(turn, theme, pad.resolve());
+		const data = entry.data;
+		if (!data || typeof data.turn !== "number" || !Number.isFinite(data.turn)) return undefined;
+		return new SeparatorComponent(data, theme, pad.resolve());
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		if (ctx.mode !== "tui" || startedAt !== undefined) return;
+		startedAt = now();
+		tools = 0;
+		failures = 0;
 	});
 
-	pi.on("agent_settled", (_event, ctx) => {
+	// A nested tool is an implementation detail of its parent, not a transcript
+	// block, so it neither counts nor contributes a failure.
+	pi.on("tool_execution_start", (event) => {
+		if (startedAt === undefined || event.parentToolCallId) return;
+		tools += 1;
+	});
+
+	pi.on("tool_execution_end", (event) => {
+		if (startedAt === undefined || event.parentToolCallId || !event.isError) return;
+		failures += 1;
+	});
+
+	pi.on("agent_settled", (event, ctx) => {
 		// The transcript is interactive-only; keep RPC/JSON/print sessions clean.
-		if (ctx.mode !== "tui") return;
+		if (ctx.mode !== "tui") {
+			reset();
+			return;
+		}
 		const turn = countSeparators(ctx.sessionManager.getBranch()) + 1;
-		pi.appendEntry<TurnSeparatorData>(CONFIG.customType, { turn });
+		const data: TurnSeparatorData = { turn };
+		if (startedAt !== undefined) {
+			data.durationMs = Math.max(0, now() - startedAt);
+			if (tools > 0) data.tools = tools;
+			if (failures > 0) data.failures = failures;
+		}
+		if (event.aborted) data.aborted = true;
+		pi.appendEntry<TurnSeparatorData>(CONFIG.customType, data);
+		reset();
 	});
+
+	pi.on("session_shutdown", () => reset());
 }

package/extensions/bytefly/separator/types.ts

@@ -9,4 +9,12 @@
 export interface TurnSeparatorData {
 	/** 1-based index of the completed user turn this separator follows. */
 	turn: number;
+	/** From the run's first `agent_start` to `agent_settled`, in milliseconds. */
+	durationMs?: number;
+	/** Top-level tool calls the run started. */
+	tools?: number;
+	/** Top-level tool calls that ended in error. */
+	failures?: number;
+	/** Whether the run ended because the user aborted it. */
+	aborted?: boolean;
 }

package/extensions/bytefly/working/config.ts

@@ -1,13 +1,12 @@
 /**
- * Tuning for bytefly's live working timer.
+ * Tuning for bytefly's live working line.
  *
- * While Pi's working row is up, the counter is written into the working message
- * Pi renders beside its spinner. Edit this file to change the word or how often
- * the count advances.
+ * While Pi's working row is up, the message is written into the row beside Pi's
+ * spinner. Edit this file to change the words or how often the count advances.
  */
 
 export const WORKING_CONFIG = {
-	/** Word before the count. */
+	/** Word before the count, before the first tool starts. */
 	working: "Working",
 	/** Between the word and the count. */
 	ellipsis: "…",

package/extensions/bytefly/working/format.ts

@@ -1,13 +1,24 @@
 /**
- * Pure text for the live working timer.
+ * Pure text for the live working line.
  *
- * Whole seconds, because the counter advances on a one-second tick: `0s` at the
- * start, `42s`, `1m05s`, `1h02m`. Negative and non-finite input reads as `0s`,
- * so a clock that steps backwards cannot print a negative count.
+ * Before the first tool starts it is a plain count (`Working… 42s`). After that
+ * it names the last top-level tool and how many this run has started, then the
+ * elapsed time (`edit · 3 tools · 42s`). Whole seconds, because the tick
+ * advances once a second; negative and non-finite input reads as `0s`.
  */
 
+import { sanitizeLine, formatToolCount } from "../../../lib/format.ts";
+import { SEPARATORS } from "../../../lib/tui/glyphs.ts";
 import { WORKING_CONFIG } from "./config.ts";
 
+/** What the current run has done so far, for the live line. */
+export interface WorkingRun {
+	/** The last top-level tool started, or `null` before the first one. */
+	readonly tool: string | null;
+	/** Top-level tool calls started in this run. */
+	readonly tools: number;
+}
+
 /** Compact elapsed time in whole seconds: `0s`, `42s`, `1m05s`, `1h02m`. */
 export function formatElapsed(ms: number): string {
 	const total = Number.isFinite(ms) && ms > 0 ? Math.floor(ms / 1000) : 0;
@@ -19,7 +30,13 @@ export function formatElapsed(ms: number): string {
 	return `${seconds}s`;
 }
 
-/** The working-row message for an elapsed time, e.g. `Working… 4s`. */
-export function workingCounter(ms: number): string {
-	return `${WORKING_CONFIG.working}${WORKING_CONFIG.ellipsis} ${formatElapsed(ms)}`;
+/** The working-row message: `Working… 4s` until a tool starts, then the run line. */
+export function workingCounter(ms: number, run?: WorkingRun): string {
+	const elapsed = formatElapsed(ms);
+	const tools = run?.tools ?? 0;
+	const tool = run?.tool ? sanitizeLine(run.tool) : "";
+	if (tools > 0) {
+		return [tool, formatToolCount(tools), elapsed].filter((part) => part !== "").join(SEPARATORS.item);
+	}
+	return `${WORKING_CONFIG.working}${WORKING_CONFIG.ellipsis} ${elapsed}`;
 }

package/extensions/bytefly/working/register.ts

@@ -1,9 +1,11 @@
 /**
- * bytefly's live working timer.
+ * bytefly's live working line.
  *
  * Pi's working row shows a static `Working`, so a long run reads the same as a
  * short one. This surface advances the message once a second while the row is
- * up, and hands it back to Pi when the row comes down.
+ * up, and hands it back to Pi when the row comes down. Once a top-level tool
+ * starts, the message also names that tool and how many this run has started,
+ * turning the row into a live run line (`edit · 3 tools · 12s`).
  *
  * The timer is tied to the row's visibility. The host shows the working
  * indicator in its own `turn_start` handler and clears it at `agent_end`
@@ -12,6 +14,11 @@
  * one run do not restart it: the host leaves the same indicator up across
  * turns, and `start` is a no-op while it is counting.
  *
+ * A nested tool call (one carrying `parentToolCallId`, such as a codemode
+ * script's inner call) is not counted and does not take over the line, so the
+ * number matches the tool blocks the transcript shows. The tool events repaint
+ * the row immediately; the one-second tick is still the only timer.
+ *
  * Compaction and auto-retry also replace the row, but both run outside this
  * window (`auto_retry_start` follows `agent_end`; the before-settle compaction
  * runs after it), and neither is an extension event, so there is nothing to
@@ -49,6 +56,17 @@ export function registerWorkingTimer(pi: ExtensionAPI, deps: WorkingDeps = {}):
 	let startedAt = 0;
 	// A boolean, not `startedAt === 0`: an injected clock is allowed to start at 0.
 	let active = false;
+	// The last top-level tool and how many this run has started. Reset with the run.
+	let tool: string | null = null;
+	let tools = 0;
+
+	/** The current row text, from the run state and the elapsed time. */
+	const message = (): string => workingCounter(now() - startedAt, { tool, tools });
+
+	/** Repaint an active row now, so a tool start does not wait for the next tick. */
+	const refresh = (ctx: ExtensionContext): void => {
+		if (active) ctx.ui.setWorkingMessage(message());
+	};
 
 	/** Stop the tick and hand the working message back to Pi. Idempotent. */
 	const stop = (ctx: ExtensionContext): void => {
@@ -56,6 +74,8 @@ export function registerWorkingTimer(pi: ExtensionAPI, deps: WorkingDeps = {}):
 		cancel = undefined;
 		if (!active) return;
 		active = false;
+		tool = null;
+		tools = 0;
 		ctx.ui.setWorkingMessage(undefined);
 	};
 
@@ -64,8 +84,10 @@ export function registerWorkingTimer(pi: ExtensionAPI, deps: WorkingDeps = {}):
 		if (active) return;
 		startedAt = now();
 		active = true;
+		tool = null;
+		tools = 0;
 		const tick = (): void => {
-			ctx.ui.setWorkingMessage(workingCounter(now() - startedAt));
+			ctx.ui.setWorkingMessage(message());
 		};
 		tick();
 		cancel = schedule(tick, WORKING_CONFIG.intervalMs);
@@ -78,6 +100,15 @@ export function registerWorkingTimer(pi: ExtensionAPI, deps: WorkingDeps = {}):
 		start(ctx);
 	});
 
+	// A nested tool is an implementation detail of its parent run, not a
+	// transcript block, so it neither counts nor takes over the line.
+	pi.on("tool_execution_start", (event, ctx) => {
+		if (ctx.mode !== "tui" || !active || event.parentToolCallId) return;
+		tool = event.toolName;
+		tools += 1;
+		refresh(ctx);
+	});
+
 	// The host clears the working indicator at `agent_end`.
 	pi.on("agent_end", (_event, ctx) => {
 		if (ctx.mode !== "tui") return;

package/extensions/memory/README.md

@@ -7,6 +7,8 @@ live as human-editable markdown, not in the session branch, so they survive
 `AGENTS.md`; `memory` is for the one-liners the model should not have to be
 reminded of twice.
 
+<img src="../../assets/memory.png" alt="The /memory picker: a Memory title rule, an `All · 3 project, 2 global` summary, five notes tagged by scope with the focused one marked, and the key hints" width="100%">
+
 ```bash
 pi --extension ./extensions/memory    # load just this extension
 pi -e .                               # load the whole @gavin-hu/my-pi-agent package

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);
+}