pi-async 0.0.0-stage → 0.2.0

package/src/tools/index.ts

@@ -0,0 +1,131 @@
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import { isTerminal, type WatchSpec } from "../core/task.ts";
+
+/**
+ * Wrap an extension-tool return value into pi's ToolResultMessage shape.
+ *
+ * pi 1.2.0 does NOT auto-wrap extension tool return values (the executor
+ * passes `await tool.execute(...)` through verbatim; only builtin tools
+ * return `{content:[{type:"text",...}]}`). A bare object without `content`
+ * crashes the TUI's ToolExecutionComponent.getTextOutput
+ * (`result.content.filter` on undefined) and persists as content:[] —
+ * see the user-reported uncaughtException on 2026-10-15.
+ *
+ * Every async_* tool MUST route its return value through this helper so the
+ * result satisfies the ToolResultMessage contract: content is an array of
+ * typed blocks, and the original payload rides along in `details` for tests
+ * and structured consumers.
+ */
+function toolResult(payload: unknown, isError = false): { content: Array<{ type: "text"; text: string }>; details: unknown; isError: boolean } {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], details: { payload }, isError };
+}
+
+const promptGuidelines = "Check commands must not swallow errors with || true; map unknown states to failure; prefer structured output and jq -e; anchor output_matches regexes (compiled with multiline `m`: ^/$ are line boundaries) to avoid premature matches; prefer stdout_contains for simple cases and avoid nested quantifiers.";
+const MAX_LOG_BYTES = 50 * 1024;
+const schema = (properties: Record<string, unknown>, required: string[] = [], allOf: unknown[] = []) => ({ type: "object", properties, required, additionalProperties: false, ...(allOf.length ? { allOf } : {}) });
+const stringField = { type: "string" };
+const timeoutField = { type: "number", minimum: 0 };
+const conditionSchema = {
+  oneOf: [
+    { type: "object", properties: { type: { const: "exit_code" }, equals: { type: "number" } }, required: ["type", "equals"], additionalProperties: false },
+    ...["stdout_contains", "stderr_contains"].map((type) => ({ type: "object", properties: { type: { const: type }, value: stringField }, required: ["type", "value"], additionalProperties: false })),
+    { type: "object", properties: {
+      type: { const: "json_path_exists" },
+      path: { type: "string", pattern: "^\\$", description: "JSONPath rooted at $; e.g. $.ready or $.items[0].state (bare names like \"ready\" are rejected)" },
+    }, required: ["type", "path"], additionalProperties: false },
+    { type: "object", properties: { type: { const: "output_matches" }, regex: stringField }, required: ["type", "regex"], additionalProperties: false },
+  ],
+};
+const watchSchema = {
+  type: "object", properties: {
+    intervalMs: { type: "number", minimum: 1000 }, timeoutMs: { type: "number", minimum: 1 },
+    success_when: { type: "array", items: conditionSchema }, failure_when: { type: "array", items: conditionSchema },
+    blind_checks: { type: "number", minimum: 1 },
+  }, required: ["intervalMs", "timeoutMs", "success_when", "failure_when"], additionalProperties: false,
+};
+
+/** Register the frozen five-tool surface. */
+export function registerTools(pi: PiCtx, registry: TaskRegistry): void {
+  type ToolDef = { name: string; label: string; description: string; parameters: unknown; execute: (toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown> };
+  // SAFETY: ExtensionAPI exposes registerTool at runtime; this local structural view keeps schemas dependency-free.
+  const api = pi as unknown as { registerTool?: (tool: ToolDef) => void };
+  if (!api.registerTool) throw new Error("Pi host does not expose registerTool");
+  api.registerTool({
+    name: "async_run", label: "Run async command",
+    description: `Run a background, delayed, or synchronous shell command. mode=sync requires timeoutMs; mode=delayed requires delayMs. onTimeout (sync only): "promote" (default) hands the still-running task to background and returns; "abort" stops WAITING only — the command keeps running in the background and will still notify on completion (Esc semantics; does not kill). ${promptGuidelines}`,
+    // Mode-conditional required fields + mode-scoped rejects enforced in execute (#45/#42),
+    // not allOf/then (host validator emits opaque "must match then schema").
+    parameters: schema({ command: stringField, name: stringField, mode: { type: "string", enum: ["background", "sync", "delayed"], default: "background" }, timeoutMs: timeoutField, delayMs: timeoutField, taskTimeoutMs: timeoutField, onTimeout: { type: "string", enum: ["promote", "abort"], default: "promote" }, notifyOnCompletion: { type: "boolean" }, triggerOnCompletion: { type: "boolean" }, env: { type: "object", additionalProperties: { type: "string" } }, watch: watchSchema }, ["command"]),
+    execute: async (_id, params, signal) => {
+      const mode = String(params.mode ?? "background");
+      if (mode !== "background" && mode !== "sync" && mode !== "delayed") throw new Error(`Unsupported async_run mode: ${mode}`);
+      const command = String(params.command ?? "");
+      if (mode === "sync" && params.timeoutMs === undefined) throw new Error("timeoutMs is required for sync mode");
+      if (mode === "delayed" && params.delayMs === undefined) throw new Error("delayMs is required for delayed mode");
+      if (params.watch !== undefined && mode === "sync") throw new Error("watch is only supported for background and delayed modes");
+      if (mode !== "sync" && params.timeoutMs !== undefined) throw new Error("timeoutMs is only valid for sync mode (use taskTimeoutMs to bound background/delayed tasks)");
+      if (mode !== "delayed" && params.delayMs !== undefined) throw new Error("delayMs is only valid for delayed mode");
+      const options = {
+        command,
+        ...(typeof params.name === "string" ? { name: params.name } : {}),
+        ...(typeof params.taskTimeoutMs === "number" ? { taskTimeoutMs: params.taskTimeoutMs } : {}),
+        ...(typeof params.notifyOnCompletion === "boolean" ? { notifyOnCompletion: params.notifyOnCompletion } : {}),
+        ...(typeof params.triggerOnCompletion === "boolean" ? { triggerOnCompletion: params.triggerOnCompletion } : {}),
+        ...(params.env && typeof params.env === "object" ? { env: params.env as Record<string, string> } : {}),
+        ...(params.watch && typeof params.watch === "object" ? { watch: params.watch as WatchSpec } : {}),
+      };
+      if (mode === "sync") { const r = await registry.runSync({ ...options, mode: "sync" }, Number(params.timeoutMs), params.onTimeout === "abort" ? "abort" : "promote", signal); return toolResult(r); }
+      const task = mode === "delayed"
+        ? registry.scheduleDelayed({ ...options, mode: "delayed" }, Number(params.delayMs))
+        : registry.submit({ ...options, mode: "background" });
+      return toolResult({ taskId: task.taskId, name: task.name, status: task.status, mode: task.mode, outputHint: `Use async_logs with taskId ${task.taskId} to inspect early output.` });
+    },
+  });
+  api.registerTool({ name: "async_wait", label: "Wait for async tasks", description: "Wait for tasks to finish or return notReady; waiting does not kill tasks.", parameters: schema({ taskIds: { type: "array", items: stringField }, timeoutMs: timeoutField }, ["taskIds", "timeoutMs"]), execute: async (_id, params, signal) => {
+    if (params.timeoutMs === undefined) throw new Error("timeoutMs is required");
+    return toolResult(await registry.wait(params.taskIds as string[], Number(params.timeoutMs), signal));
+  } });
+  api.registerTool({ name: "async_logs", label: "Read async output", description: "Read bounded, ANSI-stripped task output.", parameters: schema({ taskId: stringField, maxBytes: { type: "number", minimum: 0, maximum: MAX_LOG_BYTES }, tail: { type: "boolean" } }, ["taskId"]), execute: async (_id, params) => {
+    const maxBytes = params.maxBytes === undefined ? MAX_LOG_BYTES : Number(params.maxBytes);
+    if (maxBytes > MAX_LOG_BYTES) throw new Error("maxBytes must be at most 50 KiB");
+    return toolResult(registry.logs(String(params.taskId), { maxBytes, tail: params.tail !== false }));
+  } });
+  api.registerTool({
+    name: "async_status", label: "Async task status",
+    description: "List async tasks and current status. Defaults to active (running/pending) only; pass includeHistory:true for up to 50 recent tasks.",
+    parameters: schema({ includeHistory: { type: "boolean" } }),
+    execute: async (_id, params) => {
+      const MAX_HISTORY = 50;
+      if (params.includeHistory === true) {
+        const all = registry.list({ includeHistory: true });
+        return toolResult(all.slice(-MAX_HISTORY));
+      }
+      return toolResult(registry.list({ includeHistory: false }));
+    },
+  });
+  api.registerTool({
+    name: "async_kill", label: "Kill async task", description: "Terminate an async task and its process group.",
+    parameters: schema({ taskId: stringField }, ["taskId"]),
+    execute: async (_id, params) => {
+      const taskId = String(params.taskId);
+      const before = registry.get(taskId);
+      const alreadyTerminal = before !== undefined && isTerminal(before.status);
+      let warning: string | undefined;
+      try {
+        await registry.kill(taskId, "user");
+      } catch (error) {
+        // Kill may still have finalized the task; surface confirmation failures as warning (#6).
+        warning = error instanceof Error ? error.message : String(error);
+      }
+      const after = registry.get(taskId);
+      return toolResult({
+        taskId,
+        status: after?.status,
+        ...(after?.killKind ? { killKind: after.killKind } : {}),
+        alreadyTerminal,
+        ...(warning ? { warning } : {}),
+      }, Boolean(warning && after?.status !== "killed"));
+    },
+  });
+}

package/src/tui/host.ts

@@ -0,0 +1,30 @@
+/**
+ * Bound TUI host context.
+ *
+ * pi's factory-time ExtensionAPI exposes neither `mode` nor `ui` — those live
+ * on event-handler contexts (`pi.on(event, (event, ctx) => ...)`), and `ctx.ui`
+ * is the only object whose setWidget/setStatus/custom actually work. All TUI
+ * surfaces therefore bind lazily from the first event context whose
+ * `mode === "tui"`, and read `tuiHost()` afterwards.
+ */
+export type TuiHost = { mode: string; ui: Record<string, unknown> };
+
+let bound: TuiHost | undefined;
+
+/** Bind the first TUI-capable event context. Idempotent; only the first wins. */
+export function bindTuiHost(ctx: unknown): boolean {
+  const c = ctx as { mode?: string; ui?: Record<string, unknown> } | undefined;
+  if (bound || c?.mode !== "tui" || !c.ui) return false;
+  bound = { mode: c.mode, ui: c.ui };
+  return true;
+}
+
+/** The bound TUI host, or undefined when no TUI context has been seen. */
+export function tuiHost(): TuiHost | undefined {
+  return bound;
+}
+
+/** Test-only: forget the bound host so isolated unit tests can re-bind. */
+export function resetTuiHostForTests(): void {
+  bound = undefined;
+}

package/src/tui/panel.ts

@@ -0,0 +1,279 @@
+import { openSync, closeSync, fstatSync, readSync } from "node:fs";
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import type { TaskSnapshot } from "../core/task.ts";
+import { stripAnsi, visibleText } from "../core/output.ts";
+import { formatDuration } from "../core/duration.ts";
+import { fitWidth } from "./width.ts";
+import { clearDoneStatus, survivesClearCutoff } from "./status.ts";
+import { tuiHost } from "./host.ts";
+
+const isTui = (pi: unknown): boolean => {
+  // Event/command contexts carry mode; the factory API does not. Both paths must resolve.
+  const asCtx = pi as { mode?: string } | undefined;
+  return asCtx?.mode === "tui" || tuiHost()?.mode === "tui";
+};
+
+const UI_TAIL_BYTES = 128 * 1024;
+const PANEL_ROWS = 12;
+const visible = visibleText;
+/** Per-line sanitizer for multiline command display — keeps LF, strips controls/tabs. */
+const visibleLine = (value: unknown): string => stripAnsi(String(value ?? "")).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "").replace(/[\t]+/g, " ");
+function readUiOutput(task: TaskSnapshot, registry: TaskRegistry): { text: string; truncated: boolean } {
+  const outputPath = task.metadata.outputFile;
+  if (typeof outputPath !== "string") return { text: registry.logs(task.taskId, { maxBytes: UI_TAIL_BYTES, tail: true }).text, truncated: false };
+  try {
+    const fd = openSync(outputPath, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const start = Math.max(0, size - UI_TAIL_BYTES);
+      const buffer = Buffer.alloc(Math.min(size, UI_TAIL_BYTES));
+      readSync(fd, buffer, 0, buffer.length, start);
+      return { text: stripAnsi(buffer.toString("utf8")), truncated: start > 0 };
+    } finally { closeSync(fd); }
+  } catch {
+    return { text: registry.logs(task.taskId, { maxBytes: UI_TAIL_BYTES, tail: true }).text, truncated: false };
+  }
+}
+
+const frame = (title: string, body: string[], width: number, height: number): string[] => {
+  const w = Math.max(8, Math.floor(width));
+  const h = Math.max(4, Math.floor(height));
+  // Title prefix is "╭─ " (3) + "─╮" (2) => budget w-5; body "│ "/" │" (2+2) => w-4.
+  // #55 keeps fitTitle(w-5); #7/#62 routes both through fitWidth (cell-aware).
+  const fitTitle = (text: string): string => fitWidth(text, w - 5);
+  const fit = (text: string): string => fitWidth(text, w - 4);
+  const content = [`╭─ ${fitTitle(title)}─╮`, ...body.slice(0, h - 2).map((line) => `│ ${fit(line)} │`), `╰${"─".repeat(w - 2)}╯`];
+  while (content.length < height) content.splice(content.length - 1, 0, `│${" ".repeat(w - 2)}│`);
+  // The solid background masks chat rows beneath the overlay, as in legion-viz's live overlay.
+  return content;
+};
+
+/** Bare Esc, Kitty CSI-u Escape (key 27), and a lone CSI introducer. */
+export function isEscapeKey(data: string): boolean {
+  if (data === "\u001b") return true;
+  if (data === "\u001b[") return true;
+  return /^\u001b\[27(?:;\d+)*u$/.test(data);
+}
+
+export function registerPanelCommands(pi: PiCtx, registry: TaskRegistry): void {
+  // Commands/shortcuts are factory-time APIs (they exist on the factory pi); TUI
+  // gating comes from the bound event context. Handlers receive a rich ctx with ui.
+  const bound = tuiHost();
+  const host = pi as unknown as {
+    registerCommand?: (name: string, spec: { description: string; handler: (args: unknown, ctx: PiCtx) => void }) => void;
+    registerShortcut?: (key: string, spec: { description: string; handler: (ctx: PiCtx) => void }) => void;
+  };
+  if (!bound) return;
+  host.registerCommand?.("async", { description: "Open async task panel", handler: (_args, ctx) => openPanel(ctx, registry) });
+  host.registerCommand?.("async-clear", {
+    description: "Clear async task history",
+    handler: (_args, ctx) => {
+      if (!isTui(ctx)) return;
+      clearDoneStatus(); // shared watermark in status.ts (#31)
+    },
+  });
+  // CONTRACT: PI_ASYNC_DOCK_SHORTCUT is disableable ("可 off"). Treat
+  // off/none/false/empty (case-insensitive, trimmed) as skip registration —
+  // otherwise "off" would be registered as a literal key name (#30).
+  // Unset stays the default; only an explicitly set disable value skips.
+  const rawShortcut = process.env.PI_ASYNC_DOCK_SHORTCUT;
+  const normalized = rawShortcut === undefined ? undefined : rawShortcut.trim().toLowerCase();
+  const disabled = normalized !== undefined && ["off", "none", "false", ""].includes(normalized);
+  if (!disabled) {
+    const key = rawShortcut && rawShortcut.trim() ? rawShortcut.trim() : "ctrl+alt+a";
+    try {
+      host.registerShortcut?.(key, { description: "Open async task panel", handler: (ctx) => openPanel(ctx, registry) });
+    } catch {
+      // The /async command remains the fallback when Pi reserves this shortcut.
+    }
+  }
+}
+
+export function openPanel(pi: PiCtx, registry: TaskRegistry, initialTaskId?: string): void {
+  // Event/command contexts carry a working ui; rail-click paths pass the factory
+  // pi, whose ui is undefined — fall back to the bound TUI host in that case.
+  const ctxUi = (pi as { ui?: Record<string, unknown> }).ui ?? tuiHost()?.ui;
+  const host = {
+    ui: ctxUi as {
+      copyToClipboard?: (text: string) => void;
+      custom?: (factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value?: unknown) => void) => unknown, options: unknown) => Promise<unknown>;
+      notify?: (message: string, level?: string) => void;
+      setStatus?: (key: string, text: string | undefined) => void;
+    } | undefined,
+  };
+  if (!isTui(pi) || typeof host.ui?.custom !== "function") return;
+  const snapshots = (): TaskSnapshot[] => registry.list({ includeHistory: true }).filter((task) => survivesClearCutoff(task));
+  const custom = host.ui.custom;
+  const factory = (tui: unknown, _theme: unknown, _keybindings: unknown, done: (value?: unknown) => void) => {
+    let selected = initialTaskId ?? snapshots()[0]?.taskId;
+    let detail = Boolean(initialTaskId);
+    let history = true;
+    let confirmKill = false;
+    let scroll = 0;
+    let listScroll = 0;
+    let follow = true;
+    let width = 100;
+    let height = process.stdout.rows ?? 24;
+    let lastLines: string[] = [];
+    let actionError: string | undefined;
+    const requestRender = (): void => {
+      (tui as { requestRender?: () => void } | undefined)?.requestRender?.();
+    };
+    const filtered = (): TaskSnapshot[] => snapshots().filter((task) => history || task.status === "running" || task.status === "pending");
+    const choose = (): TaskSnapshot | undefined => snapshots().find((task) => task.taskId === selected);
+    const listBudget = (): number => Math.max(1, height - 3); // frame borders + hint row
+    const ensureListWindow = (tasks: TaskSnapshot[]): number => {
+      const budget = listBudget();
+      const selIndex = tasks.findIndex((task) => task.taskId === selected);
+      const index = selIndex < 0 ? 0 : selIndex;
+      if (index < listScroll) listScroll = index;
+      if (index >= listScroll + budget) listScroll = index - budget + 1;
+      listScroll = Math.max(0, Math.min(listScroll, Math.max(0, tasks.length - budget)));
+      return listScroll;
+    };
+    const renderBody = (): string[] => {
+      const tasks = filtered();
+      if (!detail) {
+        const start = ensureListWindow(tasks);
+        const budget = listBudget();
+        const rows = tasks.slice(start, start + budget).map((task) => {
+          const output = task.status === "running" ? registry.logs(task.taskId, { maxBytes: UI_TAIL_BYTES, tail: true }).text.split(/\r?\n/).filter(Boolean).at(-1) : undefined;
+          return `${task.taskId === selected ? "▶" : " "} ${visible(task.name)} · ${task.status} · ${formatDuration(task, Date.now())}${output ? ` · ${visible(output)}` : ""}`;
+        });
+        return ["↑/↓ select · Enter details · h history · q close", ...rows];
+      }
+      const task = choose();
+      if (!task) return ["Task not found", "Esc return · q close"];
+      const output = readUiOutput(task, registry);
+      const outputLines = output.text.split(/\r?\n/).filter((line) => line.length > 0);
+      scroll = Math.min(scroll, Math.max(0, outputLines.length - PANEL_ROWS));
+      const tail = outputLines.slice(Math.max(0, outputLines.length - PANEL_ROWS - scroll), outputLines.length - scroll);
+      const meta = JSON.stringify(task.metadata);
+      const commandLines = String(task.command ?? "").split(/\r?\n/);
+      const killHint = task.status === "pending"
+        ? "Cancel this pending task? press k again to confirm; any other key cancels"
+        : "Kill this task? press k again to confirm; any other key cancels";
+      return [
+        `${visible(task.name)} [${task.taskId}]`, `status: ${task.status} · elapsed: ${formatDuration(task, Date.now())}`,
+        "command:",
+        ...commandLines.map((line) => `  ${visibleLine(line)}`),
+        `metadata: ${meta}`, `output${output.truncated ? " (tail truncated)" : ""}:`,
+        // registry.logs caps its own data at 50 KiB; the TUI intentionally reads a larger 128 KiB tail directly from the output file.
+        ...tail.map(visible),
+        ...(actionError ? [`error: ${visible(actionError)}`] : []),
+        ...(confirmKill ? [killHint] : []),
+        "Esc return · k kill/cancel · R rerun · c copy output path · ↑/↓ scroll",
+      ];
+    };
+    const render = (nextWidth?: number): string[] => {
+      width = nextWidth ?? width;
+      height = process.stdout.rows ?? height;
+      lastLines = renderBody();
+      const maxScroll = Math.max(0, lastLines.length - PANEL_ROWS);
+      if (follow) scroll = 0;
+      else scroll = Math.min(scroll, maxScroll);
+      return frame(detail ? "Async task detail" : "Async tasks", lastLines, width, height);
+    };
+    const move = (delta: number): void => {
+      const tasks = filtered();
+      const index = tasks.findIndex((task) => task.taskId === selected);
+      // Harden dangling selection (filtered away): start from edge rather than relying on -1+delta===0 alone.
+      const base = index < 0 ? (delta > 0 ? -1 : 0) : index;
+      const next = tasks[Math.max(0, Math.min(tasks.length - 1, base + delta))];
+      if (next) selected = next.taskId;
+      if (detail && delta < 0) { scroll += -delta; follow = false; }
+      else if (detail && delta > 0) { scroll = Math.max(0, scroll - delta); follow = scroll === 0; }
+      requestRender();
+    };
+    let latchedId: string | undefined;
+    return {
+      render,
+      handleInput(data: string): void {
+        const key = data.toLowerCase();
+        if (confirmKill && key !== "k") { confirmKill = false; requestRender(); return; }
+        if (key === "q") { done(undefined); return; }
+        if (isEscapeKey(data)) { if (detail) { detail = false; confirmKill = false; actionError = undefined; requestRender(); } else done(undefined); return; }
+        if (key === "h" && !detail) {
+          history = !history;
+          const tasks = filtered();
+          if (!tasks.some((task) => task.taskId === selected)) selected = tasks[0]?.taskId;
+          listScroll = 0;
+          requestRender();
+          return;
+        }
+        if (data === "\r" || data === "\n") { detail = true; scroll = 0; follow = true; actionError = undefined; requestRender(); return; }
+        if (data === "\u001b[A" || data === "k") { if (detail && key === "k") {
+          if (!confirmKill) { confirmKill = true; requestRender(); return; }
+          confirmKill = false;
+          const task = choose();
+          if (task?.status === "running" || task?.status === "pending") void registry.kill(task.taskId, "user");
+          requestRender(); return;
+        } move(-1); return; }
+        if (data === "\u001b[B" || key === "j") { move(1); return; }
+        if (data === "R" && detail) {
+          const task = choose();
+          if (task) {
+            try {
+              const created = registry.submit({ command: task.command, name: task.name, mode: "background" });
+              selected = created.taskId;
+              scroll = 0;
+              follow = true;
+              actionError = undefined;
+            } catch (error) {
+              actionError = String(error);
+              host.ui?.notify?.(actionError, "error");
+            }
+          }
+          requestRender(); return;
+        }
+        if (data === "c" && detail) {
+          const path = choose()?.metadata.outputFile;
+          if (typeof path === "string") {
+            if (host.ui?.copyToClipboard) host.ui.copyToClipboard(path);
+            else host.ui?.notify?.(path, "info");
+          }
+        }
+      },
+      handleMouse(event: { type: string; y?: number; button?: string; wheelDelta?: number }): { handled: boolean } | undefined {
+        if (event.type === "wheel") {
+          const delta = Math.trunc(event.wheelDelta ?? 0);
+          if (detail) { scroll = Math.max(0, scroll + delta); follow = scroll === 0; }
+          else move(delta);
+          requestRender();
+          return { handled: true };
+        }
+        if (event.type === "press") {
+          latchedId = undefined;
+          if (detail) return undefined;
+          if (event.button !== "left") return undefined;
+          const tasks = filtered();
+          const start = ensureListWindow(tasks);
+          const index = (event.y ?? -1) - 2 + start;
+          const task = tasks[index];
+          if (!task) return undefined;
+          latchedId = task.taskId;
+          return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left" || detail) return undefined;
+        const tasks = filtered();
+        const start = ensureListWindow(tasks);
+        const index = (event.y ?? -1) - 2 + start;
+        const task = tasks[index];
+        if (!latchedId || !task || task.taskId !== latchedId) { latchedId = undefined; return undefined; }
+        selected = latchedId;
+        detail = true;
+        scroll = 0;
+        follow = true;
+        actionError = undefined;
+        latchedId = undefined;
+        requestRender();
+        return { handled: true };
+      },
+      dispose(): void { void width; },
+    };
+  };
+  // Required full-screen overlay geometry. custom() resolves undefined outside supported TUI contexts.
+  // The RPC peer's custom() returns a Promise even though the overlay is unavailable there; mode guards above prevent invocation.
+  void custom(factory, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", row: 0, col: 0 } }).catch(() => undefined);
+}

package/src/tui/rail.ts

@@ -0,0 +1,206 @@
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import type { TaskSnapshot } from "../core/task.ts";
+import { visibleText } from "../core/output.ts";
+import { formatDuration } from "../core/duration.ts";
+import { envNumber } from "../core/env.ts";
+import { truncateToWidth } from "./width.ts";
+import type { TUI, TuiMouseEvent } from "@earendil-works/pi-tui";
+import { openPanel } from "./panel.ts";
+import { tuiHost } from "./host.ts";
+
+type Theme = { fg(color: string, text: string): string; getFgAnsi?(color: string): string };
+export interface RailWidget {
+  render(width?: number): string[];
+  handleMouse(event: TuiMouseEvent): { handled: boolean } | undefined;
+  handleInput?(data: string): { handled?: boolean } | void;
+  dispose?(): void;
+}
+
+/** Palette color selection adapted from legion-viz/palette.ts (MIT License). */
+const TYPE_TOKENS = ["syntaxVariable", "syntaxKeyword", "syntaxNumber", "syntaxFunction", "syntaxString", "syntaxType"];
+type Swatch = { kind: "rgb"; l: number; a: number; b: number } | { kind: "key"; key: string };
+function ansiFor(theme: Theme, token: string): string {
+  // SAFETY: The peer theme exposes fg(); getFgAnsi is feature-detected for newer TUI versions.
+  const color = theme as Theme;
+  try { return color.getFgAnsi?.(token) ?? color.fg(token, "\0").split("\0")[0] ?? token; } catch { return token; }
+}
+function oklab(r: number, g: number, b: number): Swatch {
+  const linear = (n: number): number => { const v = n / 255; return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+  const R = linear(r), G = linear(g), B = linear(b);
+  const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
+  const m = Math.cbrt(0.2119034708 * R + 0.6806995451 * G + 0.1073969566 * B);
+  const s = Math.cbrt(0.0883024619 * R + 0.281718565 * G + 0.6299787005 * B);
+  return { kind: "rgb", l: 0.2104542553*l + 0.793617785*m - 0.0040720468*s, a: 1.9779984951*l - 2.428592205*m + 0.4505937099*s, b: 0.0259040371*l + 0.7827717662*m - 0.808675766*s };
+}
+function swatch(theme: Theme, token: string): Swatch {
+  const ansi = ansiFor(theme, token);
+  const rgb = /38;2;(\d+);(\d+);(\d+)/.exec(ansi);
+  if (rgb) return oklab(Number(rgb[1]), Number(rgb[2]), Number(rgb[3]));
+  const index = /38;5;(\d+)/.exec(ansi);
+  if (index) {
+    const n = Number(index[1]);
+    if (n >= 232) { const v = 8 + 10 * (n - 232); return oklab(v, v, v); }
+    if (n >= 16) { const i = n - 16, step = [0, 95, 135, 175, 215, 255]; return oklab(step[Math.floor(i / 36)]!, step[Math.floor(i / 6) % 6]!, step[i % 6]!); }
+    return { kind: "key", key: `p${n}` };
+  }
+  const basic = /(?:^|\[|;)(3[0-7]|9[0-7])m/.exec(ansi);
+  return { kind: "key", key: basic?.[1] ?? ansi };
+}
+function clashes(a: Swatch, b: Swatch): boolean {
+  if (a.kind === "key" && b.kind === "key") return a.key === b.key;
+  if (a.kind === "key" || b.kind === "key") return false;
+  return Math.hypot(a.l - b.l, a.a - b.a, a.b - b.b) < 0.025;
+}
+function typeColor(theme: Theme, mode: string, used: Swatch[]): string {
+  const modeIndex = ["background", "sync", "delayed"].indexOf(mode);
+  const preferred = TYPE_TOKENS[modeIndex < 0 ? 0 : modeIndex]!;
+  for (const token of [preferred, ...TYPE_TOKENS]) {
+    const color = swatch(theme, token);
+    if (!used.some((previous) => clashes(color, previous))) { used.push(color); return token; }
+  }
+  return preferred;
+}
+
+const statePriority: Record<TaskSnapshot["status"], number> = { running: 0, pending: 1, completed: 2, failed: 3, killed: 4 };
+/** Alias for tests / callers still importing elapsed; single source is core/duration. */
+export { formatDuration as elapsed };
+/** Fit a row to at most `width` code points; never exceed the budget (empty when width<=0). */
+/** Truncate a rail row by terminal cell width (CJK/emoji-aware via #7). */
+export function fitRailRow(row: string, width: number): string {
+  return truncateToWidth(row, Math.max(0, Math.floor(width)));
+}
+
+/** Pure, unstyled rail rows; active tasks first and a hard ten-row limit. */
+export function renderRailRows(snapshots: TaskSnapshot[], width: number, now = Date.now()): string[] {
+  const rows = snapshots
+    .slice().sort((a, b) => statePriority[a.status] - statePriority[b.status] || (b.startedAt ?? b.createdAt) - (a.startedAt ?? a.createdAt))
+    .slice(0, 10)
+    .map((task) => `▶ ${visibleText(task.name)} · ${task.status} · ${formatDuration(task, now)}`);
+  const limit = Math.max(0, Math.floor(width));
+  return rows.map((row) => truncateToWidth(row, limit));
+}
+
+/** Terminal-task linger window on the rail, overridable for tests. */
+function lingerMsFromEnv(): number {
+  return envNumber("PI_ASYNC_RAIL_LINGER_MS", 30_000, { integer: true, min: 0 });
+}
+
+const RAIL_PAGE = 5;
+
+export function createRailFactory(pi: PiCtx, registry: TaskRegistry, opts: { onOpenTask?: (taskId: string) => void } = {}): (tui: TUI, theme: Theme) => RailWidget {
+  // Factory signature includes the extension context for future host-specific rail integrations.
+  void pi;
+  return (tui, theme) => {
+    let scroll = 0;
+    let hitRows: string[] = [];
+    let latchedId: string | undefined;
+    // Terminal tasks linger briefly so the user sees the outcome, then drop off
+    // the rail (CONTRACT §8: idle sessions render nothing). Live tasks always show.
+    const lingerMs = lingerMsFromEnv();
+    const ordered = (now = Date.now()): TaskSnapshot[] => registry.list({ includeHistory: true })
+      .filter((task) => task.status === "running" || task.status === "pending"
+        || (now - (task.finishedAt ?? task.startedAt ?? task.createdAt)) < lingerMs)
+      .sort((a, b) => statePriority[a.status] - statePriority[b.status] || (b.startedAt ?? b.createdAt) - (a.startedAt ?? a.createdAt));
+    const clampScroll = (count: number, taskSlots: number): void => {
+      scroll = Math.max(0, Math.min(scroll, Math.max(0, count - taskSlots)));
+    };
+    const applyScroll = (delta: number): boolean => {
+      const count = ordered().length;
+      if (count <= 10) return false;
+      const taskSlots = 9; // reserve one row for the overflow indicator
+      const next = Math.max(0, Math.min(count - taskSlots, scroll + delta));
+      if (next === scroll) return false;
+      scroll = next;
+      latchedId = undefined;
+      tui.requestRender();
+      return true;
+    };
+    const render = (width = 120): string[] => {
+      const tasks = ordered();
+      const overflow = tasks.length > 10;
+      // Reserve one of the ≤10 rows for the overflow indicator when needed.
+      const taskSlots = overflow ? 9 : 10;
+      clampScroll(tasks.length, taskSlots);
+      const visible = tasks.slice(scroll, scroll + taskSlots);
+      hitRows = visible.map((task) => task.taskId);
+      const used = [swatch(theme, "error"), swatch(theme, "dim")];
+      const rows = renderRailRows(visible, width).map((row, index) => {
+        const task = visible[index];
+        if (!task) return row;
+        let token = "dim";
+        if (task.status === "running") token = typeColor(theme, task.mode, used);
+        else if (task.status === "completed") token = "success";
+        else if (task.status === "failed") token = "error";
+        try {
+          return theme.fg(token, row) ?? row;
+        } catch {
+          return row;
+        }
+      });
+      if (overflow) {
+        const hidden = tasks.length - visible.length;
+        const above = scroll;
+        const below = Math.max(0, tasks.length - scroll - visible.length);
+        const label = above > 0 && below > 0
+          ? `… +${hidden} more (↑${above} ↓${below})`
+          : above > 0
+            ? `… +${above} more ↑`
+            : `… +${below} more`;
+        const indicator = fitRailRow(label, width);
+        try {
+          rows.push(theme.fg("dim", indicator) ?? indicator);
+        } catch {
+          rows.push(indicator);
+        }
+        hitRows.push(""); // overflow row is not a task hit target
+      }
+      return rows;
+    };
+    return {
+      render,
+      handleInput(data: string): { handled?: boolean } | void {
+        // PageUp / PageDown, and Ctrl+↑ / Ctrl+↓ when the rail has focus.
+        if (data === "\u001b[5~" || data === "\u001b[1;5A") {
+          return applyScroll(-RAIL_PAGE) ? { handled: true } : undefined;
+        }
+        if (data === "\u001b[6~" || data === "\u001b[1;5B") {
+          return applyScroll(RAIL_PAGE) ? { handled: true } : undefined;
+        }
+        return undefined;
+      },
+      handleMouse(event: TuiMouseEvent): { handled: boolean } | undefined {
+        const mouse = event as TuiMouseEvent & { type: string; y: number; button?: string; wheelDelta?: number };
+        if (mouse.type === "wheel") {
+          const count = ordered().length;
+          if (count <= 10) return undefined;
+          const taskSlots = 9;
+          const next = Math.max(0, Math.min(count - taskSlots, scroll + Math.trunc(mouse.wheelDelta ?? 0)));
+          if (next === scroll) return undefined;
+          scroll = next; latchedId = undefined; tui.requestRender(); return { handled: true };
+        }
+        if (mouse.type === "press") {
+          latchedId = undefined;
+          if (mouse.button !== "left") return undefined;
+          const id = hitRows[mouse.y];
+          if (!id) return undefined;
+          latchedId = id; return { handled: true };
+        }
+        if (mouse.type !== "click" || mouse.button !== "left") return undefined;
+        const id = hitRows[mouse.y];
+        if (!latchedId || id !== latchedId) { latchedId = undefined; return undefined; }
+        const clicked = latchedId; latchedId = undefined; opts.onOpenTask?.(clicked); return { handled: true };
+      },
+      dispose(): void { latchedId = undefined; },
+    };
+  };
+}
+
+/** The sole rail widget registration point. */
+export function registerRail(pi: PiCtx, registry: TaskRegistry): void {
+  // TUI surfaces bind from event contexts; the factory API has no mode/ui.
+  const bound = tuiHost();
+  if (!bound) return;
+  const setWidget = bound.ui["setWidget"] as ((key: string, factory: ReturnType<typeof createRailFactory> | undefined, options?: { placement: "aboveEditor" }) => void) | undefined;
+  setWidget?.("pi-async-rail", createRailFactory(pi, registry, { onOpenTask: (id) => openPanel(pi, registry, id) }), { placement: "aboveEditor" });
+}