mixdog 1.4.0 → 1.4.2

package/src/session-runtime/agent-tool-routing.mjs

@@ -5,55 +5,22 @@
  */
 
 import { clean } from '../runtime/shared/clean.mjs';
-
-const lower = (value) => clean(value).toLowerCase();
-
-// A pinned model named by its catalog display name ("GPT-6.1-Sol") is not a
-// wire id. Canonicalize it only on an unambiguous EXACT match: the id itself,
-// or a display name / label, case-insensitively, within the requested provider
-// (or across providers when none is given and exactly one row matches).
-// Anything else — no match, several matches, an empty or partial catalog —
-// returns the args unchanged: the catalog never refuses a model and never
-// substitutes a near one.
-export function canonicalizePinnedModel(args, rows) {
-  const model = clean(args?.model);
-  if (!model || !Array.isArray(rows)) return args;
-  const provider = lower(args.provider);
-  const pool = rows.filter((row) => row && (!provider || lower(row.provider) === provider));
-  const wanted = model.toLowerCase();
-  const exactId = pool.filter((row) => row.id === model);
-  // A partial catalog may lack the real id a display name collides with, so
-  // only an exact id can pass there; aliases wait for a complete catalog.
-  const partial = pool.some((row) => row.catalogPartial === true);
-  const hits = exactId.length
-    ? exactId
-    : partial
-      ? []
-      : pool.filter((row) => lower(row.id) === wanted || lower(row.display) === wanted || lower(row.label) === wanted);
-  const distinct = [...new Map(hits.map((row) => [`${row.provider}\n${row.id}`, row])).values()];
-  if (distinct.length !== 1) return args;
-  const [hit] = distinct;
-  if (hit.id === model && hit.provider === args.provider) return args;
-  return { ...args, provider: hit.provider, model: hit.id };
-}
+import { resolveRequestedModel } from './services/agent-tool/model-select.mjs';
 
 // `listProviderModels` is this runtime's provider catalog. The agent control
 // behind `executeAgentControl` (the daemon's canonical agent) has none, so a
-// display-name model is canonicalized here before it is forwarded. Only the
-// cached/quick catalog is read, so a spawn never waits on provider listings.
+// pinned model is resolved here, by the same rule the in-process agent tool
+// applies (exact id, display name, then every query word; ambiguous or
+// unknown names fail with candidates), and forwarded as the exact route.
 export function createRoutedAgentTool({ rt, agentTool, executeAgentControl = null, listProviderModels = null }) {
   const routedAgentTool = {
     ...agentTool,
     async execute(args, context = {}) {
       if (typeof executeAgentControl !== 'function') return agentTool.execute(args, context);
-      let routedArgs = args;
-      if (typeof listProviderModels === 'function' && clean(args?.model) && (clean(args.type) || 'spawn') === 'spawn') {
-        try {
-          routedArgs = canonicalizePinnedModel(args, await listProviderModels({ quick: true }));
-        } catch {
-          routedArgs = args;
-        }
-      }
+      const routedArgs =
+        typeof listProviderModels === 'function' && clean(args?.model) && (clean(args.type) || 'spawn') === 'spawn'
+          ? await resolveRequestedModel(args, listProviderModels)
+          : args;
       return executeAgentControl(routedArgs, context);
     },
     closeAll(reason, scope = {}) {

package/src/session-runtime/boot/tools.mjs

@@ -22,7 +22,11 @@ import { TOOL_DEFS as OFFICE_TOOL_DEFS } from '../../runtime/office/tool-defs.mj
 import { TOOL_DEFS as MEDIA_TOOL_DEFS } from '../../runtime/media/tool-defs.mjs';
 import { TOOL_DEFS as TIDY_TOOL_DEFS } from '../../runtime/tidy/tool-defs.mjs';
 import { TOOL_DEFS as VISUALIZE_BRIDGE_TOOL_DEFS } from '../../runtime/visualize-bridge/tool-defs.mjs';
-import { ASK_USER_TOOL_DEFS } from '../../runtime/agent/orchestrator/runtime-core/ask-user-tool-defs.mjs';
+import { TOOL_DEFS as EXPLORE_TOOL_DEFS } from '../../runtime/explore/tool-defs.mjs';
+import {
+  ASK_USER_TOOL_DEFS,
+  HANDOFF_USER_TOOL_DEFS,
+} from '../../runtime/agent/orchestrator/runtime-core/ask-user-tool-defs.mjs';
 import { REACTION_TOOL_DEFS } from '../../runtime/agent/orchestrator/runtime-core/reaction-tool-defs.mjs';
 import { SETUP_TOOL_DEFS } from '../setup-tool/tool-defs.mjs';
 import { createSetupToolExecutor } from '../setup-tool/executor.mjs';
@@ -169,8 +173,10 @@ function wireToolSurface(boot) {
     mediaToolDefs: MEDIA_TOOL_DEFS,
     tidyToolDefs: TIDY_TOOL_DEFS,
     visualizeToolDefs: VISUALIZE_BRIDGE_TOOL_DEFS,
+    exploreToolDefs: EXPLORE_TOOL_DEFS,
     setupToolDefs: SETUP_TOOL_DEFS,
     askUserToolDefs: ASK_USER_TOOL_DEFS,
+    handoffUserToolDefs: HANDOFF_USER_TOOL_DEFS,
     reactionToolDefs: REACTION_TOOL_DEFS,
     goalTools: goalRuntime.tools,
     agentTools: agentTool.tools,

package/src/session-runtime/bot-status.mjs

@@ -1,8 +1,9 @@
 /**
  * `session bots`: the state of the user's bots, read on demand (never injected
  * into a turn). One line per bot: its home chat (`sess_home_<id>`), the last
- * activity there and its latest line, whether it works now (its chat, or a
- * task session it runs), approvals waiting on the user, its routines and what
+ * activity there and its latest line, whether it works now (its chat, or work
+ * it sent running in a task session; a turn the user typed there is the
+ * user's), approvals waiting on the user, its routines and what
  * needs attention. With one bot (`session_id`: its id or chat id): its
  * routines, its held requests and its recent sessions.
  *
@@ -143,7 +144,7 @@ function span(ms) {
 const ago = (at, now) => `${span(now - at)} ago`;
 const until = (at, now) => (at <= now ? 'due now' : `in ${span(at - now)}`);
 
-async function defaultListBots() {
+export async function defaultListBots() {
   const [{ workflowHelpers }, { getPluginData, loadConfig }, { isAgentDisabled, isContactAgentId }] = await Promise.all(
     [
       import('./boot/shared.mjs'),
@@ -203,6 +204,109 @@ function routineDetail(routine, now) {
   return cut(`${routine.kind} ${quotedText(routine.name, 64)}: ${parts.join(', ')}`, 240);
 }
 
+/** Everything known about one bot, from the gathered state. */
+function botState(bot, ctx) {
+  const homeId = agentHomeSessionId(bot.id);
+  const owned = ctx.owned.get(bot.id) || [];
+  const home = ctx.rows.get(homeId) || null;
+  // Work this bot sent that is running now: a session working with the bot's
+  // send in flight (`handedBy`, bot-owned-work.mjs). A turn the user typed
+  // in the bot's task session is the user's, not the bot working.
+  const sentWork = (row) => isWorking(row) && row.handedBy?.includes(bot.id);
+  // Running task sessions: a turn whose report is still owed, or the bot's
+  // work running now.
+  const tasks = new Map();
+  const addTask = (id, title, at) => {
+    const known = tasks.get(id);
+    if (!known) tasks.set(id, { id, title, at });
+    else if (at && (!known.at || at < known.at)) known.at = at;
+  };
+  for (const watch of ctx.watches) {
+    if (watch.agentId !== bot.id || watch.target === 'session' || !watch.taskSessionId) continue;
+    addTask(watch.taskSessionId, watch.title, Number(watch.at) || 0);
+  }
+  for (const row of owned) {
+    if (row.id === homeId || roomMemberOfSession(row.id) || !sentWork(row)) continue;
+    addTask(row.id, row.title, Number(row.createdAt) || 0);
+  }
+  const running = [...tasks.values()].sort((left, right) => left.at - right.at || (left.id < right.id ? -1 : 1));
+  const held = ctx.held.filter((entry) => entry.agentId === bot.id);
+  const approvals = held.length + [homeId, ...running.map((task) => task.id)].filter(ctx.awaitingApproval).length;
+  const routines = ctx.routines.rows
+    .filter((routine) => (routine.owner || MIXY_AGENT_ID) === bot.id)
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  const flags = [];
+  if (approvals) flags.push(`${plural(approvals, 'approval')} waiting`);
+  for (const routine of routines) {
+    const trouble = routineTrouble(routine);
+    if (trouble.length) flags.push(`${quotedText(routine.name, 20)} ${trouble.join(', ')}`);
+  }
+  if (bot.disabled) flags.push('disabled');
+  return {
+    bot,
+    homeId,
+    home,
+    owned,
+    running,
+    held,
+    approvals,
+    routines,
+    flags,
+    working: isWorking(home) || running.some((task) => sentWork(ctx.rows.get(task.id))),
+    lastAt: activityOf(home),
+  };
+}
+
+function botLine(state, now) {
+  const { bot } = state;
+  const parts = [`${quotedText(bot.name, 40)} (${bot.id})`, `chat ${state.homeId}`];
+  if (bot.self) parts.push('you');
+  parts.push(state.working ? 'working' : 'idle');
+  if (state.flags.length) parts.push(`attention: ${state.flags.join('; ')}`);
+  parts.push(state.lastAt ? `last ${ago(state.lastAt, now)}` : 'no chat yet');
+  if (state.running.length) {
+    const [first] = state.running;
+    const more = state.running.length > 1 ? ` +${state.running.length - 1}` : '';
+    const count = state.running.length > 1 ? `${state.running.length} tasks:` : 'task';
+    parts.push(`${count} "${quotedText(first.title, 24)}"${first.at ? ` ${span(now - first.at)}` : ''}${more}`);
+  }
+  if (state.routines.length) {
+    const next = state.routines
+      .filter((routine) => routine.enabled !== false && epoch(routine.nextFireAt))
+      .sort((left, right) => epoch(left.nextFireAt) - epoch(right.nextFireAt))[0];
+    parts.push(
+      `${plural(state.routines.length, 'routine')}${next ? `, next ${quotedText(next.name, 20)} ${until(epoch(next.nextFireAt), now)}` : ''}`
+    );
+  }
+  const fixed = parts.join(' · ');
+  const preview = oneLine(state.home?.lastMessagePreview || state.home?.preview);
+  const room = BOT_LINE_LIMIT - fixed.length - 5;
+  return cut(preview && room >= MIN_PREVIEW ? `${fixed} · "${quotedText(preview, room)}"` : fixed, BOT_LINE_LIMIT);
+}
+
+const mixyBot = (ctx) => ({ id: MIXY_AGENT_ID, name: ctx.mixy, self: true });
+
+/** The bots the caller sees: every bot then Mixy when she has something to
+ *  show, or just the caller's own bot. */
+function visibleStates(ctx) {
+  if (ctx.own) {
+    const bot = ctx.own === MIXY_AGENT_ID ? mixyBot(ctx) : ctx.bots[0];
+    return bot ? [botState(bot, ctx)] : [];
+  }
+  const states = ctx.bots
+    .map((bot) => botState(bot, ctx))
+    .sort(
+      (left, right) =>
+        Number(right.flags.length > 0) - Number(left.flags.length > 0) ||
+        Number(right.working) - Number(left.working) ||
+        right.lastAt - left.lastAt ||
+        (left.bot.id < right.bot.id ? -1 : 1)
+    );
+  const mixy = botState(mixyBot(ctx), ctx);
+  if (mixy.routines.length || mixy.running.length || mixy.approvals) states.push(mixy);
+  return states;
+}
+
 export function createBotStatus({
   getSessionService,
   listBots = defaultListBots,
@@ -259,104 +363,6 @@ export function createBotStatus({
     };
   }
 
-  /** Everything known about one bot, from the gathered state. */
-  function botState(bot, ctx) {
-    const homeId = agentHomeSessionId(bot.id);
-    const owned = ctx.owned.get(bot.id) || [];
-    const home = ctx.rows.get(homeId) || null;
-    // Running task sessions: a turn whose report is still owed, or one working now.
-    const tasks = new Map();
-    const addTask = (id, title, at) => {
-      const known = tasks.get(id);
-      if (!known) tasks.set(id, { id, title, at });
-      else if (at && (!known.at || at < known.at)) known.at = at;
-    };
-    for (const watch of ctx.watches) {
-      if (watch.agentId !== bot.id || watch.target === 'session' || !watch.taskSessionId) continue;
-      addTask(watch.taskSessionId, watch.title, Number(watch.at) || 0);
-    }
-    for (const row of owned) {
-      if (row.id === homeId || roomMemberOfSession(row.id) || !isWorking(row)) continue;
-      addTask(row.id, row.title, Number(row.createdAt) || 0);
-    }
-    const running = [...tasks.values()].sort((left, right) => left.at - right.at || (left.id < right.id ? -1 : 1));
-    const held = ctx.held.filter((entry) => entry.agentId === bot.id);
-    const approvals = held.length + [homeId, ...running.map((task) => task.id)].filter(ctx.awaitingApproval).length;
-    const routines = ctx.routines.rows
-      .filter((routine) => (routine.owner || MIXY_AGENT_ID) === bot.id)
-      .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
-    const flags = [];
-    if (approvals) flags.push(`${plural(approvals, 'approval')} waiting`);
-    for (const routine of routines) {
-      const trouble = routineTrouble(routine);
-      if (trouble.length) flags.push(`${quotedText(routine.name, 20)} ${trouble.join(', ')}`);
-    }
-    if (bot.disabled) flags.push('disabled');
-    return {
-      bot,
-      homeId,
-      home,
-      owned,
-      running,
-      held,
-      approvals,
-      routines,
-      flags,
-      working: isWorking(home) || running.some((task) => isWorking(ctx.rows.get(task.id))),
-      lastAt: activityOf(home),
-    };
-  }
-
-  function botLine(state, now) {
-    const { bot } = state;
-    const parts = [`${quotedText(bot.name, 40)} (${bot.id})`, `chat ${state.homeId}`];
-    if (bot.self) parts.push('you');
-    parts.push(state.working ? 'working' : 'idle');
-    if (state.flags.length) parts.push(`attention: ${state.flags.join('; ')}`);
-    parts.push(state.lastAt ? `last ${ago(state.lastAt, now)}` : 'no chat yet');
-    if (state.running.length) {
-      const [first] = state.running;
-      const more = state.running.length > 1 ? ` +${state.running.length - 1}` : '';
-      const count = state.running.length > 1 ? `${state.running.length} tasks:` : 'task';
-      parts.push(`${count} "${quotedText(first.title, 24)}"${first.at ? ` ${span(now - first.at)}` : ''}${more}`);
-    }
-    if (state.routines.length) {
-      const next = state.routines
-        .filter((routine) => routine.enabled !== false && epoch(routine.nextFireAt))
-        .sort((left, right) => epoch(left.nextFireAt) - epoch(right.nextFireAt))[0];
-      parts.push(
-        `${plural(state.routines.length, 'routine')}${next ? `, next ${quotedText(next.name, 20)} ${until(epoch(next.nextFireAt), now)}` : ''}`
-      );
-    }
-    const fixed = parts.join(' · ');
-    const preview = oneLine(state.home?.lastMessagePreview || state.home?.preview);
-    const room = BOT_LINE_LIMIT - fixed.length - 5;
-    return cut(preview && room >= MIN_PREVIEW ? `${fixed} · "${quotedText(preview, room)}"` : fixed, BOT_LINE_LIMIT);
-  }
-
-  const mixyBot = (ctx) => ({ id: MIXY_AGENT_ID, name: ctx.mixy, self: true });
-
-  /** The bots the caller sees: every bot then Mixy when she has something to
-   *  show, or just the caller's own bot. */
-  function visibleStates(ctx) {
-    if (ctx.own) {
-      const bot = ctx.own === MIXY_AGENT_ID ? mixyBot(ctx) : ctx.bots[0];
-      return bot ? [botState(bot, ctx)] : [];
-    }
-    const states = ctx.bots
-      .map((bot) => botState(bot, ctx))
-      .sort(
-        (left, right) =>
-          Number(right.flags.length > 0) - Number(left.flags.length > 0) ||
-          Number(right.working) - Number(left.working) ||
-          right.lastAt - left.lastAt ||
-          (left.bot.id < right.bot.id ? -1 : 1)
-      );
-    const mixy = botState(mixyBot(ctx), ctx);
-    if (mixy.routines.length || mixy.running.length || mixy.approvals) states.push(mixy);
-    return states;
-  }
-
   async function overview(own) {
     const ctx = await gather(own);
     const states = visibleStates(ctx);

package/src/session-runtime/bot-target.mjs

@@ -0,0 +1,38 @@
+// A bot id as the `session_id` of read, send and status: a bot's chat is a
+// session of its own (`sess_home_<id>`), but the schema also lets a model name
+// the bot (`bots` takes either), so the id resolves to that home chat — before
+// any check of the target, so the bot-chain, hop and task-origin checks see
+// the chat they would for `sess_home_<id>`. A minted session id always has an
+// underscore, a normalized bot id never does (agent-home.mjs), so only ids
+// shaped like a bot id are looked up.
+import { MIXY_AGENT_ID, agentHomeSessionId } from '../runtime/agent/orchestrator/session/agent-home.mjs';
+import { defaultListBots, quotedText } from './bot-status.mjs';
+
+const MAX_NAMED_BOTS = 30;
+/** The actions whose `session_id` may be a bot id. */
+export const BOT_TARGET_ACTIONS = new Set(['read', 'send', 'status']);
+
+/** The ids of the bots a send can reach: Mixy and every contact agent. */
+async function botIds(listBots) {
+  return [MIXY_AGENT_ID, ...(await listBots()).map((bot) => bot.id)];
+}
+
+/** `target`'s home chat when it is a known bot id, else `target` unchanged. */
+export async function resolveBotTarget(target, listBots = defaultListBots) {
+  const home = agentHomeSessionId(target);
+  return home && (await botIds(listBots)).includes(target) ? home : target;
+}
+
+/** Whether `target` is shaped like a bot id (so, with no session, a mistyped one). */
+export const isBotShaped = (target) => agentHomeSessionId(target) !== '';
+
+/** The error for a bot-shaped `target` that is neither a known bot nor a session. */
+export async function unknownBotError(target, listBots = defaultListBots, cause) {
+  const ids = await botIds(listBots);
+  const named = ids.slice(0, MAX_NAMED_BOTS).join(', ');
+  const more = ids.length > MAX_NAMED_BOTS ? `, … (${ids.length - MAX_NAMED_BOTS} more)` : '';
+  return new Error(
+    `session: "${quotedText(target, 64)}" is neither a session nor a known bot id; bot ids: ${named}${more}; session action=list finds session ids`,
+    cause ? { cause } : undefined
+  );
+}

package/src/session-runtime/channel-config-api.mjs

@@ -12,7 +12,12 @@ import {
   testWebhook,
   withScheduleRenameReserved,
 } from './services/channel-admin.mjs';
-import { getSchedule, markScheduleFailure, markScheduleSkipped, markScheduleSuccess } from '../runtime/channels/lib/schedules-db.mjs';
+import {
+  getSchedule,
+  markScheduleFailure,
+  markScheduleSkipped,
+  markScheduleSuccess,
+} from '../runtime/channels/lib/schedules-db.mjs';
 import { scheduleRenameUncertainError } from '../runtime/channels/lib/schedule-errors.mjs';
 import { loadEndpointConfig, readEndpointLastPayload } from '../runtime/channels/lib/webhooks-db.mjs';
 import { webhookEventSummary, webhookRunPrompt } from '../runtime/channels/lib/webhook/session-dispatch.mjs';

package/src/session-runtime/connector-merge-migration.mjs

@@ -1,6 +1,6 @@
-// After the multi-account connector merge (connector-catalog.mjs
-// mergeConnectorAccountServers) `gmail-2`, `google-calendar-2`… are accounts of
-// one server, no longer servers. Every store of ours that keys a setting by
+// After the connector merge (connector-catalog.mjs mergeConnectorAccountServers)
+// `gmail-2`, `notion-2`, `postgres-2`… are accounts of their connector's one
+// server, no longer servers. Every store of ours that keys a setting by
 // MCP server name must name the surviving server instead:
 //   agents/<id>/agent.json, bots/<id>/agent.json   connectors.off / connectors.tools
 //                                                  (a legacy allow list too)
@@ -11,14 +11,15 @@
 // name models, not servers.) Project and plugin hook files are the user's or
 // the plugin's own and are never rewritten here.
 //
-// Rule: the merged connector is OFF for an agent/project only when EVERY
-// merged server was off (the same rule as the merged server's `enabled`: one
-// working account keeps the connector usable). Per-tool permissions move to
-// the surviving name; where two merged servers disagree on a tool the MORE
-// PERMISSIVE permission wins, as "on beats off" does at server level. Entries
-// of a server that was off are dormant and are dropped when the connector
-// stays on, so they never become live. A setting that names no merged-away
-// server is never touched, which makes every run after the first a no-op.
+// Rule: differences are ignored and the topmost server decides. The merged
+// connector is on or off for an agent/project as the surviving server was
+// there when the setting names it, else as the lowest-numbered merged server
+// it names (so a switched-off `-N` server never becomes reachable through the
+// merge). Per-tool permissions move to the surviving name; where merged
+// servers disagree on a tool the surviving server's own entry wins, else the
+// first merged server's. Entries of a server that was off are dormant and
+// dropped when the connector stays on. A setting that names no merged-away
+// server is never touched, so every run after the first is a no-op.
 //
 // The merge is saved to the config once, so the rename mapping outlives it:
 // `<data>/connector-merge-pending.json` ({ merged: [{ name, from }] }) is
@@ -35,7 +36,6 @@ import { readdirSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { normalizeRules, standardConfigReport } from './services/hook-bus/config.mjs';
 import {
-  PERMISSION_RANK,
   PROJECT_CONNECTORS_FILE,
   connectorEnabled,
   parseConnectorPolicy,
@@ -56,7 +56,8 @@ function mapMergedConnectorPolicy(policy, merged) {
       current.off.includes(server) || current.allow?.includes(server) || Object.hasOwn(current.tools, server);
     if (!gone.some(named)) continue;
     const live = from.filter((server) => connectorEnabled(current, server));
-    const on = live.length > 0;
+    // `from` lists the surviving server first, then the others lowest-numbered first.
+    const on = connectorEnabled(current, from.find(named));
     const off = current.off.filter((server) => !from.includes(server));
     const allow = current.allow?.filter((server) => !from.includes(server));
     if (allow && on) allow.push(name);
@@ -64,9 +65,11 @@ function mapMergedConnectorPolicy(policy, merged) {
     const tools = { ...current.tools };
     for (const server of from) delete tools[server];
     const moved = {};
-    for (const server of on ? live : from) {
+    const sources = on ? live : from;
+    for (const server of [name, ...sources.filter((id) => id !== name)]) {
+      if (!sources.includes(server)) continue;
       for (const [tool, permission] of Object.entries(current.tools[server] || {})) {
-        if (!(tool in moved) || PERMISSION_RANK[permission] > PERMISSION_RANK[moved[tool]]) moved[tool] = permission;
+        if (!(tool in moved)) moved[tool] = permission;
       }
     }
     if (Object.keys(moved).length) tools[name] = moved;

package/src/session-runtime/conversation-import/codex-titles.mjs

@@ -0,0 +1,88 @@
+/**
+ * The thread titles Codex itself stores, by thread id (read-only):
+ *
+ *   state_<N>.sqlite   `threads.title`, overridden by `threads.name` (a rename)
+ *   session_index.jsonl  append-only `{ id, thread_name }`; the latest
+ *                        non-empty name of an id wins and overrides the DB
+ *
+ * Anything unreadable is skipped: a missing or locked store simply leaves the
+ * conversation to the title derived from its messages.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { titleFromText } from '../../runtime/agent/orchestrator/session/conversation-import/turns.mjs';
+
+const STATE_DB_RE = /^state_(\d+)\.sqlite$/i;
+
+async function newestStateDb(home) {
+  let newest = null;
+  for (const name of await readdir(home).catch(() => [])) {
+    const version = STATE_DB_RE.exec(name)?.[1];
+    if (version !== undefined && (!newest || Number(version) > newest.version)) {
+      newest = { name, version: Number(version) };
+    }
+  }
+  return newest ? join(home, newest.name) : null;
+}
+
+function readStateRows(path) {
+  const db = new DatabaseSync(path, { readOnly: true });
+  try {
+    const columns = new Set(
+      db
+        .prepare('PRAGMA table_info(threads)')
+        .all()
+        .map((column) => column.name)
+    );
+    const wanted = ['title', 'name'].filter((column) => columns.has(column));
+    if (!wanted.length) return [];
+    return db.prepare(`SELECT id, ${wanted.join(', ')} FROM threads`).all();
+  } finally {
+    db.close();
+  }
+}
+
+async function readStateTitles(home, titles) {
+  try {
+    const path = await newestStateDb(home);
+    if (!path) return;
+    const rows = readStateRows(path);
+    for (const column of ['title', 'name']) {
+      for (const row of rows) {
+        const title = titleFromText(row[column]);
+        if (title && typeof row.id === 'string') titles.set(row.id, title);
+      }
+    }
+  } catch {
+    /* unreadable store: fall back to the session index and derived titles */
+  }
+}
+
+async function readIndexTitles(home, titles) {
+  let text;
+  try {
+    text = await readFile(join(home, 'session_index.jsonl'), 'utf8');
+  } catch {
+    return;
+  }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const title = titleFromText(entry?.thread_name);
+    if (title && typeof entry.id === 'string') titles.set(entry.id, title);
+  }
+}
+
+/** Map of Codex thread id → its stored title (whitespace-normalized, ≤100 chars). */
+export async function loadCodexThreadTitles(home) {
+  const titles = new Map();
+  await readStateTitles(home, titles);
+  await readIndexTitles(home, titles);
+  return titles;
+}