[jayhemnani9910]

Summary

teamai session migrate (and session push) can scramble a Claude Code transcript: every user prompt comes first, then every answer. Claude Code links each record to the one before it by parentUuid, and that chain also runs through system and attachment lines. flattenDag drops those lines, so each message right after one has a parent it cannot find and becomes an extra root (src/session-flow/adapters/claude-code.ts:556). The walk is breadth-first from all roots at once (:561), so it emits every root first, then every root's child, and so on. The migration still reports Fidelity: 100.0%.

This PR walks depth-first instead, children in file order, so each root's chain stays in one piece. A linear session reads back in its real order. Sidechains are still dropped. Fork branches now follow one another instead of interleaving, so I updated that line in the known-limitations list of docs/designs/session-user-repo-sync.md.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature causing existing behavior to change)
• Documentation only
• Refactor / internal cleanup

Test Plan

• npx tsc --noEmit passes
• npm run lint passes
• npx vitest run passes (9831 pass; the same 4 tests fail on main here: two submodule-checkout cases that need git >= 2.54 (local 2.53), one hooks-reconcile-scope real-shell case, and cursor-bubble-range, which needs a sqlite3 CLI this machine does not have)
• Added/updated tests for the change

New test in session-cmd.test.ts: a session Q1 A1 [system] Q2 A2 [attachment] Q3 A3 must read back as Q1 A1 Q2 A2 Q3 A3. On main it reads back as Q1 Q2 Q3 A1 A2 A3. It passes with the fix.

Real CLI, built from main (27a026f) and from this branch (655b21f), with a throwaway HOME. The Claude Code session has a turn_duration system line after the first turn and an attachment line after the second, then:
teamai session migrate <id> -s claude-code -t codex --cwd <proj> -y, and the result read back through codex app-server (thread/read, Codex 0.162.1):

source:  Q1 A1 Q2 A2 Q3 A3
main:    Q1 Q2 Q3 A1 A2 A3   (Fidelity: 100.0%)
branch:  Q1 A1 Q2 A2 Q3 A3

Session migration is not in an npm release yet (0.27.0 and 0.28.0-beta.3 have no session migrate), so this is on main only.

Related Issues

Follow-up to #593.

Notes for Reviewers

The change is only the walk order in flattenDag. #1135 changes readSession in the same file but not this function. It also rewrites the known-limitations item just above the one this PR edits, so whichever lands second may need a one-line rebase there.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

No findings in the specified PR diff.

The depth-first traversal preserves root and child file order while keeping each chain contiguous. The regression test covers both system and attachment interruptions.

The PR description satisfies the testing requirement: it documents a built real-CLI migration and Codex readback, comparing base and head results. No additional provider × agent coverage is required.

[jeff-r2026]

Please resolve the conflicts.

[jayhemnani9910]

Rebased on main, conflicts fixed. The new test now calls readSession({ sessionId }) to match the updated signature.

[github-actions]

No findings in the specified PR diff.

The depth-first traversal preserves root and child file order while keeping each chain contiguous. The regression test covers interruptions by both system and attachment records.

The PR description satisfies the testing requirement: it documents a built real-CLI migration and Codex readback, comparing base and branch results. The older tested commit is not blocking under the review rules.

The earlier review raised no findings. I did not run, build, or install PR code.