@4yi-dev/cli 0.1.18 → 0.1.20

package/README.md

@@ -37,12 +37,16 @@ Both packages install the `4yi` command. The dev package points at `https://xcla
 
 On macOS, `4yi connect claude` also configures an installed Claude Desktop through its official third-party Gateway mode. The Desktop credential helper reads the current token from `~/.4yi/config.json`; the token is not copied into Claude's configuration. Quit and reopen Claude Desktop only after its active tasks finish. Third-party mode has a separate session list from the normal Claude profile. Run `4yi restore claude`, then reopen Claude Desktop, to return to the previous profile and session list.
 
+`4yi restore claude` skips backup snapshots that were themselves created while 4YI was active, so repeated `connect` calls still return to the latest official configuration. After restoring, quit every running Claude Code and Claude App process and open a new terminal: an existing process has already loaded `ANTHROPIC_*` into memory, and Claude's `/logout` command does not override provider environment variables.
+
 `--scope project` changes only the project's Claude Code settings and never changes the global Claude Desktop profile.
 
 Codex CLI and Codex App share the same Codex home on native Windows (`%USERPROFILE%\\.codex`). Microsoft Store/AppX installations may not expose a conventional executable path, but that detection does not gate the shared configuration update. While the external 4YI provider supplies authentication, Codex App may hide its `Log out` action because there is no App-managed provider credential to clear.
 
 `4yi migrate codex` connects Codex to 4YI and switches every stored Codex task to the 4YI provider in place. `4yi restore codex` restores the protected OpenAI configuration and switches every task back to OpenAI in place. Task IDs, projects, visible user messages, assistant answers, and tool history remain on the original sidebar entries. Finish active turns before running either command, then fully quit and reopen Codex App when it completes.
 
+Paginated tasks are migrated as a complete history lineage. The CLI validates every ancestor cutoff, removes provider-private reasoning and compaction objects across all linked rollouts, rebuilds byte offsets from stable ordinals, and invalidates the UI projection for a clean rebuild. If any lineage or database check fails, the whole migration is rolled back from its backup.
+
 Before changing anything, the CLI validates the current `state_5.sqlite` and `thread_history_1.sqlite` schemas and every target rollout. It then creates consistent database and rollout backups under `~/.4yi/backups/codex-migrations`, removes provider-private reasoning/compaction references, updates the provider/model and UI projection offsets as one migration, and rolls back automatically if a commit or verification step fails. Node.js 22.13 or newer is required for this protected SQLite workflow.
 
 Use `--thread <id>` to switch only one task, `--model <id>` to override the target default model, or `--fork` to retain the older compatibility behavior that creates a migrated copy instead of changing the original task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4yi-dev/cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "4YI command-line launcher for OAuth login and OpenCode runtime",
   "type": "module",
   "bin": {

package/src/codex-in-place.mjs

@@ -47,8 +47,8 @@ function lineParts(buffer) {
 }
 
 function privateRecordKind(record) {
-  if (record?.type === "response_item" && record.payload?.type === "reasoning") return "reasoning";
-  if (record?.type === "event_msg" && record.payload?.type === "item_completed" && record.payload?.item?.type === "reasoning") {
+  if (record?.type === "response_item" && String(record.payload?.type).toLowerCase() === "reasoning") return "reasoning";
+  if (record?.type === "event_msg" && record.payload?.type === "item_completed" && String(record.payload?.item?.type).toLowerCase() === "reasoning") {
     return "reasoning-event";
   }
   if (record?.type === "compacted") return "compaction";
@@ -75,10 +75,11 @@ function tombstoneRecord(record, kind, byteLength) {
   return `${json}${" ".repeat(byteLength - length)}`;
 }
 
-function newTransformState(threadId, targetProvider) {
+function newTransformState(threadId, targetProvider, historyBase) {
   return {
     threadId,
     targetProvider,
+    historyBase,
     sessionMetaCount: 0,
     matchingSessionMetaCount: 0,
     sourceProviders: new Set(),
@@ -87,6 +88,8 @@ function newTransformState(threadId, targetProvider) {
     originalOffset: 0,
     cumulativeDelta: 0,
     offsetChanges: [],
+    ordinalBoundaries: [],
+    changed: false,
   };
 }
 
@@ -103,12 +106,20 @@ function transformRolloutBody(body, state) {
     const recordThreadId = record.payload?.id || record.payload?.session_id;
     if (recordThreadId === state.threadId) state.matchingSessionMetaCount += 1;
     state.sourceProviders.add(record.payload?.model_provider || record.payload?.modelProvider || "openai");
+    if (record.payload?.model_provider !== state.targetProvider || record.payload?.modelProvider !== undefined) {
+      state.changed = true;
+    }
     record.payload.model_provider = state.targetProvider;
     delete record.payload.modelProvider;
+    if (state.historyBase && recordThreadId === state.threadId) {
+      if (JSON.stringify(record.payload.history_base) !== JSON.stringify(state.historyBase)) state.changed = true;
+      record.payload.history_base = state.historyBase;
+    }
     return JSON.stringify(record);
   }
   const kind = privateRecordKind(record);
   if (!kind) return body;
+  state.changed = true;
   if (kind.startsWith("reasoning")) state.removedReasoning += 1;
   else state.removedCompaction += 1;
   return tombstoneRecord(record, kind, Buffer.byteLength(body));
@@ -132,26 +143,40 @@ function transformResult(state) {
     offsetChanges: state.offsetChanges,
     removedReasoning: state.removedReasoning,
     removedCompaction: state.removedCompaction,
+    ordinalBoundaries: state.ordinalBoundaries,
+    changed: state.changed,
   };
 }
 
-export function transformCodexRollout(buffer, { threadId, targetProvider }) {
-  const state = newTransformState(threadId, targetProvider);
+export function transformCodexRollout(buffer, { threadId, targetProvider, historyBase }) {
+  const state = newTransformState(threadId, targetProvider, historyBase);
   const transformed = [];
   for (const { body, newline } of lineParts(buffer)) {
+    const originalStart = state.originalOffset;
+    let ordinal;
+    try { ordinal = JSON.parse(body).ordinal; } catch { /* transformRolloutBody reports malformed JSON. */ }
     const nextLine = `${transformRolloutBody(body, state)}${newline}`;
     transformed.push(nextLine);
     recordOffsetChange(state, Buffer.byteLength(`${body}${newline}`), Buffer.byteLength(nextLine));
+    if (Number.isSafeInteger(ordinal) && ordinal >= 0) {
+      state.ordinalBoundaries.push({
+        ordinal,
+        originalStart,
+        originalEnd: state.originalOffset,
+        transformedStart: originalStart + state.cumulativeDelta - (Buffer.byteLength(nextLine) - Buffer.byteLength(`${body}${newline}`)),
+        transformedEnd: state.originalOffset + state.cumulativeDelta,
+      });
+    }
   }
   const output = Buffer.from(transformed.join(""), "utf8");
   return { buffer: output, ...transformResult(state) };
 }
 
-function transformCodexRolloutFile(file, { threadId, targetProvider }) {
+function transformCodexRolloutFile(file, { threadId, targetProvider, historyBase }) {
   const temporary = `${file}.4yi-migration-${process.pid}.tmp`;
   const input = fs.openSync(file, "r");
   const output = fs.openSync(temporary, "wx", 0o600);
-  const state = newTransformState(threadId, targetProvider);
+  const state = newTransformState(threadId, targetProvider, historyBase);
   let pending = Buffer.alloc(0);
   const chunk = Buffer.alloc(1024 * 1024);
   let failure;
@@ -164,17 +189,43 @@ function transformCodexRolloutFile(file, { threadId, targetProvider }) {
       while ((newlineIndex = pending.indexOf(0x0a)) >= 0) {
         const originalLine = pending.subarray(0, newlineIndex + 1);
         const body = originalLine.subarray(0, -1).toString("utf8");
+        const originalStart = state.originalOffset;
+        let ordinal;
+        try { ordinal = JSON.parse(body).ordinal; } catch { /* transformRolloutBody reports malformed JSON. */ }
         const nextLine = Buffer.from(`${transformRolloutBody(body, state)}\n`, "utf8");
         fs.writeSync(output, nextLine);
+        const previousDelta = state.cumulativeDelta;
         recordOffsetChange(state, originalLine.length, nextLine.length);
+        if (Number.isSafeInteger(ordinal) && ordinal >= 0) {
+          state.ordinalBoundaries.push({
+            ordinal,
+            originalStart,
+            originalEnd: state.originalOffset,
+            transformedStart: originalStart + previousDelta,
+            transformedEnd: state.originalOffset + state.cumulativeDelta,
+          });
+        }
         pending = pending.subarray(newlineIndex + 1);
       }
     }
     if (pending.length > 0) {
       const body = pending.toString("utf8");
+      const originalStart = state.originalOffset;
+      let ordinal;
+      try { ordinal = JSON.parse(body).ordinal; } catch { /* transformRolloutBody reports malformed JSON. */ }
       const nextLine = Buffer.from(transformRolloutBody(body, state), "utf8");
       fs.writeSync(output, nextLine);
+      const previousDelta = state.cumulativeDelta;
       recordOffsetChange(state, pending.length, nextLine.length);
+      if (Number.isSafeInteger(ordinal) && ordinal >= 0) {
+        state.ordinalBoundaries.push({
+          ordinal,
+          originalStart,
+          originalEnd: state.originalOffset,
+          transformedStart: originalStart + previousDelta,
+          transformedEnd: state.originalOffset + state.cumulativeDelta,
+        });
+      }
     }
   } catch (error) {
     failure = error;
@@ -194,6 +245,99 @@ function transformCodexRolloutFile(file, { threadId, targetProvider }) {
   }
 }
 
+function readSessionMeta(file) {
+  const descriptor = fs.openSync(file, "r");
+  let pending = Buffer.alloc(0);
+  const chunk = Buffer.alloc(64 * 1024);
+  try {
+    while (pending.length <= 4 * 1024 * 1024) {
+      const bytes = fs.readSync(descriptor, chunk, 0, chunk.length, null);
+      if (bytes === 0) break;
+      pending = Buffer.concat([pending, chunk.subarray(0, bytes)]);
+      const newline = pending.indexOf(0x0a);
+      if (newline >= 0) pending = pending.subarray(0, newline);
+      if (newline >= 0) break;
+    }
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  if (pending.length > 4 * 1024 * 1024) throw new Error(`rollout 的 session_meta 过大：${file}`);
+  let record;
+  try { record = JSON.parse(pending.toString("utf8")); } catch { throw new Error(`rollout 首行不是有效 JSON：${file}`); }
+  if (record?.type !== "session_meta" || !(record.payload?.id || record.payload?.session_id)) {
+    throw new Error(`rollout 首行缺少 session_meta：${file}`);
+  }
+  return record.payload;
+}
+
+function boundaryForOrdinalExclusive(item, endOrdinalExclusive) {
+  if (!Number.isSafeInteger(endOrdinalExclusive) || endOrdinalExclusive <= 0) {
+    throw new Error(`任务 ${item.threadId} 的 history_base.end_ordinal_exclusive 无效。`);
+  }
+  const boundary = item.ordinalBoundaries.find((entry) => entry.ordinal === endOrdinalExclusive - 1);
+  if (!boundary) {
+    throw new Error(`任务 ${item.threadId} 找不到 ordinal ${endOrdinalExclusive - 1} 的分页边界。`);
+  }
+  return boundary;
+}
+
+function resolveLineage(rows, allRows = rows) {
+  const byId = new Map(allRows.map((row) => [row.id, row]));
+  const metadataById = new Map();
+  for (const row of allRows) {
+    if (!fs.existsSync(row.file)) continue;
+    metadataById.set(row.id, readSessionMeta(row.file));
+  }
+  const included = new Set(rows.map((row) => row.id));
+  let ancestorsExpanded = true;
+  while (ancestorsExpanded) {
+    ancestorsExpanded = false;
+    for (const id of [...included]) {
+      const parentId = metadataById.get(id)?.history_base?.thread_id;
+      if (parentId && !included.has(parentId)) {
+        included.add(parentId);
+        ancestorsExpanded = true;
+      }
+    }
+  }
+  let expanded = true;
+  while (expanded) {
+    expanded = false;
+    for (const row of allRows) {
+      const parentId = metadataById.get(row.id)?.history_base?.thread_id;
+      if (parentId && included.has(parentId) && !included.has(row.id)) {
+        included.add(row.id);
+        expanded = true;
+      }
+    }
+  }
+  const resolved = new Map();
+  const visiting = new Set();
+  function visit(row) {
+    if (resolved.has(row.id)) return;
+    if (visiting.has(row.id)) throw new Error(`检测到循环 paginated lineage：${row.id}`);
+    visiting.add(row.id);
+    if (!fs.existsSync(row.file)) throw new Error(`rollout 文件不存在：${row.file}`);
+    const metadata = metadataById.get(row.id) || readSessionMeta(row.file);
+    if ((metadata.id || metadata.session_id) !== row.id) {
+      throw new Error(`任务 ${row.id} 的 rollout session_meta ID 不一致。`);
+    }
+    const historyBase = metadata.history_base;
+    if (historyBase) {
+      if (metadata.history_mode !== "paginated") throw new Error(`任务 ${row.id} 包含 history_base，但 history_mode 不是 paginated。`);
+      const parent = byId.get(historyBase.thread_id);
+      if (!parent) throw new Error(`任务 ${row.id} 的分页祖先不存在：${historyBase.thread_id}`);
+      visit(parent);
+    }
+    visiting.delete(row.id);
+    resolved.set(row.id, { ...row, metadata });
+  }
+  for (const row of allRows) {
+    if (included.has(row.id)) visit(row);
+  }
+  return [...resolved.values()];
+}
+
 function mapRolloutOffset(offset, changes) {
   if (offset === null || offset === undefined) return offset;
   let delta = 0;
@@ -204,6 +348,13 @@ function mapRolloutOffset(offset, changes) {
   return Number(offset) + delta;
 }
 
+function transformedOffsetForOrdinal(item, ordinal, edge) {
+  if (ordinal === null || ordinal === undefined) return null;
+  const boundary = item.ordinalBoundaries.find((entry) => entry.ordinal === Number(ordinal));
+  if (!boundary) throw new Error(`任务 ${item.threadId} 找不到 turn ordinal ${ordinal} 的字节边界。`);
+  return edge === "start" ? boundary.transformedStart : boundary.transformedEnd;
+}
+
 function atomicWrite(file, buffer, mode) {
   const temporary = `${file}.4yi-migration-${process.pid}.tmp`;
   fs.writeFileSync(temporary, buffer, { mode });
@@ -270,13 +421,14 @@ function restoreDatabase(backupFile, destination) {
 
 function migrationCandidates(database, codexHome, targetProvider, threadId) {
   const rows = database.prepare("SELECT id, rollout_path, model_provider, model FROM threads ORDER BY created_at ASC").all();
-  const selected = threadId ? rows.filter((row) => row.id === threadId) : rows;
-  if (threadId && selected.length === 0) throw new Error(`找不到 Codex 任务：${threadId}`);
-  return selected.map((row) => ({
+  const all = rows.map((row) => ({
     ...row,
     file: resolveRolloutPath(codexHome, row.rollout_path),
     needsMigration: row.model_provider !== targetProvider,
   }));
+  const selected = threadId ? all.filter((row) => row.id === threadId) : all;
+  if (threadId && selected.length === 0) throw new Error(`找不到 Codex 任务：${threadId}`);
+  return { all, selected };
 }
 
 export async function switchCodexThreadsInPlace({
@@ -313,8 +465,15 @@ export async function switchCodexThreadsInPlace({
     requireColumns(historyDatabase, "thread_history_projection_state", ["thread_id", "next_rollout_byte_offset"]);
     requireColumns(historyDatabase, "thread_realtime_items", ["thread_id", "item_type"]);
 
-    const rows = migrationCandidates(stateDatabase, codexHome, targetProvider, threadId);
+    const candidates = migrationCandidates(stateDatabase, codexHome, targetProvider, threadId);
+    let rows;
+    try {
+      rows = resolveLineage(candidates.selected, candidates.all);
+    } catch (error) {
+      throw new Error(`全量迁移预检查失败，未修改任何任务。首个错误：${error.message}`);
+    }
     const failures = [];
+    const analyzed = new Map();
     for (const row of rows) {
       if (!fs.existsSync(row.file)) {
         failures.push({ threadId: row.id, error: `rollout 文件不存在：${row.file}` });
@@ -322,19 +481,36 @@ export async function switchCodexThreadsInPlace({
       }
       try {
         const stat = fs.statSync(row.file);
-        const transformed = transformCodexRolloutFile(row.file, { threadId: row.id, targetProvider });
-        if (!row.needsMigration && transformed.sourceProvider === targetProvider) {
-          fs.unlinkSync(transformed.temporary);
-          continue;
+        let historyBase = row.metadata.history_base;
+        if (historyBase) {
+          const parent = analyzed.get(historyBase.thread_id);
+          if (!parent) throw new Error(`任务 ${row.id} 的分页祖先尚未完成预检查：${historyBase.thread_id}`);
+          if (Number(historyBase.end_byte_offset) > parent.originalSize) {
+            throw new Error(`任务 ${row.id} 的分页 cutoff ${historyBase.end_byte_offset} 超出祖先文件长度 ${parent.originalSize}。`);
+          }
+          const boundary = boundaryForOrdinalExclusive(parent, Number(historyBase.end_ordinal_exclusive));
+          if (Number(historyBase.end_byte_offset) !== boundary.originalEnd) {
+            throw new Error(`任务 ${row.id} 的分页 cutoff 未落在 ordinal ${historyBase.end_ordinal_exclusive} 的合法边界。`);
+          }
+          historyBase = { ...historyBase, end_byte_offset: boundary.transformedEnd };
         }
-        prepared.push({
+        const transformed = transformCodexRolloutFile(row.file, { threadId: row.id, targetProvider, historyBase });
+        const analyzedItem = {
           threadId: row.id,
           file: row.file,
           mode: stat.mode & 0o777,
           originalSize: stat.size,
           originalMtimeMs: stat.mtimeMs,
+          historyMode: row.metadata.history_mode || "legacy",
+          historyBase,
           ...transformed,
-        });
+        };
+        analyzed.set(row.id, analyzedItem);
+        if (!row.needsMigration && !transformed.changed) {
+          fs.unlinkSync(transformed.temporary);
+          continue;
+        }
+        prepared.push(analyzedItem);
       } catch (error) {
         failures.push({ threadId: row.id, error: error.message });
       }
@@ -347,6 +523,34 @@ export async function switchCodexThreadsInPlace({
       throw new Error(`全量迁移预检查失败，未修改任何任务。首个错误：${failures[0].error}`);
     }
 
+    const turnColumns = tableColumns(historyDatabase, "thread_turns");
+    const hasOrdinalOffsets = turnColumns.has("rollout_ordinal") && turnColumns.has("rollout_end_ordinal");
+    const selectOffsets = historyDatabase.prepare(hasOrdinalOffsets
+      ? "SELECT turn_id, rollout_ordinal, rollout_byte_offset, rollout_end_ordinal, rollout_end_byte_offset FROM thread_turns WHERE thread_id = ?"
+      : "SELECT turn_id, rollout_byte_offset, rollout_end_byte_offset FROM thread_turns WHERE thread_id = ?");
+    try {
+      for (const item of prepared) {
+        const rebuildByOrdinal = hasOrdinalOffsets && item.ordinalBoundaries.length > 0;
+        if (item.historyMode === "paginated" && !rebuildByOrdinal) {
+          throw new Error(`任务 ${item.threadId} 是 paginated 历史，但 rollout 不包含可重建的 ordinal。`);
+        }
+        item.turnOffsets = selectOffsets.all(item.threadId).map((turn) => ({
+          turnId: turn.turn_id,
+          start: rebuildByOrdinal
+            ? transformedOffsetForOrdinal(item, turn.rollout_ordinal, "start")
+            : mapRolloutOffset(turn.rollout_byte_offset, item.offsetChanges),
+          end: rebuildByOrdinal && turn.rollout_end_ordinal !== null
+            ? transformedOffsetForOrdinal(item, turn.rollout_end_ordinal, "end")
+            : mapRolloutOffset(turn.rollout_end_byte_offset, item.offsetChanges),
+        }));
+      }
+    } catch (error) {
+      for (const item of prepared) {
+        try { fs.unlinkSync(item.temporary); } catch { /* Best effort cleanup. */ }
+      }
+      throw new Error(`全量迁移预检查失败，未修改任何任务。首个错误：${error.message}`);
+    }
+
     if (prepared.length === 0) {
       stdout(`全部 Codex 任务已经使用 ${targetProvider}，无需修改。`);
       return { migrated: [], failed: [], backupDirectory: null, targetProvider, targetModel };
@@ -376,7 +580,7 @@ export async function switchCodexThreadsInPlace({
     }
     const manifestFile = path.join(backupDirectory, "manifest.json");
     const manifest = {
-      version: 1,
+      version: 2,
       status: "prepared",
       createdAt: now.toISOString(),
       targetProvider,
@@ -387,6 +591,7 @@ export async function switchCodexThreadsInPlace({
         threadId: item.threadId,
         rolloutPath: item.file,
         backupPath: item.backupFile,
+        historyBase: item.historyBase || null,
         sourceProvider: item.sourceProvider,
         byteDelta: item.byteDelta,
         removedReasoning: item.removedReasoning,
@@ -406,28 +611,16 @@ export async function switchCodexThreadsInPlace({
     historyDatabase.exec("BEGIN IMMEDIATE");
     try {
       const updateThread = stateDatabase.prepare("UPDATE threads SET model_provider = ?, model = ? WHERE id = ?");
-      const selectOffsets = historyDatabase.prepare("SELECT turn_id, rollout_byte_offset, rollout_end_byte_offset FROM thread_turns WHERE thread_id = ?");
       const updateOffsets = historyDatabase.prepare("UPDATE thread_turns SET rollout_byte_offset = ?, rollout_end_byte_offset = ? WHERE thread_id = ? AND turn_id = ?");
-      const selectProjection = historyDatabase.prepare("SELECT next_rollout_byte_offset FROM thread_history_projection_state WHERE thread_id = ?");
-      const updateProjection = historyDatabase.prepare("UPDATE thread_history_projection_state SET next_rollout_byte_offset = ? WHERE thread_id = ?");
+      const invalidateProjection = historyDatabase.prepare("DELETE FROM thread_history_projection_state WHERE thread_id = ?");
       const deleteItems = historyDatabase.prepare("DELETE FROM thread_items WHERE thread_id = ? AND item_type IN ('reasoning', 'contextCompaction')");
       const deleteRealtime = historyDatabase.prepare("DELETE FROM thread_realtime_items WHERE thread_id = ? AND item_type IN ('reasoning', 'contextCompaction')");
       for (const item of prepared) {
         updateThread.run(targetProvider, targetModel, item.threadId);
-        if (item.offsetChanges.length > 0) {
-          for (const turn of selectOffsets.all(item.threadId)) {
-            updateOffsets.run(
-              mapRolloutOffset(turn.rollout_byte_offset, item.offsetChanges),
-              mapRolloutOffset(turn.rollout_end_byte_offset, item.offsetChanges),
-              item.threadId,
-              turn.turn_id,
-            );
-          }
-          const projection = selectProjection.get(item.threadId);
-          if (projection) {
-            updateProjection.run(mapRolloutOffset(projection.next_rollout_byte_offset, item.offsetChanges), item.threadId);
-          }
+        for (const turn of item.turnOffsets) {
+          updateOffsets.run(turn.start, turn.end, item.threadId, turn.turnId);
         }
+        invalidateProjection.run(item.threadId);
         deleteItems.run(item.threadId);
         deleteRealtime.run(item.threadId);
       }

package/src/connect.mjs

@@ -269,6 +269,19 @@ function backupGroups(target, home) {
 
 function latestBackups(target, home) {
   const groups = backupGroups(target, home);
+  if (target === "claude") {
+    return groups.find((group) => !group.some(({ record }) => {
+      if (typeof record.content !== "string") return false;
+      try {
+        const value = JSON.parse(record.content);
+        return value?.env?.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY === "1"
+          || value?.appliedId === CLAUDE_DESKTOP_PROFILE_ID
+          || value?.inferenceCredentialHelper?.includes("/.4yi/helpers/claude-desktop-credential");
+      } catch {
+        return record.content.includes("$HOME/.4yi/config.json");
+      }
+    })) || [];
+  }
   if (target !== "codex") return groups[0] || [];
 
   // Older CLI releases created a fresh backup every time `connect codex` ran,
@@ -722,6 +735,7 @@ export function restoreConnection({ target = "all", home = os.homedir(), stdout
   const normalized = normalizeTarget(target);
   if (normalized === "claude") {
     restoreOne("claude", home, stdout);
+    stdout("Claude 已恢复为官方配置。请退出所有 Claude Code/Claude App 进程并打开新终端；当前终端继承的 ANTHROPIC_* 环境变量无法由子进程清除，/logout 也不会覆盖它们。");
     return { restoredClaude: true, restoredCodex: false };
   }
   if (normalized === "codex") {
@@ -731,6 +745,9 @@ export function restoreConnection({ target = "all", home = os.homedir(), stdout
   const restoredClaude = restoreOne("claude", home, stdout, { required: false });
   const restoredCodex = restoreOne("codex", home, stdout, { required: false });
   if (!restoredClaude && !restoredCodex) throw new Error("No Claude or Codex backup found.");
+  if (restoredClaude) {
+    stdout("Claude 已恢复为官方配置。请退出所有 Claude Code/Claude App 进程并打开新终端；当前终端继承的 ANTHROPIC_* 环境变量无法由子进程清除，/logout 也不会覆盖它们。");
+  }
   return { restoredClaude, restoredCodex };
 }