fix(cli): canonicalize backfill file paths via realpath to stop symlinked-home duplicate rollups

Rollup identity hashes the absolute file path, so the same physical
session file seen through a symlinked agent home (e.g. hook running
with CODEX_HOME=~/.codex-work -> ~/.codex while a manual sync uses the
real path) uploaded duplicate rollups. Resolve every listed file to its
physical path at the listBackfillSourceFiles chokepoint and drop
same-run canonical-path duplicates. Keying by source+sessionId instead
was rejected: sessionId comes from file content and legitimately
repeats across files (Claude Code subagent transcripts), so dropping
the path would clobber them.

Schema v6->v7 re-parses history on next sync; users with symlinked
homes must run `sync --purge` once since their rollup keys change.

Refs: report by saphitv (multi-account .codex-t3 shadow homes)

Author: Jannchie

packages/cli/src/cli.ts

@@ -8,7 +8,7 @@ import type {
 import type { BackfillSourceDefinition } from './lib/backfill.js'
 import type { BackfillImportCounts, BackfillIncrementalState, BackfillSourceFile, ParsedArgs, RunContext, SyncLocalLock, SyncLocalTriggerState, WritableLike } from './lib/types.js'
 import { spawn } from 'node:child_process'
-import { rm, stat } from 'node:fs/promises'
+import { realpath, rm, stat } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -634,19 +634,19 @@ async function listBackfillSourceFiles(
   ctx: RunContext,
 ): Promise<BackfillSourceFile[]> {
   if (source.id === 'opencode') {
-    return opencodeBackfillFiles(stringOption(options['source-root']), resolveHome(options, ctx), ctx.env)
+    return canonicalizeBackfillFiles(await opencodeBackfillFiles(stringOption(options['source-root']), resolveHome(options, ctx), ctx.env))
   }
   if (source.id === 'amp') {
-    return ampBackfillFiles(stringOption(options['source-root']), resolveHome(options, ctx), ctx.env)
+    return canonicalizeBackfillFiles(await ampBackfillFiles(stringOption(options['source-root']), resolveHome(options, ctx), ctx.env))
   }
   if (source.id === 'gemini') {
-    return geminiBackfillFiles(stringOption(options['source-root']), resolveHome(options, ctx), ctx.env)
+    return canonicalizeBackfillFiles(await geminiBackfillFiles(stringOption(options['source-root']), resolveHome(options, ctx), ctx.env))
   }
   if (source.id === 'codex') {
     const files = await codexBackfillFiles(stringOption(options['source-root']), resolveHome(options, ctx), ctx.env)
-    return files
+    return canonicalizeBackfillFiles(files
       .sort((a, b) => a.path.localeCompare(b.path))
-      .slice(0, numberOption(options.limit) || undefined)
+      .slice(0, numberOption(options.limit) || undefined))
   }
 
   const roots = stringOption(options['source-root'])
@@ -658,10 +658,38 @@ async function listBackfillSourceFiles(
     .sort()
     .slice(0, numberOption(options.limit) || undefined)
 
-  return Promise.all(files.map(async (filePath) => {
+  return canonicalizeBackfillFiles(await Promise.all(files.map(async (filePath) => {
     const info = await stat(filePath)
     return { path: filePath, modifiedAt: info.mtime.toISOString() }
-  }))
+  })))
+}
+
+// Rollup identity includes a hash of the file's absolute path, so the same
+// physical file reached through different paths (symlinked agent homes like
+// CODEX_HOME=~/.codex-work → ~/.codex, macOS /var → /private/var) would
+// otherwise upload duplicate rollups — a hook-triggered sync and a manual one
+// can legitimately see different spellings of the same home. Resolve every
+// listed file to its physical path before parsing so all views agree on one
+// identity, and drop same-run duplicates that collapse together.
+async function canonicalizeBackfillFiles(files: BackfillSourceFile[]): Promise<BackfillSourceFile[]> {
+  const seen = new Set<string>()
+  const result: BackfillSourceFile[] = []
+  for (const file of files) {
+    let resolved = file.path
+    try {
+      resolved = await realpath(file.path)
+    }
+    catch {
+      // Keep the literal path: a file that vanished between listing and now
+      // (or an unreadable parent) still fails later with proper per-file logging.
+    }
+    if (seen.has(resolved)) {
+      continue
+    }
+    seen.add(resolved)
+    result.push(resolved === file.path ? file : { ...file, path: resolved })
+  }
+  return result
 }
 
 function writeBackfillDiscover(plan: BackfillPlan, options: ParsedArgs, ctx: RunContext) {

packages/cli/src/lib/types.ts

@@ -35,13 +35,15 @@ export interface BackfillSourceFile {
 // ccusage-parity token fixes — OpenCode step-finish double-count, Amp
 // tokens.total / ledger-less fallback, Codex cumulative-only token_count,
 // and the pi/gemini edge cases, and the v6 Codex UUIDv7 creation-anchor
-// that skips copied branch/goal rollout history). The CLI compares the
+// that skips copied branch/goal rollout history, and the v7 realpath
+// canonicalization of source file paths so symlinked agent homes stop
+// producing duplicate rollup identities). The CLI compares the
 // constant against the on-disk schema; on a mismatch it drops every
 // watermark so the next sync silently re-parses all jsonl from scratch
 // and upserts the rebuilt rollups (`replace: true` is already set) — no
 // purge, nothing deleted. Users get the fix transparently the next time
 // their agent runs.
-export const BACKFILL_STATE_SCHEMA_VERSION = 6
+export const BACKFILL_STATE_SCHEMA_VERSION = 7
 
 export interface BackfillIncrementalState {
   version: typeof BACKFILL_STATE_SCHEMA_VERSION

packages/cli/test/cli.test.ts

@@ -1,6 +1,6 @@
 import type { RunContext } from '../src/lib/types.ts'
 import assert from 'node:assert/strict'
-import { mkdir, mkdtemp, readdir, readFile, stat, utimes, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readdir, readFile, stat, symlink, utimes, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { Readable } from 'node:stream'
@@ -447,6 +447,36 @@ test('codexBackfillFiles discovers archived_sessions and prefers the active copy
   assert.equal(files.has(path.join(archived, 'a.jsonl')), false) // deduped in favor of active
 })
 
+test('symlinked Codex home yields the same rollup identity as the real path', async () => {
+  const home = await createCodexBackfillHome()
+  // Multi-account setups point CODEX_HOME at a shadow dir that symlinks the
+  // real ~/.codex; a hook-triggered sync sees the shadow path while a manual
+  // sync sees the real one. Both must resolve to one rollup identity.
+  const shadowCodexHome = path.join(home, '.codex-shadow')
+  await symlink(path.join(home, '.codex'), shadowCodexHome, 'dir')
+
+  const importOnce = async (env: Record<string, string>) => {
+    let body = ''
+    const exitCode = await run(['backfill', 'import', '--source', 'codex', '--home', home, '--api-url', 'http://example.test', '--force', '--json'], testContext({
+      env: { HOME: home, ...env },
+      fetch: async (_url, init) => {
+        body = String(init?.body)
+        const rollups = JSON.parse(body).rollups
+        return Response.json({ inserted: rollups.length, skipped: 0, conflicts: 0, conflictIds: [] }, { status: 200 })
+      },
+    }))
+    assert.equal(exitCode, 0)
+    return JSON.parse(body).rollups
+  }
+
+  const direct = await importOnce({})
+  const viaSymlink = await importOnce({ CODEX_HOME: shadowCodexHome })
+
+  assert.equal(direct.length, 1)
+  assert.equal(viaSymlink.length, 1)
+  assert.equal(viaSymlink[0].rollupKey, direct[0].rollupKey)
+})
+
 test('backfill import sends parsed Codex events and counts API results', async () => {
   const home = await createCodexBackfillHome()
   const calls: Array<{ url: string, body: string }> = []