/codex:transfer always fails on Windows: ledger lookup can never match (verbatim \?\ paths + hash of a live transcript)

[menzees-source]

/codex:transfer always fails on Windows: ledger lookup can never match (verbatim \\?\ paths + hash of a live transcript)

Summary

/codex:transfer reports failure on every attempt on Windows, even when Codex imports the session successfully. The import itself works — a thread is created and recorded — but the plugin's post-import lookup in external_agent_session_imports.json can never match the record, so importExternalAgentSession throws:

Codex reported that the Claude import completed, but did not record an imported thread.
Check the Codex app-server logs for the underlying import error.

There is no app-server error to find: ~/.codex/logs_2.sqlite contains zero import-related rows. The imported thread is sitting in ~/.codex/sessions/... and is fully resumable — the user just never gets told its id.

Two independent defects in importedThreadIdForSource (plugins/codex/scripts/lib/codex.mjs:661) each break the match on their own. A third issue makes the error message uninformative.

Environment

• Plugin @openai/codex-plugin-cc 1.0.6 (marketplace openai-codex)
• codex-cli 0.146.0 (desktop install, %LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe)
• Windows 11 Home 26200, ARM64, Node v24.18.0
• Claude Code, CODEX_HOME unset (default C:\Users\<user>\.codex)

Defect 1 — path comparison: Rust verbatim prefix vs Node realpath

Codex writes the ledger source_path via Rust's fs::canonicalize, which on Windows always emits a verbatim extended-length path. The plugin compares it against fs.realpathSync(), which never does:

ledger source_path : "\\\\?\\C:\\Users\\<user>\\.claude\\projects\\C--WINDOWS-system32\\<id>.jsonl"
fs.realpathSync()  : "C:\\Users\\<user>\\.claude\\projects\\C--WINDOWS-system32\\<id>.jsonl"
strictly equal     : false

fs.realpathSync.native() returns the same non-verbatim form, so there is no drop-in Node call that matches. This alone makes record?.source_path === canonicalSource (codex.mjs:673) permanently false on Windows.

Defect 2 — content_sha256 of a still-growing transcript

sourceContentSha256 is computed after the import returns, but the source is the live Claude transcript, which Claude Code appends to continuously (including the turn that invoked /codex:transfer). The hash has already moved on:

content_sha256 in ledger (at import time) : ce85932bed63eace0cd42a9e31c64f9ad57633d839fef6b10ffc836bebad51ad
sha256 recomputed seconds later           : 80d48aa5eb0dfb8a1e7af39c1d58b780e257f1454daeb70123df170bbb14fffc

So record?.content_sha256 === contentSha256 (codex.mjs:674) also fails, on every platform, whenever the session being transferred is the one currently running — i.e. the normal case. Fixing only defect 1 would leave transfers broken.

Defect 3 — failures[] from the completion notification is discarded

requestExternalAgentSessionImport (codex.mjs:701) resolves on externalAgentConfig/import/completed without reading message.params (codex.mjs:714). That payload carries both the authoritative result and any error detail:

{
  "method": "externalAgentConfig/import/completed",
  "params": {
    "importId": "cb789a11-63fe-4787-8520-949aeeb40c44",
    "itemTypeResults": [
      {
        "itemType": "SESSIONS",
        "successes": [
          {
            "itemType": "SESSIONS",
            "cwd": null,
            "source": "\\\\?\\C:\\Users\\<user>\\.claude\\projects\\C--WINDOWS-system32\\<id>.jsonl",
            "target": "019fe103-b7aa-74c1-8fb2-ef6afd58785f"
          }
        ],
        "failures": []
      }
    ]
  }
}

successes[].target is the imported thread id. The ledger round-trip is unnecessary; when it does fail, failures[] is where the real reason would be, and it is dropped.

Related: on the first attempt of the session the ledger file did not exist at all at the moment of the check (no rollout was written either), suggesting the ledger write can lag the completed notification. Reading target from the notification sidesteps that race as well.

Reproduction

On Windows, with Codex ≥ 0.146.0:

1. In Claude Code, run /codex:transfer.
2. Observe the "did not record an imported thread" error.
3. Observe that ~/.codex/external_agent_session_imports.json gained a record with a valid imported_thread_id, and ~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*-<thread-id>.jsonl exists and holds the imported turns.
4. codex resume <imported_thread_id> works fine.

Ran the command three times: three successful imports, three reported failures.

Suggested fix

Prefer the completion notification, keep the ledger as a fallback, and relax both comparisons in the fallback.

1. Return the notification payload:

   client.setNotificationHandler((message) => {
     if (message.method === EXTERNAL_AGENT_IMPORT_COMPLETED) {
-      resolveCompleted();
+      resolveCompleted(message.params ?? null);
       return;
     }
     previousHandler?.(message);
   });
   ...
   try {
     await client.request("externalAgentConfig/import", params);
-    await completed;
+    return await completed;
   } finally {

2. Resolve the thread id from successes[].target first, and surface failures[] on error:

-    const threadId = importedThreadIdForSource(options.sourcePath);
+    const threadId =
+      importedThreadIdFromCompletion(completion, options.sourcePath) ??
+      importedThreadIdForSource(options.sourcePath);
     if (!threadId) {
-      const stderr = cleanCodexStderr(client.stderr);
-      throw new Error(
-        `Codex reported that the Claude import completed, but did not record an imported thread.${stderr ? `\n${stderr}` : " Check the Codex app-server logs for the underlying import error."}`
-      );
+      const details = [importFailureDetails(completion), cleanCodexStderr(client.stderr)].filter(Boolean);
+      throw new Error(
+        [
+          "Codex reported that the Claude import completed, but did not record an imported thread.",
+          ...(details.length ? details : ["Check the Codex app-server logs for the underlying import error."])
+        ].join("\n")
+      );
     }

3. Normalize paths before comparing, and demote content_sha256 from a requirement to a preference:

function normalizeImportPath(value) {
  if (typeof value !== "string" || value === "") {
    return null;
  }
  // Codex canonicalizes with Rust's fs::canonicalize, which emits Windows
  // verbatim paths (\\?\C:\...); Node's realpathSync never does.
  const stripped = value.replace(/^\\\\\?\\UNC\\/, "\\\\").replace(/^\\\\\?\\/, "");
  const normalized = path.normalize(stripped);
  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
}

function importedThreadIdForSource(sourcePath) {
  // ...
  const candidates = records.filter(
    (record) =>
      typeof record?.imported_thread_id === "string" &&
      normalizeImportPath(record?.source_path) === normalizeImportPath(realSource)
  );
  // A live Claude transcript keeps growing while the import runs, so its hash
  // usually no longer matches the imported snapshot.
  return (
    candidates.filter((r) => r?.content_sha256 === contentSha256).at(-1) ?? candidates.at(-1)
  )?.imported_thread_id ?? null;
}

Alternatively, have Codex write a non-verbatim source_path (dunce-style de-canonicalization) and record the hash the plugin can reproduce — but the notification-first approach makes the plugin robust regardless of which side changes.

Verification

Applied the above locally to plugins/codex/scripts/lib/codex.mjs:

Transferred the Claude session into a Codex thread with visible turn history.
Codex session ID: 019fe107-6264-7260-8f15-b033ed23c603
Resume in Codex: codex resume 019fe107-6264-7260-8f15-b033ed23c603

The ledger fallback was exercised separately against the real external_agent_session_imports.json: 3/3 records match after normalization and resolve to the same thread id, so the fallback still works if a future Codex version omits target.

Happy to open a PR if the notification-first direction looks right.

[8146461-lgtm]

Confirming this still reproduces on a newer Codex build and a different Windows edition than the reports so far (#417, #513, #514 were on 0.144.2 / 0.146.0).

Environment

Plugin	codex@openai-codex 1.0.6
Codex CLI	0.147.0-alpha.6.5
OS	Windows 10 x64 (19045)
Node	v24.11.1

Symptom – /codex:transfer (no arguments) prints:

Codex reported that the Claude import completed, but did not record an imported thread.
Check the Codex app-server logs for the underlying import error.

The import in fact succeeded: a rollout was written under ~/.codex/sessions/YYYY/MM/DD/ containing the full Claude transcript, and the thread resumes normally.

Evidence for root cause 1 (verbatim path prefix) – the ledger entry, paths redacted:

{
  "source_path": "\\\\?\\C:\\Users\\<user>\\.claude\\projects\\<project>\\<session-id>.jsonl",
  "content_sha256": "<sha>",
  "imported_thread_id": "<uuid>",
  "imported_at": 1786393032,
  "source_modified_at": 1786393031091818100
}

source_path carries the \\?\ extended-length prefix, so it can never equal the value realpathSync() returns on the same file. This matches the analysis in the issue body exactly.

Two additional data points

1. The failure is idempotent. Re-running /codex:transfer on the same live session emits the identical error but does not create a second thread – the session count under ~/.codex/sessions/ was unchanged (27 before, 27 after), and the ledger kept a single entry for that source. So repeated attempts are noisy but harmless; no thread spam accumulates.

2. Exact working recovery command. The issue mentions codex resume <id> works. For a headless check, note that the sandbox flags must come before the resume subcommand, otherwise the CLI rejects them:

# fails: error: unexpected argument '-s' found
codex exec resume <id> -s read-only

# works
codex exec -s read-only --skip-git-repo-check resume <id> -

Resumed that way, the thread answered questions that could only be sourced from the transferred Claude context (naming the plugin under discussion, the test file, and the number of planted defects), which independently confirms the import content is intact – only the plugin-side lookup is broken.

The imported_thread_id field in ~/.codex/external_agent_session_imports.json is the most reliable place to recover the id from, rather than parsing rollout filenames.

[AndrewAvery7]

This lines up with root causes 1 and 2 in #417/#513/#514 — same \?\ verbatim-path mismatch and the same live-transcript hash race, independently reproduced here on plugin 1.0.6 / Codex 0.146.0.

#469 is the currently open PR tracking a fix for those two (normalizes the path, and treats the content hash as a fallback preference rather than a hard requirement). I opened #551 for the path-only fix and have since closed it in favor of #469, since normalizing the path alone would still leave the hash race in place.

Defect 3 here isn't covered by #469 — that PR only patches the ledger fallback path, it doesn't read successes[].target from the externalAgentConfig/import/completed notification. Your notification-first approach sidesteps the whole ledger race (including the write-lag you noted) rather than patching around it, which is a strictly better fix if it holds up. Worth raising against #469's review thread, or as its own PR — you already have it verified locally, so if you're willing to open that PR it'd likely subsume #469 rather than compete with it.

[chherg11]

Independently reproduced the Windows failure on this environment:

Plugin	codex@openai-codex 1.0.6
Codex CLI	0.144.1
OS	Windows 11 Pro 26200 x64
Node	v25.9.0

The path diagnosis is exact here: all 102 records in external_agent_session_imports.json use a \\?\ path, while fs.realpathSync() returns the ordinary drive path. Zero records can satisfy the current strict comparison. Normalizing the verbatim prefix fixed the lookup for every record whose source transcript still exists.

I also tested the notification-first fix proposed under Defect 3, and found an important compatibility detail: on Codex CLI 0.144.1 the completion notification is shaped correctly but contains no result entries:

{
  "method": "externalAgentConfig/import/completed",
  "params": {
    "importId": "<uuid>",
    "itemTypeResults": [{
      "itemType": "SESSIONS",
      "successes": [],
      "failures": []
    }]
  }
}

I observed that both for an already-imported live transcript and for copied transcripts with a new path/content/session id. Therefore the notification-first implementation should retain the normalized ledger lookup as a compatibility fallback; on this older CLI, successes[].target cannot be the only source of the imported thread id.

The robust order appears to be:

1. Return the completion payload instead of discarding it.
2. Resolve a matching successes[].target when present (normalizing entry.source, which can also be verbatim-prefixed).
3. If there is no target, use the normalized ledger lookup.
4. Surface failures[] when populated; use the generic logs message only when both results arrays are empty.

For matching a payload that has results, this avoids choosing the wrong thread when there are multiple successes:

function importedThreadIdFromCompletion(completion, sourcePath) {
  const { successes } = importResultsFromCompletion(completion);
  if (successes.length === 0) return null;

  const wanted = new Set([normalizeSourcePath(sourcePath)]);
  try {
    wanted.add(normalizeSourcePath(fs.realpathSync(sourcePath)));
  } catch {
    // The source may have been rotated away.
  }

  const match =
    successes.find((entry) => wanted.has(normalizeSourcePath(entry?.source))) ??
    (successes.length === 1 ? successes[0] : null);
  return typeof match?.target === "string" ? match.target : null;
}

This complements #469: notification-first avoids the ledger race on CLIs that return results, while the normalized ledger fallback remains necessary for 0.144.1 and likely other older versions.

[AndrewAvery7]

@chherg11 — really appreciate the independent repro and the quantified confirmation (102/102 ledger records failing the strict match is a stronger data point than I had). Good catch on the CLI 0.144.1 compatibility gap too — that's a real argument for keeping the normalized-ledger path as a fallback rather than retiring it once notification-first lands.

Worth flagging for anyone landing on this thread: #469 is already open and fixes Defects 1 and 2 (verbatim-path normalization + the live-transcript hash race) via a different mechanism — it snapshots the ledger before the import call and matches newly-appended records afterward, rather than reading successes[].target off the completion notification. Since it never touches the notification payload, it shouldn't be exposed to the empty-itemTypeResults gap you found on 0.144.1 — it'd be worth confirming against that environment, but the approach doesn't depend on the field that's missing there.

That leaves Defect 3 (surfacing failures[] instead of the generic "check the logs" message, and the notification-first read as a belt-and-suspenders improvement against the ledger-write race) as the piece that's still uniquely addressed here and not by #469. Might make sense as a follow-up PR once #469 lands, so it doesn't compete with a fix that's already sitting reviewed-and-waiting. Given the overlap, a maintainer merging #469 first — with this thread as extra evidence it's needed — seems like the fastest path to actually fixing this for people hitting it on Windows today.

[bloodykheeng]

Confirming this on plugin 1.0.6 / Codex CLI 0.153.4 / Node 22.19 / Windows 11.

The import succeeds every time. A thread is created, a rollout is written, and a ledger record with a valid imported_thread_id is appended. Only the post-import lookup fails, so the user is told it failed and never gets the id.

Both equality checks in importedThreadIdForSource fail independently:

1. Verbatim path. Codex writes source_path via Rust fs::canonicalize, which emits the extended-length form. Node's fs.realpathSync never does:

ledger source_path: "\\?\C:\Users\...\<session>.jsonl"
node realpathSync : "C:\Users\...\<session>.jsonl"
paths equal       : false

2. Hash of a live transcript. content_sha256 is recomputed after the import, but the source is the running Claude transcript, which grows during it:

ledger  sha256: 18f9ab5774a8421f...
current sha256: b3e0525304722ed1...

Either alone is fatal, so the match can never succeed on Windows.

Two things that may save others time here:

• Restarting does not help. state_5.sqlite shows backfill_state as status: complete with last_success_at about six weeks old (1785337278), and rollout_migration_state empty. That scan runs once and never again, so a rollout dropped in later is not picked up.
• The thread is fine, only the reporting is broken. Until this is fixed you can recover it: take the last imported_thread_id from ~/.codex/external_agent_session_imports.json and run codex resume <id>.

#701 and #469 both fix exactly these two checks and are still open. Merging either would close this, #514 and #417.

There is a related consequence worth separating out: because the failure looks identical to "already imported", a user who retries cannot tell the two apart. I have opened that as its own report.

---

A workaround, while these PRs are open

I ended up writing a small tool for my own use rather than waiting: https://github.com/bloodykheeng/ai-context-relay

It keeps a Claude Code session and a Codex thread in step in both directions, and carries tool calls, their output and pasted screenshots, which the one-shot import does not. Codex still creates the thread over the app-server externalAgentConfig/import call, exactly as this plugin does; the tool only appends to the session file afterwards.

Worth stating plainly: appending to Codex's session files is not a supported interface, and it will break if the rollout format changes. The PRs above are the actual fix for this issue, not this.