my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-tui/src/main.ts

@@ -0,0 +1,122 @@
+// dpi-tui: a pi-like terminal client for one Durable Agent Network device.
+//   dpi-tui <device>[:<session>[:<agent>]]        device from ~/.dpi/network.sqlite (seeded from dpi-network.yaml)
+//   dpi-tui --url <url> --token <token> [--save <id>]
+//   dpi-tui mac-mini --new triage                 create a session (in the device's first start dir) and attach
+import { parseArgs } from "node:util";
+import { DpiClient } from "../../dpi-sdk/src/client.ts";
+import { isDpiError } from "../../dpi-sdk/src/errors.ts";
+import { NetworkRegistry } from "../../dpi-sdk/src/node/registry.ts";
+import { syncConfigToRegistry, tryLoadNetworkConfig } from "../../dpi-sdk/src/node/config.ts";
+import { App, type DeviceRef } from "./app.ts";
+
+const USAGE = `usage: dpi-tui <device>[:<session>[:<agent>]] [options]
+       dpi-tui --url <url> --token <token> [--save <id>]
+
+  -s, --session <ref>   session id or name (else a picker opens)
+  -a, --agent <ref>     agent id, "main" or name (default: the session's root agent)
+  --new <name>          create a session on the device and attach
+  --cwd <dir>           working directory on the device for --new (absolute, or relative to its first start dir)
+  --model <id>          model for --new (default: the device's default)
+  --pair <CODE|URL>     pair THIS device's local backend with a hub before the UI opens
+  --hub <origin>        hub origin for --pair (else the code's pair URL)
+  --force               with --pair: switch hubs even if already paired
+  --url, --token        connect to any dpi-backend directly (also DPI_URL, DPI_TOKEN)
+  --save <id>           store a --url device in ~/.dpi/network.sqlite under <id>`;
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    url: { type: "string" },
+    token: { type: "string" },
+    save: { type: "string" },
+    session: { type: "string", short: "s" },
+    agent: { type: "string", short: "a" },
+    new: { type: "string" },
+    cwd: { type: "string" },
+    model: { type: "string" },
+    pair: { type: "string" },
+    hub: { type: "string" },
+    force: { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+if (values.help) {
+  process.stdout.write(`${USAGE}\n`);
+  process.exit(0);
+}
+
+const registry = new NetworkRegistry();
+const config = tryLoadNetworkConfig(process.env.INIT_CWD ?? process.cwd());
+if (config) syncConfigToRegistry(config, registry);
+
+const url = values.url ?? process.env.DPI_URL;
+const [deviceRef = "", sessionRef = values.session, agentRef = values.agent] = (
+  positionals[0] ?? (url ? "" : (process.env.DPI_DEVICE ?? ""))
+).split(":");
+
+let device: DeviceRef;
+if (url) {
+  const token = values.token ?? process.env.DPI_TOKEN ?? "";
+  if (!token) fail("--url needs --token (or DPI_TOKEN)");
+  device = { id: values.save ?? "adhoc", name: values.save ?? new URL(url).host, url: url.replace(/\/+$/, ""), token };
+} else {
+  const known = registry.list().map((d) => d.id);
+  if (!deviceRef) fail(`${USAGE}\n\nKnown devices: ${known.join(", ") || "none"}`);
+  const row = registry.get(deviceRef);
+  if (!row) fail(`Unknown device "${deviceRef}". Known: ${known.join(", ") || "none (add one to dpi-network.yaml)"}`);
+  if (!row.token) fail(`No token for ${row.id}. Run: just net register ${row.id}`);
+  if (!row.url)
+    fail(`Device ${row.id} is paired over the tunnel — it has no LAN URL. Attach through the hub web UI, or pair this machine directly.`);
+  device = { id: row.id, name: row.name, url: row.url, token: row.token };
+}
+
+const client = new DpiClient(device.url, device.token);
+const info = await client.device({ timeoutMs: 8000 }).catch((e: unknown) =>
+  fail(
+    isDpiError(e) && e.code === "unauthorized"
+      ? `${device.id}: token rejected by ${device.url}`
+      : `${device.id} is offline at ${device.url} (${(e as Error).message})`,
+  ),
+);
+if (values.save && url)
+  registry.upsert({ id: values.save, name: values.save, url: device.url, kind: "url", source: "ui", token: device.token });
+
+let session = sessionRef;
+if (values.new) {
+  const cwd = values.cwd ?? (await client.dirs("")).dirs[0]?.path;
+  if (!cwd) fail(`${device.id} has no start dirs; pass --cwd`);
+  const modelId = values.model ?? info.defaultModel;
+  const model = info.models.find((m) => m.id === modelId);
+  if (!model) fail(`Unknown model ${modelId}. Available: ${info.models.map((m) => m.id).join(", ")}`);
+  const created = await client
+    .createSession({ name: values.new, cwd, model: { provider: model.provider, modelId: model.id } })
+    .catch((e: Error) => fail(`Could not create the session: ${e.message}`));
+  session = created.id;
+}
+
+const app = new App(device, client, info, registry);
+
+// Bootstrap local pairing (--pair CODE --hub ORIGIN [--force]): runs the same
+// controller as /pair, against the LOCAL backend, before the UI opens. A bare
+// --pair without a value points at the slash command instead of guessing.
+if (values.pair !== undefined || values.hub !== undefined) {
+  const { runPairing, parsePairArgs, LocalPairing } = await import("./pairing.ts");
+  if (!values.pair) {
+    process.stdout.write("--pair needs the code from the hub wizard (or its pair URL).\nInside dpi-tui, run: /pair <CODE> --hub <origin>\n");
+    process.exit(1);
+  }
+  try {
+    LocalPairing.fromEnv();
+  } catch (e) {
+    fail((e as Error).message);
+  }
+  await app.open(session, agentRef);
+  await runPairing(app, parsePairArgs([values.pair, ...(values.hub ? ["--hub", values.hub] : []), ...(values.force ? ["--force"] : [])].join(" ")));
+} else {
+  await app.open(session, agentRef);
+}

package/apps/dpi-tui/src/pairing.ts

@@ -0,0 +1,287 @@
+/**
+ * P2-26 — TUI local pairing controller.
+ *
+ * Contract (plan §P2-26):
+ * - Talks ONLY to the local, token-authed dpi-backend (127.0.0.1:DPI_PORT with
+ *   DPI_TOKEN) — never to the currently selected remote registry target.
+ * - The TUI never creates a keypair, signs requests, writes pairing.json or
+ *   runs a second connector loop: the backend owns all of that (03 §7).
+ * - Interrupting (esc/Ctrl-C) cancels the LOCAL operation best-effort and says
+ *   honestly that the hub side is NOT cancelled by it.
+ * - Errors map to actionable text; a --force hub switch carries a warning.
+ * - The full fingerprint wraps at the terminal width (40/80/200) — never
+ *   truncated, and no token is ever rendered.
+ */
+import type { App } from "./app.ts";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { Panel } from "./pickers.ts";
+import { c } from "./theme.ts";
+
+export interface PairArgs {
+  code?: string;
+  pairUrl?: string;
+  hub?: string;
+  force?: boolean;
+}
+
+/** Parse `/pair [CODE|PAIR_URL] [--hub ORIGIN] [--force]`. */
+export function parsePairArgs(arg: string): PairArgs {
+  const out: PairArgs = {};
+  const tokens = arg.split(/\s+/).filter(Boolean);
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === "--force") out.force = true;
+    else if (t === "--hub") out.hub = tokens[++i];
+    else if (t.startsWith("--hub=")) out.hub = t.slice(6);
+    else if (t.startsWith("http://") || t.startsWith("https://")) out.pairUrl = t;
+    else out.code ??= t;
+  }
+  return out;
+}
+
+/** Wrap the full fingerprint into ≤width chunks — readable at 40/80/200 cols. */
+export function wrapFingerprint(fp: string, width: number): string[] {
+  const chunk = Math.max(8, Math.min(64, width - 4));
+  const lines: string[] = [];
+  for (let i = 0; i < fp.length; i += chunk) lines.push(fp.slice(i, i + chunk));
+  return lines.length ? lines : [fp];
+}
+
+/** Actionable text for every pairing failure code (03 §7). */
+export function describePairingError(e: unknown): string {
+  const code = typeof e === "string" ? e.split(":", 1)[0] : (e as { code?: string } | null)?.code;
+  if (code) {
+    switch (code) {
+      case "clock_skew":
+        return "This device's clock disagrees with the hub by more than a minute — sync the system clock and retry.";
+      case "enrollment_lost":
+        return "The hub lost this enrollment (restart or new code). Mint a fresh code in the hub wizard and retry.";
+      case "paired_elsewhere":
+      case "hub_mismatch":
+        return "This device is already paired to another hub. Revoke there first, or use /pair --force to switch hubs.";
+      case "revoked":
+        return "This pairing was revoked on the hub. Mint a fresh code to pair again.";
+      case "hub_required":
+        return "No hub configured yet — pass the origin: /pair CODE --hub https://hub.example.com";
+      case "busy":
+        return "A pairing is already in progress. Cancel it first (esc in the pairing panel).";
+      case "code_invalid":
+        return "The hub does not know this code — check for typos or mint a new one.";
+      case "code_expired":
+        return "The code expired. Mint a fresh one in the hub wizard.";
+      case "unauthorized":
+        return "The local backend rejected DPI_TOKEN — the token must be the device's own (dpi_…), at least 32 chars.";
+      default:
+        break;
+    }
+  }
+  return e instanceof Error ? e.message : String(e);
+}
+
+export interface PairingStatusDTO {
+  state: "unpaired" | "pairing" | "paired" | "revoked";
+  deviceUid?: string;
+  deviceName?: string;
+  fingerprint: string;
+  hubOrigin?: string;
+  deviceId?: string;
+  pairingEpoch?: string;
+  generation?: number;
+  pending?: { hubOrigin: string; startedAt: number; note?: string };
+  lastError?: string;
+}
+
+/** Local authenticated pairing endpoints (never the remote registry target). */
+export class LocalPairing {
+  readonly base: string;
+  constructor(
+    private token: string,
+    port: number,
+  ) {
+    this.base = `http://127.0.0.1:${port}`;
+  }
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): LocalPairing {
+    const token = env.DPI_TOKEN ?? "";
+    if (token.length < 32)
+      throw new Error("DPI_TOKEN is unset — local pairing talks to this machine's dpi-backend and needs its token.");
+    return new LocalPairing(token, Number(env.DPI_PORT ?? 4780));
+  }
+  private async call<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const r = await fetch(`${this.base}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const data = (await r.json().catch(() => undefined)) as
+      | T
+      | { error?: { code?: string; message?: string } }
+      | undefined;
+    if (!r.ok) {
+      const error = (data as { error?: { code?: string; message?: string } } | undefined)?.error;
+      const e = new Error(error?.message ?? `${r.status} ${r.statusText}`) as Error & { code?: string; status?: number };
+      e.code = error?.code;
+      e.status = r.status;
+      throw e;
+    }
+    return data as T;
+  }
+  status(): Promise<PairingStatusDTO> {
+    return this.call<PairingStatusDTO>("GET", "/v1/pairing");
+  }
+  start(input: PairArgs): Promise<PairingStatusDTO> {
+    return this.call<PairingStatusDTO>("POST", "/v1/pairing/start", {
+      ...(input.pairUrl ? { pairUrl: input.pairUrl } : { code: input.code }),
+      ...(input.hub ? { hub: input.hub } : {}),
+      ...(input.force ? { force: true } : {}),
+    });
+  }
+  cancel(): Promise<PairingStatusDTO> {
+    return this.call<PairingStatusDTO>("POST", "/v1/pairing/cancel");
+  }
+}
+
+/** Render the pairing panel body. Pure — unit-tested. */
+export function pairingViewLines(
+  status: PairingStatusDTO | undefined,
+  note: string,
+  width: number,
+  hubOrigin?: string,
+): string[] {
+  const lines: string[] = [c.bold(c.accent("Pair this device"))];
+  if (hubOrigin) lines.push(c.muted(`hub: ${hubOrigin}`));
+  if (!status) {
+    lines.push(c.muted(note));
+    return lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width)));
+  }
+  lines.push(c.muted(`device: ${status.deviceName ?? status.deviceUid ?? "?"} · uid ${status.deviceUid ?? "?"}`));
+  lines.push("");
+  lines.push(c.bold("key fingerprint (compare with the hub wizard):"));
+  for (const line of wrapFingerprint(status.fingerprint, width)) lines.push(`  ${c.secondary(line)}`);
+  lines.push("");
+  if (status.pending) {
+    lines.push(c.warn("Awaiting approval on the hub…"));
+    if (status.pending.note) lines.push(c.muted(`  ${status.pending.note}`));
+  } else if (status.lastError) {
+    lines.push(c.err(describePairingError(status.lastError)));
+    if (status.state === "paired")
+      lines.push(c.muted(`Existing pairing to ${status.hubOrigin} is unchanged.`));
+  } else if (status.state === "paired") {
+    lines.push(c.ok(`Paired to ${status.hubOrigin} (generation ${status.generation}).`));
+    lines.push(c.muted("The connector keeps the tunnel up; /pair again to re-pair."));
+  } else if (status.state === "revoked") {
+    lines.push(c.warn("Revoked on the hub. /pair CODE to pair again."));
+  } else {
+    lines.push(c.muted(note));
+  }
+  if (note && status.state !== "pairing") lines.push(c.muted(note));
+  return lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width)));
+}
+
+const pairingActive = (status: PairingStatusDTO) => !!status.pending || status.state === "pairing";
+
+/** What closing the panel reports when there was no local operation left to cancel: a failure stays a failure. */
+function closedIdle(status: PairingStatusDTO): [text: string, error: boolean] {
+  if (status.lastError) {
+    const kept = status.state === "paired" ? "existing credentials are unchanged." : "nothing was paired.";
+    return [`Pairing did not complete: ${describePairingError(status.lastError)} No active local operation to cancel; ${kept}`, true];
+  }
+  if (status.state === "paired") return [`Pairing panel closed. Paired to ${status.hubOrigin} (generation ${status.generation}).`, false];
+  return ["Pairing panel closed. No active local operation to cancel; existing credentials are unchanged.", false];
+}
+
+/**
+ * Run the local pairing flow in an overlay: start → poll the local status →
+ * show origin + full fingerprint + awaiting-approval → stop at paired/revoked.
+ * Closing the panel (esc) cancels the LOCAL operation best-effort.
+ */
+export async function runPairing(app: App, args: PairArgs): Promise<void> {
+  if (!args.code && !args.pairUrl) {
+    app.flash("Usage: /pair CODE --hub https://hub.example.com [--force] — mint a code in the hub wizard first.", true);
+    return;
+  }
+  if (args.force) app.flash("Warning: --force re-points this device at a different hub. Old credentials there stay until revoked.", true);
+  let local: LocalPairing;
+  try {
+    local = LocalPairing.fromEnv();
+  } catch (e) {
+    app.flash(describePairingError(e), true);
+    return;
+  }
+  let live = true;
+  let status: PairingStatusDTO | undefined;
+  let note = "Starting…";
+  let hubOrigin: string | undefined;
+  try {
+    hubOrigin = args.pairUrl ? new URL(args.pairUrl).origin : args.hub;
+  } catch {
+    hubOrigin = args.hub;
+  }
+  const starting = local.start(args);
+  const panel = new Panel(
+    (w) => pairingViewLines(status, note, w, hubOrigin),
+    () => app.closeOverlay(),
+  );
+  app.overlay(panel, () => {
+    if (!live) return;
+    live = false;
+    void (async () => {
+      // A slow start may not have created its local operation yet. Wait for its
+      // response before deciding, instead of letting it outlive this panel.
+      let started: PairingStatusDTO;
+      try {
+        started = await starting;
+      } catch (e) {
+        // The backend answered and refused: nothing started, and the refusal was already shown.
+        if (typeof (e as { status?: unknown }).status === "number") return;
+        app.flash("Pairing panel closed — local cancel was not confirmed. Check the local backend and hub; the hub-side code was not cancelled.", true);
+        return;
+      }
+      const last = status ?? started;
+      if (!pairingActive(last)) {
+        const [text, error] = closedIdle(last);
+        app.flash(text, error);
+        return;
+      }
+      // Best-effort LOCAL cancel; the hub side is NOT cancelled by this.
+      try {
+        await local.cancel();
+        app.flash("Pairing panel closed — the local operation was cancelled. The hub-side code stays until it expires; revoke there if it was already approved.", true);
+      } catch {
+        app.flash("Pairing panel closed — local cancel was not confirmed. Check the local backend and hub; the hub-side code was not cancelled.", true);
+      }
+    })();
+  });
+  const render = () => {
+    panel.invalidate();
+    app.tui.invalidate();
+    app.tui.requestRender();
+  };
+  try {
+    status = await starting;
+    if (!live) return;
+    note = "";
+    render();
+    const deadline = Date.now() + 330_000;
+    while (live && Date.now() < deadline) {
+      if (!pairingActive(status)) break;
+      await new Promise((r) => setTimeout(r, 1_000));
+      if (!live) break;
+      status = await local.status();
+      if (!live) break;
+      render();
+    }
+    if (live && status && pairingActive(status)) {
+      note = "Still waiting after 5 minutes — mint a fresh code if the hub wizard was closed.";
+      render();
+    }
+  } catch (e) {
+    if (live) {
+      note = describePairingError(e);
+      render();
+      app.flash(note, true);
+    }
+  }
+}

package/apps/dpi-tui/src/pickers.ts

@@ -0,0 +1,238 @@
+// Overlays: pick a session, agent, model or device; walk a remote directory; type a name.
+import {
+  Box,
+  Container,
+  Input,
+  matchesKey,
+  SelectList,
+  truncateToWidth,
+  type Component,
+  type Focusable,
+  type SelectItem,
+} from "@earendil-works/pi-tui";
+import { agentTree, type TreeNode } from "../../dpi-sdk/src/models.ts";
+import type { App } from "./app.ts";
+import { c, selectTheme } from "./theme.ts";
+
+const panelBg = (s: string) => `\x1b[48;2;37;26;27m${s}\x1b[49m`;
+
+class Title implements Component {
+  constructor(public text: string) {}
+  render(width: number) {
+    return [truncateToWidth(this.text, width)];
+  }
+  invalidate() {}
+}
+
+/** A titled SelectList; typing filters it. */
+export class Picker extends Box {
+  readonly list: SelectList;
+  private filter = "";
+  private title: Title;
+  constructor(
+    private label: string,
+    items: SelectItem[],
+    onPick: (item: SelectItem) => void,
+    onCancel: () => void,
+    hint = "↑↓ move │ enter select │ type to filter │ esc close",
+  ) {
+    super(1, 0, panelBg);
+    this.title = new Title(c.bold(c.accent(label)));
+    this.list = new SelectList(items, Math.max(1, Math.min(14, items.length)), selectTheme);
+    this.list.onSelect = onPick;
+    this.list.onCancel = onCancel;
+    this.addChild(this.title);
+    this.addChild(this.list);
+    this.addChild(new Title(c.muted(hint)));
+  }
+  handleInput(data: string) {
+    if (matchesKey(data, "backspace")) this.filter = this.filter.slice(0, -1);
+    else if (data.length === 1 && data >= " " && data !== "\x7f") this.filter += data;
+    else return this.list.handleInput(data);
+    this.list.setFilter(this.filter);
+    this.title.text = c.bold(c.accent(this.label)) + (this.filter ? c.muted(`  /${this.filter}`) : "");
+  }
+}
+
+/** One line of text input. */
+export class Prompt extends Box implements Focusable {
+  readonly input = new Input();
+  private _focused = false;
+  get focused() {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.input.focused = value;
+  }
+  constructor(label: string, initial: string, onSubmit: (value: string) => void, onCancel: () => void) {
+    super(1, 0, panelBg);
+    this.addChild(new Title(c.bold(c.accent(label))));
+    this.input.setValue(initial);
+    this.input.onSubmit = onSubmit;
+    this.input.onEscape = onCancel;
+    this.addChild(this.input);
+    this.addChild(new Title(c.muted("enter confirm │ esc cancel")));
+  }
+  handleInput(data: string) {
+    this.input.handleInput(data);
+  }
+}
+
+/** A read-only panel that closes on Esc or Enter (help, tasks). */
+export class Panel extends Box {
+  private body = new Container();
+  constructor(
+    private render_: (width: number) => string[],
+    private onClose: () => void,
+  ) {
+    super(1, 0, panelBg);
+    this.addChild({ render: (w: number) => this.render_(w).map((l) => truncateToWidth(l, w)), invalidate() {} });
+    this.addChild(this.body);
+  }
+  handleInput(data: string) {
+    if (matchesKey(data, "escape") || matchesKey(data, "enter") || data === "q") this.onClose();
+  }
+}
+
+// ------------------------------------------------------------------ flows
+
+export async function pickSession(app: App) {
+  const tree = await app.client.tree();
+  const items: SelectItem[] = [
+    { value: "+new", label: "＋ New session", description: `choose a directory on ${app.device.id}` },
+    ...tree.sessions.map((s) => ({
+      value: s.id,
+      label: s.name,
+      description: `${s.cwd.split("/").slice(-2).join("/")} │ ${s.agents.length} agent${s.agents.length === 1 ? "" : "s"}${s.busy ? " │ working" : ""}`,
+    })),
+  ];
+  app.overlay(
+    new Picker(`Sessions on ${app.device.id}`, items, (item) => {
+      app.closeOverlay();
+      if (item.value === "+new") return void newSession(app);
+      const s = tree.sessions.find((x) => x.id === item.value)!;
+      const root = s.agents.find((a) => a.kind === "root") ?? s.agents[0];
+      void app.attach(s.id, root?.id ?? 1);
+    }, () => app.closeOverlay(!app.sessionId)),
+  );
+}
+
+export async function newSession(app: App) {
+  const name = await app.prompt("Session name", "");
+  if (name === undefined) return app.sessionId ? undefined : pickSession(app);
+  const cwd = await walkDirs(app, "");
+  if (!cwd) return app.sessionId ? undefined : pickSession(app);
+  const model = await chooseModel(app, app.info.defaultModel);
+  if (!model) return;
+  await app.run(async () => {
+    const s = await app.client.createSession({ name: name || "New session", cwd, model: { provider: model.provider, modelId: model.id } });
+    await app.attach(s.id, s.agents.find((a) => a.kind === "root")?.id ?? 1);
+    app.flash(`Session created in ${cwd}`);
+  });
+}
+
+function walkDirs(app: App, path: string): Promise<string | undefined> {
+  return new Promise((done) => {
+    const step = async (at: string) => {
+      const listing = await app.client.dirs(at).catch((e: Error) => (app.flash(e.message, true), undefined));
+      if (!listing) return done(undefined);
+      const items: SelectItem[] = [
+        ...(listing.path ? [{ value: `use:${listing.path}`, label: `✓ Use ${listing.path}` }] : []),
+        ...(listing.path ? [{ value: listing.parent ?? "", label: listing.parent ? ".." : "⌂ start dirs" }] : []),
+        ...listing.dirs.map((d) => ({ value: d.path, label: `${d.name}/` })),
+      ];
+      app.overlay(
+        new Picker(`Working directory on ${app.device.id}`, items, (item) => {
+          app.closeOverlay();
+          if (item.value.startsWith("use:")) done(item.value.slice(4));
+          else void step(item.value);
+        }, () => {
+          app.closeOverlay();
+          done(undefined);
+        }),
+      );
+    };
+    void step(path);
+  });
+}
+
+function chooseModel(app: App, current?: string) {
+  return new Promise<(typeof app.info.models)[number] | undefined>((done) => {
+    const models = app.info.models;
+    const picker = new Picker(
+      `Model (${app.device.id})`,
+      models.map((m) => ({ value: `${m.provider}/${m.id}`, label: m.name, description: `${m.tier} │ ${m.provider}` })),
+      (item) => {
+        app.closeOverlay();
+        done(models.find((m) => `${m.provider}/${m.id}` === item.value));
+      },
+      () => {
+        app.closeOverlay();
+        done(undefined);
+      },
+    );
+    const index = models.findIndex((m) => m.id === current);
+    if (index >= 0) picker.list.setSelectedIndex(index);
+    app.overlay(picker);
+  });
+}
+
+export async function pickModel(app: App) {
+  if (!app.handle) return;
+  const model = await chooseModel(app, app.model.state.agent.model?.modelId);
+  if (!model) return;
+  await app.run(async () => {
+    await app.handle!.configure({ model: { provider: model.provider, modelId: model.id } });
+    app.flash(`Model: ${model.name} (next turn)`);
+  });
+}
+
+export function pickAgent(app: App) {
+  const summary = app.sessionSummary();
+  if (!summary) return;
+  const rows: SelectItem[] = [];
+  const walk = (nodes: TreeNode[], depth: number) => {
+    for (const node of nodes) {
+      if (node.type !== "agent") continue;
+      const a = node.agent;
+      const icon = a.kind === "fork" ? "⑂" : a.kind === "subagent" ? "↳" : "◆";
+      rows.push({
+        value: String(a.id),
+        label: `${"  ".repeat(depth)}${icon} ${a.name}${a.busy ? " ●" : ""}`,
+        description: [a.kind === "fork" ? `fork @ #${a.forkedAt}` : a.kind, a.background ? `${a.background} bg` : ""]
+          .filter(Boolean)
+          .join(" │ "),
+      });
+      walk(node.children, depth + 1);
+    }
+  };
+  walk(agentTree(app.device.id, summary, false), 0);
+  const picker = new Picker(`Agents in ${summary.name}`, rows, (item) => {
+    app.closeOverlay();
+    void app.attach(summary.id, Number(item.value));
+  }, () => app.closeOverlay());
+  const index = rows.findIndex((r) => r.value === String(app.agentId));
+  if (index >= 0) picker.list.setSelectedIndex(index);
+  app.overlay(picker);
+}
+
+export function pickDevice(app: App) {
+  const devices = app.registry?.list() ?? [];
+  if (!devices.length) return app.flash("No saved devices. Use --url/--token --save <id>.", true);
+  app.overlay(
+    new Picker(
+      "Devices",
+      devices.map((d) => ({
+        value: d.id,
+        label: `${d.id === app.device.id ? "● " : "  "}${d.id}`,
+        description: `${d.kind} │ ${d.url}${d.token ? "" : " │ no token"}`,
+      })),
+      (item) => {
+        app.closeOverlay();
+        void app.switchDevice(item.value);
+      },
+      () => app.closeOverlay(),
+    ),
+  );
+}