[DeJeune]

What this PR does

Before this PR: editing an Agent input deleted its original tail. History was flat, and session-wide resume selection could not safely distinguish retained branches.

After this PR: Agent archives have a hidden root, parent links and a selected path. Edit/resend preserves the original tail, creates a sibling input with an independent Pi context, and exposes the existing sibling navigator. Late output and cross-session replies stay on their originating branch.

Fixes: None

Why we need it and why it was done in this way

The following tradeoffs were made:

• Keep the existing Agent tables and DataApi ownership. Append a schema migration; backfill existing archives through the registered Seeder without changing message IDs, timestamps, attachments, usage or admission facts.
• Bind native identity, published head and fork checkpoint mappings at root/branch anchors. Shared prefix rows retain their original native provenance.
• Capture the send target before asynchronous validation. Reject a stale append or busy cross-branch send; close an idle connection before changing native targets. Closing barriers retain the token's original branch.
• Refresh the renderer from Main's selected path after acknowledgement. Queued output and completion/error replies cannot follow a later UI selection.

The following alternatives were considered: immediately merging Agent archives into topic/message, representing branches as context trees, and rebuilding native history from displayed messages. None is required to retain branches safely.

Links to places where the discussion took place: #22071, #22010, #20635.

Agent Note / Spec

Agent Note: .agents/notes/proposed/architecture/2026-10-17-agent-runtime-contract.md, with its Chinese counterpart and pairing record.

Spec PR: #22071 / #22010 for the storage and tree plan; #21910 for the common runtime contract. Workspace discussion explicitly authorized implementation. Exact-head Spec review approval is pending, so this PR stays draft and the note remains proposed.

Acceptance criteria: tree-layer portions of AC8 (populated migration), AC9 (branch projection) and AC12 (native edit/fork behavior), plus target-isolation evidence relevant to AC6. This intermediate layer does not complete the full common Runtime desktop or crash-recovery criteria.

Verification

Stack refresh: rebased onto the native-gateway layers without changing this PR's implementation scope. pnpm change:scope --base feature/agent-runtime-native-contexts --head feature/agent-runtime-message-tree and pnpm docs:affected --base feature/agent-runtime-native-contexts --head feature/agent-runtime-message-tree --json were inspected. The cumulative gateway checks are recorded in #22107; prior package/storage verification below is retained as historical evidence and was not rerun solely for this rebase.

• Main: 569 tests passed across 18 explicitly selected files; Renderer: 85 tests passed across 3 files. Covers real SQLite migration, repeatable seeding, retained branches, native Pi fork publication, repeated edits, branch-pinned pagination, delayed delivery, stale sends and closing-token isolation.
• Development Electron with a local scripted OpenAI-compatible HTTP model: sent two turns, edited the second, switched to the original branch and continued, switched back and continued, then edited the first input. Native HTTP requests contained only each branch's inputs; the original subtree remained navigable. The translated edit warning was checked in the UI. After a graceful Electron restart at the committed head, the selected branch and its native history continued correctly. No external provider or tool execution was needed.
• pnpm typecheck:node and pnpm typecheck:web passed. Changed-file Oxlint (--deny-warnings), ESLint, Oxfmt and git diff --check passed; ESLint reports one existing non-blocking dynamic-i18n warning on an unchanged line.
• pnpm db:migrations:check passed and pnpm db:migrations:generate reported no schema changes. pnpm docs:check, bilingual pairing, pnpm i18n:sync and pnpm i18n:check passed; all 14 renderer locales have the revised warning.
• pnpm change:scope --base 34f0655860cbf4519a89df47a67381fc84befaa4, pnpm docs:affected --base 34f0655860cbf4519a89df47a67381fc84befaa4, and pnpm check --plan --base 34f0655860cbf4519a89df47a67381fc84befaa4 were inspected. Affected reference documents were reviewed; the fork/runtime references and owning bilingual note were updated. The planner's broad test-project selection was not run locally.

Exact scoped test commands

pnpm test:main \
  src/main/ai/agentSession/fork/__tests__/publication.test.ts \
  src/main/ai/agentSession/fork/__tests__/branchPublication.sdkContract.test.ts \
  src/main/data/services/__tests__/AgentSessionMessageService.test.ts \
  src/main/data/services/__tests__/AgentSessionService.test.ts \
  src/main/data/services/__tests__/agentSessionMessageTree.test.ts \
  src/main/data/db/__tests__/agentNativeContextMigration.test.ts \
  src/main/ai/agentSession/__tests__/AgentSessionRuntimeService.test.ts \
  src/main/ai/streamManager/context/__tests__/AgentChatContextProvider.test.ts \
  src/main/ai/runtime/pi/PiRuntimeConnection.sdkContract.test.ts \
  src/main/ai/agentSession/__tests__/AgentSessionDeliveryService.test.ts \
  src/main/ai/streamManager/api/__tests__/startAgentSessionRun.test.ts \
  src/main/services/remoteAccess/__tests__/agent.test.ts \
  src/main/ai/runtime/pi/__tests__/retiredSessionHistory.test.ts \
  src/main/data/db/seeding/__tests__/SeedRunner.test.ts \
  src/main/data/services/__tests__/AgentSessionSubmission.test.ts \
  src/main/data/db/seeding/seeders/__tests__/AgentSessionContextSeeder.test.ts \
  src/main/ai/agentSession/__tests__/nativeContext.test.ts \
  src/main/ai/agentSession/__tests__/AgentSessionArchivePersistence.integration.test.ts

pnpm test:renderer \
  src/renderer/hooks/__tests__/useAgentSessionParts.test.ts \
  src/renderer/pages/agents/__tests__/useAgentChatRuntimeState.test.tsx \
  src/renderer/pages/agents/messages/__tests__/agentMessageListAdapter.test.tsx

Breaking changes

New forward migration and Seeder for existing v2 databases. Edit/resend now retains earlier branches; it still does not undo filesystem changes. Existing IDs and physical archive tables remain. No mandatory common Runtime interface change.

Special notes for your reviewer

Eleventh stack layer, based on #22071. Most added lines are the generated Drizzle snapshot. This layer adapts the existing desktop driver path; the common Runtime root owner/projection cutover remains next. Native backup/deletion integration, Durable application scheduling, packaged builds, external-provider acceptance and forced-process recovery remain separate gates. Previously deleted message tails cannot be recovered.

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

• Branch: This PR targets main
• PR: The PR description is expressive enough and will help future contributors
• Code: Write code that humans can understand and Keep it simple
• Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
• Upgrade: Impact of this change on upgrade flows was considered and addressed if required
• Documentation: A user-guide update was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior.
• Self-review: I have reviewed my own code (e.g., via /gh-pr-review, gh pr diff, or GitHub UI) before requesting review from others

Release note

Agent edit/resend now preserves the original conversation branch and lets you switch between branches and continue either one.