chainlesschain 0.162.30 → 0.162.31

package/src/lib/file-checkpoint.js

@@ -0,0 +1,300 @@
+/**
+ * file-checkpoint — manual file-state snapshot / rewind for `cc checkpoint`.
+ *
+ * Claude-Code "rewind" parity at the CLI level: snapshot a set of files (or
+ * directories) before a risky agentic run, then restore them if it goes wrong.
+ * This is the standalone store + ops; auto-snapshotting inside the agent
+ * tool-loop is a separate follow-up (it lives in the churn-prone agent-core).
+ *
+ * On-disk layout (under <home>/checkpoints, overridable via opts.root for tests):
+ *   <root>/<id>.json        manifest { id, label, createdAt, cwd, files:[...] }
+ *   <root>/<id>/<sha256>    raw bytes of each distinct file (content-addressed,
+ *                           so duplicate contents are stored once)
+ *
+ * Distinct from `cc workflow checkpoint` (which snapshots workflow EXECUTION
+ * state in the DB, not files).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { getHomeDir } from "./paths.js";
+
+/** Directories never walked into when a checkpoint path is a directory. */
+export const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".chainlesschain",
+  ".next",
+  ".cache",
+  "coverage",
+]);
+
+/** Safety cap so `checkpoint create <huge-dir>` can't snapshot the universe. */
+export const DEFAULT_MAX_FILES = 2000;
+
+function defaultRoot() {
+  return path.join(getHomeDir(), "checkpoints");
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+function newId() {
+  // Date.now/random are fine here (plain CLI lib, not a resumable workflow).
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `cp-${Date.now()}-${rand}`;
+}
+
+/**
+ * Recursively collect regular files under an absolute path, honoring SKIP_DIRS
+ * and a running maxFiles budget. Symlinks are not followed.
+ */
+function collectFiles(abs, { maxFiles, acc }) {
+  let stat;
+  try {
+    stat = fs.lstatSync(abs);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) return;
+  if (stat.isFile()) {
+    if (acc.length >= maxFiles) {
+      throw new Error(
+        `checkpoint exceeds ${maxFiles} files — narrow the paths or raise maxFiles`,
+      );
+    }
+    acc.push(abs);
+    return;
+  }
+  if (stat.isDirectory()) {
+    if (SKIP_DIRS.has(path.basename(abs))) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(abs);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      collectFiles(path.join(abs, name), { maxFiles, acc });
+    }
+  }
+}
+
+/**
+ * Create a checkpoint snapshotting the given paths (files and/or dirs).
+ *
+ * @param {string[]} paths
+ * @param {object} [opts] { cwd, label, root, maxFiles }
+ * @returns {{ id, label, createdAt, cwd, fileCount, files:Array }}
+ */
+export function createCheckpoint(paths, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const root = opts.root || defaultRoot();
+  const maxFiles = Number.isFinite(opts.maxFiles)
+    ? opts.maxFiles
+    : DEFAULT_MAX_FILES;
+  const list = Array.isArray(paths) ? paths : [paths];
+  if (list.filter(Boolean).length === 0) {
+    throw new Error("createCheckpoint requires at least one path");
+  }
+
+  const absFiles = [];
+  for (const p of list) {
+    if (!p) continue;
+    const abs = path.resolve(cwd, p);
+    if (!fs.existsSync(abs)) {
+      throw new Error(`no such path: ${p}`);
+    }
+    collectFiles(abs, { maxFiles, acc: absFiles });
+  }
+  // De-dupe (overlapping paths) while preserving order.
+  const uniqueAbs = [...new Set(absFiles)];
+
+  const id = opts.id || newId();
+  const blobDir = path.join(root, id);
+  ensureDir(blobDir);
+
+  const files = [];
+  for (const abs of uniqueAbs) {
+    const buf = fs.readFileSync(abs);
+    const hash = sha256(buf);
+    const blobPath = path.join(blobDir, hash);
+    if (!fs.existsSync(blobPath)) fs.writeFileSync(blobPath, buf);
+    files.push({
+      rel: path.relative(cwd, abs) || path.basename(abs),
+      abs,
+      bytes: buf.length,
+      sha256: hash,
+    });
+  }
+
+  const manifest = {
+    id,
+    label: opts.label || "",
+    createdAt: new Date().toISOString(),
+    cwd,
+    fileCount: files.length,
+    files,
+  };
+  ensureDir(root);
+  fs.writeFileSync(
+    path.join(root, `${id}.json`),
+    JSON.stringify(manifest, null, 2),
+    "utf-8",
+  );
+  return manifest;
+}
+
+/** Load a checkpoint manifest by id, or null. */
+export function getCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = path.join(root, `${id}.json`);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** List all checkpoint manifests, newest first. */
+export function listCheckpoints(opts = {}) {
+  const root = opts.root || defaultRoot();
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(root)) {
+    if (!name.endsWith(".json")) continue;
+    const m = getCheckpoint(name.slice(0, -5), { root });
+    if (m) {
+      out.push({
+        id: m.id,
+        label: m.label,
+        createdAt: m.createdAt,
+        cwd: m.cwd,
+        fileCount: m.fileCount,
+      });
+    }
+  }
+  return out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+
+/**
+ * Compare the current on-disk state against a checkpoint.
+ * @returns {{ id, modified:[], unchanged:[], deleted:[] }}
+ *   modified = content differs; deleted = file is gone now.
+ */
+export function diffCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const m = getCheckpoint(id, { root });
+  if (!m) throw new Error(`no such checkpoint: ${id}`);
+  const modified = [];
+  const unchanged = [];
+  const deleted = [];
+  for (const f of m.files) {
+    if (!fs.existsSync(f.abs)) {
+      deleted.push(f.rel);
+      continue;
+    }
+    const cur = sha256(fs.readFileSync(f.abs));
+    if (cur === f.sha256) unchanged.push(f.rel);
+    else modified.push(f.rel);
+  }
+  return { id, modified, unchanged, deleted };
+}
+
+/**
+ * Restore files from a checkpoint to their original paths. By default a safety
+ * checkpoint of the CURRENT contents is taken first, so a restore is itself
+ * reversible. `dryRun` reports what would change without writing.
+ *
+ * @param {string} id
+ * @param {object} [opts] { root, dryRun, skipSafety, cwd }
+ * @returns {{ id, restored:[], unchanged:[], missingBlob:[], safetyId:string|null }}
+ */
+export function restoreCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const m = getCheckpoint(id, { root });
+  if (!m) throw new Error(`no such checkpoint: ${id}`);
+
+  const restored = [];
+  const unchanged = [];
+  const missingBlob = [];
+  const toWrite = [];
+
+  for (const f of m.files) {
+    const blobPath = path.join(root, id, f.sha256);
+    if (!fs.existsSync(blobPath)) {
+      missingBlob.push(f.rel);
+      continue;
+    }
+    const blob = fs.readFileSync(blobPath);
+    const cur = fs.existsSync(f.abs) ? fs.readFileSync(f.abs) : null;
+    if (cur && sha256(cur) === f.sha256) {
+      unchanged.push(f.rel);
+      continue;
+    }
+    toWrite.push({ abs: f.abs, rel: f.rel, blob });
+  }
+
+  if (opts.dryRun) {
+    return {
+      id,
+      restored: toWrite.map((w) => w.rel),
+      unchanged,
+      missingBlob,
+      safetyId: null,
+      dryRun: true,
+    };
+  }
+
+  // Snapshot the current state of the files we're about to overwrite, so the
+  // restore can itself be rewound. Only the files that actually change and
+  // currently exist need protecting.
+  let safetyId = null;
+  if (!opts.skipSafety) {
+    const existing = toWrite
+      .filter((w) => fs.existsSync(w.abs))
+      .map((w) => w.abs);
+    if (existing.length > 0) {
+      const safety = createCheckpoint(existing, {
+        root,
+        cwd: m.cwd,
+        label: `auto-before-restore-${id}`,
+      });
+      safetyId = safety.id;
+    }
+  }
+
+  for (const w of toWrite) {
+    ensureDir(path.dirname(w.abs));
+    fs.writeFileSync(w.abs, w.blob);
+    restored.push(w.rel);
+  }
+
+  return { id, restored, unchanged, missingBlob, safetyId };
+}
+
+/** Delete a checkpoint (manifest + blobs). Returns true if it existed. */
+export function deleteCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = path.join(root, `${id}.json`);
+  const blobDir = path.join(root, id);
+  let existed = false;
+  if (fs.existsSync(file)) {
+    fs.rmSync(file);
+    existed = true;
+  }
+  if (fs.existsSync(blobDir)) {
+    fs.rmSync(blobDir, { recursive: true, force: true });
+    existed = true;
+  }
+  return existed;
+}

package/src/lib/llm-pricing.js

@@ -0,0 +1,227 @@
+/**
+ * llm-pricing — turn token counts into estimated $ cost.
+ *
+ * Layers a price table on top of the token roll-ups produced by
+ * `session-usage.js`, so `cc cost` can show spend per provider/model.
+ *
+ * IMPORTANT: these rates are ESTIMATES of public list prices (USD per 1M
+ * tokens) and drift over time. Local providers (ollama / local) are free.
+ * An unmatched model is reported as `matched:false` with zero cost rather
+ * than guessed — the caller surfaces it as "unpriced" so the number is never
+ * silently wrong. Override or extend PRICE_TABLE below as prices change.
+ *
+ * Rate shape: { in: <USD per 1M input tokens>, out: <USD per 1M output> }.
+ * Matching is provider-scoped, longest-pattern-first, case-insensitive
+ * substring against the model id.
+ */
+
+/** Providers whose models run locally and cost nothing to call. */
+export const FREE_PROVIDERS = Object.freeze([
+  "ollama",
+  "local",
+  "llamacpp",
+  "mediapipe",
+]);
+
+/**
+ * Per-provider model price patterns. Each entry: { match, in, out }.
+ * Order within a provider matters — more specific patterns first so
+ * "gpt-4o-mini" is not shadowed by "gpt-4o".
+ */
+export const PRICE_TABLE = Object.freeze({
+  anthropic: [
+    { match: "opus", in: 15, out: 75 },
+    { match: "sonnet", in: 3, out: 15 },
+    { match: "haiku", in: 1, out: 5 },
+  ],
+  openai: [
+    { match: "gpt-4o-mini", in: 0.15, out: 0.6 },
+    { match: "gpt-4o", in: 2.5, out: 10 },
+    { match: "gpt-4-turbo", in: 10, out: 30 },
+    { match: "gpt-4", in: 30, out: 60 },
+    { match: "gpt-3.5", in: 0.5, out: 1.5 },
+    { match: "o1-mini", in: 1.1, out: 4.4 },
+    { match: "o1", in: 15, out: 60 },
+  ],
+  deepseek: [
+    { match: "reasoner", in: 0.55, out: 2.19 },
+    { match: "chat", in: 0.27, out: 1.1 },
+  ],
+  // Volcengine Doubao — rough USD conversion of public RMB list pricing.
+  volcengine: [
+    { match: "seed-1-6", in: 0.11, out: 0.28 },
+    { match: "seed", in: 0.11, out: 0.28 },
+    { match: "pro", in: 0.11, out: 0.28 },
+    { match: "lite", in: 0.04, out: 0.08 },
+    { match: "doubao", in: 0.11, out: 0.28 },
+  ],
+});
+
+const round = (n, dp = 6) => {
+  const f = Math.pow(10, dp);
+  return Math.round((Number(n) + Number.EPSILON) * f) / f;
+};
+
+/**
+ * Merge user-supplied price overrides (typically `config.llm.pricing`) onto the
+ * built-in table. Override shape mirrors PRICE_TABLE:
+ *   { "<provider>": [ { match: "<substr>", in: <num>, out: <num> }, ... ] }
+ *
+ * Per provider, a user entry whose `match` equals a built-in pattern REPLACES
+ * it; brand-new patterns are prepended so they win ties; unknown providers are
+ * added. Malformed entries (missing match / non-numeric rate) are skipped so a
+ * bad config line can't crash cost reporting. Returns a new table; never
+ * mutates PRICE_TABLE or the input.
+ *
+ * @param {object} [overrides]
+ * @param {object} [base=PRICE_TABLE]
+ * @returns {object} merged price table
+ */
+export function mergePricing(overrides, base = PRICE_TABLE) {
+  const merged = {};
+  for (const [p, entries] of Object.entries(base)) {
+    merged[p] = entries.map((e) => ({ ...e }));
+  }
+  if (!overrides || typeof overrides !== "object") return merged;
+
+  for (const [provider, rawEntries] of Object.entries(overrides)) {
+    if (!Array.isArray(rawEntries)) continue;
+    const valid = rawEntries
+      .filter(
+        (e) =>
+          e &&
+          typeof e.match === "string" &&
+          e.match.trim() &&
+          Number.isFinite(Number(e.in)) &&
+          Number.isFinite(Number(e.out)),
+      )
+      .map((e) => ({
+        match: e.match.toLowerCase(),
+        in: Number(e.in),
+        out: Number(e.out),
+      }));
+    if (valid.length === 0) continue;
+    const overridden = new Set(valid.map((v) => v.match));
+    const kept = (merged[provider] || []).filter(
+      (e) => !overridden.has(e.match.toLowerCase()),
+    );
+    merged[provider] = [...valid, ...kept];
+  }
+  return merged;
+}
+
+/**
+ * Look up the rate for a provider/model, or null if unpriced.
+ * @param {string} provider
+ * @param {string} model
+ * @param {object} [table=PRICE_TABLE] merged table from mergePricing()
+ * @returns {{ in:number, out:number, pattern:string }|null}
+ */
+export function lookupRate(provider, model, table = PRICE_TABLE) {
+  const p = String(provider || "").toLowerCase();
+  const m = String(model || "").toLowerCase();
+  if (FREE_PROVIDERS.includes(p)) {
+    return { in: 0, out: 0, pattern: "free" };
+  }
+  const entries = (table || PRICE_TABLE)[p];
+  if (!entries) return null;
+  // Longest pattern first so specific beats generic regardless of table order.
+  const sorted = [...entries].sort((a, b) => b.match.length - a.match.length);
+  for (const e of sorted) {
+    if (m.includes(e.match)) {
+      return { in: e.in, out: e.out, pattern: e.match };
+    }
+  }
+  return null;
+}
+
+/**
+ * Estimate cost for a single usage record.
+ * @returns {{ inputCost:number, outputCost:number, totalCost:number,
+ *             currency:string, matched:boolean, free:boolean, rate:object|null }}
+ */
+export function estimateCost({
+  provider,
+  model,
+  inputTokens = 0,
+  outputTokens = 0,
+  table,
+} = {}) {
+  const rate = lookupRate(provider, model, table);
+  if (!rate) {
+    return {
+      inputCost: 0,
+      outputCost: 0,
+      totalCost: 0,
+      currency: "USD",
+      matched: false,
+      free: false,
+      rate: null,
+    };
+  }
+  const inputCost = round((Number(inputTokens) / 1e6) * rate.in);
+  const outputCost = round((Number(outputTokens) / 1e6) * rate.out);
+  return {
+    inputCost,
+    outputCost,
+    totalCost: round(inputCost + outputCost),
+    currency: "USD",
+    matched: true,
+    free: rate.pattern === "free",
+    rate: { in: rate.in, out: rate.out, pattern: rate.pattern },
+  };
+}
+
+/**
+ * Augment a session-usage aggregate ({ total, byModel:[...] }) with cost.
+ * Returns a new object — does not mutate the input.
+ *
+ * Each byModel row gains: cost, currency, matched. The returned `cost`
+ * top-level sums priced rows; `unpriced` lists provider/model rows that had
+ * usage but no matching rate (their tokens are excluded from `cost.totalCost`).
+ */
+export function priceRollup(aggregate, { table } = {}) {
+  const byModel = (aggregate?.byModel || []).map((row) => {
+    const est = estimateCost({
+      provider: row.provider,
+      model: row.model,
+      inputTokens: row.inputTokens,
+      outputTokens: row.outputTokens,
+      table,
+    });
+    return {
+      ...row,
+      cost: est.totalCost,
+      inputCost: est.inputCost,
+      outputCost: est.outputCost,
+      currency: est.currency,
+      matched: est.matched,
+      free: est.free,
+    };
+  });
+
+  let totalCost = 0;
+  const unpriced = [];
+  for (const row of byModel) {
+    if (row.matched) {
+      totalCost = round(totalCost + row.cost);
+    } else if (row.totalTokens > 0) {
+      unpriced.push({
+        provider: row.provider,
+        model: row.model,
+        totalTokens: row.totalTokens,
+      });
+    }
+  }
+
+  return {
+    ...aggregate,
+    byModel,
+    cost: {
+      totalCost,
+      currency: "USD",
+      unpricedCount: unpriced.length,
+    },
+    unpriced,
+  };
+}

package/src/lib/personal-data-hub-wiring.js

@@ -263,11 +263,41 @@ async function initHub() {
     // Fall back to rule-only — registry still works
   }
 
+  // ADB one-click readiness for the social platforms (B站/微博/抖音/小红书/
+  // 头条/快手): each has a *AdbSync hub method that pulls from a rooted phone
+  // over USB. The probe runs one `adb devices` so readiness() can show
+  // "已连接手机，点一键采集" vs "请插上 root 手机" instead of the misleading
+  // snapshot guidance. Best-effort — never throws into the readiness probe.
+  const ADB_ONE_CLICK_NAMES = new Set([
+    "social-bilibili",
+    "social-weibo",
+    "social-douyin",
+    "social-xiaohongshu",
+    "social-toutiao",
+    "social-kuaishou",
+  ]);
+  const adbReadinessProbe = async () => {
+    try {
+      const { listDevices } = await import("./host-adb-bridge.js");
+      const serials = await listDevices();
+      return {
+        deviceConnected: Array.isArray(serials) && serials.length > 0,
+        serial: serials && serials[0],
+      };
+    } catch (_e) {
+      return { deviceConnected: false };
+    }
+  };
+
   const registry = new AdapterRegistry({
     vault,
     kgSink: kgSink ? kgSink.write.bind(kgSink) : null,
     ragSink: ragSink ? ragSink.write.bind(ragSink) : null,
     entityResolver,
+    adbReadiness: {
+      probe: adbReadinessProbe,
+      oneClickNames: ADB_ONE_CLICK_NAMES,
+    },
   });
 
   const engine = new AnalysisEngine({

package/src/lib/recent-session.js

@@ -0,0 +1,72 @@
+/**
+ * Resolve the most-recent session id across both stores (DB + JSONL).
+ *
+ * Shared by `cc agent --continue` and `cc session resume` (id-less form) so a
+ * user can pick up the last conversation with a one-liner — Claude-Code
+ * `claude --continue` parity.
+ */
+
+import { listSessions } from "./session-manager.js";
+import { listJsonlSessions } from "../harness/jsonl-session-store.js";
+import { feature } from "./feature-flags.js";
+
+/**
+ * Merge both stores into a single newest-first, id-deduped list.
+ *
+ * @param {object} ctx   bootstrap() context (may be null; db is optional)
+ * @param {object} [opts]
+ * @param {number} [opts.scan=20]  how many recent rows to merge per store
+ * @returns {Array<object>}  session rows (id, title, message_count, updated_at, _store)
+ */
+export function listRecentSessions(ctx, opts = {}) {
+  const scan = Math.max(1, opts.scan || 20);
+  const sessions = [];
+
+  if (ctx && ctx.db) {
+    try {
+      const db = ctx.db.getDatabase();
+      sessions.push(
+        ...listSessions(db, { limit: scan }).map((s) => ({
+          ...s,
+          _store: "db",
+        })),
+      );
+    } catch (err) {
+      /* db unavailable — fall through to JSONL */
+      void err;
+    }
+  }
+
+  if (feature("JSONL_SESSION")) {
+    try {
+      sessions.push(
+        ...listJsonlSessions({ limit: scan }).map((s) => ({
+          ...s,
+          _store: "jsonl",
+        })),
+      );
+    } catch (err) {
+      void err;
+    }
+  }
+
+  // Dedup by id (JSONL precedence via sort+seen), newest updated_at first.
+  const seen = new Set();
+  return sessions
+    .sort((a, b) => ((b.updated_at || "") > (a.updated_at || "") ? 1 : -1))
+    .filter((s) => {
+      if (!s || !s.id || seen.has(s.id)) return false;
+      seen.add(s.id);
+      return true;
+    });
+}
+
+/**
+ * @param {object} ctx   bootstrap() context (may be null; db is optional)
+ * @param {object} [opts] forwarded to {@link listRecentSessions}
+ * @returns {string|null}  the most-recently-updated session id, or null
+ */
+export function resolveMostRecentSessionId(ctx, opts = {}) {
+  const sessions = listRecentSessions(ctx, opts);
+  return sessions.length > 0 ? sessions[0].id : null;
+}

package/src/lib/session-picker.js

@@ -0,0 +1,68 @@
+/**
+ * Interactive "which session to resume?" picker — shared by `cc session resume`
+ * and `cc agent --resume/--continue` so both render the same list and apply the
+ * same fallbacks (Claude-Code `--resume` parity).
+ *
+ * Behaviour:
+ *  - 0 sessions            → { id: null }   (caller decides how to report)
+ *  - non-TTY / single / noPicker → most-recent, no prompt (claude --continue)
+ *  - TTY + >1 sessions     → inquirer `select`; Ctrl-C falls back to most-recent
+ *
+ * All non-determinism (the session list, TTY-ness, the prompt fn) is injectable
+ * via `deps` so the deterministic branches are unit-testable without a TTY.
+ */
+
+import chalk from "chalk";
+import { listRecentSessions } from "./recent-session.js";
+
+/** Render one session row for the picker list. */
+export function formatSessionChoice(s) {
+  const title = (s.title || "Untitled").slice(0, 50).padEnd(50);
+  const msgs = chalk.cyan(`${s.message_count ?? 0} msgs`);
+  const when = chalk.gray(s.updated_at || "");
+  const store = s._store === "jsonl" ? " " + chalk.yellow("[JSONL]") : "";
+  return {
+    name: `${title} ${msgs}  ${when}${store}`,
+    value: s.id,
+    short: String(s.id).slice(0, 12),
+  };
+}
+
+/**
+ * Resolve which recent session to resume.
+ *
+ * @param {object} ctx              bootstrap() context (db optional)
+ * @param {object} [opts]
+ * @param {string} [opts.message]   picker prompt
+ * @param {boolean} [opts.noPicker] force most-recent, skip the prompt
+ * @param {number} [opts.scan]      forwarded to listRecentSessions
+ * @param {object} [deps]           { listRecentSessions, isTTY, select }
+ * @returns {Promise<{id:string|null, sessions:Array, picked:boolean}>}
+ */
+export async function pickRecentSession(ctx, opts = {}, deps = {}) {
+  const list = deps.listRecentSessions || listRecentSessions;
+  const isTTY =
+    deps.isTTY !== undefined ? deps.isTTY : Boolean(process.stdin.isTTY);
+
+  const sessions = list(ctx, { scan: opts.scan });
+  if (!sessions || sessions.length === 0) {
+    return { id: null, sessions: [], picked: false };
+  }
+
+  // No interactive prompt possible/wanted → newest wins (claude --continue).
+  if (!isTTY || sessions.length === 1 || opts.noPicker) {
+    return { id: sessions[0].id, sessions, picked: false };
+  }
+
+  const select = deps.select || (await import("@inquirer/prompts")).select;
+  try {
+    const id = await select({
+      message: opts.message || "Resume which session?",
+      choices: sessions.map(formatSessionChoice),
+    });
+    return { id, sessions, picked: true };
+  } catch {
+    // Ctrl-C / non-interactive environment → fall back to most recent.
+    return { id: sessions[0].id, sessions, picked: false };
+  }
+}