fix(server): session import skips Codex subagent sessions

[Mnigos]

Fixes #16222

Problem

Codex writes every subagent it spawns (spawn_agent), plus its /review and guardian agents, as a separate rollout under ~/.codex/sessions. The session import scanner treated every rollout as a user conversation. Importing a project's recent sessions therefore created one top-level import:codex:<id> thread per subagent, titled after injected setup text such as # AGENTS.md instructions. The project list in onboarding also counted those subagents in its session totals.

Change

The first record of a Codex rollout (session_meta) says where the session came from. Top-level sessions store a string source ("cli", "vscode", "exec", "unknown") or an object such as { custom }. Subagents store an object keyed subagent, which the app-server schema spells subAgent. The scanner now drops a rollout whose session_meta.payload.source has either key.

This follows the fix area suggested in the triage comment on the issue:

• It excludes a rollout whenever the subagent/subAgent key is present, not only for thread_spawn, so review, compact, guardian and other child agents are excluded too.
• The check runs where the scanner reads the rollout's cwd. A dropped rollout is left out of the project's session count in onboarding, never takes a slot in the import's transcript budget, and is not reported as Skipped, so it raises no "could not be imported" warning.

This matches Codex's own resume list, which shows only interactive sources by default. The issue suggests Claude subagents are attached to their parent thread. In fact the scanner skips them too: Claude keeps subagent transcripts in a subagents/ subdirectory the scanner never lists, and inline isSidechain records are ignored.

Unchanged or not covered:

• Subagent threads that were already imported stay until they are deleted.
• Subagents are skipped, not attached to their parent thread. Attaching would mean mapping parent_thread_id to the imported parent and replaying the child as a subagent turn item. That is a feature, not part of this fix.
• A rollout whose first cwd-bearing record is a turn_context written before any session_meta would still be listed. None of the 3,272 local rollouts looked like that.
• Skipped subagent rollouts still count against the scan's discovery budget, so in a truncated scan they can still crowd out older sessions.

Verification

The rollout shapes were checked against the first line of 3,272 local Codex rollouts. Only the type of source and its keys were read. String sources: vscode, exec, unknown, cli. Object sources, all subagent: thread_spawn (with parent_thread_id, depth, agent_path, agent_nickname, agent_role), review, and { other: "guardian" }. None of the top-level sessions had an object source. The generated Codex app-server schema lists the same split in ThreadSourceKind (cli, vscode, exec, appServer, unknown, and the subAgent* kinds).

A new test in AgentSessionScanner.test.ts writes synthetic rollouts to a temporary Codex home. Each one has a session_meta, a turn_context that repeats the cwd, and a user message. The test scans and then lists recent threads through the same scanner instance, so the import reads the candidates cached by the scan:

Test case	Base 25d5c7cacb	This branch
lists top-level Codex sessions but not the subagents they spawned (sources: "vscode", absent, null, { custom }, subagent with thread_spawn, review and { other: "guardian" }, and { subAgent: "compact" })	Fail: project counts 8 sessions	Pass: counts 4, imports only the four top-level sessions

Gate	Result
(cd apps/server && vp test run src/project/AgentSessionScanner.test.ts src/project/AgentSessionImporter.test.ts)	82 passed, 1 failed: excludes sandboxes reached through a symlink into the worktrees dir also fails on unmodified code on macOS
(cd apps/server && vp run typecheck)	Exit 0, no error TS or warning TS
vp fmt --check / vp lint on the two changed files	Pass
knip --workspace apps/server --exports	Pass

This is a server-only change with no UI, so there are no screenshots.

Limitations / not checked: no real import was run on a server. The fixtures are synthetic, and the shapes come from local rollout first lines and the generated schema.

Implemented with Claude Opus 5.5, verified with GPT-6 Astra, coordinated by Claude Fable 5.1 in Claude Code.

[macroscopeapp]

Approvability

Verdict: Approved at 526519d

Macroscope's review found this PR approvable — This is a focused server-side bug fix that prevents Codex subagent rollouts from being incorrectly counted and imported as user sessions, while preserving top-level session behavior. The change is localized and covered by targeted tests, with no schema, deployment, product-default, or static-analysis impact.

Notes:

• Diff unchanged. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 23649d90-1678-4cbb-8787-921ee95ade73

📥 Commits

Reviewing files that changed from the base of the PR and between d021f57 and 526519d.

📒 Files selected for processing (2)

• apps/server/src/project/AgentSessionScanner.test.ts
• apps/server/src/project/AgentSessionScanner.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The Codex session scanner now skips records whose session_meta source marks them as subagents. A test covers missing, null, string, and object-valued source metadata, including subagent variants.

Changes

Codex subagent filtering

Layer / File(s)	Summary
Detect and skip subagent sessions apps/server/src/project/AgentSessionScanner.ts, apps/server/src/project/AgentSessionScanner.test.ts	extractCwd returns an empty string when a Codex session_meta record has an object-valued source containing subagent or subAgent. The grouping loop skips falsy cwd values. The test checks source variants and expects four candidate threads and four importable outcomes.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: juliusmarminge

Merge Risk: 🔵 Low · up to 52651

Very high-volume Codex homes may miss some recent top-level sessions during import; this is a bounded follow-up risk rather than a general failure.

Architecture Summary

Architecture risk: 🔵 Low · up to 52651

The change affects 1 system.

Changed systems: apps/server

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — apps/server (service) was modified; 2 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in apps/server/src/project/AgentSessionScanner.test.ts: Adds a test covering Codex session-source variants. Its expectations include four top-level sessions in the candidate count and four importable outcomes, excluding the spawned session and other tested subagent markers.
• observed — Modified behavior in apps/server/src/project/AgentSessionScanner.ts: Expanded the extractCwd comment to document that Codex subagent rollouts return an empty string and are skipped.
• observed — Modified behavior in apps/server/src/project/AgentSessionScanner.ts: For session_meta records, added detection of object-valued payload.source with a subagent or subAgent key; these records now return an empty string before nested cwd extraction.
• observed — Modified behavior in apps/server/src/project/AgentSessionScanner.ts: The grouping loop now skips any falsy cwd, replacing the prior check that skipped only null.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: the server skips Codex subagent sessions during import.
Description check	✅ Passed	The description covers the problem, change, scope, verification, and limitations. The Scope and approval section links issue #16222 and its triage comment, but does not include an explicit maintainer …
Linked Issues check	✅ Passed	Issue #16222 asks the importer to skip Codex subagent rollouts or attach them to their parent. The PR implements the skip option. extractCwd detects payload.source objects with subagent or `subA…
Out of Scope Changes check	✅ Passed	The changes are limited to Codex rollout filtering in AgentSessionScanner.ts and a scanner test. Returning an empty path and skipping falsy paths directly supports excluding subagent rollouts from p…
Approvability	✅ Passed	The pull request changes only apps/server/src/project/AgentSessionScanner.ts and its test. The scanner change excludes Codex subagent rollouts from session imports, and the test covers that behavior…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

Dismissing prior approval to re-evaluate 526519d