@ai-matrx/coding-sessions 0.1.166 → 0.3.0

package/dist/engine/index.d.cts

@@ -1,4 +1,4 @@
-export { e as CodingSessionsAgentsOptions, c as CodingSessionsEngine, d as CodingSessionsEngineOptions, D as DEFAULT_SERVER_URL, f as DEFAULT_SUPABASE_URL, E as EFFORT_LEVELS, P as PreferenceStore, g as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, h as RawBackupPolicy, i as RawBackupSink, j as RunStatus, k as buildCleanEnv, l as claudeDefaults, m as codexDefaults, n as createAiMatrxRawBackupSink, o as createCodingSessionsEngine, p as createRawBackupScheduler, q as defaultProviderHomes, r as describeActivity, s as describeProviderStatus, t as discoverLocalSessions, u as endsWithOpenToolCall, v as findDrivingProcess, w as findSessionFile, x as isAllowedEnvName, y as listProcesses, z as readSessionFile, A as searchLocalChats, B as sessionActivity, F as snippetAround } from '../index-CDeDKQHe.cjs';
+export { f as CodexHome, e as CodingSessionsAgentsOptions, c as CodingSessionsEngine, d as CodingSessionsEngineOptions, D as DEFAULT_SERVER_URL, g as DEFAULT_SUPABASE_URL, E as EFFORT_LEVELS, P as PreferenceStore, h as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, i as RawBackupPolicy, j as RawBackupSink, k as RunStatus, T as TitleHint, l as TitleHints, m as buildCleanEnv, n as claudeDefaults, o as codexDefaults, p as codexHome, q as createAiMatrxRawBackupSink, r as createCodingSessionsEngine, s as createRawBackupScheduler, t as createTitleHintsStore, u as defaultProviderHomes, v as describeActivity, w as describeProviderStatus, x as discoverLocalSessions, y as endsWithOpenToolCall, z as findDrivingProcess, A as findSessionFile, B as isAllowedEnvName, F as listProcesses, G as readSessionFile, H as searchLocalChats, I as sessionActivity, J as snippetAround, K as titleHintKey } from '../index-Bbe11HoB.cjs';
 import '@ai-matrx/agents/portable/mcp';
 import '@ai-matrx/agents/portable';
 import '@ai-matrx/data';

package/dist/engine/index.d.ts

@@ -1,4 +1,4 @@
-export { e as CodingSessionsAgentsOptions, c as CodingSessionsEngine, d as CodingSessionsEngineOptions, D as DEFAULT_SERVER_URL, f as DEFAULT_SUPABASE_URL, E as EFFORT_LEVELS, P as PreferenceStore, g as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, h as RawBackupPolicy, i as RawBackupSink, j as RunStatus, k as buildCleanEnv, l as claudeDefaults, m as codexDefaults, n as createAiMatrxRawBackupSink, o as createCodingSessionsEngine, p as createRawBackupScheduler, q as defaultProviderHomes, r as describeActivity, s as describeProviderStatus, t as discoverLocalSessions, u as endsWithOpenToolCall, v as findDrivingProcess, w as findSessionFile, x as isAllowedEnvName, y as listProcesses, z as readSessionFile, A as searchLocalChats, B as sessionActivity, F as snippetAround } from '../index-CDeDKQHe.js';
+export { f as CodexHome, e as CodingSessionsAgentsOptions, c as CodingSessionsEngine, d as CodingSessionsEngineOptions, D as DEFAULT_SERVER_URL, g as DEFAULT_SUPABASE_URL, E as EFFORT_LEVELS, P as PreferenceStore, h as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, i as RawBackupPolicy, j as RawBackupSink, k as RunStatus, T as TitleHint, l as TitleHints, m as buildCleanEnv, n as claudeDefaults, o as codexDefaults, p as codexHome, q as createAiMatrxRawBackupSink, r as createCodingSessionsEngine, s as createRawBackupScheduler, t as createTitleHintsStore, u as defaultProviderHomes, v as describeActivity, w as describeProviderStatus, x as discoverLocalSessions, y as endsWithOpenToolCall, z as findDrivingProcess, A as findSessionFile, B as isAllowedEnvName, F as listProcesses, G as readSessionFile, H as searchLocalChats, I as sessionActivity, J as snippetAround, K as titleHintKey } from '../index-Bbe11HoB.js';
 import '@ai-matrx/agents/portable/mcp';
 import '@ai-matrx/agents/portable';
 import '@ai-matrx/data';

package/dist/engine/index.js

@@ -1133,6 +1133,9 @@ var PROVIDER_LABEL = {
   claude: "Claude Code",
   codex: "Codex"
 };
+function chatKey(provider, providerSessionId, sessionId) {
+  return providerSessionId ? `${provider}:${providerSessionId}` : `session:${sessionId ?? ""}`;
+}
 var TERMINAL_RUN_STATUSES = ["completed", "stopped", "failed"];
 function isTerminalRunStatus(status) {
   return TERMINAL_RUN_STATUSES.includes(status);
@@ -1447,6 +1450,78 @@ import fs4 from "fs/promises";
 import os3 from "os";
 import path5 from "path";
 
+// src/sessions/titles.ts
+var TITLE_MAX = 300;
+var BRIDGE_PLACEHOLDER = /^AI Matrx · [a-z-]+$/;
+var TITLE_PRECEDENCE = [
+  /** The person's rename inside Matrx (Coding Sessions' preference). */
+  "override",
+  /** What the coding app's own sidebar shows: Claude's record `title` (renames included); Codex's thread name; Cursor's name. */
+  "app",
+  /** The title the app last showed, remembered by the claude-accounts engine after the record went away. */
+  "app-remembered",
+  /** Claude Code transcript entries (the last one of each kind that is not the bridge placeholder). */
+  "custom-title",
+  "ai-title",
+  "agent-name",
+  "summary",
+  /** The person's first typed message (Codex: the thread's title / first user message). */
+  "first-prompt",
+  "last-prompt"
+];
+var STAMPABLE = /* @__PURE__ */ new Set(["custom-title", "ai-title", "agent-name"]);
+function isBridgePlaceholder(value) {
+  return typeof value === "string" && BRIDGE_PLACEHOLDER.test(value.trim());
+}
+function cleanTitle(value) {
+  if (typeof value !== "string") return null;
+  const line = value.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0);
+  if (!line) return null;
+  return line.length > TITLE_MAX ? `${line.slice(0, TITLE_MAX - 1)}\u2026` : line;
+}
+function resolveSessionTitle(sources) {
+  for (const source of TITLE_PRECEDENCE) {
+    const raw = sources[source];
+    if (STAMPABLE.has(source) && isBridgePlaceholder(raw)) continue;
+    const title = cleanTitle(raw);
+    if (title) return { title, source };
+  }
+  return null;
+}
+function claudeTranscriptTitleSources(head, tail = []) {
+  const out = {};
+  const take = (source, value) => {
+    if (typeof value !== "string" || !value.trim()) return;
+    if (STAMPABLE.has(source) && isBridgePlaceholder(value)) return;
+    out[source] = value;
+  };
+  const normalizer = createClaudeNormalizer();
+  let firstPrompt = null;
+  const scan = (entries, findPrompt) => {
+    for (const entry of entries) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const e = entry;
+      if (e.type === "custom-title") take("custom-title", e.customTitle);
+      else if (e.type === "ai-title") take("ai-title", e.aiTitle);
+      else if (e.type === "agent-name") take("agent-name", e.agentName);
+      else if (e.type === "summary") take("summary", e.summary);
+      else if (e.type === "last-prompt") take("last-prompt", e.lastPrompt);
+      else if (findPrompt && firstPrompt === null) {
+        for (const item of normalizer.push(entry)) {
+          if (item.kind === "user" && item.text.trim()) {
+            firstPrompt = item.text;
+            break;
+          }
+        }
+      }
+    }
+  };
+  scan(head, true);
+  scan(tail, false);
+  if (firstPrompt !== null) out["first-prompt"] = firstPrompt;
+  return out;
+}
+
 // src/engine/activity.ts
 import { execFile as execFile2 } from "child_process";
 var RECENT_WRITE_MS = 2 * 60 * 1e3;
@@ -1512,11 +1587,18 @@ function describeActivity(input) {
 }
 
 // src/engine/files.ts
+function codexHome(dir) {
+  return {
+    sessions: path5.join(dir, "sessions"),
+    archived: path5.join(dir, "archived_sessions"),
+    index: path5.join(dir, "session_index.jsonl")
+  };
+}
 function defaultProviderHomes(home = os3.homedir()) {
   return {
     claudeProjects: path5.join(home, ".claude", "projects"),
-    codexSessions: path5.join(home, ".codex", "sessions"),
-    codexIndex: path5.join(home, ".codex", "session_index.jsonl")
+    claudeVault: path5.join(home, ".claude", "claude-app-vault"),
+    codex: [codexHome(path5.join(home, ".codex"))]
   };
 }
 var UUIDISH = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
@@ -1550,7 +1632,7 @@ async function claudeCandidates(root) {
   }
   return out;
 }
-async function codexCandidates(root) {
+async function codexTree(root) {
   const out = [];
   for (const year of await safeReaddir(root)) {
     if (!year.isDirectory()) continue;
@@ -1558,17 +1640,23 @@ async function codexCandidates(root) {
       if (!month.isDirectory()) continue;
       for (const day of await safeReaddir(path5.join(root, year.name, month.name))) {
         if (!day.isDirectory()) continue;
-        const dir = path5.join(root, year.name, month.name, day.name);
-        const entries = await safeReaddir(dir);
-        const stats = await Promise.all(
-          entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", path5.join(dir, e.name)))
-        );
-        for (const s of stats) if (s) out.push(s);
+        out.push(...await codexFlat(path5.join(root, year.name, month.name, day.name), false));
       }
     }
   }
   return out;
 }
+async function codexFlat(dir, archived) {
+  const entries = await safeReaddir(dir);
+  const stats = await Promise.all(
+    entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", path5.join(dir, e.name)))
+  );
+  return stats.filter((s) => s !== null).map((s) => archived ? { ...s, archived: true } : s);
+}
+async function codexCandidates(homes) {
+  const lists = await Promise.all(homes.flatMap((h) => [codexTree(h.sessions), codexFlat(h.archived, true)]));
+  return lists.flat();
+}
 async function readSlice(file, start, length) {
   const handle = await fs4.open(file, "r");
   try {
@@ -1590,56 +1678,38 @@ function completeLines(text, droppedFirst) {
 }
 var HEAD_BYTES = 256 * 1024;
 var TAIL_BYTES = 128 * 1024;
-function oneLine(text, max = 140) {
-  const flat = text.replace(/\s+/g, " ").trim();
-  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
-}
 async function describeClaude(candidate) {
   const head = parseJsonl(completeLines(await readSlice(candidate.file, 0, HEAD_BYTES), false));
   const tailStart = Math.max(0, candidate.size - TAIL_BYTES);
   const tail = tailStart > 0 ? parseJsonl(completeLines(await readSlice(candidate.file, tailStart, TAIL_BYTES), true)) : head;
   let cwd = null;
-  let firstPrompt = null;
   let entrypoint = null;
-  const normalizer = createClaudeNormalizer();
   for (const entry of head) {
     if (typeof entry !== "object" || entry === null) continue;
     const e = entry;
     if (!cwd && typeof e.cwd === "string") cwd = e.cwd;
     if (!entrypoint && typeof e.entrypoint === "string") entrypoint = e.entrypoint;
-    if (firstPrompt === null) {
-      for (const item of normalizer.push(entry)) {
-        if (item.kind === "user") {
-          firstPrompt = item.text;
-          break;
-        }
-      }
-    }
-    if (cwd && firstPrompt !== null) break;
+    if (cwd && entrypoint) break;
   }
-  const titles = { custom: null, ai: null, agent: null, summary: null, last: null };
-  for (const entry of [...head, ...tail]) {
-    if (typeof entry !== "object" || entry === null) continue;
-    const e = entry;
-    if (e.type === "custom-title" && typeof e.customTitle === "string") titles.custom = e.customTitle;
-    if (e.type === "ai-title" && typeof e.aiTitle === "string") titles.ai = e.aiTitle;
-    if (e.type === "agent-name" && typeof e.agentName === "string") titles.agent = e.agentName;
-    if (e.type === "summary" && typeof e.summary === "string") titles.summary = e.summary;
-    if (e.type === "last-prompt" && typeof e.lastPrompt === "string") titles.last = e.lastPrompt;
-  }
-  const title = titles.custom ?? titles.ai ?? titles.agent ?? titles.summary ?? firstPrompt ?? titles.last;
-  if (!title) return null;
+  const resolved = resolveSessionTitle(claudeTranscriptTitleSources(head, tailStart > 0 ? tail : []));
+  if (!resolved) return null;
   return {
     provider: "claude",
     providerSessionId: candidate.id,
     cwd,
-    title: oneLine(title),
+    title: resolved.title,
+    titleSource: resolved.source,
     updatedAt: new Date(candidate.mtimeMs).toISOString(),
     source: entrypoint,
     activeElsewhere: null
   };
 }
-async function readCodexIndex(file) {
+async function readCodexIndex(files) {
+  const names = /* @__PURE__ */ new Map();
+  for (const file of files) for (const [id, name] of await readCodexIndexFile(file)) if (!names.has(id)) names.set(id, name);
+  return names;
+}
+async function readCodexIndexFile(file) {
   const names = /* @__PURE__ */ new Map();
   let text;
   try {
@@ -1685,18 +1755,26 @@ async function describeCodex(candidate, names) {
     }
   }
   if (isSubAgent) return null;
-  const title = names.get(candidate.id) ?? firstPrompt;
-  if (!title) return null;
+  const resolved = resolveSessionTitle({ app: names.get(candidate.id), "first-prompt": firstPrompt });
+  if (!resolved) return null;
   return {
     provider: "codex",
     providerSessionId: candidate.id,
     cwd,
-    title: oneLine(title),
+    title: resolved.title,
+    titleSource: resolved.source,
+    ...candidate.archived ? { archived: true } : {},
     updatedAt: new Date(candidate.mtimeMs).toISOString(),
     source,
     activeElsewhere: null
   };
 }
+async function codexNames(homes, appTitles) {
+  if (!appTitles) return readCodexIndex(homes.codex.map((h) => h.index));
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, title] of appTitles) if (key.startsWith("codex:")) out.set(key.slice(6), title);
+  return out;
+}
 async function readTail(file, size) {
   const start = Math.max(0, size - TAIL_BYTES);
   return parseJsonl(completeLines(await readSlice(file, start, Math.min(size, TAIL_BYTES)), start > 0));
@@ -1736,8 +1814,8 @@ async function discoverLocalSessions(options = {}) {
   const homes = options.homes ?? defaultProviderHomes();
   const [claude, codex, names] = await Promise.all([
     claudeCandidates(homes.claudeProjects),
-    codexCandidates(homes.codexSessions),
-    readCodexIndex(homes.codexIndex)
+    codexCandidates(homes.codex),
+    codexNames(homes, options.appTitles)
   ]);
   const candidates = [...claude, ...codex].sort((a, b) => b.mtimeMs - a.mtimeMs);
   const processes = await listProcesses();
@@ -1757,9 +1835,14 @@ async function discoverLocalSessions(options = {}) {
 }
 async function findSessionFile(provider, providerSessionId, homes = defaultProviderHomes()) {
   if (!/^[0-9a-f-]{36}$/i.test(providerSessionId)) return null;
-  const candidates = provider === "claude" ? await claudeCandidates(homes.claudeProjects) : await codexCandidates(homes.codexSessions);
+  const candidates = provider === "claude" ? await claudeCandidates(homes.claudeProjects) : await codexCandidates(homes.codex);
   const hits = candidates.filter((c) => c.id === providerSessionId).sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return hits[0]?.file ?? null;
+  if (hits[0]) return hits[0].file;
+  if (provider === "claude" && homes.claudeVault) {
+    const copy = path5.join(homes.claudeVault, providerSessionId, "transcript.jsonl");
+    if ((await fs4.stat(copy).catch(() => null))?.isFile()) return copy;
+  }
+  return null;
 }
 var HISTORY_BUDGET = 24 * 1024 * 1024;
 var MAX_HISTORY_BUDGET = 256 * 1024 * 1024;
@@ -1809,12 +1892,12 @@ async function readSessionFile(provider, file, endOffset, maxBytes = HISTORY_BUD
 async function listSessionFiles(homes = defaultProviderHomes()) {
   const [claude, codex] = await Promise.all([
     claudeCandidates(homes.claudeProjects),
-    codexCandidates(homes.codexSessions)
+    codexCandidates(homes.codex)
   ]);
   return [...claude, ...codex].sort((a, b) => b.mtimeMs - a.mtimeMs);
 }
-async function describeSessionFile(candidate, codexNames) {
-  return (candidate.provider === "claude" ? describeClaude(candidate) : describeCodex(candidate, codexNames)).catch(
+async function describeSessionFile(candidate, codexNames2) {
+  return (candidate.provider === "claude" ? describeClaude(candidate) : describeCodex(candidate, codexNames2)).catch(
     () => null
   );
 }
@@ -1852,7 +1935,7 @@ var PreferenceStore = class {
     if (!key || key.length > 200) throw new Error("That chat can't be found.");
     const next = { ...this.data[key] };
     if ("title" in patch) {
-      const title = typeof patch.title === "string" ? patch.title.replace(/\s+/g, " ").trim().slice(0, 200) : "";
+      const title = typeof patch.title === "string" ? patch.title.replace(/\s+/g, " ").trim().slice(0, TITLE_MAX) : "";
       if (title) next.title = title;
       else delete next.title;
     }
@@ -1870,6 +1953,18 @@ var PreferenceStore = class {
     this.persist();
     return this.all();
   }
+  /**
+   * Move a preference to the chat's lasting key (`session:<id>` → `<provider>:<id>` once the
+   * provider's id is known), so a rename made early is the one rename everywhere. A preference
+   * already under the lasting key wins field by field.
+   */
+  rekey(from, to) {
+    if (from === to || !this.data[from]) return false;
+    this.data[to] = { ...this.data[from], ...this.data[to] };
+    delete this.data[from];
+    this.persist();
+    return true;
+  }
   persist() {
     const snapshot = JSON.stringify(this.data, null, 1);
     this.writing = this.writing.then(async () => {
@@ -1997,12 +2092,12 @@ async function searchLocalChats(query, options = {}) {
   const raw = JSON.stringify(needle).slice(1, -1);
   const limit = Math.max(1, Math.min(options.limit ?? 30, 100));
   const deadline = Date.now() + (options.budgetMs ?? 3500);
-  const names = await readCodexIndex(homes.codexIndex);
+  const names = await codexNames(homes, options.appTitles);
   const hits = [];
   let i = cursor;
   for (; i < files.length && hits.length < limit && Date.now() < deadline; i += 1) {
     const candidate = files[i];
-    const named = candidate.provider === "codex" ? names.get(candidate.id) : void 0;
+    const named = options.appTitles?.get(`${candidate.provider}:${candidate.id}`) ?? (candidate.provider === "codex" ? names.get(candidate.id) : void 0);
     const nameHit = named !== void 0 && named.toLowerCase().includes(needle);
     const scanned = nameHit ? null : await scanFile(candidate.provider, candidate.file, needle, raw, deadline);
     if (scanned === TIMED_OUT) {
@@ -2032,6 +2127,81 @@ async function searchLocalChats(query, options = {}) {
   };
 }
 
+// src/sessions/hints.ts
+function titleHintKey(provider, sessionId) {
+  return `${provider}:${sessionId}`;
+}
+function createTitleHintsStore() {
+  let hints = null;
+  let problem = null;
+  const listeners = /* @__PURE__ */ new Set();
+  const tell = () => {
+    for (const l of listeners) l();
+  };
+  return {
+    current: () => hints,
+    problem: () => problem,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    set(next) {
+      hints = next;
+      problem = null;
+      tell();
+    },
+    setProblem(next) {
+      if (next === problem) return;
+      problem = next;
+      tell();
+    }
+  };
+}
+function appTitlesOf(hints) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, hint] of hints) out.set(key, hint.title);
+  return out;
+}
+
+// src/engine/title-hints.ts
+function overlayHint(chat, hints, expected) {
+  if (!expected) return chat;
+  if (hints === null) return { ...chat, titlePending: true };
+  const hint = hints.get(titleHintKey(chat.provider, chat.providerSessionId));
+  if (!hint) return chat;
+  return {
+    ...chat,
+    title: hint.title,
+    titleSource: hint.source,
+    ...hint.archived || chat.archived ? { archived: true } : {},
+    ...hint.scheduled ? { scheduled: true } : {}
+  };
+}
+function unavailableFromHints(hints, covered) {
+  if (!hints) return [];
+  const out = [];
+  for (const [key, hint] of hints) {
+    if (!hint.unavailable || covered.has(key)) continue;
+    const at = key.indexOf(":");
+    const provider = key.slice(0, at);
+    if (provider !== "claude" && provider !== "codex") continue;
+    out.push({
+      provider,
+      providerSessionId: key.slice(at + 1),
+      cwd: null,
+      title: hint.title,
+      titleSource: hint.source,
+      updatedAt: new Date(hint.lastActiveMs ?? 0).toISOString(),
+      source: null,
+      activeElsewhere: null,
+      unavailable: hint.unavailable,
+      ...hint.archived ? { archived: true } : {},
+      ...hint.scheduled ? { scheduled: true } : {}
+    });
+  }
+  return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
 // src/engine/store.ts
 import { randomUUID as randomUUID3 } from "crypto";
 import fs6 from "fs/promises";
@@ -2302,7 +2472,7 @@ function describeAuthStatus(provider, probe) {
 async function createCodingSessionsEngine(options = {}) {
   const dataDir = options.dataDir ?? path9.join(os5.homedir(), ".matrx", "coding-sessions");
   const stateDir = path9.join(dataDir, "paperclip-state");
-  const homes = options.homes ?? defaultProviderHomes();
+  let homes = options.homes ?? defaultProviderHomes();
   const index = new RunIndex(dataDir);
   await index.load();
   const preferences = new PreferenceStore(dataDir);
@@ -2382,6 +2552,18 @@ async function createCodingSessionsEngine(options = {}) {
       }
     }
   }
+  const titleHints = options.titleHints;
+  const hintsNow = () => titleHints?.current() ?? null;
+  const appTitles = () => {
+    if (!titleHints) return void 0;
+    const hints = hintsNow();
+    return hints ? appTitlesOf(hints) : /* @__PURE__ */ new Map();
+  };
+  const unsubscribeHints = titleHints?.subscribe(() => emit({ type: "titles" })) ?? null;
+  const withHintTitle = (session) => {
+    const hint = session.providerSessionId ? hintsNow()?.get(titleHintKey(session.provider, session.providerSessionId)) : void 0;
+    return hint ? { ...session, title: hint.title } : session;
+  };
   function saveSession(session) {
     index.putSession(session);
     emit({ type: "session", session });
@@ -2538,7 +2720,12 @@ async function createCodingSessionsEngine(options = {}) {
         if (sid && sid !== knownProviderSession) {
           knownProviderSession = sid;
           const current = index.session(session.id);
-          if (current) saveSession({ ...current, providerSessionId: sid });
+          if (current) {
+            saveSession({ ...current, providerSessionId: sid });
+            if (preferences.rekey(chatKey(current.provider, null, current.id), chatKey(current.provider, sid))) {
+              emit({ type: "preferences", preferences: preferences.all() });
+            }
+          }
         }
         for (const item of items) emitItem(liveRun, item);
       }
@@ -2846,7 +3033,9 @@ async function createCodingSessionsEngine(options = {}) {
       );
     },
     async discoverSessions(opts) {
-      const found = await discoverLocalSessions({ limit: opts?.limit, homes, excludePids: ourPids() });
+      const read = await discoverLocalSessions({ limit: opts?.limit, homes, excludePids: ourPids(), appTitles: appTitles() });
+      const hints = hintsNow();
+      const found = read.map((chat) => overlayHint(chat, hints, titleHints !== void 0));
       if (backups) {
         for (const chat of found) {
           const key = `${chat.provider}:${chat.providerSessionId}`;
@@ -2857,7 +3046,12 @@ async function createCodingSessionsEngine(options = {}) {
           }
         }
       }
-      return found;
+      const limit = opts?.limit ?? 60;
+      const oldest = found.length >= limit ? found[found.length - 1]?.updatedAt ?? "" : "";
+      const gone = unavailableFromHints(hints, new Set(found.map((c) => titleHintKey(c.provider, c.providerSessionId)))).filter(
+        (c) => c.updatedAt >= oldest
+      );
+      return gone.length ? [...found, ...gone].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).slice(0, limit) : found;
     },
     async recentFolders() {
       const seen = /* @__PURE__ */ new Map();
@@ -2877,8 +3071,19 @@ async function createCodingSessionsEngine(options = {}) {
         }))
       );
     },
+    async titleStatus() {
+      if (!titleHints) return { owner: false, pending: false, problem: null };
+      const problem = titleHints.problem?.() ?? null;
+      return { owner: true, pending: hintsNow() === null && problem === null, problem };
+    },
+    async retryTitles() {
+      titleHints?.retry?.();
+    },
+    setHomes(next) {
+      homes = next;
+    },
     async listSessions() {
-      return index.sessions();
+      return index.sessions().map(withHintTitle);
     },
     async listRuns(sessionId) {
       const session = index.session(sessionId);
@@ -3053,7 +3258,9 @@ async function createCodingSessionsEngine(options = {}) {
       return all;
     },
     async searchChats(query, opts) {
-      return searchLocalChats(String(query ?? ""), { homes, cursor: opts?.cursor, limit: opts?.limit });
+      const result = await searchLocalChats(String(query ?? ""), { homes, cursor: opts?.cursor, limit: opts?.limit, appTitles: appTitles() });
+      const hints = hintsNow();
+      return { ...result, hits: result.hits.map((hit) => ({ ...hit, title: hints?.get(titleHintKey(hit.provider, hit.providerSessionId))?.title ?? hit.title })) };
     },
     async openFolder(raw, target) {
       const folder = await assertFolder(String(raw ?? ""));
@@ -3083,6 +3290,7 @@ async function createCodingSessionsEngine(options = {}) {
       return agents.handleMcp(secret, body);
     },
     async dispose() {
+      unsubscribeHints?.();
       for (const liveRun of live.values()) {
         liveRun.stopRequested = true;
         if (liveRun.pgid !== null) killGroup(liveRun);
@@ -3138,9 +3346,11 @@ export {
   buildCleanEnv,
   claudeDefaults,
   codexDefaults,
+  codexHome,
   createAiMatrxRawBackupSink,
   createCodingSessionsEngine,
   createRawBackupScheduler,
+  createTitleHintsStore,
   defaultProviderHomes,
   describeActivity,
   describeProviderStatus,
@@ -3153,6 +3363,7 @@ export {
   readSessionFile,
   searchLocalChats,
   sessionActivity,
-  snippetAround
+  snippetAround,
+  titleHintKey
 };
 //# sourceMappingURL=index.js.map