zcode-pro 0.18.0 → 0.20.0

package/src/host/main.mjs

@@ -17,11 +17,15 @@ import { runSetup } from './setup.mjs';
 const here = dirname(fileURLToPath(import.meta.url));
 const INJECT_BUNDLE = resolve(here, '..', '..', 'dist', 'inject.js');
 
-// Windows 控制台中文乱码适配：输出为 UTF-8 字节，旧版 conhost/PowerShell 的默认
-// 代码页（936/GBK）按 GBK 解码会显示乱码。检测到真实控制台且非 UTF-8 代码页时
-// 切到 65001——只影响当前控制台会话（重开终端即恢复），重定向/非交互不干预。
+// Windows 控制台中文乱码适配：输出为 UTF-8 字节，旧版 conhost/cmd 的默认代码页
+//（936/GBK）按 GBK 解码会显示乱码。检测到非 UTF-8 代码页时切到 65001——只影响
+// 当前控制台会话（重开终端即恢复）。不能用 stdout.isTTY 单独作前提：npm 全局
+// 入口（bin/zcode-pro.mjs）spawn ZCode 运行时跑 cli.mjs，子进程 stdout 经
+// stdio:'inherit' 是管道（isTTY=false），但控制台乱码照样发生（0.18/0.19 用户
+// 实拍）；此时 stdin 仍连着终端，故用 stdout 或 stdin 任一 isTTY 判定。真正的
+// 重定向场景（stdout 与 stdin 都不是 TTY）不干预。
 // 放在模块顶层：cli.mjs 经 import main.mjs 进入，setup 等子命令的输出同样受益。
-if (process.platform === 'win32' && process.stdout.isTTY) {
+if (process.platform === 'win32' && (process.stdout.isTTY || process.stdin.isTTY)) {
   try {
     const cp = execSync('chcp.com', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).match(/(\d+)/)?.[1];
     if (cp && cp !== '65001') execSync('chcp.com 65001', { stdio: 'ignore', windowsHide: true });

package/src/host/setup.mjs

@@ -1,5 +1,5 @@
 // zcode-pro setup：本机集成设置入口（npm / pip 等包管理器安装不写系统目录，
-// 需要菜单入口等集成时显式运行本子命令）。按「设置项」组织（id / 标题 /
+// 需要菜单入口等集成时显式运行本子命令）。按“设置项”组织（id / 标题 /
 // install / uninstall），以后新增设置项往 items 里加即可。
 // setup 不依赖 ZCode 运行，在 main.run 里先于 ZCode 定位处理。
 //
@@ -291,17 +291,17 @@ function plistContent(hasIcon) {
 
 const shortcutItem = {
   id: 'desktop-shortcut',
-  title: '快捷方式“ZCode Pro”（应用菜单/开始菜单，图标复用 ZCode）',
+  title: 'Shortcut "ZCode Pro" (app/start menu, icon reuses ZCode)',
   supported: (plat) => SUPPORTED.includes(plat),
 
   install(plat, opts = {}) {
     const cmd = commandInPath(plat);
     if (!cmd) {
-      throw new Error('未在 PATH 中找到 zcode-pro 命令，无法创建快捷方式；请确认安装方式后重试。');
+      throw new Error('zcode-pro command not found in PATH, cannot create shortcut; check your install and retry');
     }
     if (!sameInstall(cmd, plat)) {
-      throw new Error(`PATH 中的 zcode-pro（${cmd}）不属于当前运行的这份安装，` +
-        '为避免快捷方式指向旧版本已跳过；请用那份安装自己的方式管理快捷方式。');
+      throw new Error(`the zcode-pro in PATH (${cmd}) is not part of this installation, ` +
+        'skipped so the shortcut will not point at an old version; manage shortcuts with that installation instead');
     }
     if (plat === 'linux') return this.installLinux(cmd, opts);
     if (plat === 'win32') return this.installWindows(cmd, opts);
@@ -312,7 +312,7 @@ const shortcutItem = {
     // 系统级（AUR 等）已有同名条目时不再建用户级：desktop 文件 id 相同时用户级
     // 会遮蔽系统级（项目既有约定），残留后表现为菜单一直运行另一份
     if (existsSync('/usr/share/applications/zcode-pro.desktop')) {
-      return { skipped: '检测到系统级 ZCode Pro 快捷方式（AUR 等已安装），用户级条目会遮蔽它，已跳过' };
+      return { skipped: 'system-level shortcut detected (e.g. AUR); a user entry would shadow it, skipped' };
     }
     const appsDir = applicationsDir();
     const target = join(appsDir, DESKTOP_FILE);
@@ -320,21 +320,21 @@ const shortcutItem = {
     if (existsSync(target)) {
       const cur = readFileSync(target, 'utf-8');
       if (!cur.includes(SETUP_MARK)) {
-        return { skipped: `${target} 已存在且非 setup 创建（如 install.sh），未覆盖` };
+        return { skipped: `${target} exists and was not created by setup (e.g. install.sh), not overwritten` };
       }
       // 早期版本写过 0644 的条目：即使内容无需重写也补上执行位（原因见 writeDesktopEntry）
       chmodSync(target, 0o755);
       const exec = (cur.match(/^Exec=(.+)$/m) || [])[1] || '';
       if (exec.includes(cmd)) {
-        parts.push('应用菜单条目已存在且指向当前命令，无需重复创建');
+        parts.push('app-menu entry already exists and points to the current command, nothing to do');
       } else {
         writeDesktopEntry(target, cmd);
-        parts.push(`已更新 ${target}（Exec=${cmd}）`);
+        parts.push(`updated ${target} (Exec=${cmd})`);
       }
     } else {
       mkdirSync(appsDir, { recursive: true });
       writeDesktopEntry(target, cmd);
-      parts.push(`已写入 ${target}（Exec=${cmd}）`);
+      parts.push(`written ${target} (Exec=${cmd})`);
     }
     try { execFileSync('update-desktop-database', [appsDir], { stdio: 'ignore' }); } catch { /* 无该命令时忽略 */ }
     // 桌面条目独立判断（不因菜单条目幂等而短路）
@@ -347,13 +347,13 @@ const shortcutItem = {
         // GNOME 的桌面（Nautilus）额外要求 trusted 元数据才显示“允许启动”；
         // 其他环境无 gio / 写不进元数据时忽略
         try { execFileSync('gio', ['set', dTarget, 'metadata::trusted', 'true'], { stdio: 'ignore' }); } catch { /* 非 GNOME 忽略 */ }
-        parts.push(`桌面 ${dTarget}`);
+        parts.push(`desktop ${dTarget}`);
       } else {
-        parts.push('桌面已存在非 setup 创建的条目，未覆盖');
+        parts.push('desktop entry exists and was not created by setup, not overwritten');
       }
     }
-    if (parts.length === 1 && parts[0].startsWith('应用菜单条目已存在')) return { skipped: parts[0] };
-    return { detail: parts.join('；') };
+    if (parts.length === 1 && parts[0].startsWith('app-menu entry already exists')) return { skipped: parts[0] };
+    return { detail: parts.join('; ') };
   },
 
   installWindows(cmd, opts = {}) {
@@ -367,9 +367,9 @@ const shortcutItem = {
     const plan = windowsShortcutPlan(cmd, !!opts.desktop, wshOk, !menuForeign);
     if (menuForeign && (!opts.desktop || deskForeign)) {
       return { skipped: [
-        menuForeign ? `已存在其他方式创建的 ${plan.lnkPath}，未覆盖` : '',
-        deskForeign ? `桌面 ${deskPath} 已存在其他方式创建的条目，未覆盖` : '',
-      ].filter(Boolean).join('；') };
+        menuForeign ? `${plan.lnkPath} exists (created elsewhere), not overwritten` : '',
+        deskForeign ? `desktop ${deskPath} exists (created elsewhere), not overwritten` : '',
+      ].filter(Boolean).join('; ') };
     }
     if (wshOk) {
       mkdirSync(plan.vbsDir, { recursive: true });
@@ -377,14 +377,14 @@ const shortcutItem = {
     }
     runPowerShell(plan.psScript);
     const how = wshOk
-      ? `经 ${plan.vbsPath} 静默启动`
-      : '本机 WSH 异常，经 cmd 最小化启动（启动时会短暂闪烁控制台窗口）';
+      ? `silent launch via ${plan.vbsPath}`
+      : 'WSH unavailable on this machine; minimized cmd launch (console flashes briefly on start)';
     const parts = [];
     parts.push(menuForeign
-      ? `开始菜单 ${plan.lnkPath} 已存在其他方式创建的条目，未覆盖`
-      : `已创建 ${plan.lnkPath}`);
-    if (opts.desktop) parts.push(deskForeign ? `桌面 ${deskPath} 已存在其他方式创建的条目，未覆盖` : '已创建桌面快捷方式');
-    return { detail: `${parts.join('；')}（${how}）` };
+      ? `start menu ${plan.lnkPath} exists (created elsewhere), not overwritten`
+      : `created ${plan.lnkPath}`);
+    if (opts.desktop) parts.push(deskForeign ? `desktop ${deskPath} exists (created elsewhere), not overwritten` : 'desktop shortcut created');
+    return { detail: `${parts.join('; ')} (${how})` };
   },
 
   installMac(cmd, opts = {}) {
@@ -392,7 +392,7 @@ const shortcutItem = {
     const contents = join(app, 'Contents');
     const marker = join(contents, 'zcodepro-setup-marker');
     if (existsSync(app) && !existsSync(marker)) {
-      return { skipped: `${app} 已存在且非 setup 创建，未覆盖` };
+      return { skipped: `${app} exists and was not created by setup, not overwritten` };
     }
     let iconCopied = false;
     for (const src of [join('/', 'Applications', 'ZCode.app', 'Contents', 'Resources', 'app.icns'),
@@ -411,15 +411,15 @@ const shortcutItem = {
     chmodSync(launcher, 0o755);
     writeFileSync(join(contents, 'Info.plist'), plistContent(iconCopied));
     writeFileSync(marker, '');
-    let detail = `已创建 ${app}（启动器指向 ${cmd}${iconCopied ? '，图标已复制' : ''}）`;
+    let detail = `created ${app} (launcher -> ${cmd}${iconCopied ? ', icon copied' : ''})`;
     if (opts.desktop) {
       const link = macDesktopLink();
       if (existsSync(link)) {
-        detail += '；桌面已存在同名入口，未覆盖';
+        detail += '; desktop entry with the same name exists, not overwritten';
       } else {
         try {
           symlinkSync(app, link);
-          detail += `；桌面 ${link}`;
+          detail += `; desktop ${link}`;
         } catch { /* 建链接失败仅省略桌面入口 */ }
       }
     }
@@ -445,16 +445,16 @@ const shortcutItem = {
       rmSync(dTarget);
       removed.push(dTarget);
     }
-    if (!removed.length) return { skipped: '未发现 setup 创建的快捷方式' };
+    if (!removed.length) return { skipped: 'no setup-created shortcuts found' };
     try { execFileSync('update-desktop-database', [applicationsDir()], { stdio: 'ignore' }); } catch { /* 无该命令时忽略 */ }
-    return { detail: `已移除 ${removed.join('、')}` };
+    return { detail: `removed ${removed.join(', ')}` };
   },
 
   uninstallWindows() {
     const paths = windowsPaths();
     const hadVbs = existsSync(paths.vbsPath);
     const hadLnk = existsSync(paths.lnkPath);
-    if (!hadVbs && !hadLnk) return { skipped: '未发现 setup 创建的快捷方式' };
+    if (!hadVbs && !hadLnk) return { skipped: 'no setup-created shortcuts found' };
     // .lnk 可能已被 install.ps1 等重建并指向它自己：只有 Arguments 带本功能归属
     // 标记才删；校验失败也保留 .lnk（宁可漏删不误删）
     let lnkRemoved = false;
@@ -488,29 +488,29 @@ const shortcutItem = {
           vbsCleaned = true;
         } catch {
           vbsCleaned = !existsSync(paths.vbsPath);
-          if (!vbsCleaned) console.error(`  （${paths.vbsDir} 删除失败，可能被占用，可稍后手动删除）`);
+          if (!vbsCleaned) console.error(`  (${paths.vbsDir} could not be deleted (may be in use); remove it manually later)`);
         }
       }
     }
     const parts = [];
     if (hadLnk) {
-      parts.push(lnkRemoved ? '开始菜单/桌面快捷方式' : verified ? '快捷方式已非本功能创建，未删除' : '快捷方式归属校验失败，未删除 .lnk');
+      parts.push(lnkRemoved ? 'start-menu/desktop shortcut' : verified ? 'shortcut not created by setup, kept' : 'shortcut ownership check failed, .lnk kept');
     }
-    if (hadVbs) parts.push(vbsCleaned ? '生成的启动脚本' : '启动脚本（删除失败）');
-    return { detail: `已移除：${parts.join('；')}` };
+    if (hadVbs) parts.push(vbsCleaned ? 'generated launcher script' : 'launcher script (delete failed)');
+    return { detail: `removed: ${parts.join(', ')}` };
   },
 
   uninstallMac() {
     const app = macAppBundle();
     const marker = join(app, 'Contents', 'zcodepro-setup-marker');
-    if (!existsSync(marker)) return { skipped: '未发现 setup 创建的应用包' };
+    if (!existsSync(marker)) return { skipped: 'no setup-created app bundle found' };
     // setup --desktop 建的桌面入口一并清理（只删指向本应用包的链接）
     const link = macDesktopLink();
     try {
       if (existsSync(link) && realpathSync(link) === realpathSync(app)) rmSync(link);
     } catch { /* 链接失效则忽略 */ }
     rmSync(app, { recursive: true, force: true });
-    return { detail: `已移除 ${app}` };
+    return { detail: `removed ${app}` };
   },
 };
 
@@ -532,22 +532,25 @@ function rmSyncWithRetry(target, tries = 4) {
 const items = [shortcutItem];
 
 export async function runSetup({ uninstall = false, platform: plat = platform(), desktop = false } = {}) {
-  console.log(`[zcodepro] setup ${uninstall ? '卸载' : '安装'}本机集成${desktop && !uninstall ? '（含桌面）' : ''}：`);
+  // 输出全用 ASCII 英文：setup 常在 GBK 代码页的 cmd/PowerShell 里跑，中文经
+  // 管道输出时极易乱码（chcp 适配也不是所有入口都来得及生效）；ASCII 文案
+  // 在任何代码页下都稳定显示
+  console.log(`[zcodepro] setup ${uninstall ? 'remove' : 'install'} local integration${desktop && !uninstall ? ' (with desktop)' : ''}:`);
   let failed = 0;
   for (const item of items) {
     if (!item.supported(plat)) {
-      console.log(`  · ${item.title}：当前平台（${plat}）暂不支持，跳过`);
+      console.log(`  - ${item.title}: not supported on ${plat}, skipped`);
       continue;
     }
     try {
       const res = uninstall ? item.uninstall(plat) : item.install(plat, { desktop });
-      if (res && res.skipped) console.log(`  · ${item.title}：${res.skipped}`);
-      else console.log(`  ✓ ${item.title}：${res && res.detail ? res.detail : '完成'}`);
+      if (res && res.skipped) console.log(`  - ${item.title}: ${res.skipped}`);
+      else console.log(`  [OK] ${item.title}: ${res && res.detail ? res.detail : 'done'}`);
     } catch (err) {
       failed++;
-      console.error(`  ✗ ${item.title}：${err?.message || err}`);
+      console.error(`  [FAIL] ${item.title}: ${err?.message || err}`);
     }
   }
-  console.log(uninstall ? '' : '  撤销：zcode-pro setup --uninstall');
+  console.log(uninstall ? '' : '  undo: zcode-pro setup --uninstall');
   if (failed) process.exitCode = 1;
 }

package/src/host/taskIndex.mjs

@@ -206,11 +206,140 @@ export async function listOverriddenTitles(dataRoot) {
   return { titles };
 }
 
+// 智能起名的前置判定：会话是否已被手动重命名（或已被起名写过）。双写前先查它，
+// 已重命名就整体跳过——避免起名晚到的写入盖掉用户的 custom 标题。读取失败按
+// 未重命名处理（后续写入自带原子守卫兜底）
+export async function isTaskTitleOverridden(dataRoot, sessId) {
+  const dbFile = taskIndexPath(dataRoot);
+  if (!existsSync(dbFile)) return false;
+  const driver = await loadDriver();
+  if (!driver) return false;
+  try {
+    if (driver.kind === 'node') {
+      const db = new driver.DatabaseSync(dbFile, { readOnly: true });
+      try {
+        const r = db.prepare('SELECT title_overridden FROM tasks WHERE task_id = ? AND deleted = 0').get(sessId);
+        return r?.title_overridden === 1;
+      } finally { db.close(); }
+    }
+    const esc = (v) => "'" + String(v).replace(/'/g, "''") + "'";
+    const r = runCli(dbFile, `SELECT title_overridden FROM tasks WHERE task_id = ${esc(sessId)} AND deleted = 0;`);
+    return /^1/m.test(r.stdout);
+  } catch { return false; }
+}
+
+// 智能起名写入：把生成标题按“手动重命名”存入索引（title_overridden = 1），
+// 之后官方自动标题不会再覆盖这条记录。仅在会话未删除、且从未被手动重命名过
+// （title_overridden = 0）时写入——手动重命名永远优先。返回 { written, title }；
+// written = false 表示没写（已重命名或会话不在索引中）。库被占用时抛 index-busy。
+export async function setTaskTitleIfNotOverridden(dataRoot, sessId, title) {
+  const dbFile = taskIndexPath(dataRoot);
+  if (!existsSync(dbFile)) return { written: false, title };
+  const driver = await loadDriver();
+  if (!driver) {
+    const err = new Error('缺少 SQLite 支持（需要 Node ≥23.4 或 sqlite3 命令）');
+    err.code = 'index-error';
+    throw err;
+  }
+  try {
+    if (driver.kind === 'node') {
+      const db = new driver.DatabaseSync(dbFile);
+      try {
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+        db.exec('BEGIN IMMEDIATE');
+        try {
+          const r = db.prepare(
+            'UPDATE tasks SET title = ?, title_overridden = 1 WHERE task_id = ? AND deleted = 0 AND title_overridden = 0'
+          ).run(title, sessId);
+          db.exec('COMMIT');
+          return { written: r.changes > 0, title };
+        } catch (err) {
+          try { db.exec('ROLLBACK'); } catch { /* 已回滚/连接失效 */ }
+          throw err;
+        }
+      } finally { db.close(); }
+    }
+    const esc = (v) => "'" + String(v).replace(/'/g, "''") + "'";
+    const r = runCli(dbFile,
+      'BEGIN IMMEDIATE;\n'
+      + `UPDATE tasks SET title = ${esc(title)}, title_overridden = 1`
+      + ` WHERE task_id = ${esc(sessId)} AND deleted = 0 AND title_overridden = 0;\n`
+      + 'SELECT changes();\nCOMMIT;');
+    return { written: Number(r.stdout.trim()) > 0, title };
+  } catch (err) {
+    if (isBusyError(err)) {
+      const e = new Error('任务索引正被占用（ZCode 可能正在写入）');
+      e.code = 'index-busy';
+      throw e;
+    }
+    const e = new Error('写入任务标题失败: ' + (err?.message || err));
+    e.code = 'index-error';
+    throw e;
+  }
+}
+
 function isBusyError(err) {
   const s = String(err?.code || '') + String(err?.message || '');
   return /SQLITE_BUSY|database is locked/i.test(s);
 }
 
+// 读某会话记录的模型信息（智能起名“跟随当前会话”用）。model 列存
+// “<供应商id>/<模型id>”（如 be0a90cb…/glm-5.3），拆开后返回
+// { providerId, modelId }；没有斜线时 providerId 退回 provider 列的值。
+// 会话不存在返回 null；读取失败按 null 处理（调用方换明确报错）
+export async function getTaskProviderModel(dataRoot, sessId) {
+  const driver = await loadDriver();
+  if (!driver) return null;
+  const esc = (v) => "'" + String(v).replace(/'/g, "''") + "'";
+
+  // 优先读 CLI 会话库的 model_usage：首个 turn 开始时即写入，比任务索引的
+  // model 列早十几秒（任务索引由桌面同步器延迟写；新会话头十几秒里它还是
+  // 空值，起名第一次调用会因此解析到不存在的模型，实测 400 模型不存在）
+  const usageFile = join(dataRoot, 'cli', 'db', 'db.sqlite');
+  if (existsSync(usageFile)) {
+    try {
+      if (driver.kind === 'node') {
+        const db = new driver.DatabaseSync(usageFile, { readOnly: true });
+        try {
+          const r = db.prepare(
+            "SELECT provider_id, model_id FROM model_usage WHERE session_id = ? AND provider_id IS NOT NULL AND provider_id != '' ORDER BY started_at DESC LIMIT 1"
+          ).get(sessId);
+          if (r && r.model_id) return { providerId: r.provider_id, modelId: r.model_id };
+        } finally { db.close(); }
+      } else {
+        const r = runCli(usageFile,
+          `SELECT coalesce(json_object('provider_id', provider_id, 'model_id', model_id), 'null') FROM (SELECT provider_id, model_id FROM model_usage WHERE session_id = ${esc(sessId)} AND provider_id IS NOT NULL AND provider_id != '' ORDER BY started_at DESC LIMIT 1);`);
+        const parsed = JSON.parse(r.stdout.trim() || 'null');
+        if (parsed && parsed.model_id) return { providerId: parsed.provider_id, modelId: parsed.model_id };
+      }
+    } catch { /* 表不存在（旧版 CLI）等：走任务索引兜底 */ }
+  }
+
+  const dbFile = taskIndexPath(dataRoot);
+  if (!existsSync(dbFile)) return null;
+  let row = null;
+  try {
+    if (driver.kind === 'node') {
+      const db = new driver.DatabaseSync(dbFile);
+      try {
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+        row = db.prepare('SELECT provider, model FROM tasks WHERE task_id = ? AND deleted = 0').get(sessId) || null;
+      } finally { db.close(); }
+    } else {
+      const r = runCli(dbFile,
+        `SELECT coalesce(json_object('provider', provider, 'model', model), 'null') FROM tasks WHERE task_id = ${esc(sessId)} AND deleted = 0;`);
+      const parsed = JSON.parse((r.stdout.trim() || 'null'));
+      row = parsed && typeof parsed === 'object' ? parsed : null;
+    }
+  } catch { /* 读不了就当没有 */ }
+  if (!row) return null;
+  const model = String(row.model || '');
+  const slash = model.indexOf('/');
+  return slash > 0
+    ? { providerId: model.slice(0, slash), modelId: model.slice(slash + 1) }
+    : { providerId: String(row.provider || ''), modelId: model };
+}
+
 // 任务（会话）ID → 工作区路径（无尾分隔符）：空闲回收在 Windows 上的后台命令
 // 归属判定用（命令行里只带会话 ID，需经索引反查它属于哪个项目）。
 // 读取失败返回空表，调用方按“无法归属”保守处理
@@ -253,3 +382,132 @@ function runCli(dbFile, script) {
   if (r.status !== 0) throw new Error('sqlite3 CLI 执行失败: ' + (r.stderr || r.stdout || ('exit ' + r.status)));
   return r;
 }
+
+// CLI 会话库（~/.zcode/cli/db/db.sqlite）的会话标题权威写入：title + title_source=
+// 'custom'（官方 setCustomSessionTitle 同款语义）。custom 后官方运行时彻底知情：
+// 自动起名写回后的自动校正：桌面端打开会话时会把运行时内存缓存的旧标题写回
+// 任务索引（实测点开会话的瞬间发生，运行时不知道我们直写过 CLI 库），索引里的
+// 标题因此被改回旧值。CLI 库的 custom 标题才是权威——对“我们写过、且 CLI 标题
+// 仍等于我们所写”的会话，索引标题若不同就改回 CLI 值。只认自己写过的记录：
+// 官方手动改名（renameTask）两库同步更新不会分歧；其 v4 同步失败时索引比 CLI 新
+// （历史会话场景），不认记录就绝不会误回滚用户的手动改名。
+// writtenMap: { sessId → { title, at } }；返回本次校正的会话数（失败静默，下次再试）
+export async function reconcileCustomTitles(dataRoot, writtenMap) {
+  const repaired = [];
+  if (!writtenMap || typeof writtenMap !== 'object') return repaired;
+  const driver = await loadDriver();
+  if (!driver) return repaired;
+  const esc = (v) => "'" + String(v).replace(/'/g, "''") + "'";
+  const cliFile = join(dataRoot, 'cli', 'db', 'db.sqlite');
+  const idxFile = taskIndexPath(dataRoot);
+  if (!existsSync(cliFile) || !existsSync(idxFile)) return repaired;
+
+  const readCli = async (sessId) => {
+    if (driver.kind === 'node') {
+      const db = new driver.DatabaseSync(cliFile, { readOnly: true });
+      try {
+        return db.prepare("SELECT title, title_source FROM session WHERE id = ?").get(sessId) || null;
+      } finally { db.close(); }
+    }
+    const r = runCli(cliFile, `SELECT coalesce(json_object('title', title, 'title_source', title_source), 'null') FROM session WHERE id = ${esc(sessId)};`);
+    const parsed = JSON.parse(r.stdout.trim() || 'null');
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  };
+
+  for (const [sessId, rec] of Object.entries(writtenMap)) {
+    if (!/^sess_[A-Za-z0-9._-]+$/.test(sessId) || !rec || typeof rec.title !== 'string') continue;
+    let cli;
+    try { cli = await readCli(sessId); } catch { continue; }
+    // CLI 已不是我们所写的 custom 标题：别人改过（手动改名/官方），不碰
+    if (!cli || cli.title_source !== 'custom' || cli.title !== rec.title) continue;
+    try {
+      if (driver.kind === 'node') {
+        const db = new driver.DatabaseSync(idxFile);
+        try {
+          db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+          db.exec('BEGIN IMMEDIATE');
+          try {
+            const r = db.prepare(
+              'UPDATE tasks SET title = ? WHERE task_id = ? AND deleted = 0 AND title_overridden = 1 AND title != ?'
+            ).run(rec.title, sessId, rec.title);
+            db.exec('COMMIT');
+            if (r.changes > 0) repaired.push(sessId);
+          } catch (err) {
+            try { db.exec('ROLLBACK'); } catch { /* 已回滚 */ }
+            throw err;
+          }
+        } finally { db.close(); }
+      } else {
+        const r = runCli(idxFile,
+          'BEGIN IMMEDIATE;\n'
+          + `UPDATE tasks SET title = ${esc(rec.title)} WHERE task_id = ${esc(sessId)} AND deleted = 0 AND title_overridden = 1 AND title != ${esc(rec.title)};\n`
+          + 'SELECT changes();\nCOMMIT;');
+        if (Number(r.stdout.trim()) > 0) repaired.push(sessId);
+      }
+    } catch { /* 占用等：下次再校正 */ }
+  }
+  return repaired;
+}
+
+// 自动起名在写回前重读时看到 custom 会放弃（session-title.ts 的 custom_title 短路），
+// 桌面同步器（zcodeTaskIndexSyncer）会把 custom 标题带着 titleOverridden=1 写回
+// 任务索引——单写任务索引被官方排队的自动标题覆盖的竞态（实测 14 秒后覆盖）由此
+// 消除。time_title_updated/time_updated 与官方 updateSession 一致（title 变更即刷新，
+// time_updated 只增不减）；title_message_id 保留原值。旧版 CLI 库没有 title_source
+// 列时返回 skipped（缺 custom 语义，写了也守不住，退回单写任务索引的旧行为）。
+// 库被占用时抛 index-busy（与任务索引写入同款重试语义）。
+export async function setCustomSessionTitle(dataRoot, sessId, title) {
+  const dbFile = join(dataRoot, 'cli', 'db', 'db.sqlite');
+  if (!existsSync(dbFile)) return { written: false, skipped: 'no-cli-db' };
+  const driver = await loadDriver();
+  if (!driver) {
+    const err = new Error('缺少 SQLite 支持（需要 Node ≥23.4 或 sqlite3 命令）');
+    err.code = 'index-error';
+    throw err;
+  }
+  try {
+    if (driver.kind === 'node') {
+      const db = new driver.DatabaseSync(dbFile);
+      try {
+        const cols = db.prepare("PRAGMA table_info('session')").all();
+        if (!cols.some((c) => c.name === 'title_source')) return { written: false, skipped: 'no-title-source' };
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+        db.exec('BEGIN IMMEDIATE');
+        try {
+          const now = Date.now();
+          const r = db.prepare(
+            "UPDATE session SET title = ?, title_source = 'custom', time_title_updated = ?, time_updated = max(time_updated, ?) WHERE id = ?"
+          ).run(title, now, now, sessId);
+          db.exec('COMMIT');
+          return { written: r.changes > 0, skipped: r.changes > 0 ? '' : 'no-session-row' };
+        } catch (err) {
+          try { db.exec('ROLLBACK'); } catch { /* 已回滚/连接失效 */ }
+          throw err;
+        }
+      } finally {
+        db.close();
+      }
+    }
+    const esc = (v) => "'" + String(v).replace(/'/g, "''") + "'";
+    const cols = runCli(dbFile, "PRAGMA table_info('session');").stdout;
+    if (!/title_source/.test(cols)) return { written: false, skipped: 'no-title-source' };
+    const now = Date.now();
+    const r = runCli(dbFile,
+      'BEGIN IMMEDIATE;\n'
+      + `UPDATE session SET title = ${esc(title)}, title_source = 'custom',`
+      + ` time_title_updated = ${now}, time_updated = max(time_updated, ${now})`
+      + ` WHERE id = ${esc(sessId)};\n`
+      + 'SELECT changes();\nCOMMIT;');
+    const changed = Number(r.stdout.trim()) > 0;
+    return { written: changed, skipped: changed ? '' : 'no-session-row' };
+  } catch (err) {
+    if (isBusyError(err)) {
+      const e = new Error('CLI 会话库正被占用（ZCode 可能正在写入）');
+      e.code = 'index-busy';
+      throw e;
+    }
+    const e = new Error('写入 CLI 会话标题失败: ' + (err?.message || err));
+    e.code = 'index-error';
+    throw e;
+  }
+}