my-durable 0.0.9 → 0.0.11

package/apps/dpi-playground/apps/dpi-playground-fe/dist/index.html

@@ -7,7 +7,7 @@
     <meta name="referrer" content="no-referrer" />
     <link rel="icon" type="image/svg+xml" href="/icons/durable-pi.svg" />
     <title>Durable Pi | Network</title>
-    <script type="module" crossorigin src="/assets/index-CoYMgU-2.js"></script>
+    <script type="module" crossorigin src="/assets/index-Ct_cPQy9.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Cg3vey95.css">
   </head>
   <body>

package/apps/dpi-sdk/src/protocol/pairing.ts

@@ -383,7 +383,12 @@ export function parseHubOrigin(
     return { ok: false, error: "origin: not a valid URL" };
   }
   if (url.protocol !== "https:") {
-    return { ok: false, error: "origin: HTTPS origin required" };
+    // Loopback dev hubs (one machine running both ends) speak plain HTTP. The
+    // same rule as the device's own origin check: only 127.0.0.1/[::1]/localhost
+    // qualify, so a hub another machine can reach is still HTTPS-only.
+    const loopback =
+      url.protocol === "http:" && /^(127\.0\.0\.1|\[::1\]|localhost)$/.test(url.hostname);
+    if (!loopback) return { ok: false, error: "origin: HTTPS origin required" };
   }
   if (url.username || url.password) {
     return { ok: false, error: "origin: userinfo not allowed" };

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

@@ -26,8 +26,9 @@ import {
 } from "../../dpi-sdk/src/api.ts";
 import type { DeviceRow, NetworkRegistry } from "../../dpi-sdk/src/node/registry.ts";
 import { COMMANDS, runCommand } from "./commands.ts";
-import { Prompt, SecretPrompt, pickModel } from "./pickers.ts";
+import { Prompt, SecretPrompt, pickModel, newSession } from "./pickers.ts";
 import { renderHeader, renderHerd, renderHerdPanel, renderNetwork, renderStatusbar, renderViewbar, herdRows, joinPanel, networkRows } from "./views.ts";
+import { appendFileSync } from "node:fs";
 import { fetchHubNetwork } from "./hub-feed.ts";
 import { HubMux } from "./hub-mux.ts";
 import { box, c, STATE_COLOR, STATE_GLYPH, type RowState } from "./theme.ts";
@@ -358,7 +359,13 @@ export class App {
     ];
   }
 
-  private rows(): Array<{ sessionId?: string; deviceId?: string; label: string }> {
+  /** Herd and network rows share a shape; `kind` tells a header from an entry. */
+  private rows(): Array<{
+    kind: "group" | "session" | "device";
+    sessionId?: string;
+    deviceId?: string;
+    label: string;
+  }> {
     if (this.view === "herd") return herdRows(this.sessions, this.filter);
     if (this.view === "network") return networkRows(this.devicesCache, this.device.id, this.filter);
     return [];
@@ -368,6 +375,14 @@ export class App {
     const rows = this.rows();
     const row = rows[this.cursor] ?? rows.find((r) => r.sessionId);
     if (row?.sessionId) return this.openSession(row.sessionId, row.deviceId);
+    // A group header opens its first session — pressing enter on a header used
+    // to do literally nothing.
+    if (row?.kind === "group") {
+      // The next session row after the header belongs to that group.
+      const at = rows.indexOf(row);
+      const target = rows.slice(at + 1).find((r) => r.kind !== "group");
+      if (target?.sessionId) return this.openSession(target.sessionId, target.deviceId);
+    }
     if (row?.deviceId && this.view === "network") {
       const target = this.devicesCache.find((d) => d.id === row.deviceId);
       if (!target) return;
@@ -402,7 +417,11 @@ export class App {
 
   /** 1-9 jump: the nth session row of the current view. */
   private jump(n: number) {
-    const rows = this.rows().filter((r) => r.sessionId);
+    // Digits address sessions, so they work from the agent view as well — that
+    // is the fastest way out of a session you no longer want.
+    const rows = (this.view === "herd" ? this.rows() : herdRows(this.sessions, this.filter)).filter(
+      (r): r is { kind: "session"; sessionId: string; deviceId?: string; label: string } => !!r.sessionId,
+    );
     const nth = rows[n - 1];
     if (nth?.sessionId) this.openSession(nth.sessionId, nth.deviceId);
     else this.notify(`no session #${n} in this view`);
@@ -454,6 +473,17 @@ export class App {
   // ------------------------------------------------------------------- input
 
   handleInput(data: string): TuiInputListenerResult {
+    // DPI_TUI_KEYS=<file> traces every key the app receives — the fastest way to
+    // tell "the terminal never sent it" from "a branch swallowed it".
+    if (process.env.DPI_TUI_KEYS)
+      try {
+        appendFileSync(
+          process.env.DPI_TUI_KEYS,
+          `${JSON.stringify({ data, view: this.view, tab: this.tab, input: this.input?.kind ?? null, overlays: this.overlays.length })}\n`,
+        );
+      } catch {
+        /* tracing must never break input */
+      }
     // pi-tui overlays (welcome screen, pickers, prompts) own the keyboard while
     // open; only ctrl+c still closes them from here.
     if (this.overlays.length) {
@@ -489,7 +519,7 @@ export class App {
     else if (data === "/") {
       this.beginInput("message", "follow-up ❯ ");
       this.input!.value = "/";
-    } else if (data === "f") this.beginInput("filter", "/ ");
+    } else if (data === "f") this.beginInput("filter", "filter ❯ ");
     else if (data === "n") this.beginInput("new", "new session › ");
     else if (data === "x") this.beginInput("kill", `reset ${this.sessionSummary()?.name ?? "context"}? y/n`);
     else if (data === "g") this.setView("herd");
@@ -508,12 +538,9 @@ export class App {
     else if (data === "]" || matchesKey(data, "tab")) this.cycleTab(1);
     else if (data === "[" || matchesKey(data, "shift+tab")) this.cycleTab(-1);
     else if (/^[1-9]$/.test(data)) this.jump(Number(data));
-    // Agent view keeps pi muscle memory: any other printable char opens the
-    // message line seeded with itself (herdr requires "m"; typing talks here).
-    else if (this.view === "agent" && /^[^\x00-\x1f]$/.test(data)) {
-      this.beginInput("message", "follow-up ❯ ");
-      this.input!.value = data;
-    }
+    // No catch-all: a stray letter used to jump views or open the composer with
+    // itself as the first character. herdr and piggery both require an explicit
+    // key (m, / or enter), and so do we now.
     return { consume: true };
   }
 
@@ -587,7 +614,7 @@ export class App {
       } else if (input.kind === "kill") {
         if (value.trim().toLowerCase().startsWith("y")) void this.command("reset");
         else this.notify("reset cancelled");
-      } else if (input.kind === "new") void this.command("new");
+      } else if (input.kind === "new") void newSession(this, value);
       return true;
     }
     if (data === "\x7f" || matchesKey(data, "backspace")) (input.value = input.value.slice(0, -1)), (this.suggIndex = 0);
@@ -607,15 +634,27 @@ export class App {
     this.requestRender();
   }
 
+  /**
+   * esc is BACK, the way every list/detail client behaves (piggery: "esc back").
+   * Interrupting a running turn is a destructive action and keeps its own key
+   * (i) — folding it into esc meant "leave this screen" did nothing at all while
+   * an agent was idle.
+   */
   private escape() {
     if (this.filter) {
       this.filter = "";
       this.notify("filter cleared");
-    } else if (this.view === "agent") {
-      if (this.busy()) void this.interrupt();
-    } else this.setView("agent");
+    } else if (this.view === "agent" || this.view === "log") {
+      this.setView("herd");
+    }
   }
 
+  /**
+   * Move the cursor. Group rows ("~/project/ · 3 agents") are headers, not
+   * entries: stepping onto one left the marker and the OVERVIEW panel frozen on
+   * the previous session, which reads as "navigation is dead". Skip them, the
+   * way piggery's list only ever has real rows under the cursor.
+   */
   private move(delta: number) {
     if (this.view === "agent" && this.tab === "transcript") {
       // Scroll the transcript instead of moving a cursor (herdr H04's lesson).
@@ -625,9 +664,24 @@ export class App {
     }
     const rows = this.rows();
     if (!rows.length) return;
-    this.cursor = Math.max(0, Math.min(this.cursor + delta, rows.length - 1));
-    const row = rows[this.cursor];
-    if (row?.sessionId) this.selectedId = row.sessionId;
+    const selectable = (i: number) => !!rows[i] && rows[i].kind !== "group";
+    let next = this.cursor;
+    for (let step = 0; step < rows.length; step += 1) {
+      next += delta;
+      if (next < 0 || next >= rows.length) break;
+      if (selectable(next)) {
+        this.cursor = next;
+        this.selectedId = rows[next]!.sessionId ?? this.selectedId;
+        this.requestRender();
+        return;
+      }
+    }
+    // Nothing selectable in that direction: still clamp to a valid row so the
+    // highlight never points past the list.
+    if (!selectable(this.cursor)) {
+      const first = rows.findIndex((_, i) => selectable(i));
+      if (first >= 0) this.cursor = first;
+    }
     this.requestRender();
   }
 
@@ -767,7 +821,9 @@ export class App {
 
   tick() {
     if (this.toastTicks > 0 && --this.toastTicks === 0) this.toast = "";
-    if (this.hub && ++this.hubTick >= 125) {
+    // Live network: refresh the hub feed every ~5 s (tick = 120 ms), so a device
+    // paired from the CLI shows up while the operator is looking at the list.
+    if (this.hub && ++this.hubTick >= 42) {
       this.hubTick = 0;
       void fetchHubNetwork(this.hub.url, this.hub.token).then((rows) => {
         if (rows) {
@@ -855,7 +911,7 @@ export class App {
     }).slice(0, h);
     if (!wide) return table;
     const selected = this.sessions.find((s) => s.id === (this.selectedId ?? this.sessionId));
-    const panel = renderHerdPanel(panelW, h, selected, this.contextLeft());
+    const panel = renderHerdPanel(panelW, h, selected, this.contextLeft(), this.device.name);
     return joinPanel(table, panel, tableW, w, h);
   }
 

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

@@ -61,6 +61,11 @@ export async function runCommand(app: App, text: string): Promise<boolean> {
       pickDevice(app);
       break;
     case "new":
+      // "new agent" needs an open session; the n KEY (new session) is the other door.
+      if (!app.sessionId) {
+        app.notify("no session open — press n to create one");
+        break;
+      }
       await app.run(async () => {
         const created = await app.client.session(app.sessionId!).createAgent(arg ? { name: arg } : {});
         await app.attach(app.sessionId!, created.id);

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

@@ -25,35 +25,91 @@ class Title implements Component {
   invalidate() {}
 }
 
-/** A titled SelectList; typing filters it. */
+/**
+ * A titled list with local filtering. Two deliberate departures from pi-tui's
+ * SelectList defaults, both found by driving the real picker:
+ *  - it filters on `value.startsWith`, so typing "pro" found nothing in a
+ *    directory named "project/"; we filter on the LABEL (substring), which is
+ *    what the user reads;
+ *  - its empty message is "No matching commands" — the wrong vocabulary for a
+ *    directory or model list, so the theme names the filter instead.
+ * j/k move (as the app advertises) instead of being swallowed as filter text.
+ */
 export class Picker extends Box {
-  readonly list: SelectList;
+  list: SelectList;
   private filter = "";
   private title: Title;
+  private readonly hintText: string;
   constructor(
     private label: string,
-    items: SelectItem[],
-    onPick: (item: SelectItem) => void,
-    onCancel: () => void,
-    hint = "↑↓ move │ enter select │ type to filter │ esc close",
-    subtitle?: string,
+    private readonly allItems: SelectItem[],
+    private onPick: (item: SelectItem) => void,
+    private readonly onCancel: () => void,
+    hint = "↑↓/j/k move │ enter select │ type to filter │ esc close",
+    private readonly subtitle?: string,
   ) {
     super(1, 0, panelBg);
+    this.hintText = hint;
     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.list = this.makeList(this.allItems);
+    this.rebuild();
+  }
+  private makeList(items: SelectItem[]): SelectList {
+    const theme = {
+      ...selectTheme,
+      // Name the filter: "no match for “pro”" beats a command-palette phrase.
+      noMatch: (s: string) => c.muted(this.filter ? `  no match for “${this.filter}”` : s),
+    };
+    const list = new SelectList(items, Math.max(1, Math.min(14, items.length)), theme);
+    list.onSelect = this.onPick;
+    list.onCancel = this.onCancel;
+    return list;
+  }
+  /** Rebuild typing the children in order — the filter changes the item set. */
+  private rebuild() {
+    this.clear();
     this.addChild(this.title);
-    if (subtitle) this.addChild(new Title(subtitle));
+    if (this.subtitle) this.addChild(new Title(this.subtitle));
     this.addChild(this.list);
-    this.addChild(new Title(c.muted(hint)));
+    this.addChild(new Title(c.muted(this.hintText)));
+    this.invalidate();
+  }
+  /** Every item this picker was built with (shortcut lookups need the whole set). */
+  items(): SelectItem[] {
+    return this.allItems;
+  }
+  /** Run the same path a click/enter takes. */
+  pick(item: SelectItem) {
+    this.onPick(item);
+  }
+  private applyFilter() {
+    const needle = this.filter.toLowerCase();
+    const items = needle
+      ? this.allItems.filter((i) => `${i.label} ${i.description ?? ""}`.toLowerCase().includes(needle))
+      : this.allItems;
+    this.list = this.makeList(items);
+    this.title.text =
+      c.bold(c.accent(this.label)) + (this.filter ? c.muted(`  /${this.filter}`) : "");
+    this.rebuild();
   }
   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}`) : "");
+    // Navigation first: j/k are movement everywhere else in the app, so a list
+    // must not swallow them as filter characters.
+    // SelectList only knows arrows/enter/esc, so vim keys are translated to the
+    // arrow sequences it already understands.
+    if (data === "j") return this.list.handleInput("\x1b[B");
+    if (data === "k") return this.list.handleInput("\x1b[A");
+    if (matchesKey(data, "up") || matchesKey(data, "down") || matchesKey(data, "enter") || matchesKey(data, "escape"))
+      return this.list.handleInput(data);
+    if (matchesKey(data, "backspace")) {
+      this.filter = this.filter.slice(0, -1);
+      return this.applyFilter();
+    }
+    if (data.length === 1 && data >= " " && data !== "\x7f") {
+      this.filter += data;
+      return this.applyFilter();
+    }
+    this.list.handleInput(data);
   }
 }
 
@@ -216,17 +272,25 @@ export async function pickSession(app: App) {
   );
 }
 
-export async function newSession(app: App) {
-  const name = await app.prompt("Session name", "");
+export async function newSession(app: App, presetName?: string) {
+  // The `n` input line already carries the typed name — never re-ask for it.
+  const name = presetName !== undefined ? presetName : 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);
+  // A device without a provider key (the Windows default) lists ZERO models —
+  // the picker would be empty and creation dead-ends. Fall back to the device's
+  // own default exactly like the web dialog's "(device default)" option.
+  const models = app.info.models;
+  const model = models.length
+    ? await chooseModel(app, app.info.defaultModel)
+    : { provider: (app.info as { provider?: string }).provider ?? "openrouter", id: app.info.defaultModel, name: "(device default)" };
   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}`);
+    if (!models.length) app.flash(`no model catalog on the device — using its default (${app.info.defaultModel})`);
   });
 }
 
@@ -241,7 +305,7 @@ function walkDirs(app: App, path: string): Promise<string | undefined> {
         ...listing.dirs.map((d) => ({ value: d.path, label: `${d.name}/` })),
       ];
       app.overlay(
-        new Picker(`Working directory on ${app.device.id}`, items, (item) => {
+        new Picker(`Working directory on ${app.device.name}`, items, (item) => {
           app.closeOverlay();
           if (item.value.startsWith("use:")) done(item.value.slice(4));
           else void step(item.value);
@@ -259,7 +323,7 @@ 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})`,
+      `Model (${app.device.name})`,
       models.map((m) => ({ value: `${m.provider}/${m.id}`, label: m.name, description: `${m.tier} │ ${m.provider}` })),
       (item) => {
         app.closeOverlay();

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

@@ -121,9 +121,10 @@ export function renderHerd(
     if (row.kind === "group") {
       const group = sessions.filter((s) => basename(s.cwd) === row.label);
       const busy = group.filter((s) => s.busy).length;
-      lines.push(
-        `${c.muted("~/")}${c.text(row.label)}${c.muted("/")}  ${c.muted(`· ${group.length} agent${group.length === 1 ? "" : "s"} · ${busy} busy`)}`,
-      );
+      const header = `${c.muted("~/")}${c.text(row.label)}${c.muted("/")}  ${c.muted(`· ${group.length} agent${group.length === 1 ? "" : "s"} · ${busy} busy`)}`;
+      // The cursor is drawn on headers too: a keypress must always be visible,
+      // even though j/k skips them (they are not selectable entries).
+      lines.push(cursorRow === row ? c.inverse(fit(header, w)) : fit(header, w));
       continue;
     }
     const s = sessions.find((x) => x.id === row.sessionId);
@@ -142,6 +143,16 @@ export function renderHerd(
     if (showAge) line += `  ${fit(c.muted(ageOf(s.createdAt)), cols.age)}`;
     lines.push(atCursor && !selected ? c.inverse(fit(line, w)) : fit(line, w));
   }
+  if (!rows.length && !opts.filter) {
+    // herdr never shows a bare header over nothing: the empty state points at
+    // the next move instead of a wall of blank rows.
+    lines.push(
+      "",
+      `  ${c.muted("no sessions yet on this device")}`,
+      "",
+      `  ${c.accent("n")} ${c.muted("new session")}   ${c.accent(":")} ${c.muted("palette")}   ${c.accent("N")} ${c.muted("network view")}`,
+    );
+  }
   if (opts.filter) lines.push(c.warn(`filter: ${opts.filter}`));
   // herdr frames pad EVERY line to the exact width — the caller paints rows as-is.
   return lines.map((l) => fit(l, w));
@@ -273,8 +284,23 @@ export function renderHerdPanel(
   h: number,
   s: SessionSummary | undefined,
   ctxLeft?: number,
+  device?: string,
 ): string[] {
-  if (!s) return Array.from({ length: Math.max(0, h) }, () => rep(" ", w));
+  // No session selected: a blank panel next to the divider is what made the
+  // wide layout look broken — herdr's panel always carries a device header.
+  if (!s) {
+    const lines = [
+      c.muted(" OVERVIEW"),
+      ` ${c.bold(device ?? "device")}`,
+      ` ${c.muted("no session selected")}`,
+      "",
+      ` ${c.muted("n")}        ${c.text("new session")}`,
+      ` ${c.muted("↵")}        ${c.text("open the cursor row")}`,
+      ` ${c.muted("j/k")}      ${c.text("move")}`,
+      ` ${c.muted(":")}        ${c.text("palette")}`,
+    ];
+    return lines.slice(0, h).map((l) => fit(l, w));
+  }
   const agents = s.agents.map((a) =>
     a.kind === "fork" ? `⑂ ${a.name}` : a.kind === "subagent" ? `↳ ${a.name}` : `● ${a.name}`,
   );

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

@@ -194,8 +194,8 @@ export function validateDeviceInput(urlAnswer: string, tokenAnswer: string): { u
 // ------------------------------------------------------------------ the welcome screen
 
 export function welcomeItems(deviceCount: number, port: number): SelectItem[] {
-  // Values lead with the bracket letter, so typing it jumps to the action (the
-  // Picker filters on the value); enter selects it.
+  // The bracket letter is a real shortcut (see WelcomePicker) — typing it runs
+  // the action instead of relying on filter order.
   const items: SelectItem[] = [
     { value: "pair", label: "[p] Pair this machine", description: "code or pair URL from the hub wizard" },
     { value: "add-url", label: "[a] Add a device by URL", description: "http://host:port + its DPI_TOKEN" },
@@ -219,6 +219,12 @@ export class WelcomePicker extends Picker {
   }
   handleInput(data: string) {
     if (data === "q" || matchesKey(data, "escape")) return this.cancel();
+    // Letters in the labels are shortcuts, not filter text: "[d] Detect" must
+    // DETECT regardless of which other label happens to contain a "d".
+    if (data.length === 1) {
+      const item = this.items().find((i) => i.label.startsWith(`[${data}]`));
+      if (item) return this.pick(item);
+    }
     return super.handleInput(data);
   }
 }

package/bin/dpi.mjs

@@ -23,6 +23,10 @@ Usage:
   dpi device start | stop | status                    background daemon without a terminal
   dpi device install | uninstall                      OS service (systemd/launchd); Windows: no
                                                       autostart — run "dpi device start" after login
+  dpi pair <code|link> [--hub <origin>]               pair THIS machine from the CLI (no browser)
+  dpi pair --hub <origin>                             this machine asks the hub itself
+  dpi pair offer|list|approve|revoke                  operator side, from the CLI (dpi pair --help)
+  dpi devices [--watch] [--hub <origin>]              paired machines + live status (CLI, no web)
   dpi tui
       Terminal admin client.
   dpi help | dpi --help | dpi -h
@@ -88,75 +92,48 @@ if (command === "version" || command === "--version" || command === "-v") {
 
 if (command === "update" || command === "upgrade") {
   const { readFileSync } = await import("node:fs");
-  const { spawn } = await import("node:child_process");
+  const { runUpdate, fetchLatestVersion, spawnNpm, daemonControl } = await import("./update.mjs");
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-  const current = pkg.version;
-  const checkOnly = commandRest.includes("--check") || commandRest.includes("-c");
-
-  let latest;
-  try {
-    const res = await fetch("https://registry.npmjs.org/my-durable/latest", {
-      headers: { accept: "application/json" },
-    });
-    if (!res.ok) throw new Error(`registry responded ${res.status}`);
-    latest = (await res.json()).version;
-    // This string is later interpolated into a command line (shell on Windows):
-    // anything that is not a plain semver must stop the update, not run.
-    if (!/^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$/.test(String(latest)))
-      throw new Error(`registry returned a malformed version: ${latest}`);
-  } catch (error) {
-    process.stderr.write(`dpi update: cannot reach the npm registry (${error.message})\n`);
-    process.exit(1);
-  }
-
-  // Numeric triple compare; a prerelease tag on either side counts as older.
-  const rank = (v) => {
-    const [core, ...pre] = String(v).split("-");
-    const nums = core.split(".").map((n) => Number.parseInt(n, 10) || 0);
-    return { nums: [nums[0] ?? 0, nums[1] ?? 0, nums[2] ?? 0], pre: pre.length > 0 };
-  };
-  const a = rank(current);
-  const b = rank(latest);
-  let order = 0;
-  for (let i = 0; i < 3; i += 1) {
-    if (a.nums[i] !== b.nums[i]) {
-      order = a.nums[i] < b.nums[i] ? -1 : 1;
-      break;
-    }
-  }
-  if (order === 0 && a.pre !== b.pre) order = a.pre ? -1 : 1;
-
-  if (order >= 0) {
-    process.stdout.write(`dpi ${current} is up to date (latest ${latest}).\n`);
-    process.exit(0);
-  }
-  process.stdout.write(`dpi ${current} -> ${latest} available.\n`);
-  if (checkOnly) {
-    process.stdout.write("Run `dpi update` to install it.\n");
-    process.exit(0);
-  }
-
-  // Windows: npm is npm.cmd and cmd.exe only executes batch files through a
-  // shell — a bare spawn("npm") dies with ENOENT (CreateProcess does no
-  // PATHEXT resolution). Args are literals plus the strictly-validated
-  // version above, so shell: true has no injection surface here.
-  const onWindows = process.platform === "win32";
-  const child = spawn(onWindows ? "npm.cmd" : "npm", ["install", "-g", `my-durable@${latest}`], {
-    stdio: "inherit",
-    shell: onWindows,
-  });
-  child.on("error", (error) => {
-    process.stderr.write(`dpi update: cannot run npm (${error.message})\n`);
-    process.exit(1);
+  const port = Number(process.env.DPI_PORT ?? "4780");
+  const code = await runUpdate({
+    argv: commandRest,
+    pkg,
+    nodeVersion: process.versions.node,
+    fetchLatest: fetchLatestVersion,
+    // Stop/start through this same launcher: the daemon must not block npm's
+    // rename on Windows, and it must come back afterwards.
+    daemon: daemonControl(fileURLToPath(import.meta.url), port),
+    runNpm: (version) => spawnNpm(["install", "-g", `my-durable@${version}`]),
+    print: (line) => process.stdout.write(`${line}\n`),
+    printErr: (line) => process.stderr.write(`${line}\n`),
   });
-  child.on("exit", (code) => {
-    if (code !== 0) {
-      process.stderr.write(`dpi update: npm exited ${code}; still on ${current}.\n`);
-      process.exit(code ?? 1);
-    }
-    process.stdout.write(`dpi updated ${current} -> ${latest}.\n`);
+  process.exit(code);
+} else if (command === "devices") {
+  // The CLI view of the network: same data the web sidebar and the TUI show.
+  process.argv = [process.argv[0], process.argv[1], ...commandRest];
+  const { register } = await loadTsx();
+  register();
+  const { listDevices } = await import("../apps/dpi-backend/src/pair-cli.ts");
+  const hubIdx = commandRest.indexOf("--hub");
+  process.exit(
+    await listDevices({}, hubIdx >= 0 ? commandRest[hubIdx + 1] : undefined, commandRest.includes("--watch")),
+  );
+} else if (command === "pair") {
+  // Pairing is its own surface: it runs headless (no TUI, no browser) and both
+  // directions live in one command — this machine, and the operator's side.
+  if (commandRest.includes("--help") || commandRest.includes("-h")) {
+    process.argv = [process.argv[0], process.argv[1], ...commandRest];
+    const { register } = await loadTsx();
+    register();
+    const { PAIR_USAGE } = await import("../apps/dpi-backend/src/pair-cli.ts");
+    process.stdout.write(PAIR_USAGE);
     process.exit(0);
-  });
+  }
+  process.argv = [process.argv[0], process.argv[1], ...commandRest];
+  const { register } = await loadTsx();
+  register();
+  const { runPairCommand } = await import("../apps/dpi-backend/src/pair-cli.ts");
+  process.exit(await runPairCommand(commandRest));
 } else if (!Object.hasOwn(COMMANDS, command)) {
   process.stderr.write(`dpi: unknown command '${command}'\n\n${HELP}`);
   process.exit(2);

package/bin/update.d.mts

@@ -0,0 +1,24 @@
+// Types for bin/update.mjs — the updater is plain JS (it must run before any
+// TS toolchain is available), so its public surface is declared here.
+export interface UpdateDeps {
+  argv: string[];
+  pkg: { version: string; engines?: { node?: string } };
+  nodeVersion: string;
+  fetchLatest: () => Promise<string>;
+  daemon: { running: () => Promise<boolean>; stop: () => Promise<unknown>; start: () => Promise<unknown> };
+  runNpm: (version: string) => Promise<{ code: number; output: string }>;
+  print: (line: string) => void;
+  printErr: (line: string) => void;
+}
+export function rank(version: string): { nums: number[]; pre: boolean };
+export function compareVersions(a: string, b: string): -1 | 0 | 1;
+export function satisfiesEngine(current: string, required: string): boolean;
+export function normalizeExitCode(code: number | undefined): number;
+export function isBusyFailure(text: string): boolean;
+export function runUpdate(deps: UpdateDeps): Promise<number>;
+export function spawnNpm(args: string[]): Promise<{ code: number; output: string }>;
+export function fetchLatestVersion(): Promise<string>;
+export function daemonControl(
+  dpiPath: string,
+  port: number,
+): { running: () => Promise<boolean>; stop: () => Promise<number>; start: () => Promise<number> };