one-code-extension 0.4.0 → 0.5.0

package/extensions/subagents/shell-panel.ts

@@ -1,198 +1,56 @@
 /**
- * Pure state + rendering for the background-shells side of the below-editor
- * panel — Claude Code's shell manager. Three stages, entered with the FIRST
- * down-arrow (a second ↓ moves on to the agent rows):
+ * Pure state + rendering for the background-shells chip in the below-editor
+ * panel, Claude Code's shell pill. The FIRST down-arrow focuses it (a second ↓
+ * moves on to the agent rows), and Enter opens the Background dialog that
+ * `/tasks` opens too (tasks-dialog.ts), where shells and agents are listed
+ * together:
  *
- *   chip     "2 shells · ↓ to manage" → focused: "[2 shells] · Enter to view tasks"
- *   list     the Background panel: selectable command rows, x stops, Esc backs out
- *   details  one shell: Status/Runtime/Command + a live bordered output box
+ *   "2 shells · ↓ to manage" → focused: "[2 shells] · Enter to view tasks"
  *
  * Task objects arrive over TASK_REGISTER_CHANNEL (lib/shell-tasks.ts) and stay
- * live — output()/status are read at render time. Key wiring lives in
- * index.ts; this file owns layout and the focus reducer only.
+ * live; status is read at render time. Key wiring lives in index.ts; this file
+ * owns layout and the focus reducer only.
  */
 
 import type { BackgroundTask } from "../background/registry.ts";
-import { countNoun, cutPlainText as cut, formatDuration, padPlainText } from "../lib/tui-render.ts";
+import { countNoun, cutPlainText as cut } from "../lib/tui-render.ts";
 import type { StripKey } from "./panel-keys.ts";
-import type { Paint } from "./panel-render.ts";
+import { type Paint, STRIP_LINGER_MS } from "./panel-render.ts";
 
 export interface ShellPaint extends Paint {
 	inverse(text: string): string;
 }
 
-export type ShellFocus =
-	| { stage: "chip" }
-	| { stage: "list"; selectedId: string }
-	| { stage: "details"; selectedId: string };
-
-/** A finished shell stays listed this long, so its terminal status is seen. */
-export const SHELL_LIST_LINGER_MS = 60_000;
-
-/** Output-box height in the details view (content rows, borders excluded). */
-export const OUTPUT_BOX_ROWS = 10;
-
-/** Most list rows shown at once; the selection slides a window over the rest. */
-export const MAX_SHELL_LIST_ROWS = 8;
-
-/** Only this much of the spool is split per frame — the box shows 10 lines. */
-const OUTPUT_TAIL_CHARS = 8192;
-
-/** The list rows: running shells first, newest-first within each group. */
-export function shellRows(tasks: BackgroundTask[], now: number): BackgroundTask[] {
-	return tasks
-		.filter((t) => t.status === "running" || (t.finishedAt ?? now) > now - SHELL_LIST_LINGER_MS)
-		.sort((a, b) => Number(b.status === "running") - Number(a.status === "running") || b.startedAt - a.startedAt);
-}
-
 /**
- * Re-anchor a focus whose selected shell left the rows (lingered out or never
- * existed): fall back to the first row, or to the chip when the list emptied.
+ * The shells the chip counts: running ones, and finished ones for as long as a
+ * finished agent keeps its strip row (STRIP_LINGER_MS).
  */
-export function anchorShellFocus(focus: ShellFocus, ids: string[]): ShellFocus {
-	if (focus.stage === "chip" || ids.includes(focus.selectedId)) return focus;
-	return ids.length ? { ...focus, selectedId: ids[0] } : { stage: "chip" };
-}
-
-export interface ShellTransition {
-	/** The next focus; undefined closes the shell section entirely. */
-	focus: ShellFocus | undefined;
-	/** stopSelected: stop the selected task; toAgents: hand ↓ on to the agent
-	 * rows; passthrough: unhandled byte — drop focus and let the editor have it. */
-	effect?: "stopSelected" | "toAgents" | "passthrough";
-}
-
-/**
- * The focus reducer — Claude Code's shell-manager keys. `ids` is the current
- * row order (shellRows), `focus` is already anchored against it.
- */
-export function reduceShellKey(focus: ShellFocus, key: StripKey | undefined, ids: string[]): ShellTransition {
-	const index = focus.stage === "chip" ? -1 : ids.indexOf(focus.selectedId);
-	switch (focus.stage) {
-		case "chip":
-			if (key === "down") return { focus: undefined, effect: "toAgents" };
-			if (key === "open") return { focus: ids.length ? { stage: "list", selectedId: ids[0] } : focus };
-			if (key === "up" || key === "leave") return { focus: undefined };
-			return { focus: undefined, effect: "passthrough" };
-		case "list":
-			if (key === "up") return { focus: index > 0 ? { stage: "list", selectedId: ids[index - 1] } : focus };
-			if (key === "down")
-				return { focus: index < ids.length - 1 ? { stage: "list", selectedId: ids[index + 1] } : focus };
-			if (key === "open") return { focus: { stage: "details", selectedId: focus.selectedId } };
-			if (key === "stop") return { focus, effect: "stopSelected" };
-			if (key === "leave" || key === "left") return { focus: { stage: "chip" } };
-			if (key === "pageUp" || key === "pageDown") return { focus };
-			return { focus: undefined, effect: "passthrough" };
-		case "details":
-			if (key === "left") return { focus: { stage: "list", selectedId: focus.selectedId } };
-			if (key === "leave" || key === "open" || key === "space") return { focus: undefined };
-			if (key === "stop") return { focus, effect: "stopSelected" };
-			if (key === "up" || key === "down" || key === "pageUp" || key === "pageDown") return { focus };
-			return { focus: undefined, effect: "passthrough" };
-	}
-}
-
-export interface ShellSectionInput {
-	/** shellRows()-ordered. */
-	rows: BackgroundTask[];
-	runningCount: number;
-	focus: ShellFocus | undefined;
-	width: number;
-	now: number;
+export function shellRows(tasks: BackgroundTask[], now: number): BackgroundTask[] {
+	return tasks.filter((t) => t.status === "running" || (t.finishedAt !== undefined && t.finishedAt > now - STRIP_LINGER_MS));
 }
 
 /**
- * Whether the section renders at all (drives widget visibility and ↓ entry).
- * Keyed on the ROW count, not the running count, so a finished shell's chip
- * stays reachable for the linger window — otherwise its outcome would only be
- * visible if the panel happened to be open when it finished.
+ * What a key does on the focused chip. Every key drops the chip's focus;
+ * openTasks opens the Background dialog, toAgents hands ↓ on to the agent rows,
+ * passthrough lets the editor have an unhandled byte, and undefined (↑, Esc)
+ * only leaves the chip.
  */
-export function shellSectionVisible(rowCount: number, focus: ShellFocus | undefined): boolean {
-	return rowCount > 0 || focus !== undefined;
-}
-
-const STATUS_COLOR: Record<string, string> = { running: "accent", failed: "error", stopped: "dim" };
-
-/** The section's lines at the current stage. Caller checks visibility first. */
-export function renderShellSection(input: ShellSectionInput, paint: ShellPaint): string[] {
-	const width = Math.max(20, input.width);
-	const focus = input.focus;
-	// The label counts ROWS (running + lingering finished), matching what the
-	// panel actually shows — visibility keys on rows too, so a finished shell's
-	// chip must not read "0 shells" while it is still openable.
-	if (!focus) return [paint.fg("dim", cut(`${countNoun(input.rows.length, "shell")} · ↓ to manage`, width))];
-	if (focus.stage === "chip") {
-		// Cut the plain parts BEFORE painting — cutting painted text breaks escapes.
-		const label = cut(` ${countNoun(input.rows.length, "shell")} `, width);
-		const hint = cut("· Enter to view tasks", Math.max(0, width - label.length - 1));
-		return [`${paint.inverse(label)}${hint ? ` ${paint.fg("dim", hint)}` : ""}`];
-	}
-	if (focus.stage === "list") return renderShellList(input, focus.selectedId, paint, width);
-	return renderShellDetails(input, focus.selectedId, paint, width);
-}
-
-function renderShellList(input: ShellSectionInput, selectedId: string, paint: ShellPaint, width: number): string[] {
-	const out: string[] = [];
-	out.push(paint.fg("accent", paint.bold("Background")));
-	out.push(cut(countNoun(input.runningCount, "active shell"), width));
-	out.push("");
-	// A window of MAX_SHELL_LIST_ROWS slid to keep the selection visible, so a
-	// big shell fan-out cannot grow the panel past the terminal.
-	const selectedIndex = Math.max(0, input.rows.findIndex((t) => t.id === selectedId));
-	const start = Math.min(Math.max(0, selectedIndex - MAX_SHELL_LIST_ROWS + 1), Math.max(0, input.rows.length - MAX_SHELL_LIST_ROWS));
-	const shown = input.rows.slice(start, start + MAX_SHELL_LIST_ROWS);
-	if (start > 0) out.push(paint.fg("dim", `  +${start} more above`));
-	for (const task of shown) {
-		const marker = task.id === selectedId ? "❯ " : "  ";
-		const status = ` (${task.status})`;
-		const command = cut(task.command ?? task.description, Math.max(1, width - marker.length - status.length));
-		out.push(`${marker}${command}${paint.fg(STATUS_COLOR[task.status] ?? "dim", status)}`);
-	}
-	const below = input.rows.length - start - shown.length;
-	if (below > 0) out.push(paint.fg("dim", `  +${below} more below`));
-	if (!input.rows.length) out.push(paint.fg("dim", "  no shells"));
-	out.push("");
-	out.push(paint.fg("dim", cut("↑/↓ to select · Enter to view · x to stop · Esc to close", width)));
-	return out;
-}
-
-function renderShellDetails(input: ShellSectionInput, selectedId: string, paint: ShellPaint, width: number): string[] {
-	const task = input.rows.find((t) => t.id === selectedId);
-	const out: string[] = [];
-	out.push(paint.fg("accent", paint.bold("Shell details")));
-	out.push("");
-	if (!task) {
-		out.push(paint.fg("dim", "shell gone"));
-		return out;
-	}
-	const field = (label: string, value: string) => `${paint.bold(padPlainText(label, 9))} ${value}`;
-	out.push(field("Status:", paint.fg(STATUS_COLOR[task.status] ?? "dim", task.status)));
-	out.push(field("Runtime:", formatDuration(task.startedAt, task.finishedAt, input.now)));
-	out.push(field("Command:", cut(task.command ?? task.description, Math.max(1, width - 10))));
-	out.push("");
-	out.push(paint.bold("Output:"));
-
-	let output = "";
-	try {
-		output = task.output();
-	} catch {
-		output = "(output unavailable)";
-	}
-	// Bound the split to a tail slice — re-splitting a 200KB spool every ticker
-	// frame to keep 10 lines is O(buffer) work for nothing. A mid-line cut only
-	// matters when the tail holds fewer lines than the box, and those are
-	// width-cut anyway.
-	const tail = output.length > OUTPUT_TAIL_CHARS ? output.slice(-OUTPUT_TAIL_CHARS) : output;
-	const lines = tail ? tail.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n") : [];
-	const shown = lines.slice(-OUTPUT_BOX_ROWS);
-	const inner = Math.max(1, width - 4);
-	out.push(`┌${"─".repeat(Math.max(0, width - 2))}┐`);
-	for (let i = 0; i < OUTPUT_BOX_ROWS; i++) {
-		out.push(`│ ${padPlainText(cut(shown[i] ?? "", inner), inner)} │`);
-	}
-	out.push(`└${"─".repeat(Math.max(0, width - 2))}┘`);
-	out.push(paint.fg("dim", `Showing ${countNoun(shown.length, "line")}`));
-	out.push("");
-	out.push(paint.fg("dim", cut("← to go back · Esc/Enter/Space to close · x to stop", width)));
-	return out;
+export type ShellKeyEffect = "openTasks" | "toAgents" | "passthrough" | undefined;
+
+/** The focused chip's keys. */
+export function reduceShellKey(key: StripKey | undefined): ShellKeyEffect {
+	if (key === "down") return "toAgents";
+	if (key === "open") return "openTasks";
+	if (key === "up" || key === "leave") return undefined;
+	return "passthrough";
+}
+
+/** The chip's one line. Callers render it only while shellRows() is non-empty. */
+export function renderShellChip(count: number, focused: boolean, width: number, paint: ShellPaint): string {
+	width = Math.max(20, width);
+	if (!focused) return paint.fg("dim", cut(`${countNoun(count, "shell")} · ↓ to manage`, width));
+	// Cut the plain parts BEFORE painting: cutting painted text breaks escapes.
+	const label = cut(` ${countNoun(count, "shell")} `, width);
+	const hint = cut("· Enter to view tasks", Math.max(0, width - label.length - 1));
+	return `${paint.inverse(label)}${hint ? ` ${paint.fg("dim", hint)}` : ""}`;
 }

package/extensions/subagents/tasks-dialog.ts

@@ -0,0 +1,170 @@
+/**
+ * `/tasks`: Claude Code 2.1.283's Background dialog (findings §40), pure
+ * layout and key handling. It lists the shells the chip counts (running ones,
+ * and finished ones for the chip's linger window, so Enter on the chip always
+ * finds them), the running local agents, and the finished agents the user
+ * viewed:
+ *
+ *   Background
+ *   2 active shells · 1 active agent
+ *     Shells (2)
+ *   ❯ ⏺ sleep 25; echo done   running
+ *     Local agents (1)
+ *     ⏺ Read notes.txt and report after delay   running · Sonnet 5
+ *     Completed (1)
+ *     ✔ write a 300-word poem about the word in the file   done · Haiku 4.5
+ *   ↑/↓ to select · Enter to view · x to stop · Esc to close
+ *
+ * With nothing to list it reads `No tasks currently running`. Enter on a shell
+ * shows its details in the same dialog (renderShellDetail), and ← goes back
+ * to the list. The shells chip below the editor opens this dialog too.
+ * index.ts owns the dialog and what Enter and x do.
+ */
+
+import type { BackgroundTask } from "../background/registry.ts";
+import { countNoun, cutPlainText as cut, formatDuration, hintLines, padPlainText } from "../lib/tui-render.ts";
+import { sanitizeDisplayText } from "../lib/terminal-text.ts";
+
+/** One selectable row. */
+export type TasksItem =
+	| { kind: "shell"; id: string; text: string; running: boolean; status: BackgroundTask["status"] }
+	| { kind: "agent"; taskId: string; text: string; model?: string; running: boolean };
+
+export interface TasksDialogInput {
+	shells: Array<Extract<TasksItem, { kind: "shell" }>>;
+	/** Running agents first, then the viewed finished ones (the caller splits them). */
+	agents: Array<Extract<TasksItem, { kind: "agent" }>>;
+	selected: number;
+	width: number;
+}
+
+export interface TasksPaint {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+/** The agents split into running and completed, each in the caller's order. */
+function splitAgents(agents: TasksDialogInput["agents"]) {
+	return { running: agents.filter((a) => a.running), completed: agents.filter((a) => !a.running) };
+}
+
+/** Every row in display order: shells, running agents, completed agents. */
+export function tasksItems(input: Pick<TasksDialogInput, "shells" | "agents">): TasksItem[] {
+	const agents = splitAgents(input.agents);
+	return [...input.shells, ...agents.running, ...agents.completed];
+}
+
+/** The dialog's lines, every one cut to `width`. */
+export function renderTasksDialog(input: TasksDialogInput, paint: TasksPaint): string[] {
+	const width = Math.max(20, input.width);
+	const line = (text: string) => cut(text, width);
+	const out = [paint.bold(line("  Background"))];
+	const items = tasksItems(input);
+	const current = items[input.selected];
+	// Hints wrap at their separators on a narrow terminal, so none is cut off.
+	const hint = ["↑/↓ to select", "Enter to view", ...(current?.running ? ["x to stop"] : []), "Esc to close"].join(" · ");
+	const pushHints = () => out.push(...hintLines(hint, width, "  ").map((hintLine) => paint.fg("dim", hintLine)));
+	if (items.length === 0) {
+		out.push(line("  No tasks currently running"));
+		pushHints();
+		return out;
+	}
+	const agents = splitAgents(input.agents);
+	const runningShells = input.shells.filter((s) => s.running).length;
+	const counts = [runningShells ? countNoun(runningShells, "active shell") : "", agents.running.length ? countNoun(agents.running.length, "active agent") : ""]
+		.filter(Boolean)
+		.join(" · ");
+	if (counts) out.push(paint.fg("dim", line(`  ${counts}`)));
+	const groups: Array<[title: string, rows: TasksItem[]]> = [
+		["Shells", input.shells],
+		["Local agents", agents.running],
+		["Completed", agents.completed],
+	];
+	let index = 0;
+	for (const [title, rows] of groups) {
+		if (rows.length === 0) continue;
+		out.push(paint.fg("dim", line(`    ${title} (${rows.length})`)));
+		for (const row of rows) {
+			const selected = index === input.selected;
+			// A finished shell shows how it ended; only a clean finish reads "done",
+			// and only a failure gets the cross (a stop is the user's own choice).
+			const ended = row.kind === "shell" && !row.running && row.status !== "completed" ? row.status : undefined;
+			const mark = row.running ? "⏺" : ended === "failed" ? "✗" : "✔";
+			const status = row.running ? "running" : (ended ?? "done");
+			const suffix = row.kind === "agent" && row.model ? `${status} · ${row.model}` : status;
+			const text = line(`  ${selected ? "❯" : " "} ${mark} ${sanitizeDisplayText(row.text)}   ${suffix}`);
+			out.push(selected ? paint.fg("accent", paint.bold(text)) : text);
+			index++;
+		}
+	}
+	pushHints();
+	return out;
+}
+
+export type TasksKey = "up" | "down" | "view" | "stop" | "close";
+
+/** Move the selection within `count` rows, stopping at the ends. */
+export function moveTasksSelection(selected: number, key: "up" | "down", count: number): number {
+	if (count === 0) return 0;
+	return key === "up" ? Math.max(0, selected - 1) : Math.min(count - 1, selected + 1);
+}
+
+/** What the dialog shows: the list, or one shell's details. */
+export type TasksView = { mode: "list" } | { mode: "shell"; id: string };
+
+/**
+ * The view to render now. A shell's details last while the shell is known: one
+ * that finishes while shown keeps its details, with its final status and no
+ * `x`, and the dialog goes back to the list once the shell is gone.
+ */
+export function settleTasksView(view: TasksView, shellKnown: boolean): TasksView {
+	return view.mode === "shell" && !shellKnown ? { mode: "list" } : view;
+}
+
+/** What a key does in a shell's details: ← goes back, Esc/Enter/Space close, x stops a running shell. */
+export function shellDetailKey(id: string | undefined, text: string | undefined, running: boolean): "back" | "close" | "stop" | undefined {
+	if (id === "left") return "back";
+	if (id === "escape" || id === "enter" || id === "space" || text === " ") return "close";
+	if (running && text?.toLowerCase() === "x") return "stop";
+	return undefined;
+}
+
+/** Output-box height in a shell's details (content rows, borders excluded). */
+export const OUTPUT_BOX_ROWS = 10;
+
+/** Only this much of the spool is split per frame: the box shows 10 lines. */
+const OUTPUT_TAIL_CHARS = 8192;
+
+const STATUS_COLOR: Record<string, string> = { running: "accent", failed: "error", stopped: "dim" };
+
+/** One shell's details: Status, Runtime, Command, a bordered tail of its output, and the keys it takes. */
+export function renderShellDetail(task: BackgroundTask, width: number, now: number, paint: TasksPaint): string[] {
+	width = Math.max(20, width);
+	const out = [paint.bold(cut("Shell details", width)), ""];
+	const field = (label: string, value: string) => `${paint.bold(padPlainText(label, 9))} ${value}`;
+	out.push(field("Status:", paint.fg(STATUS_COLOR[task.status] ?? "dim", task.status)));
+	out.push(field("Runtime:", formatDuration(task.startedAt, task.finishedAt, now)));
+	out.push(field("Command:", cut(sanitizeDisplayText(task.command ?? task.description), Math.max(1, width - 10))));
+	out.push("", paint.bold("Output:"));
+
+	let output = "";
+	try {
+		output = task.output();
+	} catch {
+		output = "(output unavailable)";
+	}
+	// Bound the split to a tail slice: re-splitting a 200KB spool every frame to
+	// keep 10 lines is O(buffer) work for nothing. A mid-line cut only matters
+	// when the tail holds fewer lines than the box, and those are width-cut anyway.
+	const tail = output.length > OUTPUT_TAIL_CHARS ? output.slice(-OUTPUT_TAIL_CHARS) : output;
+	const lines = tail ? tail.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n") : [];
+	const shown = lines.slice(-OUTPUT_BOX_ROWS);
+	const inner = Math.max(1, width - 4);
+	out.push(`┌${"─".repeat(Math.max(0, width - 2))}┐`);
+	for (let i = 0; i < OUTPUT_BOX_ROWS; i++) out.push(`│ ${padPlainText(cut(shown[i] ?? "", inner), inner)} │`);
+	out.push(`└${"─".repeat(Math.max(0, width - 2))}┘`);
+	out.push(paint.fg("dim", `Showing ${countNoun(shown.length, "line")}`), "");
+	const hint = ["← to go back", "Esc/Enter/Space to close", ...(task.status === "running" ? ["x to stop"] : [])].join(" · ");
+	out.push(...hintLines(hint, width).map((hintLine) => paint.fg("dim", hintLine)));
+	return out;
+}

package/extensions/subagents/viewport-mirror.ts

@@ -0,0 +1,95 @@
+/**
+ * Viewport mirror for the agent view (pure; no pi imports).
+ *
+ * In pi's fullscreen mode the terminal's scroll input (PageUp/PageDown, the
+ * mouse wheel, Ctrl+Home/Ctrl+End, plain Home/End before pi 1.0.3) is taken
+ * by pi-tui's own viewport handler before any extension input listener runs
+ * (findings §10), and it scrolls the main transcript. The agent view is an
+ * overlay over that transcript, so the user saw nothing move in the view while
+ * main, hidden below it, scrolled away and stayed scrolled up after the view
+ * closed.
+ *
+ * The mirror turns those moves into agent-view scrolling, as Claude Code
+ * scrolls whatever transcript is on screen: each frame it reads how far the
+ * main viewport moved since it was last parked, hands that distance to the
+ * view, and parks main again. Main is parked above its bottom by up to the
+ * view's own scroll (at most half main's range), so a later move down has room
+ * to register too. `restore()` puts main back where it was when the view
+ * opened.
+ *
+ * Only the main transcript's range can register a move: when main is shorter
+ * than one screen, the page keys move nothing and the view cannot see them.
+ */
+
+/** The slice of pi-tui's fullscreen TUI the mirror drives (structural). */
+export interface ScrollableViewport {
+	readonly viewportTop: number;
+	readonly isFollowingOutput: boolean;
+	scrollBy(lines: number): void;
+	scrollToBottom(): void;
+}
+
+/** The TUI's fullscreen viewport, or undefined in regular (main-screen) mode. */
+export function asScrollableViewport(tui: unknown): ScrollableViewport | undefined {
+	const candidate = tui as Partial<ScrollableViewport> | undefined;
+	if (!candidate || typeof candidate.viewportTop !== "number" || typeof candidate.isFollowingOutput !== "boolean") return undefined;
+	if (typeof candidate.scrollBy !== "function" || typeof candidate.scrollToBottom !== "function") return undefined;
+	return candidate as ScrollableViewport;
+}
+
+export class ViewportMirror {
+	private readonly openedFollowing: boolean;
+	private readonly openedTop: number;
+	private parkedTop: number;
+	private parkedAtBottom: boolean;
+
+	constructor(private readonly viewport: ScrollableViewport) {
+		this.openedFollowing = viewport.isFollowingOutput;
+		this.openedTop = viewport.viewportTop;
+		this.parkedTop = this.openedTop;
+		this.parkedAtBottom = this.openedFollowing;
+	}
+
+	/**
+	 * Fold any main-viewport move since the last park into the view's scroll
+	 * (lines from the bottom, up is positive) and park main again. Returns the
+	 * new scroll, clamped to `[0, maxScroll]`.
+	 */
+	absorb(scroll: number, maxScroll: number): number {
+		const { viewport } = this;
+		// Parked at the bottom and still following: main only grew, nobody scrolled.
+		if (this.parkedAtBottom && viewport.isFollowingOutput) {
+			this.parkedTop = viewport.viewportTop;
+			return scroll;
+		}
+		const top = viewport.viewportTop;
+		if (top === this.parkedTop) return scroll;
+		const next = clamp(scroll + (this.parkedTop - top), maxScroll);
+		this.park(next);
+		return next;
+	}
+
+	/** Park main for a view scroll of `scroll` lines (after a retarget, say). */
+	park(scroll: number): void {
+		const { viewport } = this;
+		viewport.scrollToBottom();
+		const bottom = viewport.viewportTop;
+		const lift = Math.min(Math.max(0, scroll), Math.floor(bottom / 2));
+		if (lift > 0) viewport.scrollBy(-lift);
+		this.parkedTop = viewport.viewportTop;
+		this.parkedAtBottom = lift === 0;
+	}
+
+	/** Put main back where it was when the view opened. */
+	restore(): void {
+		const { viewport } = this;
+		viewport.scrollToBottom();
+		if (this.openedFollowing) return;
+		const delta = this.openedTop - viewport.viewportTop;
+		if (delta !== 0) viewport.scrollBy(delta);
+	}
+}
+
+function clamp(value: number, max: number): number {
+	return Math.max(0, Math.min(Math.max(0, max), value));
+}

package/extensions/subagents/worktree.ts

@@ -3,25 +3,31 @@
  *
  * Claude Code's `isolation: "worktree"` gives an agent its own checkout so
  * parallel agents editing files cannot collide, and removes it again if the agent
- * changed nothing.
+ * changed nothing: no uncommitted change and no commit past the HEAD it was
+ * created at. A worktree whose agent committed its work is kept like one with
+ * uncommitted edits, so the commits stay reachable on its branch.
  */
 
 import { execFile } from "node:child_process";
 import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { registerWorktreeIsolation, releaseWorktreeIsolation } from "../lib/worktree-isolation.ts";
+import { findProjectRoot, HARNESS_GIT_CONFIG, HARNESS_GIT_NO_HOOKS } from "../lib/git.ts";
+import { checkoutGitRunsProgram } from "../auto-mode/git-checkout-programs.ts";
 
 const run = promisify(execFile);
 
 export interface Worktree {
 	path: string;
 	branch: string;
+	/** The commit the worktree was created at; commits past it are the agent's work. */
+	baseCommit: string;
 }
 
 async function git(args: string[], cwd: string): Promise<string> {
-	const { stdout } = await run("git", args, { cwd, maxBuffer: 10 * 1024 * 1024 });
+	const { stdout } = await run("git", [...HARNESS_GIT_CONFIG, ...HARNESS_GIT_NO_HOOKS, ...args], { cwd, maxBuffer: 10 * 1024 * 1024 });
 	return stdout.trim();
 }
 
@@ -33,31 +39,57 @@ export async function isGitRepo(cwd: string): Promise<boolean> {
 	}
 }
 
-/** Creates a detached worktree at the current HEAD. */
+/** Creates a worktree on a new throwaway branch at the current HEAD. */
 export async function createWorktree(cwd: string, label: string): Promise<Worktree> {
+	const program = checkoutGitRunsProgram(cwd, homedir(), []);
+	if (program) {
+		throw new Error(`Cannot create an isolation worktree: ${program}. Create the worktree with an explicitly approved git worktree add command, then start a session there without automatic isolation.`);
+	}
 	const safeLabel = label.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 24) || "agent";
 	const dir = mkdtempSync(join(tmpdir(), `cc-wt-${safeLabel}-`));
 	const path = join(dir, "tree");
-	const branch = `cc-subagent/${safeLabel}-${Date.now().toString(36)}`;
+	const branch = `cc-subagent/${basename(dir).slice("cc-wt-".length)}`;
 	await git(["worktree", "add", "-b", branch, path, "HEAD"], cwd);
 	// Register for the child permission gate's git-isolation guard. The shared
-	// checkout's ROOT, not cwd — the spawn may run from a subdirectory.
+	// checkout's ROOT, not cwd — the spawn may run from a subdirectory — and the
+	// MAIN checkout's root when it runs from a linked worktree (an entered
+	// `enter_worktree` session), so git into either is refused.
 	let sharedRoot = cwd;
 	try {
-		sharedRoot = await git(["rev-parse", "--show-toplevel"], cwd);
+		// git prints `C:/…` on Windows; resolve gives the native form.
+		const top = resolve(await git(["rev-parse", "--show-toplevel"], cwd));
+		sharedRoot = findProjectRoot(top) ?? top;
 	} catch {
 		// Keep cwd as the best available anchor.
 	}
 	registerWorktreeIsolation(path, sharedRoot);
-	return { path, branch };
+	let baseCommit: string;
+	try {
+		baseCommit = await git(["rev-parse", "HEAD"], path);
+	} catch (error) {
+		// Without the base, cleanup could not tell the agent's commits apart;
+		// remove the fresh worktree now rather than run in one we cannot judge.
+		await git(["worktree", "remove", "--force", path], cwd).catch(() => undefined);
+		await git(["branch", "-D", branch], cwd).catch(() => undefined);
+		releaseWorktreeIsolation(path);
+		throw error;
+	}
+	return { path, branch, baseCommit };
 }
 
+/**
+ * Whether the worktree holds work: uncommitted changes, or commits reachable
+ * from its HEAD or its branch that the base commit does not contain (an agent
+ * that commits leaves a clean status). Any git failure counts as work.
+ */
 export async function worktreeHasChanges(worktree: Worktree): Promise<boolean> {
 	try {
-		const status = await git(["status", "--porcelain"], worktree.path);
-		return status.length > 0;
+		const status = await git(["status", "--porcelain", "--untracked-files=all", "--ignore-submodules=none"], worktree.path);
+		if (status.length > 0) return true;
+		const ahead = await git(["rev-list", "--count", "HEAD", `refs/heads/${worktree.branch}`, `^${worktree.baseCommit}`], worktree.path);
+		return ahead !== "0";
 	} catch {
-		// If status fails, assume there is something worth keeping.
+		// If git fails, assume there is something worth keeping.
 		return true;
 	}
 }
@@ -70,13 +102,25 @@ export async function cleanupWorktree(cwd: string, worktree: Worktree): Promise<
 	if (await worktreeHasChanges(worktree)) return false;
 	try {
 		await git(["worktree", "remove", "--force", worktree.path], cwd);
-		await git(["branch", "-D", worktree.branch], cwd);
 	} catch {
 		// Leave it behind rather than failing the run.
 		return false;
 	}
+	try {
+		// `-d`, not `-D`: git itself refuses to drop a branch with unmerged work,
+		// a second check behind worktreeHasChanges. A refused delete leaves a
+		// branch at the base commit, which holds none of the agent's work.
+		await git(["branch", "-d", worktree.branch], cwd);
+	} catch {
+		// The worktree is gone; the branch stays for the user to inspect.
+	}
 	// Release only when the worktree is actually gone — a kept worktree can
 	// still host a resumed session (SendMessage), which must stay guarded.
 	releaseWorktreeIsolation(worktree.path);
 	return true;
 }
+
+/** The note a result carries for a worktree kept because it holds the agent's work. */
+export function keptWorktreeNote(path: string, branch: string | undefined): string {
+	return `(Changes or commits left in worktree ${path}${branch ? ` on branch ${branch}` : ""} — review or merge them.)`;
+}