feat(migration): 重建 OpenCode 原生 subagent 会话

[yororoA]

问题

TRAE 会把 subagent 执行记录合并进主 session。记录中既包含空工具占位符和矛盾时间，也包含可恢复的 agent_run_id / parent_agent_run_ids 拓扑。此前整个会话会被拒绝；第一版修复只能扁平导入，无法在 OpenCode 中显示为真正的 subagent。

修复

• 忽略结构为空的工具占位符，非空非法调用仍保持 fail-closed
• 对有明确诊断证据的 partial session 归一矛盾完成时间，并保留原始时间
• 按唯一且一致的 run、父链、agent、任务描述、状态和 timing 重建直接 subagent 子会话
• 在子会话写入 info.parentID，在父 assistant 消息写入原生 subagent tool，并通过 state.metadata.sessionID 关联
• 选择根会话时自动包含派生子会话；跨消息、不完整、冲突或嵌套 run 保守保持内联
• mapping 升级到 v10，继续识别 v1-v9 所有权记录用于安全覆盖和回滚

验证

• 真实失败会话：重建 1 个父会话和 21 个子会话，dry-run ready=22、blocked=0
• OpenCode 2.0.18 隔离原生导入：22 个会话全部导入并回读
• 父消息 21 个 subagent tool 的 sessionID 与 children API 返回的 21 个子会话完全一致
• npm run check：489 项测试通过
• npm run verify:opencode -- --json
• npm run verify:versions
• npm run verify:package
• OpenCode v1 1.18.32 / 1.17.9 集成回归通过

产品版本和 CHANGELOG 继续由 release-please 管理。

Summary by Sourcery

将可验证的 TRAE 内联 subagent 历史迁移为 OpenCode 原生父子会话，同时增强部分会话恢复和派生会话图的安全处理。

New Features:

• 重建可验证的 TRAE subagent 调用为 OpenCode 原生父子会话，并在父时间线中显示关联的 Agent 工具。

Bug Fixes:

• 忽略空的 TRAE 工具占位符，同时继续拒绝非空非法工具调用。
• 对有诊断依据的部分恢复会话归一矛盾的完成时间并保留原始时间证据。

Enhancements:

• 支持派生会话图的选择、完整性校验、迁移计划和安全覆盖/回滚。
• 对跨消息、冲突、不完整或嵌套的 subagent run 采取保守内联处理。

Documentation:

• 更新迁移、映射、操作和故障排查文档，说明原生 subagent 重建及 mapping v10 行为。

Tests:

• 补充 subagent 解析、会话组装、父子链接、时间投影及派生会话迁移流程测试。

Chores:

• 将 OpenCode 映射版本升级至 v10，并继续兼容 v1-v9 的所有权记录。

[sourcery-ai]

Sorry @yororoA, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 20 hours and 21 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Mapping v9 adds targeted recovery for TRAE sessions containing merged subagent history: empty tool placeholders are ignored, proven-invalid assistant completion times are clamped only in partial sessions with full source evidence retained, and both OpenCode mapping paths expose the projection metadata while preserving v1–v8 ownership compatibility.

Sequence diagram for mapping a TRAE subagent session

sequenceDiagram
    participant Bundle as TRAE bundle
    participant Parser as parseTraeToolCalls
    participant Mapper as mapOpenCodeSession
    participant Target as OpenCode session

    Bundle->>Parser: parseTraeToolCalls
    Parser-->>Mapper: tool calls
    Note over Parser: Empty name + null/empty params/result is ignored
    Parser-->>Mapper: Non-empty invalid call fails closed
    Bundle->>Mapper: assistant event and diagnostics
    Mapper->>Mapper: projectedAssistantTime
    alt partial session with T2O_IR_EVENT_TIME_INVALID evidence
        Mapper->>Target: Clamp completed time to created time
        Mapper->>Target: Store source and target times in metadata
    else no explicit invalid-time evidence
        Mapper-->>Bundle: Reject session
    end

Loading

File-Level Changes

Change	Details	Files
Relax parsing for structurally empty subagent tool placeholders while preserving fail-closed validation for malformed non-empty calls.	Treat null and undefined parameters as empty-placeholder cases when name and result are also empty. Add coverage for null placeholders and mixed malformed calls. Keep invalid non-empty tool calls diagnostic and blocking.	src/source/trae/tool-calls.ts src/source/__tests__/tool-calls.test.ts src/source/__tests__/assemble-bundle.test.ts
Normalize contradictory assistant event times only when partial-session diagnostics prove the source timestamp is invalid, and preserve the projection evidence.	Detect source completion times earlier than creation times using event and source-reference diagnostics. Clamp target completion to creation time only for partial sessions with T2O_IR_EVENT_TIME_INVALID. Record source/target timestamps and projection reason in message or v1 provenance metadata. Emit T2O_OPENCODE_EVENT_TIME_PROJECTED while continuing to reject unsupported contradictory timestamps.	src/target/opencode/mapping.ts src/target/opencode/v1/mapping.ts src/target/__tests__/opencode-mapping.test.ts src/target/__tests__/opencode-v1-mapping.test.ts
Upgrade OpenCode mappings to v9 while retaining ownership compatibility with prior mapping versions.	Centralize the current mapping version as OPENCODE_MAPPING_VERSION = 9. Apply v9 markers to sessions and continuation boundaries for both mapping paths. Allow ownership checks to recognize verified mappings from v1 through v9 for overwrite and rollback.	src/target/opencode/mapping.ts src/target/opencode/v1/mapping.ts src/migration/ownership.ts src/target/__tests__/opencode-mapping.test.ts
Document subagent recovery behavior, timestamp projection semantics, and the v9 migration path.	Explain that empty placeholders are ignored but unverifiable tool data still stops migration. Update operational and troubleshooting guidance from v8 to v9. Document v1 provenance storage for projected timing and update the mapping version table.	docs/operation-manual.md docs/troubleshooting.md docs/versioning.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.