multi-codex 0.7.0__py3-none-any.whl

multi_codex/platform.py

@@ -0,0 +1,184 @@
+"""平台适配：默认路径、创建与识别链接、占用检查。
+
+一期只支持 macOS 与 Linux。二期加 Windows 时，平台差异都在本模块和启动命令模板里扩展，
+其它模块不直接判断操作系统。
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from typing import List, NamedTuple, Optional, Tuple
+
+from .fsutil import expand, is_under
+
+# 这些变量在全局设置时会破坏账号隔离，见方案 §3。
+ISOLATION_BREAKING_ENV = ("CODEX_SQLITE_HOME", "CODEX_API_KEY", "CODEX_ACCESS_TOKEN")
+
+
+def is_supported() -> bool:
+    return sys.platform == "darwin" or sys.platform.startswith("linux")
+
+
+def default_source() -> str:
+    return "~/.codex"
+
+
+def default_root() -> str:
+    return "~/.cx"
+
+
+def default_bin_dir() -> str:
+    return "~/.local/bin"
+
+
+def dir_on_path(directory: str) -> bool:
+    """directory 是否在当前 PATH 中。两边都解析软链后比较，`~` 写法与软链写法都算命中。
+
+    doctor 的 path 检查与 add / migrate-default 之后的提示共用它，两处结论必须一致。
+    """
+    entries = [os.path.realpath(expand(entry)) for entry in os.environ.get("PATH", "").split(os.pathsep) if entry]
+    return os.path.realpath(directory) in entries
+
+
+def state_dir() -> str:
+    """工具状态目录：config.json、lock、migrate-journal.json 所在位置。"""
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = xdg if xdg and os.path.isabs(xdg) else os.path.expanduser("~/.config")
+    return os.path.join(base, "multi-codex")
+
+
+def create_link(target: str, link_path: str) -> None:
+    """在 link_path 创建指向 target 的软链；target 使用绝对路径，避免随工作目录变化。"""
+    os.symlink(target, link_path)
+
+
+class BusyProcess(NamedTuple):
+    pid: int
+    command: str
+    # 占用方式（给人看的）：cwd（工作目录）、executable（可执行文件）、mapped（内存映射）或 fd N（打开的文件）
+    usage: str
+    # 落在源目录下的那个路径，让用户一眼看出是哪个文件被占用
+    path: str
+
+
+def describe_usage(fd: str) -> str:
+    """把 lsof 的 fd 字段或 /proc 的条目名翻译成好懂的占用方式；未知值原样返回。"""
+    if fd == "txt":
+        return "executable"
+    if fd == "mem":
+        return "mapped"
+    digits = fd.rstrip("rwuRWU")
+    if digits.isdigit():
+        return "fd " + digits
+    return fd
+
+
+class BusyCheckError(Exception):
+    """占用检查本身无法完成（找不到检查工具，或 lsof 没有正常输出）。"""
+
+
+def find_busy_processes(path: str, exclude_pids: Optional[List[int]] = None) -> List[BusyProcess]:
+    """列出工作目录、可执行文件或打开的文件落在 path 之下的进程。
+
+    只检查顶层数据库文件会漏掉浏览器扩展宿主这类只把工作目录设在其中的进程，
+    所以这里对全部进程逐个判断。结果按“进程名含 codex 的在前”排序。
+    """
+    root = os.path.realpath(path)
+    excluded = set(exclude_pids or [])
+    excluded.add(os.getpid())
+    if shutil.which("lsof"):
+        found = _scan_with_lsof(root, excluded)
+    elif sys.platform.startswith("linux") and os.path.isdir("/proc"):
+        found = _scan_proc(root, excluded)
+    else:
+        raise BusyCheckError("neither lsof nor /proc is available")
+    found.sort(key=lambda item: ("codex" not in item.command.lower(), item.pid))
+    return found
+
+
+def _scan_with_lsof(root: str, excluded: set) -> List[BusyProcess]:
+    # -F pcfn：按字段输出 pid、命令、fd、文件名；-n -P 关闭 DNS 与端口名解析，避免卡顿。
+    proc = subprocess.Popen(
+        ["lsof", "-n", "-P", "-F", "pcfn"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        universal_newlines=True,
+        errors="replace",
+    )
+    stdout, _stderr = proc.communicate()
+    excluded = excluded | {proc.pid}
+    has_process_record = False
+    found = {}
+    pid = None
+    command = ""
+    fd = ""
+    for line in stdout.splitlines():
+        if not line:
+            continue
+        field, value = line[0], line[1:]
+        if field == "p":
+            has_process_record = True
+            pid = int(value) if value.isdigit() else None
+            command = ""
+            fd = ""
+        elif field == "c":
+            command = value
+        elif field == "f":
+            fd = value
+        elif field == "n" and pid is not None and pid not in excluded:
+            if value.startswith("/") and is_under(value, root) and pid not in found:
+                found[pid] = BusyProcess(pid, command, describe_usage(fd), value)
+    # Linux 普通用户运行 lsof 时，常因无权读取其它用户的进程而返回非 0 并输出告警；
+    # 只有一个进程记录都没有时才视为检查失败，否则会把正常情况误判为失败。
+    if proc.returncode != 0 and not has_process_record:
+        raise BusyCheckError("lsof exited with code {} and produced no output".format(proc.returncode))
+    return list(found.values())
+
+
+def _scan_proc(root: str, excluded: set) -> List[BusyProcess]:
+    found = []
+    for entry in os.listdir("/proc"):
+        if not entry.isdigit():
+            continue
+        pid = int(entry)
+        if pid in excluded:
+            continue
+        base = os.path.join("/proc", entry)
+        hit = _proc_usage(base, root)
+        if hit:
+            found.append(BusyProcess(pid, _proc_command(base), describe_usage(hit[0]), hit[1]))
+    return found
+
+
+def _proc_usage(base: str, root: str) -> Optional[Tuple[str, str]]:
+    """返回 (占用方式, 路径)；与 lsof 的 fd 字段取值保持一致，交给 describe_usage 统一翻译。"""
+    for name, usage in (("cwd", "cwd"), ("exe", "txt")):
+        target = _readlink_quiet(os.path.join(base, name))
+        if target and is_under(target, root):
+            return usage, target
+    fd_dir = os.path.join(base, "fd")
+    try:
+        fds = os.listdir(fd_dir)
+    except OSError:
+        return None
+    for fd in fds:
+        target = _readlink_quiet(os.path.join(fd_dir, fd))
+        if target and target.startswith("/") and is_under(target, root):
+            return fd, target
+    return None
+
+
+def _proc_command(base: str) -> str:
+    try:
+        with open(os.path.join(base, "comm"), "r", encoding="utf-8", errors="replace") as handle:
+            return handle.read().strip()
+    except OSError:
+        return "?"
+
+
+def _readlink_quiet(path: str) -> str:
+    try:
+        return os.readlink(path)
+    except OSError:
+        return ""

multi_codex/shared.py

@@ -0,0 +1,127 @@
+"""共享资源链接的计划（方案 §5.1.6）。
+
+每个账号可以把 AGENTS.md、skills 等条目软链到同一个共享目录。
+判断“是不是本工具建的链接”只看 Account.managed_links：链接本身带不了受管标记，
+而用户很可能早就手工建过指向同一共享目录的链接，这类链接关闭共享时不能删。
+"""
+
+import os
+from typing import List, Optional
+
+from . import platform
+from .actions import CONFLICT, CREATE, DELETE, SKIP, UNCHANGED, UPDATE, Action
+from .config import Account, Config
+from .fsutil import KIND_LINK, KIND_MISSING, entry_kind, expand, same_target
+
+
+def plan_shared(new: Config, account: Account, account_dir: str,
+                old_shared_dir: Optional[str], adopt: bool = False) -> List[Action]:
+    """为一个账号生成共享链接动作，并就地更新 account.managed_links。
+
+    adopt 为真时（`add --adopt`），已经指向对应共享条目、但不在名单里的软链会被写进名单（接管），
+    链接本身不动。只接管“指向正确”的软链：指向别处的软链和真实目录照旧判冲突，
+    以免把用户另有用途的东西交给工具，之后关闭共享时被删掉。
+
+    old_shared_dir 是变更前的共享目录：修改 shared.dir 后，
+    仍指向旧目录的受管链接需要改指向新目录，而不是被当成“指向别处”的冲突。
+    """
+    actions: List[Action] = []
+    desired = {}
+    if account.shared:
+        if not new.shared_dir:
+            return [Action(CONFLICT, "shared-link", account_dir,
+                           "shared.dir is not configured; run `multi-codex init --shared-dir DIR`")]
+        shared_root = expand(new.shared_dir)
+        for item in new.shared_items:
+            source = os.path.join(shared_root, item)
+            if entry_kind(source) == KIND_MISSING:
+                actions.append(Action(SKIP, "shared-link", os.path.join(account_dir, item),
+                                      "not present in shared dir {}".format(shared_root)))
+                continue
+            desired[item] = source
+
+    managed = set(account.managed_links)
+    old_root = expand(old_shared_dir) if old_shared_dir else None
+    kept: List[str] = []
+
+    for item, source in desired.items():
+        link = os.path.join(account_dir, item)
+        kind = entry_kind(link)
+        if kind == KIND_MISSING:
+            actions.append(Action(CREATE, "shared-link", link, "-> " + source,
+                                  _create_link(source, link)))
+            kept.append(item)
+        elif kind == KIND_LINK and same_target(link, source):
+            if item in managed:
+                actions.append(Action(UNCHANGED, "shared-link", link))
+                kept.append(item)
+            elif adopt:
+                # 没有文件操作：接管只体现在 config.json 的 managed_links 里。
+                actions.append(Action(UPDATE, "shared-link", link, "adopted"))
+                kept.append(item)
+            else:
+                actions.append(Action(UNCHANGED, "shared-link", link))
+        elif kind == KIND_LINK and item in managed and _points_to(link, old_root, item):
+            actions.append(Action(UPDATE, "shared-link", link, "-> " + source,
+                                  _replace_link(source, link)))
+            kept.append(item)
+        else:
+            reason = "a link to another location" if kind == KIND_LINK else "a real {}".format(
+                "directory" if kind == "dir" else "file")
+            actions.append(Action(CONFLICT, "shared-link", link,
+                                  "already exists as {}".format(reason)))
+
+    for item in account.managed_links:
+        if item in desired:
+            continue
+        link = os.path.join(account_dir, item)
+        kind = entry_kind(link)
+        if kind == KIND_MISSING:
+            continue
+        if kind == KIND_LINK and (_points_to(link, old_root, item) or
+                                  _points_to(link, expand(new.shared_dir) if new.shared_dir else None, item)):
+            actions.append(Action(DELETE, "shared-link", link, "sharing disabled for this item",
+                                  _unlink(link)))
+        else:
+            # 用户已把它换成了别的东西，不再归本工具管理；从名单里移除，但不动它。
+            actions.append(Action(SKIP, "shared-link", link,
+                                  "no longer the link multi-codex created; left untouched"))
+
+    # 保持与 shared_items 相同的顺序，便于人工阅读 config.json。
+    order = {item: index for index, item in enumerate(new.shared_items)}
+    account.managed_links = sorted(set(kept), key=lambda item: order.get(item, len(order)))
+    return actions
+
+
+def plan_remove_links(account: Account, account_dir: str, shared_dir: Optional[str]) -> List[Action]:
+    """账号被注销时，删除本工具建立、且仍指向共享目录的链接。"""
+    actions: List[Action] = []
+    root = expand(shared_dir) if shared_dir else None
+    for item in account.managed_links:
+        link = os.path.join(account_dir, item)
+        if entry_kind(link) == KIND_LINK and _points_to(link, root, item):
+            actions.append(Action(DELETE, "shared-link", link, "account removed", _unlink(link)))
+    return actions
+
+
+def _points_to(link: str, shared_root: Optional[str], item: str) -> bool:
+    return shared_root is not None and same_target(link, os.path.join(shared_root, item))
+
+
+def _create_link(source: str, link: str):
+    def run() -> None:
+        platform.create_link(source, link)
+    return run
+
+
+def _replace_link(source: str, link: str):
+    def run() -> None:
+        os.unlink(link)
+        platform.create_link(source, link)
+    return run
+
+
+def _unlink(link: str):
+    def run() -> None:
+        os.unlink(link)
+    return run

multi_codex/switch.py

@@ -0,0 +1,286 @@
+"""切换默认账号（use）与撤销迁移（restore），见 docs/feature/feature-default-switch.md。
+
+“默认账号”就是 `~/.codex` 软链指向的账号目录：直接运行的 codex、桌面端和 IDE 扩展都用它。
+
+为什么切换前必须确认没有进程在用旧账号：没设置 CODEX_HOME 的 Codex 进程只记住字面路径 `~/.codex`，
+之后每次读写都按这个路径重新打开文件（上游 utils/home-dir/src/lib.rs:52-61）。运行中改了软链，
+它已打开的句柄还在旧账号、新打开的文件却落到新账号；刷新 token 时甚至可能把旧账号的 token
+写进新账号的 auth.json（上游 login/src/auth/manager.rs:1600-1622）。
+
+restore 的进度标记 restore-journal.json：
+- 写于移动任何东西之前，第 3 步注销成功后才删除；
+- 标记存在期间，cli 拦下其它写命令（见 cli._blocked_by_migration），否则 use / migrate-default
+  可能在 restore 做到一半时新建或改动 ~/.codex，让它再也无法完成；
+- 用来区分“restore 做到一半”和“用户手工删掉了账号目录”，两者的文件状态相同。
+调用方（cli.dispatch）已持有写锁。
+"""
+
+import json
+import os
+from typing import Optional, Tuple
+
+from . import accounts, binding, launcher, migrate, platform
+from .actions import error, info, warn
+from .config import Config
+from .fsutil import KIND_DIR, KIND_LINK, KIND_MISSING, atomic_write, entry_kind, expand
+
+STATE_A = "A"
+STATE_A2 = "A'"
+STATE_B = "B"
+STATE_C = "C"
+
+
+class RestoreJournalError(Exception):
+    """restore 标记存在但读不出来；不能猜测进度，交给用户手工检查。"""
+
+
+def default_link() -> str:
+    # default_source() 返回字面量 "~/.codex"，必须展开后才能操作。
+    return expand(platform.default_source())
+
+
+def restore_journal_path() -> str:
+    return os.path.join(platform.state_dir(), "restore-journal.json")
+
+
+def load_restore_journal() -> Optional[dict]:
+    path = restore_journal_path()
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            journal = json.load(handle)
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError) as exc:
+        raise RestoreJournalError("cannot read the restore marker {}: {}".format(path, exc))
+    if not isinstance(journal, dict) or any(not isinstance(journal.get(key), str)
+                                            for key in ("name", "source", "target")):
+        raise RestoreJournalError("the restore marker {} is incomplete".format(path))
+    return journal
+
+
+def pending_restore_notice() -> Optional[str]:
+    journal = load_restore_journal()
+    if journal is None:
+        return None
+    return "an unfinished `restore {0}` exists; rerun `multi-codex restore {0}` to finish it".format(journal["name"])
+
+
+def _registered_owner(config: Config, real_path: str) -> Optional[str]:
+    for name in config.accounts:
+        if os.path.realpath(accounts.account_dir(config, name)) == real_path:
+            return name
+    return None
+
+
+def describe_default(config: Config) -> Tuple[Optional[str], str]:
+    """返回 (默认账号名或 None, 给人看的说明)，供 `use`（不带参数）和 `list` 使用。"""
+    link = default_link()
+    kind = entry_kind(link)
+    if kind == KIND_MISSING:
+        return None, "(none)"
+    if kind == KIND_DIR:
+        return None, "(not migrated: ~/.codex is a real directory)"
+    if kind == KIND_LINK:
+        real = os.path.realpath(link)
+        owner = _registered_owner(config, real)
+        if owner is not None:
+            return owner, owner
+        return None, "(unregistered: {})".format(real)
+    return None, "(~/.codex is neither a directory nor a link)"
+
+
+def use_account(config: Config, name: str, skip_process_check: bool, dry_run: bool) -> int:
+    account = config.find(name)
+    if account is None:
+        error(config.not_registered(name), phase="use")
+        return accounts.EXIT_ERROR
+    target = accounts.account_dir(config, account.name)
+    # 不跟随软链：账号目录本身是软链时，~/.codex 会变成“软链指向软链”，与 restore 的前提不一致。
+    if entry_kind(target) != KIND_DIR:
+        error("account directory is not a real directory", phase="use", path=target)
+        return accounts.EXIT_ERROR
+    link = default_link()
+    kind = entry_kind(link)
+    if kind == KIND_LINK:
+        current = os.path.realpath(link)
+        if current == os.path.realpath(target):
+            info("already the default account: {}".format(account.name))
+            return accounts.EXIT_OK
+        if _registered_owner(config, current) is None:
+            error("~/.codex links to {}, which is not a registered account; nothing was changed".format(current),
+                  phase="use", path=link)
+            return accounts.EXIT_CONFLICT
+        if skip_process_check:
+            warn("--skip-process-check: a running Codex that uses ~/.codex may mix files of the two accounts")
+        else:
+            # 只查旧账号目录：正在用它的进程会在切换后读写到新账号；查不出占用不代表绝对安全，见方案 §1.1。
+            code = migrate._busy_check(current)
+            if code:
+                return code
+    elif kind == KIND_DIR:
+        error("~/.codex is a real directory; run `multi-codex migrate-default NAME` first", phase="use", path=link)
+        return accounts.EXIT_CONFLICT
+    elif kind != KIND_MISSING:
+        error("~/.codex is neither a directory nor a link", phase="use", path=link)
+        return accounts.EXIT_CONFLICT
+
+    if dry_run:
+        info("(dry-run) would point ~/.codex at {}".format(target))
+        return accounts.EXIT_OK
+    temp_link = "{}.multi-codex-tmp.{}".format(link, os.getpid())
+    try:
+        platform.create_link(target, temp_link)
+        migrate._test_hook("use-replace")
+        # 用 rename 原子替换：任何时刻 ~/.codex 要么指向旧账号、要么指向新账号，不会暂时不存在。
+        os.replace(temp_link, link)
+    except Exception as exc:  # noqa: BLE001 —— 任何失败都要清掉临时软链，~/.codex 保持原样
+        if os.path.lexists(temp_link):
+            os.unlink(temp_link)
+        error("{}: {}".format(type(exc).__name__, exc), phase="use", path=link)
+        return accounts.EXIT_ERROR
+    info("default account is now {} (~/.codex -> {}); restart the Codex desktop app and IDE extensions".format(
+        account.name, target))
+    if os.environ.get("CODEX_HOME"):
+        warn("CODEX_HOME is set in this shell; running `codex` here ignores ~/.codex")
+    return accounts.EXIT_OK
+
+
+def _restore_state(config: Config, name: str, link: str, target: str,
+                   journal: Optional[dict]) -> Tuple[Optional[str], Optional[int], str]:
+    """判断 restore 从哪一步开始。返回 (状态, 直接结束时的退出码, 说明)。"""
+    link_kind, target_kind = entry_kind(link), entry_kind(target)
+    points_to_target = link_kind == KIND_LINK and os.path.realpath(link) == os.path.realpath(target)
+    registered = config.find(name) is not None
+    if journal is None:
+        if points_to_target and target_kind == KIND_DIR and registered:
+            return STATE_A, None, ""
+        if not registered and target_kind == KIND_MISSING:
+            return None, None, "D"
+        if link_kind == KIND_LINK and registered and not points_to_target:
+            return None, accounts.EXIT_CONFLICT, ("~/.codex does not point to {}; run `multi-codex use {}` "
+                                                  "first".format(target, name))
+        if not registered:
+            return None, accounts.EXIT_ERROR, config.not_registered(name)
+        if target_kind != KIND_DIR:
+            return None, accounts.EXIT_CONFLICT, "{} is not a real directory".format(target)
+        return None, accounts.EXIT_CONFLICT, "~/.codex is not a link to {}".format(target)
+    # 有标记：只有三项都一致才续跑，避免 HOME 或根目录配置变了以后按旧标记去移动目录。
+    if journal["name"].casefold() != name.casefold() or journal["source"] != link or journal["target"] != target:
+        return None, accounts.EXIT_CONFLICT, ("an unfinished restore of {!r} ({} -> {}) exists; finish it or "
+                                              "check it by hand".format(journal["name"], journal["target"],
+                                                                        journal["source"]))
+    if points_to_target and target_kind == KIND_DIR:
+        return STATE_A2, None, ""
+    if link_kind == KIND_MISSING and target_kind == KIND_DIR:
+        return STATE_B, None, ""
+    if link_kind == KIND_DIR and target_kind == KIND_MISSING:
+        return STATE_C, None, ""
+    return None, accounts.EXIT_CONFLICT, "unexpected state: ~/.codex is {}, {} is {}".format(
+        link_kind, target, target_kind)
+
+
+def restore_account(config: Config, config_exists: bool, name: str, skip_process_check: bool,
+                    accept_relogin: bool, dry_run: bool) -> int:
+    link = default_link()
+    account = config.find(name)
+    journal = load_restore_journal()
+    # 账号已注销（状态 C 中途）时配置里查不到原名，用标记中记录的名字，用户输入的大小写不同也能续跑。
+    if account is not None:
+        canonical = account.name
+    elif journal is not None and journal["name"].casefold() == name.casefold():
+        canonical = journal["name"]
+    else:
+        canonical = name
+    target = accounts.account_dir(config, canonical)
+    state, code, message = _restore_state(config, canonical, link, target, journal)
+
+    if state is None and message == "D":
+        # 没有标记、账号未登记、目录也不在：要么从未有过这个账号，要么上一次 restore 写完配置后、
+        # 删启动命令前中断了。后一种情况要把残留的启动命令清掉。
+        path = launcher.launcher_path(expand(config.bin_dir), canonical)
+        owner = launcher.managed_account(path)
+        if owner is None or owner.casefold() != canonical.casefold():
+            error(config.not_registered(name), phase="restore")
+            return accounts.EXIT_ERROR
+        if dry_run:
+            info("(dry-run) would delete the leftover launcher {}".format(path))
+            return accounts.EXIT_OK
+        code = accounts.converge(config, config.copy(), config_exists=config_exists, dry_run=False,
+                                 orphan_scope=frozenset([canonical.casefold()]))
+        if code == accounts.EXIT_OK:
+            info("restore of {} finished".format(canonical))
+        return code
+    if state is None:
+        error(message, phase="restore", path=link)
+        return code
+    if state != STATE_A:
+        info("resuming restore of {} from state {}".format(canonical, state))
+
+    relogin_needed = bool(journal.get("relogin_needed")) if journal else False
+    if state in (STATE_A, STATE_A2, STATE_B):
+        parent = os.path.dirname(link)
+        if os.stat(target).st_dev != os.stat(parent).st_dev:
+            error("{} and ~/.codex are on different file systems; restore by hand: remove the ~/.codex link, "
+                  "copy {} to ~/.codex, then run `multi-codex remove {}`".format(target, target, canonical),
+                  phase="restore", path=target)
+            return accounts.EXIT_CONFLICT
+        if state == STATE_A:
+            # 移回 ~/.codex 改变了真实路径，与迁移一样会让钥匙串里的登录失效。
+            code, relogin_needed = migrate._check_credentials_store(target, canonical, accept_relogin,
+                                                                    relogin_command="codex login")
+            if code is not None:
+                return code
+        if skip_process_check:
+            warn("--skip-process-check: {} may still be in use".format(target))
+        else:
+            code = migrate._busy_check(target)
+            if code:
+                return code
+
+    if dry_run:
+        if state in (STATE_A, STATE_A2):
+            info("(dry-run) would unlink ~/.codex")
+        if state in (STATE_A, STATE_A2, STATE_B):
+            info("(dry-run) would move {} to ~/.codex".format(target))
+        info("(dry-run) would unregister {} and delete codex-{}".format(canonical, canonical))
+        return accounts.EXIT_OK
+
+    if state == STATE_A:
+        atomic_write(restore_journal_path(), json.dumps({
+            "name": canonical, "source": link, "target": target, "relogin_needed": relogin_needed,
+        }, indent=2, ensure_ascii=False) + "\n", mode=0o600)
+        migrate._test_hook("restore-marked")
+    if state in (STATE_A, STATE_A2):
+        os.unlink(link)
+        info("step=unlink {}".format(link))
+        migrate._test_hook("restore-unlinked")
+    if state in (STATE_A, STATE_A2, STATE_B):
+        try:
+            os.rename(target, link)
+        except OSError as exc:
+            # 第 1、2 步之间有人运行了 codex，新建了非空的 ~/.codex。
+            error("cannot move {} to ~/.codex ({}); move the new ~/.codex away and rerun "
+                  "`multi-codex restore {}`".format(target, exc, canonical), phase="restore", path=link)
+            return accounts.EXIT_ERROR
+        info("step=rename {} -> {}".format(target, link))
+        migrate._test_hook("restore-renamed")
+
+    info("step=unregister {}".format(canonical))
+    new = config.copy()
+    current = new.find(canonical)
+    if current is not None:
+        del new.accounts[current.name]
+    binding.drop_account(new, canonical)
+    code = accounts.converge(config, new, config_exists=config_exists, dry_run=False,
+                             orphan_scope=frozenset([canonical.casefold()]))
+    if code != accounts.EXIT_OK:
+        # 保留标记：现在处于状态 C，修好问题后重跑同一命令即可。
+        error("data is back at ~/.codex but unregistering failed; fix the problem above and rerun "
+              "`multi-codex restore {}`".format(canonical), phase="restore")
+        return code
+    if os.path.exists(restore_journal_path()):
+        os.unlink(restore_journal_path())
+    info("restored {} to ~/.codex".format(canonical))
+    if relogin_needed:
+        info("log in again: codex login")
+    return accounts.EXIT_OK