pi-jar 0.1.0

package/src/prompt-search.ts

@@ -0,0 +1,83 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { fuzzyFilter, Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { cleanText } from "./status.ts";
+
+export interface PastPrompt { text: string; source: "this session" | "earlier session"; at?: number }
+
+const userText = (message: { content?: unknown }) => typeof message.content === "string" ? message.content
+  : Array.isArray(message.content) ? message.content.filter((part: { type?: string }) => part?.type === "text").map((part: { text?: string }) => part.text ?? "").join("\n") : "";
+
+/**
+ * Prompts newest first and deduplicated: every user message in this session file (all branches),
+ * then the opening prompt of earlier sessions for the project.
+ */
+export function collectPrompts(entries: readonly unknown[], earlier: readonly { firstMessage?: string; modified?: Date }[] = []): PastPrompt[] {
+  const seen = new Set<string>();
+  const result: PastPrompt[] = [];
+  const add = (text: string, source: PastPrompt["source"], at?: number) => {
+    const value = text.trim();
+    const key = value.replace(/\s+/g, " ");
+    if (!value || value.length > 8000 || seen.has(key)) return;
+    seen.add(key);
+    result.push({ text: value, source, ...(at ? { at } : {}) });
+  };
+  const own = entries.filter((raw): raw is { type: string; message: { role: string; content?: unknown }; timestamp?: string } =>
+    !!raw && typeof raw === "object" && (raw as { type?: string }).type === "message" && (raw as { message?: { role?: string } }).message?.role === "user");
+  for (const entry of [...own].reverse()) add(userText(entry.message), "this session", entry.timestamp ? Date.parse(entry.timestamp) : undefined);
+  for (const session of earlier) if (session.firstMessage) add(session.firstMessage, "earlier session", session.modified?.getTime());
+  return result;
+}
+
+/** Type to fuzzy-filter past prompts; Enter puts the selection in the composer for editing. */
+export async function openPromptSearch(ctx: ExtensionContext, prompts: readonly PastPrompt[]): Promise<string | undefined> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return undefined;
+  if (!prompts.length) { ctx.ui.notify("pi-jar: no earlier prompts yet", "info"); return undefined; }
+  return ctx.ui.custom<string | undefined>((tui, theme, _keys, done) => {
+    let query = "";
+    let selected = 0;
+    let first = 0;
+    let visible: PastPrompt[] = [...prompts];
+    const rows = 10;
+    const filter = () => { visible = query ? fuzzyFilter([...prompts], query, (item) => item.text) : [...prompts]; selected = 0; first = 0; };
+    return {
+      invalidate() {},
+      handleInput(data: string) {
+        if (matchesKey(data, Key.escape)) return done(undefined);
+        if (matchesKey(data, Key.enter)) return done(visible[selected]?.text);
+        if (matchesKey(data, Key.up) || matchesKey(data, Key.ctrl("p"))) selected = Math.max(0, selected - 1);
+        else if (matchesKey(data, Key.down) || matchesKey(data, Key.ctrl("n"))) selected = Math.min(visible.length - 1, selected + 1);
+        else if (matchesKey(data, Key.backspace)) { query = [...query].slice(0, -1).join(""); filter(); }
+        else if (matchesKey(data, Key.ctrl("u"))) { query = ""; filter(); }
+        else if (data.length >= 1 && !data.startsWith("\x1b") && !/[\x00-\x1f\x7f]/.test(data)) { query += data; filter(); }
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type === "wheel" && event.wheelDelta) { selected = Math.max(0, Math.min(visible.length - 1, selected + Math.sign(event.wheelDelta))); tui.requestRender(); return { handled: true }; }
+        if (event.type !== "click" || event.button !== "left") return;
+        const index = first + event.y - 2;
+        if (event.y >= 2 && event.y < 2 + rows && visible[index]) { done(visible[index]!.text); return { handled: true }; }
+      },
+      render(width: number): string[] {
+        const w = Math.max(20, width);
+        const inner = w - 4;
+        if (selected < first) first = selected;
+        if (selected >= first + rows) first = selected - rows + 1;
+        const fit = (text: string) => { const value = truncateToWidth(text, inner); return value + " ".repeat(Math.max(0, inner - visibleWidth(value))); };
+        const dim = (text: string) => theme.fg("dim", text);
+        const lines = [
+          theme.fg("accent", "╭─ ⌕ PROMPT HISTORY ") + dim("─".repeat(Math.max(0, w - 21)) + "╮"),
+          dim("│ ") + fit(theme.fg("accent", "› ") + query + "\x1b[7m \x1b[0m" + dim(`  ${visible.length}/${prompts.length}`)) + dim(" │")
+        ];
+        for (let row = 0; row < rows; row++) {
+          const item = visible[first + row];
+          const active = first + row === selected;
+          const text = item ? (active ? "❯ " : "  ") + cleanText(item.text, 400) : "";
+          const tag = item?.source === "earlier session" ? dim(" · earlier") : "";
+          lines.push(dim("│ ") + fit(item ? theme.fg(active ? "accent" : "muted", truncateToWidth(text, Math.max(4, inner - 10))) + tag : "") + dim(" │"));
+        }
+        lines.push(dim("╰─ type to filter · ↑↓ select · Enter edit · Esc close " + "─".repeat(Math.max(0, w - 57)) + "╯"));
+        return lines.map((line) => truncateToWidth(line, w));
+      }
+    };
+  }, { overlay: true, overlayOptions: { width: "80%", maxHeight: "60%" } });
+}

package/src/quota.ts

@@ -0,0 +1,134 @@
+export type QuotaProvider = "openai-codex" | "anthropic";
+export interface QuotaWindow { used: number; resetsAt?: number }
+export interface Quota { fiveHour?: QuotaWindow; week?: QuotaWindow }
+
+export const QUOTA_TTL_MS = 5 * 60_000;
+export const QUOTA_PREFIX = "pi-jar.quota.";
+
+function windowValue(value: unknown): QuotaWindow | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const item = value as Record<string, unknown>;
+  if (typeof item.used !== "number" || !Number.isFinite(item.used) || item.used < 0 || item.used > 100) return undefined;
+  return { used: item.used, ...(typeof item.resetsAt === "number" && Number.isFinite(item.resetsAt) ? { resetsAt: item.resetsAt } : {}) };
+}
+
+function parseQuota(value: unknown): Quota | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const object = value as Record<string, unknown>;
+  const fiveHour = windowValue(object.fiveHour);
+  const week = windowValue(object.week);
+  return fiveHour || week ? { ...(fiveHour ? { fiveHour } : {}), ...(week ? { week } : {}) } : undefined;
+}
+
+/** Public statuses are authoritative only when valid and fresh. No arbitrary status prose is parsed. */
+export function publishedQuota(statuses: ReadonlyMap<string, string>, provider: string, now: number): Quota | undefined {
+  const raw = statuses.get(QUOTA_PREFIX + provider);
+  if (typeof raw !== "string" || raw.length > 2048) return undefined;
+  try {
+    const data: unknown = JSON.parse(raw);
+    if (!data || typeof data !== "object") return undefined;
+    const obj = data as Record<string, unknown>;
+    if (typeof obj.expiresAt !== "number" || obj.expiresAt <= now || obj.expiresAt > now + QUOTA_TTL_MS) return undefined;
+    return parseQuota(obj);
+  } catch { return undefined; }
+}
+
+function codexAccountId(token: string): string | undefined {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload) return undefined;
+    const claims: unknown = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (!claims || typeof claims !== "object") return undefined;
+    const auth = (claims as Record<string, unknown>)["https://api.openai.com/auth"];
+    const id = auth && typeof auth === "object" ? (auth as Record<string, unknown>).chatgpt_account_id : undefined;
+    return typeof id === "string" && id.length > 0 ? id : undefined;
+  } catch { return undefined; }
+}
+
+/** Never persist credentials; resolve through Pi's public model registry only on explicit opt-in. */
+export async function fetchQuota(provider: QuotaProvider, resolveAuth: (provider: string) => Promise<{ auth: { apiKey?: string }; source?: string } | undefined>, signal: AbortSignal): Promise<Quota | undefined> {
+  try {
+    const resolved = await resolveAuth(provider);
+    if (signal.aborted || !resolved?.source?.toLowerCase().includes("oauth") || !resolved.auth.apiKey) return undefined;
+    const token = resolved.auth.apiKey;
+    const headers: Record<string, string> = { Authorization: `Bearer ${token}`, Accept: "application/json" };
+    let url: string;
+    if (provider === "openai-codex") {
+      const id = codexAccountId(token);
+      if (!id) return undefined;
+      headers["ChatGPT-Account-Id"] = id;
+      url = "https://chatgpt.com/backend-api/wham/usage";
+    } else {
+      headers["anthropic-beta"] = "oauth-2025-04-20";
+      url = "https://api.anthropic.com/api/oauth/usage";
+    }
+    const response = await fetch(url, { method: "GET", headers, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) });
+    if (!response.ok) return undefined;
+    const data: unknown = await response.json();
+    if (!data || typeof data !== "object") return undefined;
+    const body = data as Record<string, unknown>;
+    if (provider === "openai-codex") {
+      const rate = body.rate_limit && typeof body.rate_limit === "object" ? body.rate_limit as Record<string, unknown> : {};
+      const parse = (window: unknown): QuotaWindow | undefined => {
+        if (!window || typeof window !== "object") return undefined;
+        const item = window as Record<string, unknown>;
+        return windowValue({ used: item.used_percent, resetsAt: typeof item.reset_at === "number" ? item.reset_at * 1000 : undefined });
+      };
+      return parseQuota({ fiveHour: parse(rate.primary_window), week: parse(rate.secondary_window) });
+    }
+    const parse = (window: unknown): QuotaWindow | undefined => {
+      if (!window || typeof window !== "object") return undefined;
+      const item = window as Record<string, unknown>;
+      const utilization = item.utilization;
+      const resetsAt = typeof item.resets_at === "string" ? Date.parse(item.resets_at) : undefined;
+      return windowValue({ used: typeof utilization === "number" && utilization <= 1 ? utilization * 100 : utilization, resetsAt });
+    };
+    return parseQuota({ fiveHour: parse(body.five_hour), week: parse(body.seven_day) });
+  } catch { return undefined; }
+}
+
+/** One in-flight request per provider, negative-cache failures, never show expired values. */
+export class QuotaCache {
+  private entries = new Map<QuotaProvider, { value?: Quota; expiresAt: number }>();
+  private pending = new Map<QuotaProvider, AbortController>();
+  enabled = false;
+  private readonly fetcher: (provider: QuotaProvider, signal: AbortSignal) => Promise<Quota | undefined>;
+  private readonly changed: () => void;
+  constructor(fetcher: (provider: QuotaProvider, signal: AbortSignal) => Promise<Quota | undefined>, changed: () => void) {
+    this.fetcher = fetcher;
+    this.changed = changed;
+  }
+  get(provider: string | undefined, statuses: ReadonlyMap<string, string>, now: number): Quota | undefined {
+    if (provider !== "openai-codex" && provider !== "anthropic") return undefined;
+    const published = publishedQuota(statuses, provider, now);
+    if (published) {
+      this.pending.get(provider)?.abort();
+      this.pending.delete(provider);
+      return published;
+    }
+    if (!this.enabled) return undefined;
+    const cached = this.entries.get(provider);
+    if (cached && cached.expiresAt > now) return cached.value;
+    if (!this.pending.has(provider)) {
+      const controller = new AbortController();
+      this.pending.set(provider, controller);
+      // A microtask keeps IO outside the synchronous render cycle.
+      queueMicrotask(() => {
+        if (controller.signal.aborted) {
+          if (this.pending.get(provider) === controller) this.pending.delete(provider);
+          return;
+        }
+        void this.fetcher(provider, controller.signal).then((value) => {
+          if (!controller.signal.aborted) {
+            this.entries.set(provider, { value, expiresAt: Date.now() + QUOTA_TTL_MS });
+            this.changed();
+          }
+        }).catch(() => {}).finally(() => {
+          if (this.pending.get(provider) === controller) this.pending.delete(provider);
+        });
+      });
+    }
+    return undefined;
+  }
+  stop(): void { for (const controller of this.pending.values()) controller.abort(); this.pending.clear(); this.entries.clear(); }
+}

package/src/roles-ui.ts

@@ -0,0 +1,190 @@
+import type { ExtensionContext, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, stripTerminalSequences, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { promptText } from "./dialogs.ts";
+import { isRoleName, normalizeSpec, THINKING, type ModelRoleManager, type RoleRow } from "./model-roles.ts";
+import { contentRows, optionList, sidebarWidth, splitFrame } from "./split-view.ts";
+
+type RoleAction = "model" | "alias" | "thinking" | "scope" | "activate" | "clear" | "new" | "delete";
+const ACTIONS: { action: RoleAction; key: string; hint: string; label: string }[] = [
+  { action: "activate", key: "\r", hint: "⏎", label: "Activate this role now" },
+  { action: "model", key: "m", hint: "m", label: "Assign a model" },
+  { action: "alias", key: "a", hint: "a", label: "Alias another role (@role)" },
+  { action: "thinking", key: "t", hint: "t", label: "Set thinking effort" },
+  { action: "scope", key: "s", hint: "s", label: "Move between global and project" },
+  { action: "clear", key: "c", hint: "c", label: "Clear the assignment" },
+  { action: "new", key: "n", hint: "n", label: "New custom role" },
+  { action: "delete", key: "d", hint: "d", label: "Delete this custom role" }
+];
+
+function detail(row: RoleRow, active: string | undefined): [ThemeColor, string][] {
+  const target: [ThemeColor, string] = row.error ? ["error", "⚠ " + row.error]
+    : row.resolved ? ["accent", row.resolved.provider + "/" + row.resolved.model] : ["dim", "follows the current model"];
+  return [
+    ["accent", row.label + (row.custom ? "  (custom role)" : "")],
+    ["dim", ""],
+    ["muted", "Role      " + row.role + (active === row.role ? "  ● active" : "")],
+    ["muted", "Used by   " + (row.usedBy ?? "your prompts and other extensions")],
+    ["muted", "Spec      " + (row.spec ?? "—")],
+    [target[0], "Model     " + target[1]],
+    ["muted", "Alias     " + (row.resolved && row.resolved.via.length > 1 ? row.resolved.via.join(" → ") : "—")],
+    ["muted", "Effort    " + (row.resolved?.thinking ?? "follow current")],
+    ["muted", "Scope     " + (row.scope ?? "unset") + (row.scope === "project" ? "  (.pi/pi-jar-roles.json)" : row.scope === "global" ? "  (agent dir)" : "")],
+    ["dim", ""],
+    ["dim", "Specs: provider/model[:effort] · @role[:effort] · *"],
+    ["dim", "Project assignments override global ones."]
+  ];
+}
+
+async function roleScreen(ctx: ExtensionContext, roles: ModelRoleManager, initial: number): Promise<{ action: RoleAction; index: number } | undefined> {
+  return ctx.ui.custom<{ action: RoleAction; index: number } | undefined>((tui, theme, _keys, done) => {
+    let selected = initial;
+    let scroll = 0;
+    let layout = { top: 1, rows: 0, leftWidth: 0, bodyX: 2, footerTop: 0 };
+    let width = 80;
+    let actionsTop = -1;
+    const rows = () => roles.list();
+    const finish = (action: RoleAction) => done({ action, index: selected });
+    return {
+      invalidate() {},
+      handleInput(data: string) {
+        const count = rows().length;
+        if (matchesKey(data, Key.escape) || data === "q") return done(undefined);
+        if (matchesKey(data, Key.up) || data === "k") selected = (selected + count - 1) % count;
+        else if (matchesKey(data, Key.down) || data === "j") selected = (selected + 1) % count;
+        else if (matchesKey(data, Key.enter)) return finish("activate");
+        else {
+          const hit = ACTIONS.find((item) => item.key === data);
+          if (hit) return finish(hit.action);
+        }
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        const count = rows().length;
+        if (event.type === "wheel" && event.wheelDelta) {
+          selected = Math.max(0, Math.min(count - 1, selected + Math.sign(event.wheelDelta)));
+          tui.requestRender(); return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left") return;
+        if (event.y === 0 && event.x >= width - 3) { done(undefined); return { handled: true }; }
+        const row = event.y - layout.top;
+        // Actions are listed in the detail pane, one per row.
+        const actionIndex = row - actionsTop;
+        if (row >= 0 && row < layout.rows && event.x >= layout.bodyX && actionIndex >= 0 && actionIndex < ACTIONS.length) {
+          finish(ACTIONS[actionIndex]!.action); return { handled: true };
+        }
+        if (row >= 0 && row < layout.rows && (layout.leftWidth === 0 || event.x < layout.leftWidth + 3)) {
+          const index = scroll + row;
+          if (index < count) { selected = index; tui.requestRender(); return { handled: true, focus: true }; }
+        }
+      },
+      render(available: number): string[] {
+        width = Math.max(24, available);
+        const list = rows();
+        selected = Math.max(0, Math.min(list.length - 1, selected));
+        const height = Math.min(contentRows(5, 8), Math.max(12 + ACTIONS.length + 2, list.length));
+        if (selected < scroll) scroll = selected;
+        if (selected >= scroll + height) scroll = selected - height + 1;
+        const active = roles.activeRole();
+        const left = list.slice(scroll, scroll + height).map((row, index) => {
+          const current = scroll + index === selected;
+          const mark = row.error ? "⚠" : row.resolved ? "●" : "○";
+          return theme.fg(current ? "accent" : row.resolved ? "muted" : "dim", (current ? "❯ " : "  ") + mark + " " + row.role + (active === row.role ? " *" : ""));
+        });
+        const row = list[selected]!;
+        const info = detail(row, active).map(([color, text]) => theme.fg(color, text));
+        // Narrow terminals collapse the sidebar into a pager header above the details.
+        const narrow = sidebarWidth(width) === 0;
+        const header = narrow ? [theme.fg("accent", `‹ ${selected + 1}/${list.length} ${row.role} ›`)] : [];
+        const actions = optionList(theme, ACTIONS.map((item) => item.label), -1, ACTIONS.map((item) => item.hint))
+          .map((line, at) => ACTIONS[at]!.action === "delete" && !row.custom ? theme.fg("dim", stripTerminalSequences(line)) : line);
+        // Actions come right after the facts; the spec help (last three lines) goes last.
+        const facts = info.slice(0, -3), help = info.slice(-3);
+        const body = [...header, ...facts, theme.fg("accent", "Actions"), ...actions, ...help];
+        actionsTop = header.length + facts.length + 1;
+        const split = splitFrame(theme, width, "pi-jar · roles", narrow ? [] : left, body, [
+          theme.fg("dim", "↑↓ choose role · press a key or click an action · Esc close")
+        ], height);
+        layout = split.layout;
+        return split.lines;
+      }
+    };
+  }, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%" } });
+}
+
+/** Keyboard- and pointer-driven model role manager. */
+export async function openRolesUi(ctx: ExtensionContext, roles: ModelRoleManager): Promise<void> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return;
+  let index = 0;
+  while (true) {
+    const result = await roleScreen(ctx, roles, index);
+    if (!result) return;
+    index = result.index;
+    const row = roles.list()[index];
+    if (!row) return;
+    try {
+      await applyAction(ctx, roles, row, result.action, (next) => { index = next; });
+    } catch (error) {
+      ctx.ui.notify("Role change failed: " + (error as Error).message, "error");
+    }
+  }
+}
+
+async function applyAction(ctx: ExtensionContext, roles: ModelRoleManager, row: RoleRow, action: RoleAction, select: (index: number) => void): Promise<void> {
+  const scope = row.scope ?? "global";
+  const effort = () => {
+    const spec = row.spec ?? "";
+    const colon = spec.lastIndexOf(":");
+    return colon > 0 && THINKING.includes(spec.slice(colon + 1) as never) ? spec.slice(colon) : "";
+  };
+  const base = () => {
+    const spec = row.spec ?? "";
+    return effort() ? spec.slice(0, spec.length - effort().length) : spec;
+  };
+  switch (action) {
+    case "model": {
+      const models = ctx.modelRegistry.getAvailable().slice().sort((a, b) => (a.provider + "/" + a.id).localeCompare(b.provider + "/" + b.id));
+      if (!models.length) { ctx.ui.notify("No authenticated models are currently available", "warning"); return; }
+      const labels = models.map((model) => model.provider + "/" + model.id);
+      const selected = await ctx.ui.select("Model for " + row.role, labels);
+      if (selected) roles.update(row.role, selected + effort(), scope);
+      return;
+    }
+    case "alias": {
+      const targets = roles.list().filter((item) => item.role !== row.role).map((item) => "@" + item.role);
+      const selected = await ctx.ui.select("Alias " + row.role + " to", targets);
+      if (selected) roles.update(row.role, selected + effort(), scope);
+      return;
+    }
+    case "thinking": {
+      if (!row.spec) { ctx.ui.notify("Assign a model or alias first", "warning"); return; }
+      const selected = await ctx.ui.select("Thinking effort for " + row.role, ["follow current", ...THINKING]);
+      if (selected) roles.update(row.role, base() + (selected === "follow current" ? "" : ":" + selected), scope);
+      return;
+    }
+    case "scope": {
+      if (!row.spec) { ctx.ui.notify("Assign the role before moving it between scopes", "warning"); return; }
+      const next = scope === "global" ? "project" : "global";
+      roles.update(row.role, row.spec, next);
+      roles.update(row.role, undefined, scope);
+      ctx.ui.notify(`Role ${row.role} moved to ${next} scope`, "info");
+      return;
+    }
+    case "activate": await roles.activate(row.role, ctx); return;
+    case "clear": if (row.spec) roles.update(row.role, undefined, scope); return;
+    case "new": {
+      const name = (await promptText(ctx, "New role", "Role name (lowercase, e.g. review)"))?.toLowerCase();
+      if (!name) return;
+      if (!isRoleName(name)) { ctx.ui.notify("Role names use a-z, 0-9 and -, starting with a letter", "warning"); return; }
+      const spec = await promptText(ctx, "Role target", "provider/model[:effort] or @role", "@default");
+      if (!spec || !normalizeSpec(spec)) { ctx.ui.notify("Invalid role target", "warning"); return; }
+      roles.update(name, spec, "global");
+      select(roles.list().findIndex((item) => item.role === name));
+      return;
+    }
+    case "delete":
+      if (!row.custom) { ctx.ui.notify("Built-in roles can be cleared, not deleted", "info"); return; }
+      roles.update(row.role, undefined, scope);
+      select(0);
+      return;
+  }
+}

package/src/roles.ts

@@ -0,0 +1,25 @@
+export type RoleState =
+  | "idle"
+  | "thinking"
+  | "working"
+  | "waiting"
+  | "reviewing"
+  | "done"
+  | "failed";
+
+export interface RoleStatus {
+  id: string;
+  label: string;
+  name: string;
+  state: RoleState;
+  task?: string;
+}
+
+/** Sample data only. Live teammates are supplied by external publishers, not by this list. */
+export function createDemoRoles(): RoleStatus[] {
+  return [
+    { id: "explorer", label: "EXP", name: "Explorer", state: "thinking", task: "analyze" },
+    { id: "builder", label: "BLD", name: "Builder", state: "working", task: "implement" },
+    { id: "reviewer", label: "REV", name: "Reviewer", state: "waiting", task: "waiting" }
+  ];
+}

package/src/session-gallery.ts

@@ -0,0 +1,52 @@
+import { readFile, stat } from "node:fs/promises";
+import type { SessionInfo } from "@earendil-works/pi-coding-agent";
+import { sessionDisplayName } from "./composer.ts";
+import { GOAL_ENTRY, GoalStore } from "./goals.ts";
+import { cleanText } from "./status.ts";
+
+export const RECENT_SESSIONS = 3;
+/** Larger session files are listed without goal/plan details. */
+const MAX_SCAN_BYTES = 8 * 1024 * 1024;
+
+export interface RecentSession { path: string; title: string; modified: Date; messages: number; goal?: string; plan?: string }
+
+export function ago(date: Date, now = Date.now()): string {
+  const minutes = Math.max(0, Math.floor((now - date.getTime()) / 60_000));
+  if (minutes < 1) return "now";
+  if (minutes < 60) return `${minutes}m`;
+  if (minutes < 60 * 24) return `${Math.round(minutes / 60)}h`;
+  return `${Math.round(minutes / 60 / 24)}d`;
+}
+
+/** Latest goal and plan title recorded by pi-jar in a session file's JSONL. */
+export function sessionWorkflow(jsonl: string): { goal?: string; plan?: string } {
+  const entries: unknown[] = [];
+  let plan: string | undefined;
+  for (const line of jsonl.split("\n")) {
+    if (!line.includes('"pi-jar.')) continue;
+    let entry: { type?: string; customType?: string; data?: { title?: unknown } };
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (entry.type !== "custom") continue;
+    if (entry.customType === GOAL_ENTRY) entries.push(entry);
+    else if (entry.customType === "pi-jar.plan" && typeof entry.data?.title === "string" && entry.data.title.trim()) plan = cleanText(entry.data.title, 60);
+  }
+  const goals = new GoalStore(() => {});
+  goals.restore(entries);
+  const goal = goals.current();
+  return { ...(goal && goal.status !== "dropped" ? { goal: cleanText(goal.text, 60) + (goal.status === "complete" ? " ✔" : goal.status === "paused" ? " (paused)" : "") } : {}),
+    ...(plan ? { plan } : {}) };
+}
+
+/** Most recent sessions for the project other than the current one, with their goal and plan. */
+export async function recentSessions(sessions: readonly SessionInfo[], current: string | undefined, limit = RECENT_SESSIONS,
+  read: (path: string) => Promise<string> = (path) => readFile(path, "utf8"), size: (path: string) => Promise<number> = async (path) => (await stat(path)).size): Promise<RecentSession[]> {
+  const picked = [...sessions].filter((session) => session.path !== current && session.messageCount > 0)
+    .sort((a, b) => b.modified.getTime() - a.modified.getTime()).slice(0, limit);
+  return Promise.all(picked.map(async (session) => {
+    const title = session.name ? cleanText(session.name, 60) : cleanText(session.firstMessage || sessionDisplayName(undefined, session.id), 60);
+    let workflow: { goal?: string; plan?: string } = {};
+    try { if (await size(session.path) <= MAX_SCAN_BYTES) workflow = sessionWorkflow(await read(session.path)); }
+    catch { /* unreadable session: show it without details */ }
+    return { path: session.path, title, modified: session.modified, messages: session.messageCount, ...workflow };
+  }));
+}

package/src/session-ui.ts

@@ -0,0 +1,76 @@
+import type { ExtensionContext, SessionInfo } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { sessionDisplayName } from "./composer.ts";
+import { cleanText } from "./status.ts";
+
+/** Search session titles and first prompts, without exposing raw JSONL contents in the picker. */
+export function filterSessions(sessions: readonly SessionInfo[], query: string): SessionInfo[] {
+  const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  return sessions.filter((session) => {
+    const haystack = `${session.name ?? ""} ${sessionDisplayName(session.name, session.id)} ${session.firstMessage}`.toLowerCase();
+    return terms.every((term) => haystack.includes(term));
+  });
+}
+
+export async function pickSession(ctx: ExtensionContext, sessions: readonly SessionInfo[], initial = ""): Promise<string | undefined> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return undefined;
+  return ctx.ui.custom<string | undefined>((tui, theme, _keys, done) => {
+    let query = initial.slice(0, 100);
+    let selected = 0;
+    let first = 0;
+    let width = 80;
+    const pageSize = () => Math.max(2, Math.min(10, Math.floor(((process.stdout.rows ?? 24) - 7) / 2)));
+    const matches = () => filterSessions(sessions, query);
+    const refresh = () => { selected = 0; first = 0; tui.requestRender(); };
+    return {
+      invalidate() {},
+      handleInput(data: string) {
+        const rows = matches();
+        if (matchesKey(data, Key.escape)) return done(undefined);
+        if (matchesKey(data, Key.enter)) return done(rows[selected]?.path);
+        if (matchesKey(data, Key.up)) selected = Math.max(0, selected - 1);
+        else if (matchesKey(data, Key.down)) selected = Math.min(rows.length - 1, selected + 1);
+        else if (matchesKey(data, Key.pageUp)) selected = Math.max(0, selected - pageSize());
+        else if (matchesKey(data, Key.pageDown)) selected = Math.min(rows.length - 1, selected + pageSize());
+        else if (matchesKey(data, Key.backspace) || data === "\x7f") { query = query.slice(0, -1); return refresh(); }
+        else if (/^[\x20-\x7e]$/.test(data) && query.length < 100) { query += data; return refresh(); }
+        first = Math.max(0, Math.min(selected, first), selected - pageSize() + 1);
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type === "wheel" && event.wheelDelta) {
+          selected = Math.max(0, Math.min(matches().length - 1, selected + Math.sign(event.wheelDelta)));
+          first = Math.max(0, Math.min(selected, first), selected - pageSize() + 1);
+          tui.requestRender(); return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left" || event.x >= width) return;
+        const index = first + Math.floor((event.y - 2) / 2);
+        const row = matches()[index];
+        if (event.y >= 2 && event.y < 2 + 2 * pageSize() && row) {
+          selected = index; done(row.path); return { handled: true };
+        }
+      },
+      render(available: number): string[] {
+        width = Math.max(0, available);
+        const fit = (line: string) => truncateToWidth(line, width);
+        const rows = matches();
+        selected = Math.max(0, Math.min(selected, rows.length - 1));
+        const lines = [
+          fit(theme.fg("accent", `╭─ SESSIONS · ${rows.length}/${sessions.length} ─`)),
+          fit(theme.fg("muted", `│ Search: ${cleanText(query, 100)}${query ? "" : "(type to filter)"}`))
+        ];
+        for (let i = first; i < Math.min(rows.length, first + pageSize()); i++) {
+          const session = rows[i]!;
+          const title = cleanText(sessionDisplayName(session.name, session.id), 55);
+          const prompt = cleanText(session.firstMessage, 90);
+          const when = Number.isNaN(session.modified.getTime()) ? "" : session.modified.toISOString().slice(0, 10);
+          lines.push(fit(theme.fg(i === selected ? "accent" : "muted", `│ ${i === selected ? "❯" : " "} ${title} · ${when}`)));
+          lines.push(fit(theme.fg("dim", `│     ${prompt || "No first prompt"}`)));
+        }
+        if (!rows.length) lines.push(fit(theme.fg("dim", "│ No matching sessions")));
+        lines.push(fit(theme.fg("dim", "╰─ Type to search · ↑↓/PgUp/PgDn select · Enter resume · Esc cancel")));
+        return lines;
+      }
+    };
+  });
+}