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

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

package/extensions/subagent/transcripts.ts

@@ -0,0 +1,202 @@
+/**
+ * Opt-in per-run transcripts.
+ *
+ * The dispatching process writes these; a child never learns that one exists, so
+ * the read-only tool set and the project-agent trust gate stay exactly as strict
+ * as they are. Lines are buffered in memory up to {@link MAX_TRANSCRIPT_BYTES}
+ * and flushed once at the end of the run, which keeps the store ordered without a
+ * stream to close and still writes on the abort path.
+ *
+ * Every failure is reported, never thrown: an unwritable checkout must not fail a
+ * delegation that already did its work.
+ */
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { repoRootFor } from "../../lib/git/index.ts";
+import type { SingleResult } from "./types.ts";
+
+/** Ceiling for one run's buffered transcript, stdout and stderr together. */
+export const MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
+
+/** `YYYYMMDD-HHMMSS-abcdef`; a name sort is chronological, so pruning never parses one. */
+const RUN_ID_PATTERN = /^\d{8}-\d{6}-[0-9a-f]{6}$/;
+
+const EVENTS_FILE = "events.jsonl";
+const STDERR_FILE = "stderr.log";
+const META_FILE = "meta.json";
+
+/** What a transcript needs from the run that produced it. */
+export interface TranscriptContext {
+	/** Working directory the child ran in. */
+	cwd: string;
+	/** Whether the run forced a reader-only tool set. */
+	readOnly: boolean;
+}
+
+/** The outcome of writing one run directory. */
+export interface TranscriptWritten {
+	/** Directory written, absent when the write failed. */
+	path?: string;
+	/** Bytes buffered for this run. */
+	bytes: number;
+	/** Whether the size cap cut the transcript short. */
+	truncated: boolean;
+	/** Why the write failed, when it did. */
+	error?: string;
+}
+
+/** A run's buffered transcript, written once the run has finished. */
+export interface Transcript {
+	/** Append one raw stdout line. */
+	line(raw: string): void;
+	/** Append stderr text, which may arrive in partial chunks. */
+	stderr(text: string): void;
+	/** Write the run directory under `dir`. Never throws. */
+	write(dir: string, result: SingleResult, context: TranscriptContext): TranscriptWritten;
+}
+
+/** The directory holding every transcript for `cwd`'s repository. */
+export async function transcriptsDirFor(pi: Pick<ExtensionAPI, "exec">, cwd: string): Promise<string> {
+	const root = await repoRootFor(pi, cwd, 5_000);
+	return root ? join(root, CONFIG_DIR_NAME, "subagents") : join(getAgentDir(), "subagents");
+}
+
+/** A run id for `at` (epoch ms, rendered in UTC) with a six-hex suffix. */
+export function runIdFor(at: number, suffix: string): string {
+	const date = new Date(at);
+	const pad = (value: number, width = 2) => String(value).padStart(width, "0");
+	const day = `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}`;
+	const time = `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}`;
+	return `${day}-${time}-${suffix}`;
+}
+
+/** The metadata written beside a run's stream; enough to audit it without one. */
+function metaFor(runId: string, result: SingleResult, context: TranscriptContext, truncated: boolean) {
+	return {
+		version: 1,
+		runId,
+		agent: result.agent,
+		agentSource: result.agentSource,
+		task: result.task,
+		step: result.step,
+		cwd: context.cwd,
+		readOnly: context.readOnly,
+		provider: result.provider,
+		model: result.model,
+		startedAt: result.startedAt,
+		finishedAt: result.finishedAt,
+		exitCode: result.exitCode,
+		timedOut: result.timedOut === true,
+		stopReason: result.stopReason,
+		errorMessage: result.errorMessage,
+		toolErrors: result.toolErrors ?? 0,
+		usage: result.usage,
+		transcript: { truncated },
+	};
+}
+
+/** Buffer one run's stream until it finishes. */
+export function createTranscript(options: { maxBytes?: number } = {}): Transcript {
+	const maxBytes = options.maxBytes ?? MAX_TRANSCRIPT_BYTES;
+	const lines: string[] = [];
+	let stderr = "";
+	let bytes = 0;
+	let truncated = false;
+
+	const append = (text: string, kind: "line" | "stderr"): void => {
+		if (truncated || !text) return;
+		const size = Buffer.byteLength(text);
+		if (bytes + size > maxBytes) {
+			// Stop growing; the marker is added on write so the file stays parseable.
+			truncated = true;
+			return;
+		}
+		bytes += size;
+		if (kind === "line") lines.push(text);
+		else stderr += text;
+	};
+
+	return {
+		line: (raw) => append(raw, "line"),
+		stderr: (text) => append(text, "stderr"),
+
+		write(dir, result, context) {
+			const runId = runIdFor(result.startedAt ?? Date.now(), randomBytes(3).toString("hex"));
+			const runDir = join(dir, runId);
+			try {
+				mkdirSync(runDir, { recursive: true });
+				const body = truncated ? [...lines, JSON.stringify({ type: "transcript-truncated", bytes })] : lines;
+				if (body.length > 0) writeFileSync(join(runDir, EVENTS_FILE), `${body.join("\n")}\n`, { mode: 0o600 });
+				if (stderr) writeFileSync(join(runDir, STDERR_FILE), stderr, { mode: 0o600 });
+				// Written last: a directory without metadata is an interrupted write.
+				const meta = `${JSON.stringify(metaFor(runId, result, context, truncated), null, 2)}\n`;
+				writeFileSync(join(runDir, META_FILE), meta, { mode: 0o600 });
+				return { path: runDir, bytes, truncated };
+			} catch (error) {
+				return {
+					bytes,
+					truncated,
+					error: error instanceof Error ? error.message : String(error),
+				};
+			}
+		},
+	};
+}
+
+/** Which run directories a prune keeps and which it removes. */
+export interface PruneOutcome {
+	removed: string[];
+	/** Runs still on disk after the prune. */
+	kept: number;
+}
+
+/**
+ * Remove aged and surplus run directories. Only names matching a run id are
+ * candidates, so an unrelated directory under the store is never touched.
+ */
+export function pruneTranscripts(
+	dir: string,
+	options: { retentionDays: number; maxRuns: number; now?: number },
+): PruneOutcome {
+	const now = options.now ?? Date.now();
+	let names: string[];
+	try {
+		names = readdirSync(dir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && RUN_ID_PATTERN.test(entry.name))
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return { removed: [], kept: 0 };
+	}
+
+	const kept: string[] = [];
+	const stale: string[] = [];
+	for (const name of names) {
+		let modified: number;
+		try {
+			modified = statSync(join(dir, name)).mtimeMs;
+		} catch {
+			continue;
+		}
+		if (now - modified > options.retentionDays * 86_400_000) stale.push(name);
+		else kept.push(name);
+	}
+	while (kept.length > options.maxRuns) {
+		const oldest = kept.shift();
+		if (oldest) stale.push(oldest);
+	}
+
+	const removed: string[] = [];
+	for (const name of stale) {
+		try {
+			rmSync(join(dir, name), { recursive: true, force: true });
+			removed.push(name);
+		} catch {
+			// Best-effort: a locked directory is retried at the next session start.
+		}
+	}
+	return { removed, kept: kept.length };
+}

package/extensions/subagent/types.ts

@@ -50,6 +50,18 @@ export interface SingleResult {
 	startedAt?: number;
 	/** Epoch ms when the subprocess finished. */
 	finishedAt?: number;
+	/** Whether the run hit its wall-clock limit, which fails the run without aborting it. */
+	timedOut?: boolean;
+	/** The limit that applied to this run in ms; absent when it had none. */
+	timeoutMs?: number;
+	/** Directory of the run's transcript, when one was written. */
+	artifactPath?: string;
+	/** Bytes buffered for the transcript. */
+	artifactBytes?: number;
+	/** Whether the transcript stopped at the size cap. */
+	artifactTruncated?: boolean;
+	/** Why the transcript could not be written, when it could not. */
+	artifactError?: string;
 }
 
 /** Structured result carried on the `subagent` tool result for rendering. */

package/extensions/watch/README.md

@@ -103,6 +103,8 @@ render the tail of the sanitized lines, with the hidden count noted above and
 
 ### Command: /watch
 
+<img src="../../assets/watch.png" alt="The /watch screen: a Watch title rule, a `2 watchers · 1 running · 3 matches` summary, a selected file watcher and a finished command watcher, the focused watcher's path and pattern with its line and match counts, and the key hints" width="100%">
+
 A bare `/watch` opens a dock screen listing watchers. `j`/`k` (and the wheel)
 move, `Enter`/`l` opens a watcher's matches, `x`/`K` stops a running watcher
 behind a `y/N` confirm, `d` clears stopped ones behind a `y/N` confirm, `Esc`

package/extensions/wechat/README.md

@@ -116,6 +116,8 @@ polling. `l` logs in or reconnects, `n` starts a new session, `o` logs out,
 actions and the only route outside the TUI; an unknown subcommand reports the
 valid ones.
 
+<img src="../../assets/wechat.png" alt="The /wechat control screen: account and an open connection, peer, queued, refused, and waiting-prompt rows, three conversation rows showing running, queued, and idle states, and the key hints" width="100%">
+
 Pause is per runtime and keeps the account and peer sessions: a running turn
 may finish and reply, a waiting prompt is withdrawn with the timeout notice,
 and the poller lock is released so another runtime can take over. Resume

package/lib/README.md

@@ -18,7 +18,7 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | Module | Responsibility |
 |---|---|
 | [`browser.ts`](./browser.ts) | Cross-platform default-browser opener shared by `file-browse` and `plan`: pure `browserCommand(url, platform)` plus best-effort `openInBrowser(url, { platform, spawn })` with an injectable spawn. |
-| [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` (the last two edit one leaf, flat or nested, preserving siblings and metadata). Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
+| [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` / `unsetConfigValueAt` (the last three edit one leaf, flat or nested, preserving siblings and metadata; the last removes it and prunes what it emptied). Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
 | [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters. |
 | [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` / `JobFinishedEvent` (published by `job`, consumed by bytefly's notify capability), `SUBAGENT_FINISHED_CHANNEL` / `SubagentFinishedEvent` (published by `subagent`, consumed by bytefly's footer roll-up), and `WEB_SEARCH_PROVIDER_CHANNEL` / `WebSearchProviderEvent` (published by `web-access` at session start, consumed by bytefly's doctor so it can report the resolved provider without importing the extension — the key itself is never in the payload). |