@estebanforge/pi-antigravity-bridge 1.7.3 → 1.7.4

package/src/models.ts

@@ -25,6 +25,14 @@ import type { Api, Model, ThinkingLevel, ThinkingLevelMap } from "@earendil-work
 
 const DISCOVERY_TIMEOUT_MS = 8_000;
 
+/** Stdout ceiling for `agy models`. Real output is a few KB of ASCII slugs;
+ *  anything past 1 MiB is a runaway process. Fail closed to "" so the
+ *  fallback catalog engages instead of letting the buffer grow without
+ *  limit. The check counts decoded string length (UTF-16 code units), not
+ *  raw bytes — a deliberate proxy, since the margin between a few KB of
+ *  real output and 1 MiB dwarfs any encoding difference. */
+export const MODELS_OUTPUT_CAP_BYTES = 1024 * 1024;
+
 /** Reasoning-effort tiers agy accepts via --effort. */
 export type AgyEffort = "low" | "medium" | "high";
 
@@ -104,28 +112,50 @@ export interface AgyModelEntry {
 	efforts?: AgyEffort[];
 }
 
-/** Spawn `agy models` and return its raw stdout text. Returns "" on any
- *  failure (non-zero exit, spawn error, or watchdog timeout). Bounded by
- *  DISCOVERY_TIMEOUT_MS so a hung agy (auth prompt, network stall) can't
- *  block extension load. Shared by the provider and the tool catalog so the
- *  extension spawns `agy models` ONCE per load. */
-export async function spawnAgyModelsRaw(binary: string): Promise<string> {
+/** Spawn a read-only agy listing subcommand and return its raw stdout text.
+ *  Returns "" on any failure (non-zero exit, spawn error, watchdog timeout,
+ *  or output cap). Bounded by timeoutMs (default DISCOVERY_TIMEOUT_MS) so a
+ *  hung agy (auth prompt, network stall) can't block the caller, and by
+ *  capBytes (default MODELS_OUTPUT_CAP_BYTES) so a runaway agy can't grow
+ *  the buffer without limit. Shared by the model catalog (spawned ONCE per
+ *  load, provider + tool catalog), the agent roster, and the quota fetch
+ *  (which passes its own 30s budget: /usage answers in ~10s live). */
+export async function spawnAgyRaw(
+	binary: string,
+	args: string[],
+	timeoutMs: number = DISCOVERY_TIMEOUT_MS,
+	capBytes: number = MODELS_OUTPUT_CAP_BYTES,
+): Promise<string> {
 	try {
 		return await new Promise<string>((resolve, reject) => {
-			const proc = spawn(binary, ["models"], {
+			const proc = spawn(binary, args, {
 				stdio: ["ignore", "pipe", "ignore"],
 				shell: false,
 			});
 			proc.stdout?.setEncoding("utf8");
 			let out = "";
 			let done = false;
+			let capped = false;
 			const finish = (v: string) => {
 				if (done) return;
 				done = true;
 				clearTimeout(watchdog);
 				resolve(v);
 			};
-			proc.stdout?.on("data", (d: string) => (out += d));
+			proc.stdout?.on("data", (d: string) => {
+				if (capped) return;
+				if (out.length + d.length > capBytes) {
+					capped = true;
+					try {
+						proc.kill("SIGKILL");
+					} catch {
+						/* already gone */
+					}
+					finish("");
+					return;
+				}
+				out += d;
+			});
 			proc.on("error", (err) => {
 				clearTimeout(watchdog);
 				reject(err);
@@ -138,13 +168,18 @@ export async function spawnAgyModelsRaw(binary: string): Promise<string> {
 					/* already gone */
 				}
 				finish("");
-			}, DISCOVERY_TIMEOUT_MS);
+			}, timeoutMs);
 		});
 	} catch {
 		return "";
 	}
 }
 
+/** Spawn `agy models`: the model catalog listing. */
+export async function spawnAgyModelsRaw(binary: string): Promise<string> {
+	return spawnAgyRaw(binary, ["models"]);
+}
+
 // --- catalog cache ----------------------------------------------------------
 //
 // `agy models` can take seconds (OAuth refresh, cold start) and its output

package/src/native-tools.ts

@@ -5,7 +5,7 @@
 //
 // Mutating tools (commands, edits, writes) and agy-specialty tools are never
 // re-executed - they replay through the display-only `antigravity` wrapper
-// tool. Ported from tianzuo/pi-antigravity lib/native-tools.ts (MIT).
+// tool.
 
 export interface NativeToolCall {
 	/** pi builtin tool name (`read`, `ls`, `grep`, `find`). */

package/src/parked-turn.ts

@@ -0,0 +1,125 @@
+// Parked-turn stall probe (stream-json engine only).
+//
+// The stall guard fails a turn after N minutes of stdout silence. But agy
+// sometimes finishes its answer without streaming it (parked turn): the
+// response only ever lands in the conversation's brain transcript. Before
+// failing, this module reads the transcript tail and looks for a DONE,
+// MODEL-sourced final-response step written DURING the turn. One found, the
+// driver can settle the turn OK with the withheld answer instead of
+// throwing away finished work.
+//
+// Live-verified format (agy 1.2.10, transcript_full.jsonl last line):
+//   {"step_index":1,"source":"MODEL","type":"PLANNER_RESPONSE",
+//    "status":"DONE","created_at":"2026-09-08T16:11:43Z","content":"..."}
+// A corpus sweep (2026-09-24, 9205 response steps across all local
+// transcripts) shows PLANNER_RESPONSE is the only *RESPONSE type agy
+// writes, so the gate matches it exactly. A deeper sweep during the agy
+// peer review (2026-09-25, 9547 steps) found 96.6% of PLANNER_RESPONSE
+// steps carry tool_calls — they are intermediate plan-and-act steps whose
+// content is status text ("Running test..."), NOT answers. The probe
+// therefore requires the NEWEST step written during the turn to be a
+// clean, tool-free response; any other newer step means the turn was
+// still mid-flight. If a future agy renames the type, the probe degrades
+// to the old stall-fail — the safe direction.
+// The ACP engine writes no transcript under its brain tree (probed
+// 2026-09-24) and reports turn completion itself, so this probe is
+// deliberately stream-json-only.
+
+import { open } from "node:fs/promises";
+import { agyConversationDir } from "./agy-paths.js";
+
+/** How much of the transcript tail to read. One final step is a few KiB;
+ *  512KiB covers it plus slack for big tool-step lines above it. */
+export const PARKED_PROBE_MAX_BYTES = 512 * 1024;
+
+/** Clock tolerance for "written during the turn": transcript timestamps are
+ *  second-precision and may come from a slightly skewed source. */
+const CREATED_AT_TOLERANCE_MS = 2_000;
+
+/** Pull the parked answer out of a transcript tail. Scans from the END;
+ *  the FIRST step written during the turn decides: a clean, tool-free DONE
+ *  MODEL response yields its content; any other step from the turn (tool
+ *  output, error, plan step with tool_calls) means no answer landed and
+ *  the probe returns undefined. Steps older than the turn (clock tolerance
+ *  2s) end the scan. Malformed or foreign lines are skipped without
+ *  deciding. Pure; exported for tests. */
+export function extractParkedAnswer(
+	tail: string,
+	turnStartedMs: number,
+): string | undefined {
+	const lines = tail.split("\n");
+	for (let i = lines.length - 1; i >= 0; i -= 1) {
+		const line = lines[i]?.trim();
+		if (!line) continue;
+		let step: {
+			source?: unknown;
+			type?: unknown;
+			status?: unknown;
+			created_at?: unknown;
+			content?: unknown;
+			tool_calls?: unknown;
+		};
+		try {
+			step = JSON.parse(line) as typeof step;
+		} catch {
+			continue;
+		}
+		if (typeof step.created_at !== "string") continue;
+		const createdAtMs = Date.parse(step.created_at);
+		if (Number.isNaN(createdAtMs)) continue;
+		if (createdAtMs < turnStartedMs - CREATED_AT_TOLERANCE_MS) break;
+
+		// The newest step written during this turn must be a completed MODEL
+		// response without tool calls. Intermediate tool steps, errors, or
+		// non-terminal responses mean the turn did not finish with a parked answer.
+		if (step.source !== "MODEL" || step.status !== "DONE") return undefined;
+		if (step.type !== "PLANNER_RESPONSE") return undefined;
+		if (Array.isArray(step.tool_calls) && step.tool_calls.length > 0) return undefined;
+		if (typeof step.content !== "string" || step.content.length === 0) return undefined;
+		return step.content;
+	}
+	return undefined;
+}
+
+/** Read at most `maxBytes` from the end of a file. Empty string on any
+ *  error (missing file, permission, ...) — the caller degrades to the old
+ *  stall-fail behavior. */
+export async function readTranscriptTail(filePath: string, maxBytes: number): Promise<string> {
+	let handle;
+	try {
+		handle = await open(filePath, "r");
+	} catch {
+		return "";
+	}
+	try {
+		const { size } = await handle.stat();
+		const start = Math.max(0, size - maxBytes);
+		const length = size - start;
+		const buffer = Buffer.alloc(length);
+		let read = 0;
+		while (read < length) {
+			const { bytesRead } = await handle.read(buffer, read, length - read, start + read);
+			if (bytesRead === 0) break;
+			read += bytesRead;
+		}
+		return buffer.subarray(0, read).toString("utf8");
+	} catch {
+		return "";
+	} finally {
+		await handle.close().catch(() => {});
+	}
+}
+
+/** Probe one stream-json conversation's transcript for a parked answer.
+ *  Undefined whenever nothing usable is found (missing transcript, no DONE
+ *  step from this turn) — never throws; the stall guard must not fail. */
+export async function parkedTurnAnswer(
+	conversationId: string,
+	turnStartedMs: number,
+	home: string | undefined = undefined,
+): Promise<string | undefined> {
+	const transcript = `${agyConversationDir("stream-json", conversationId, home)}/.system_generated/logs/transcript_full.jsonl`;
+	const tail = await readTranscriptTail(transcript, PARKED_PROBE_MAX_BYTES);
+	if (tail === "") return undefined;
+	return extractParkedAnswer(tail, turnStartedMs);
+}

package/src/provider.ts

@@ -33,6 +33,7 @@ import {
 import fs from "node:fs";
 import type { Api } from "@earendil-works/pi-ai";
 import type { DriverActivity, TurnDriver, TurnHandle } from "./driver-types.js";
+import { SubagentRoster } from "./subagent-roster.js";
 import { toPiUsage } from "./stream-events.js";
 import { mapAgyToolToNative } from "./native-tools.js";
 import { toAgyEffort, type AgyModelEntry } from "./models.js";
@@ -349,6 +350,8 @@ export interface StreamSimpleDeps {
 	/** Output-only ACP tool events; persisted as TUI entries, never sent to
 	 *  Antigravity or dispatched through Pi's executable tools. */
 	onNativeEvent?: (event: NativeDisplayEvent) => void;
+	/** Subagent roster (both engines); folded from every activity. */
+	roster?: SubagentRoster;
 	/** Daily file log sink (src/daily-log.ts). Records pre-dispatch turn
 	 *  errors that never create a driver turn (and so never reach onTurnEnd). */
 	log?: (event: string, data?: unknown, level?: "debug" | "info" | "warn" | "error") => void;
@@ -916,6 +919,8 @@ export interface DriverDeps {
 	replay?: WrapperReplay;
 	nativeActive?: (name: string) => boolean;
 	onNativeEvent?: (event: NativeDisplayEvent) => void;
+	/** Subagent roster fold target (both engines; best-effort telemetry). */
+	roster?: SubagentRoster;
 	/** Active engine (config), for engine-scoped session keys. */
 	engine: "stream-json" | "acp";
 	/** Daily file log sink for pre-dispatch errors (see StreamSimpleDeps). */
@@ -930,6 +935,7 @@ export interface ActivityFeatures {
 	roundTrips?: ToolRoundTrips;
 	engine?: "stream-json" | "acp";
 	onNativeEvent?: (event: NativeDisplayEvent) => void;
+	roster?: SubagentRoster;
 }
 
 /** Process-wide counter: round-trip ids must never repeat across turns in
@@ -976,6 +982,10 @@ export function consumeActivity(
 	feats: ActivityFeatures,
 ): "parked" | "continue" {
 	const partial = blocks.partial;
+	// Subagent roster folds BEFORE any rendering branch: pure in-memory
+	// telemetry over the same activities both engines emit, and it must see
+	// spawn/message/manage steps regardless of how they render.
+	feats.roster?.fold(activity);
 	switch (activity.type) {
 		case "text":
 			appendText(stream, blocks, activity.delta);
@@ -1232,6 +1242,7 @@ async function runTurnDriver(
 				effort,
 				mode: config.mode,
 				skipPermissions: config.skipPermissions,
+				agent: config.agent,
 				timeoutMin: config.turnTimeoutMin,
 				inactivityMin: config.inactivityTimeoutMin,
 				conversationId: existing?.conversationId ?? null,
@@ -1261,6 +1272,7 @@ async function runTurnDriver(
 		roundTrips: deps.roundTrips,
 		engine: deps.engine,
 		onNativeEvent: deps.onNativeEvent,
+		roster: deps.roster,
 	};
 
 	for (;;) {
@@ -1285,7 +1297,7 @@ async function runTurnDriver(
 		finalize(stream, blocks, "error", outcome.error ?? "agy turn failed");
 		return;
 	}
-	if (blocks.textIdx === null && blocks.thinkingIdx === null && outcome.response) {
+	if (blocks.textIdx === null && outcome.response) {
 		appendText(stream, blocks, outcome.response);
 	}
 	if (blocks.textIdx === null && blocks.thinkingIdx === null) {
@@ -1328,6 +1340,7 @@ export function createStreamSimple(
 				replay: deps.replay,
 				nativeActive: deps.nativeActive,
 				onNativeEvent: deps.onNativeEvent,
+				roster: deps.roster,
 				// Record the engine of the driver that will ACTUALLY run: if the
 				// ACP driver is absent, the config switch falls back to stream,
 				// and keying the session as @acp would store a stream

package/src/skills.ts

@@ -5,7 +5,6 @@
 // can tell when a skill applies. Calling it returns the full SKILL.md plus the
 // bundled resource dir. Nothing is appended to the prompt: agy sees the
 // catalog in tools/list on every spawn, including after pi compaction.
-// Shape borrowed from tianzuo/pi-antigravity lib/skills.ts (MIT).
 
 import fs from "node:fs";
 import os from "node:os";

package/src/stream-events.ts

@@ -3,8 +3,7 @@
 // `agy --input-format stream-json --output-format stream-json` emits one JSON
 // object per line on stdout: `init` (conversation binding), `step_update`
 // (user_input / agent_response / checkpoint / tool steps), `result` (terminal).
-// Shapes captured from live output and cross-checked against
-// tianzuo/pi-antigravity lib/events.ts (MIT). Unknown event kinds parse as
+// Shapes captured from live output. Unknown event kinds parse as
 // {kind:"unknown"} so a future agy release degrades instead of crashing the
 // reader loop.
 

package/src/subagent-roster.ts

@@ -0,0 +1,245 @@
+// In-memory subagent roster, folded from driver activities.
+//
+// agy has no read-only subcommand for live subagent state, so the only
+// zero-token source is the turn stream: subagent spawns arrive as ordinary
+// tool steps (invoke_subagent, run_subagent, define_subagent,
+// browser_subagent), send_message addresses a spawned agent, and
+// manage_subagents carries lifecycle actions. The roster folds
+// DriverActivity — the engine-agnostic contract both turn engines emit — so
+// stream-json (stepId-keyed) and ACP (toolCallId-keyed) feed one roster.
+//
+// Accepted heuristic limits (telemetry only, never persisted — agy's own
+// conversation database remains the durable record):
+// - send_message routes to the FIRST entry with the matching agent name
+//   regardless of status, so a message after a name is reused may credit a
+//   stale entry.
+// - manage_subagents kill marks ALL running entries killed; the target arg
+//   is ignored because its shape is not stable across agy builds.
+// - Parallel spawns with the same agent name are separate entries, but
+//   name-based routing cannot tell them apart.
+
+import type { DriverActivity } from "./driver-types.js";
+
+/** Tools whose start opens a roster entry and whose done/error closes it. */
+const SPAWN_TOOLS = new Set(["invoke_subagent", "run_subagent", "browser_subagent"]);
+/** Tools addressed at an already-spawned agent. */
+const MESSAGE_TOOLS = new Set(["send_message"]);
+/** Tools carrying lifecycle actions (kill/stop/...). */
+const MANAGE_TOOLS = new Set(["manage_subagents"]);
+
+/** Arg keys that plausibly name the target agent (their casing varies). */
+const NAME_ARG_KEYS = /^(name|subagent|subagent_name|agent|agent_name|type|recipient|role|to)$/i;
+/** Arg keys plausibly holding a manage_subagents lifecycle action. */
+const ACTION_ARG_KEYS = /^(action|command|operation|op)$/i;
+const DETAIL_MAX = 120;
+
+export interface SubagentEntry {
+	/** Stable fold key: `s:<stepId>` on stream-json, `n:<seq>` on ACP. */
+	key: string;
+	name: string;
+	status: "running" | "done" | "error" | "killed";
+	spawnedAtMs: number;
+	lastActivityMs: number;
+	/** send_message count since spawn. */
+	messages: number;
+	/** First non-name string arg, truncated — usually the task text. */
+	detail: string;
+	error?: string;
+}
+
+function truncate(value: string): string {
+	return value.length > DETAIL_MAX ? `${value.slice(0, DETAIL_MAX)}…` : value;
+}
+
+/** First string arg whose key plausibly names the agent. */
+function subagentNameFromArgs(args: Record<string, unknown>): string {
+	for (const [k, v] of Object.entries(args)) {
+		if (NAME_ARG_KEYS.test(k) && typeof v === "string" && v.trim()) return truncate(v.trim());
+	}
+	return "subagent";
+}
+
+/** First string arg that is not the name — the task text, when agy passes one. */
+function detailFromArgs(args: Record<string, unknown>): string {
+	for (const [k, v] of Object.entries(args)) {
+		if (!NAME_ARG_KEYS.test(k) && typeof v === "string" && v.trim()) return truncate(v.trim());
+	}
+	return "";
+}
+
+interface ExtractedSpawn {
+	name: string;
+	detail: string;
+}
+
+function extractSpawnsFromArgs(args: Record<string, unknown>): ExtractedSpawn[] {
+	const raw = args.Subagents ?? args.subagents;
+	if (Array.isArray(raw) && raw.length > 0) {
+		const out: ExtractedSpawn[] = [];
+		for (const item of raw) {
+			if (item && typeof item === "object") {
+				const rec = item as Record<string, unknown>;
+				const name =
+					(typeof rec.Role === "string" && rec.Role.trim()) ||
+					(typeof rec.role === "string" && rec.role.trim()) ||
+					(typeof rec.TypeName === "string" && rec.TypeName.trim()) ||
+					(typeof rec.type_name === "string" && rec.type_name.trim()) ||
+					(typeof rec.name === "string" && rec.name.trim()) ||
+					"subagent";
+				const detail =
+					(typeof rec.Prompt === "string" && rec.Prompt.trim()) ||
+					(typeof rec.prompt === "string" && rec.prompt.trim()) ||
+					(typeof rec.task === "string" && rec.task.trim()) ||
+					"";
+				out.push({ name: truncate(name), detail: truncate(detail) });
+			}
+		}
+		if (out.length > 0) return out;
+	}
+	return [{ name: subagentNameFromArgs(args), detail: detailFromArgs(args) }];
+}
+
+function manageActionIsKill(args: Record<string, unknown>): boolean {
+	for (const [k, v] of Object.entries(args)) {
+		if (ACTION_ARG_KEYS.test(k) && typeof v === "string" && /kill|stop|terminate|cancel/i.test(v))
+			return true;
+	}
+	return false;
+}
+
+export class SubagentRoster {
+	#entries = new Map<string, SubagentEntry>();
+	#acpSeq = 0;
+
+	/** Fold key precedence: ACP toolCallId (stable protocol id), stream-json
+	 *  numeric stepId, then a process-local sequence for hypothetical engines
+	 *  with neither. */
+	#keyFor(activity: Extract<DriverActivity, { type: "tool_start" }>): string {
+		if (activity.toolCallId !== undefined) return `t:${activity.toolCallId}`;
+		if (activity.stepId !== undefined) return `s:${activity.stepId}`;
+		return `n:${this.#acpSeq++}`;
+	}
+
+	#entriesFor(activity: Extract<DriverActivity, { type: "tool_done" | "tool_error" }>): SubagentEntry[] {
+		const baseKey =
+			activity.toolCallId !== undefined
+				? `t:${activity.toolCallId}`
+				: activity.stepId !== undefined
+					? `s:${activity.stepId}`
+					: undefined;
+		if (baseKey !== undefined) {
+			const matched: SubagentEntry[] = [];
+			for (const [k, v] of this.#entries) {
+				if (k === baseKey || k.startsWith(`${baseKey}:`)) matched.push(v);
+			}
+			return matched;
+		}
+		for (const entry of this.#entries.values()) {
+			if (entry.status === "running") return [entry];
+		}
+		return [];
+	}
+
+	/** Fold one driver activity. Non-tool activities are ignored; unknown
+	 *  tool names are other features' business. Never throws: roster
+	 *  bookkeeping must not be able to fail a turn. */
+	fold(activity: DriverActivity): void {
+		try {
+			this.#fold(activity);
+		} catch {
+			/* roster is best-effort telemetry */
+		}
+	}
+
+	#fold(activity: DriverActivity): void {
+		if (activity.type === "tool_start") {
+			if (SPAWN_TOOLS.has(activity.name)) {
+				const baseKey = this.#keyFor(activity);
+				const spawns = extractSpawnsFromArgs(activity.args);
+				const now = Date.now();
+				for (let i = 0; i < spawns.length; i++) {
+					const key = spawns.length === 1 ? baseKey : `${baseKey}:${i}`;
+					this.#entries.set(key, {
+						key,
+						name: spawns[i]!.name,
+						status: "running",
+						spawnedAtMs: now,
+						lastActivityMs: now,
+						messages: 0,
+						detail: spawns[i]!.detail,
+					});
+				}
+				return;
+			}
+			if (MESSAGE_TOOLS.has(activity.name)) {
+				const entry = this.#entryByName(subagentNameFromArgs(activity.args));
+				if (entry) {
+					entry.messages += 1;
+					entry.lastActivityMs = Date.now();
+				}
+				return;
+			}
+			if (MANAGE_TOOLS.has(activity.name) && manageActionIsKill(activity.args)) {
+				const now = Date.now();
+				for (const entry of this.#entries.values()) {
+					if (entry.status === "running") {
+						entry.status = "killed";
+						entry.lastActivityMs = now;
+					}
+				}
+			}
+			return;
+		}
+		if (activity.type === "tool_done" || activity.type === "tool_error") {
+			const entries = this.#entriesFor(activity);
+			if (entries.length === 0) return;
+			const now = Date.now();
+			for (const entry of entries) {
+				entry.lastActivityMs = now;
+				if (activity.type === "tool_error") {
+					entry.status = "error";
+					entry.error = truncate(activity.message);
+				} else if (entry.status === "running") {
+					entry.status = "done";
+				}
+			}
+		}
+	}
+
+	#entryByName(name: string, ...statuses: SubagentEntry["status"][]): SubagentEntry | undefined {
+		for (const entry of this.#entries.values()) {
+			if (entry.name === name && (statuses.length === 0 || statuses.includes(entry.status)))
+				return entry;
+		}
+		return undefined;
+	}
+
+	/** Entries in spawn order (Map preserves insertion). */
+	snapshot(): SubagentEntry[] {
+		return [...this.#entries.values()];
+	}
+
+	/** Live wire for status surfaces. */
+	runningCount(): number {
+		let n = 0;
+		for (const entry of this.#entries.values()) if (entry.status === "running") n += 1;
+		return n;
+	}
+}
+
+export function formatSubagentRoster(entries: SubagentEntry[]): string {
+	const running = entries.filter((e) => e.status === "running").length;
+	const lines = [`antigravity subagents: ${entries.length} tracked, ${running} running`];
+	for (const entry of entries) {
+		const secs = Math.max(0, Math.round((Date.now() - entry.spawnedAtMs) / 1000));
+		const dur = secs >= 60 ? `${Math.floor(secs / 60)}m${String(secs % 60).padStart(2, "0")}s` : `${secs}s`;
+		const parts = [
+			`${entry.name} · ${entry.status} · ${dur}`,
+			entry.messages > 0 ? `${entry.messages} msg` : undefined,
+			entry.detail || undefined,
+			entry.error ? `error: ${entry.error}` : undefined,
+		].filter((p): p is string => p !== undefined);
+		lines.push(`- ${parts.join(" · ")}`);
+	}
+	return lines.join("\n");
+}

package/src/tasks-ui.ts

@@ -0,0 +1,88 @@
+// /agy tasks overlay: SelectList over one conversation's background tasks.
+//
+// UI mirrors the artifacts browser (engine-picker pattern). Watch-only:
+// enter closes (the list IS the dashboard), r rescans, esc closes. Tails
+// live in the command form: /agy tasks tail <id> — a log tail is chat
+// content, not overlay content.
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+import type { AgyTask } from "./tasks.js";
+
+export type TasksBrowserAction = { type: "rescan" } | { type: "close" };
+
+export function taskItems(tasks: AgyTask[]): SelectItem[] {
+	return tasks.map((t) => {
+		const when = new Date(t.modifiedMs);
+		const stamp = `${String(when.getHours()).padStart(2, "0")}:${String(when.getMinutes()).padStart(2, "0")}`;
+		const state = t.livenessKnown ? (t.active ? "ACTIVE" : "idle") : "liveness?";
+		return {
+			value: String(t.id),
+			label: `#${t.id} · ${state}`,
+			description: `${humanBytes(t.bytes)} · last write ${stamp}`,
+		};
+	});
+}
+
+function humanBytes(n: number): string {
+	if (n < 1024) return `${n}B`;
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+	return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/** Render the overlay. Resolves rescan (caller re-lists and reopens) or
+ *  close. */
+export async function showTasksBrowser(
+	ctx: ExtensionUIContext,
+	tasks: AgyTask[],
+	livenessKnown: boolean,
+): Promise<TasksBrowserAction> {
+	const items = taskItems(tasks);
+	return ctx.custom<TasksBrowserAction>((tui, theme, _keybindings, done) => {
+		const container = new Container();
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+		container.addChild(
+			new Text(theme.fg("accent", theme.bold(`Antigravity tasks (${tasks.length})`)), 1, 0),
+		);
+		if (!livenessKnown) {
+			container.addChild(
+				new Text(theme.fg("warning", "lsof not found; liveness unknown (install lsof for ACTIVE/idle)"), 1, 0),
+			);
+		}
+		container.addChild(new Spacer(1));
+
+		const list = new SelectList(items, Math.min(items.length, 12), {
+			selectedPrefix: (t: string) => theme.fg("accent", t),
+			selectedText: (t: string) => theme.fg("accent", t),
+			description: (t: string) => theme.fg("muted", t),
+			scrollInfo: (t: string) => theme.fg("dim", t),
+			noMatch: (t: string) => theme.fg("warning", t),
+		});
+		list.onSelect = () => done({ type: "close" });
+		list.onCancel = () => done({ type: "close" });
+		container.addChild(list);
+
+		container.addChild(new Spacer(1));
+		container.addChild(
+			new Text(theme.fg("dim", "↑↓ navigate · r rescan · esc close · /agy tasks tail <id> for a log"), 1, 0),
+		);
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				if (data.trim().toLowerCase() === "r") {
+					done({ type: "rescan" });
+					return;
+				}
+				list.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	}, {
+		overlay: true,
+		overlayOptions: { anchor: "center" as const, width: 72, maxHeight: "85%" as const, margin: 1 },
+	});
+}