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

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/todo/nudge.ts

@@ -86,7 +86,11 @@ export function shouldNudge({ mutations, writes, touched, nudged, todos }: Nudge
 	return todos.length === 0 && !touched && writes > 0 && mutations >= EMPTY_LIST_MUTATIONS;
 }
 
-/** Marker on the injected reminder, so it is recognizable and filterable. */
+/**
+ * Marker on the injected reminder, so it is recognizable and filterable.
+ *
+ * allow:todo the marker is text the model reads, not a to-do for a human.
+ */
 export const TODO_NUDGE_MARKER = "[TODO SYNC]";
 
 /**

package/extensions/watch/README.md

@@ -33,8 +33,9 @@ How the `watch` call and its result look in the transcript — the call line as
   match is announced on `my-pi-agent/watch-match`, which bytefly's
   [notify](../bytefly/README.md#notifications) capability turns into a desktop
   notification when `notify.enabled` and `notify.matchFound` are on.
-- Watchers are session-only: `shutdown` flushes a partial line, kills every
-  command's process tree, and clears the chips.
+- Watchers are session-only: `shutdown` flushes a partial line, sends SIGTERM to
+  every command's process tree (escalating to SIGKILL after a short grace), and
+  clears the chips.
 
 ## Tool
 
@@ -42,7 +43,7 @@ How the `watch` call and its result look in the transcript — the call line as
 |---|---|
 | `name` | `watch` |
 | `action` | `add` \| `list` \| `status` \| `matches` \| `logs` \| `stop` \| `clear` |
-| `path` | File to tail (`add`); exactly one of `path`/`command`. |
+| `path` | Regular file to tail (`add`); exactly one of `path`/`command`. |
 | `command` | Shell command whose output to tail (`add`). |
 | `cwd` | Working directory for a command source; defaults to the effective cwd. |
 | `pattern` | Regular expression a line must match (`add`, required). |
@@ -102,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`
@@ -131,7 +134,7 @@ value is clamped; a missing or malformed document is ignored.
 
 | Key | Default | Meaning |
 |---|---|---|
-| `enabled` | `true` | Track watchers at all. |
+| `enabled` | `true` | Allow `add`; `false` refuses to start a watcher. |
 | `showStatus` | `true` | Show the two status chips. |
 | `wakeOnMatch` | `false` | Default for a new watcher's `wake`; a per-watcher `wake` overrides it. |
 | `maxWatchers` | `20` | Live watchers before `add` is refused. |
@@ -160,6 +163,8 @@ other.
 
 - A file watcher polls, so a new line can take up to `pollMs` to surface; it does
   not use `fs.watch`.
+- `add` requires a path that exists and is a regular file; a directory, FIFO, or
+  a file created after the call is refused.
 - A watcher holds live state in memory and is stopped on shutdown; a detached or
   resumed session starts with no watchers.
 - `matches` and `logs` keep bounded histories (`maxMatches`/`maxLogLines`), so
@@ -200,7 +205,10 @@ UTF-8 sequence split across a read boundary is never mangled. State is
 session-only by design: a watcher is a live process or file position, not
 transcript state, so it cannot be faithfully rebuilt from a `/tree` fork. Match
 delivery mirrors `job` — reported at the next turn, with `wake` triggering one
-turn — so a match is never dropped when the wake window is busy.
+turn — so a match is never dropped when the wake window is busy. Stopping a
+command sends SIGTERM to its process group and escalates to SIGKILL after a 2 s
+grace; shutdown waits the same grace, so a command that ignores SIGTERM cannot
+outlive the session.
 
 ## Files
 

package/extensions/watch/commands.ts

@@ -14,7 +14,7 @@ import type { WatchRuntime } from "./runtime.ts";
 import { WatchListComponent } from "./tui.ts";
 
 /** How often the open screen re-reads live state. */
-const POLL_MS = 500;
+const REFRESH_MS = 500;
 
 const SUBCOMMANDS = [
 	{ value: "list", label: "list" },
@@ -125,12 +125,13 @@ export function registerCommands(pi: ExtensionAPI, runtime: WatchRuntime): void
 							() => tui.terminal?.rows,
 						);
 
+						// The runtime's own clock owns file polling; this only refreshes
+						// what the screen shows, so opening it cannot change the poll cadence.
 						timer = setInterval(() => {
-							runtime.tick();
 							const open = component.currentLineId();
 							if (open) component.refreshLines(open);
 							tui.requestRender();
-						}, POLL_MS);
+						}, REFRESH_MS);
 						timer.unref?.();
 
 						return component;

package/extensions/watch/config.ts

@@ -9,7 +9,7 @@
 import { clampInteger, loadConfigSection } from "../../lib/config.ts";
 
 export interface WatchConfig {
-	/** Track watchers at all. Default: true. */
+	/** Allow starting watchers; false refuses `add`. Default: true. */
 	enabled: boolean;
 	/** Show the status chips while watchers run or a match is unreported. */
 	showStatus: boolean;

package/extensions/watch/format.ts

@@ -10,15 +10,12 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../lib/format.ts";
+import { clip, labelLine } from "../../lib/tui/columns.ts";
 import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { PendingMatch, WatchRecord, WatchStatus } from "./types.ts";
 
-/** Longest label shown in the transcript or `/watch` screen. */
-const MAX_DISPLAY_LABEL = 48;
-
 /** Longest sanitized watched line kept for display; longer lines are clipped. */
 const MAX_WATCH_LINE = 200;
 
@@ -50,7 +47,7 @@ export function compileRegex(pattern: string, caseSensitive: boolean): RegExp {
 
 /** A label clipped to one safe display line. */
 export function clipLabel(text: string): string {
-	return truncateToWidth(sanitizeWatchLine(text), MAX_DISPLAY_LABEL, "…");
+	return labelLine(text, sanitizeWatchLine);
 }
 
 /** What a watcher reads: a path or a command, clipped for display. */
@@ -177,9 +174,9 @@ export function formatCallText(action: string, args: Record<string, unknown>, ar
 			const command = typeof args.command === "string" ? args.command.trim() : "";
 			const source = path ? path : command ? `$ ${command}` : "";
 			if (!source) return argsComplete ? "add" : "add …";
-			const preview = truncateToWidth(sanitizeLine(source), MAX_DISPLAY_LABEL, "…");
+			const preview = labelLine(source);
 			const pattern = typeof args.pattern === "string" ? args.pattern.trim() : "";
-			return pattern ? `add ${preview} /${truncateToWidth(sanitizeLine(pattern), 24, "…")}/` : `add ${preview}`;
+			return pattern ? `add ${preview} /${clip(sanitizeLine(pattern), 24)}/` : `add ${preview}`;
 		}
 		case "status":
 		case "matches":

package/extensions/watch/runtime.ts

@@ -22,6 +22,8 @@ import type { PendingMatch, WatchMatch, WatchRecord, WatchSource } from "./types
 const MAX_CHUNK = 1024 * 1024;
 /** A line without a newline is flushed once it grows past this. */
 const MAX_LINE_BYTES = 1024 * 1024;
+/** Grace period before a stopped command is escalated to SIGKILL. */
+const KILL_GRACE_MS = 2000;
 
 /** Internal watcher state: the public record plus non-serializable fields. */
 interface Internal {
@@ -50,6 +52,7 @@ interface Internal {
 	rawLines: string[];
 	matches: WatchMatch[];
 	child?: SpawnedProcess;
+	killTimer?: ReturnType<typeof setTimeout>;
 	notified: boolean;
 	seq: number;
 }
@@ -95,6 +98,8 @@ export interface WatchRuntimeOptions {
 	config?: WatchConfig;
 	/** When false, never create a real interval; tests call `tick()` directly. */
 	autoClock?: boolean;
+	/** Grace before SIGTERM escalates to SIGKILL; default {@link KILL_GRACE_MS}. */
+	killGraceMs?: number;
 }
 
 export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRuntime {
@@ -103,6 +108,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const now = options.now ?? (() => Date.now());
 	const fixedConfig = options.config;
 	const autoClock = options.autoClock ?? true;
+	const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
 
 	let config: WatchConfig = fixedConfig ?? DEFAULT_CONFIG;
 	const watches = new Map<string, Internal>();
@@ -243,15 +249,60 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		emit(w, rest, time);
 	};
 
-	const killChild = (w: Internal): void => {
+	const clearKillTimer = (w: Internal): void => {
+		if (w.killTimer) {
+			clearTimeout(w.killTimer);
+			w.killTimer = undefined;
+		}
+	};
+
+	const killChild = (w: Internal, signal: "SIGTERM" | "SIGKILL"): void => {
 		const pid = w.pid;
 		try {
-			if (pid !== undefined) killTree(pid, "SIGTERM");
-			else w.child?.kill("SIGTERM");
+			if (pid !== undefined) killTree(pid, signal, signal === "SIGKILL");
+			else w.child?.kill(signal);
 		} catch {
 			// Best-effort: the child may already be gone.
 		}
-		w.child = undefined;
+	};
+
+	/** SIGTERM a command, escalating to SIGKILL when it has not closed in time. */
+	const terminateChild = (w: Internal): void => {
+		clearKillTimer(w);
+		killChild(w, "SIGTERM");
+		if (w.pid === undefined && !w.child) return;
+		w.killTimer = setTimeout(() => {
+			w.killTimer = undefined;
+			if (w.child) killChild(w, "SIGKILL");
+		}, killGraceMs);
+		w.killTimer.unref?.();
+	};
+
+	/** Resolve when every command has closed, or after `ms`, whichever comes first. */
+	const waitForChildren = (watches: Internal[], ms: number): Promise<void> => {
+		const alive = watches.filter((w) => w.child !== undefined);
+		if (alive.length === 0) return Promise.resolve();
+		return new Promise((resolve) => {
+			let remaining = alive.length;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const settle = (): void => {
+				if (--remaining > 0) return;
+				if (timer !== undefined) clearTimeout(timer);
+				resolve();
+			};
+			for (const w of alive) {
+				let done = false;
+				const once = (): void => {
+					if (done) return;
+					done = true;
+					settle();
+				};
+				w.child?.on("close", once);
+				w.child?.on("error", once);
+			}
+			timer = setTimeout(resolve, ms);
+			timer.unref?.();
+		});
 	};
 
 	const pollFile = (w: Internal, time: number): void => {
@@ -278,6 +329,9 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 			const read = readSync(fd, buffer, 0, length, w.offset);
 			w.offset += read;
 			consume(w, buffer.subarray(0, read), time);
+		} catch {
+			// The path can vanish or change type between stat and read (rotation, a
+			// replacement); skip this tick and pick it up next time.
 		} finally {
 			if (fd !== undefined) {
 				try {
@@ -305,22 +359,24 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		child.stdout?.on("data", onData);
 		child.stderr?.on("data", onData);
 		child.on("close", (code, signal) => {
+			clearKillTimer(w);
+			w.child = undefined;
 			if (w.status !== "running") return;
 			flushPending(w, now());
 			w.status = "exited";
 			w.exitCode = code;
 			w.signal = signal;
 			w.endedAt = now();
-			w.child = undefined;
 			ui.paint();
 			if (runningCount() === 0) stopClock();
 		});
 		child.on("error", (error) => {
+			clearKillTimer(w);
+			w.child = undefined;
 			if (w.status !== "running") return;
 			w.status = "error";
 			w.error = error.message;
 			w.endedAt = now();
-			w.child = undefined;
 			ui.paint();
 			if (runningCount() === 0) stopClock();
 		});
@@ -337,6 +393,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	};
 
 	const add = (opts: AddWatchOptions, ctx: ExtensionContext): WatchRecord => {
+		if (!config.enabled) throw new Error("watch is disabled.");
 		if (watches.size >= config.maxWatchers) {
 			throw new Error(`at most ${config.maxWatchers} watchers; stop one first.`);
 		}
@@ -349,11 +406,13 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 					cwd: opts.cwd ? (isAbsolute(opts.cwd) ? opts.cwd : resolve(base, opts.cwd)) : base,
 				};
 		if (source.kind === "file") {
+			let info: ReturnType<typeof statSync>;
 			try {
-				statSync(source.path ?? "");
+				info = statSync(source.path ?? "");
 			} catch {
 				throw new Error(`file not found: ${source.path}`);
 			}
+			if (!info.isFile()) throw new Error(`not a regular file: ${source.path}`);
 		}
 		const caseSensitive = opts.caseSensitive ?? false;
 		const regex = compileRegex(opts.pattern, caseSensitive);
@@ -423,7 +482,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		const w = watches.get(id);
 		if (!w || w.status !== "running") return false;
 		flushPending(w, now());
-		killChild(w);
+		terminateChild(w);
 		w.status = "stopped";
 		w.endedAt = now();
 		ui.paint();
@@ -473,7 +532,13 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const load = (ctx: ExtensionContext): void => {
 		disposed = false;
 		stopClock();
-		for (const w of watches.values()) if (w.status === "running") killChild(w);
+		for (const w of watches.values()) {
+			if (w.status !== "running") continue;
+			w.status = "stopped";
+			clearKillTimer(w);
+			killChild(w, "SIGKILL");
+			w.child = undefined;
+		}
 		watches.clear();
 		counter = 0;
 		config = fixedConfig ?? loadConfig(ctx.cwd);
@@ -484,12 +549,18 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const shutdown = async (): Promise<void> => {
 		disposed = true;
 		stopClock();
-		for (const w of watches.values()) {
-			if (w.status !== "running") continue;
+		const running = [...watches.values()].filter((w) => w.status === "running");
+		for (const w of running) {
 			flushPending(w, now());
-			killChild(w);
 			w.status = "stopped";
 			w.endedAt = now();
+			clearKillTimer(w);
+			killChild(w, "SIGTERM");
+		}
+		await waitForChildren(running, killGraceMs);
+		for (const w of running) {
+			clearKillTimer(w);
+			if (w.child) killChild(w, "SIGKILL");
 		}
 		watches.clear();
 		ui.detach();

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/extensions/worktree/README.md

@@ -122,9 +122,15 @@ exclude the name here to load alongside it. It is read when the extension
 loads, from the process working directory; reload after changing it. `/worktree`
 and `list_worktrees` list any overridden tool that is not re-rooted.
 
-Add the worktree directory to `.gitignore`:
+`.gitignore` must cover the managed directory, or worktrees show up as untracked
+files in the main checkout. `enter_worktree` offers once per session to append
+`.pi/worktrees/`, and skips the offer when `git check-ignore` already reports the
+directory as ignored, so a wider rule is enough and no literal line is needed:
 
 ```
+# either, when the rest of `.pi/` is disposable
+.pi/
+# or, when other `.pi/` state must stay tracked
 .pi/worktrees/
 ```
 

package/extensions/worktree/enter.ts

@@ -17,6 +17,7 @@ import {
 	currentBranch,
 	fetchPrRef,
 	hasCommits,
+	isIgnored,
 	lockWorktree,
 	mergeBase,
 	parsePrReference,
@@ -54,12 +55,19 @@ function generateName(): string {
 }
 
 /** Offer once per session to ignore the managed worktree directory. */
-async function maybeIgnoreWorktreeDir(ctx: ExtensionContext, root: string, config: WorktreeConfig): Promise<void> {
+async function maybeIgnoreWorktreeDir(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	root: string,
+	config: WorktreeConfig,
+): Promise<void> {
 	if (isGitignoreOffered()) return;
 	if (!ctx.hasUI) return;
 	markGitignoreOffered();
 
 	const entry = `${config.dir.replace(/\/+$/, "")}/`;
+	if (await isIgnored(pi, root, entry)) return;
+
 	const gitignorePath = join(root, ".gitignore");
 	let content = "";
 	try {
@@ -67,7 +75,6 @@ async function maybeIgnoreWorktreeDir(ctx: ExtensionContext, root: string, confi
 	} catch {
 		return;
 	}
-	if (content.split(/\r?\n/).some((line) => line.trim() === entry || line.trim() === config.dir)) return;
 
 	const confirmed = await ctx.ui.confirm(
 		"Add the worktree directory to .gitignore?",
@@ -225,7 +232,7 @@ export async function enterWorktree(
 	let copiedIncludes: string[] = [];
 	if (!existed) {
 		copiedIncludes = await copyIncludes(pi, root, target, includePatterns(root, config.include), config.dir);
-		await maybeIgnoreWorktreeDir(ctx, root, config);
+		await maybeIgnoreWorktreeDir(pi, ctx, root, config);
 	}
 
 	const state: WorktreeState = {