[totigm]

ELI5

You are chatting with Claude or Codex in a workspace and want to try something else without losing that line of work. Right-click the workspace, pick Fork Agent Session..., give the new branch a name, and Orca makes a new workspace nested under the current one. It starts from the exact same code, optionally including your uncommitted changes, and the same agent continues the same conversation there. The original workspace and its conversation are left untouched.

What Changed

Before: branching agent work took three manual steps:

1. Create a workspace. It started from the project's default branch, not from the work you were on.
2. Re-parent it with Set Parent Worktree....
3. Start a new agent with no memory of the conversation.

The existing terminal Fork Agent Session... only pasted a capped copy of the terminal scrollback into a fresh agent. It created a top-level workspace from the branch tip and left uncommitted changes behind.

After:

• Where it lives:
  • The workspace context menu has Fork Agent Session....
  • The terminal and native-chat menu item opens the same dialog, with that pane's session preselected.
  • The item is hidden for folder workspaces. It is disabled, with the reason shown inline, for detached, archived or bare worktrees.
• The dialog: a session picker (only sessions that can be forked natively), the name, a Create as a child of … switch (on by default), a Bring uncommitted changes switch (shown only when there are changes, with counts), and Advanced → Start from to pick another base.
  • With no agent session, it creates a branch-only child workspace. That covers [Feature]: Create a child workspace from the worktree context menu, based on the parent's branch #10849.
  • Progress shows in stages (Preparing → Creating workspace → Copying changes → Starting agent).
• The fork:
  • Native conversation fork. Claude runs claude --resume <id> --fork-session. Codex runs codex fork -c tui.resume_cwd=current <id>. Both get a brand-new session id, so the parent's session keeps its own writer.
    • Verified with Claude Code 2.1.282: SessionStart (source fork), UserPromptSubmit and Stop all report the new id.
    • Other agents opened from a terminal still get the transcript as a draft, as before.
  • Exact base. The child starts at the parent's HEAD commit, re-read at submit time, rather than at a remote-tracking ref. Source Control in the child compares against the parent's branch.
  • Uncommitted changes, all or nothing, on the execution host (local, SSH relay, or remote orca serve behind a capability):
    • Tracked edits move with git stash create / git stash apply (binary-safe, Git ≥ 2.25). Untracked files are copied with the filesystem.
    • The parent is never modified.
    • Any collision, symlinked parent folder, or concurrent commit in the parent is refused before anything is written. A failure after the first write is rolled back.
    • A lost connection or a timeout is reported as "may be partially applied", never as "nothing happened" (per ssh-execution-boundary.md).
  • Setup and trust. The repo's setup script and default tabs run in the child. Before that, the user goes through the same orca.yaml trust confirmation as every other create path. Folder trust for the agent comes from the existing launch-time trust (feat(agents): pre-trust the folder wherever Orca starts an agent #23744).
  • Remote workspaces. On a remote Orca runtime, the agent tab is created on the host, as other launches already do.
• Removed: the old terminal-only fork dialog and its dead code. The native session ownership guard now lets claude --resume X --fork-session through, but only as a single command it can fully parse. Chained, substituted or otherwise unparseable commands keep the guard.

Why

This is the stacked-work flow #10849 asks for, plus the part the terminal fork never had: the agent actually remembers the conversation.

Alternatives considered:

• feat(worktrees): create a child workspace from the worktree context menu #9859 (child workspace from the menu). It solves the lineage and base, but the agent starts from zero. This PR covers the same entry point and adds native conversation forking and uncommitted changes.
• Add first-class agent session forking #5609 (first-class fork system, CLI/RPC). It is much larger (about 11k lines) and adds a new runtime surface. This PR keeps every change in the renderer, except the carry operation, which runs on the host because it has to.
• Patch-based carry (git diff + git apply). Rejected: stdin is text-only in both the local runner and the relay, and GIT_INDEX_FILE doesn't cross into WSL. stash create/apply moves the changes as git objects and is binary-safe.

How to review

98 files, but about 58% of the lines are tests and many production files are 1–10 line registrations. Suggested order, smallest to largest:

1. Native fork (about 100 lines):
   • src/shared/agent-session-fork-argv.ts: the fork command per agent.
   • The mode: 'fork' option in src/shared/tui-agent-resume-startup.ts.
   • The --fork-session exemption in src/main/ai-vault/structured-session-ownership.ts.
2. Fork flow (renderer):
   • src/renderer/src/lib/agent-session-fork-flow.ts runs the steps: trust/setup decision → create the child at the parent commit → carry → launch → activate. It's the best single file to read first.
   • Its helpers, each small: agent-session-fork-launch.ts (+ -launch-target, agent-fork-launch-platform), worktree-agent-fork-sessions.ts (which sessions can be forked), agent-session-fork-setup-decision.ts and agent-session-fork-source-repo.ts.
3. UI and entry points:
   • src/renderer/src/components/agent-session-fork/ holds the dialog, its state hook, and the status probe.
   • sidebar/WorktreeForkAgentSessionMenuItem.tsx is the sidebar item (one line in the menu view).
   • terminal-pane/* now opens the shared dialog; the old dialog is deleted.
   • The modal is mounted in AppRootSurfaces.tsx.
   • CreateFromPicker.tsx and SettingsFormControls.tsx only gain optional a11y props, so existing callers are unchanged.
4. Carry uncommitted changes (host-side, read top-down):
   • src/shared/working-tree-change-carry.ts is the whole algorithm; it is pure, with injected I/O and tested against real repos.
   • working-tree-change-carry-node-fs.ts holds the filesystem side.
   • Then one thin adapter per execution path:
     • local: main/git/source-control/carry-working-tree-changes.ts and the IPC handler in filesystem-git-index-handlers.ts
     • SSH: ssh-git-working-tree-provider.ts, plus relay/git-handler-working-tree-carry.ts
     • remote runtime: runtime-git-working-tree-carry-commands.ts and the git.carryWorkingTreeChanges RPC, behind a capability in protocol-version.ts
     • renderer client and web client: runtime-git-working-tree-carry-client.ts and web-git-carry-api.ts
   • The rest (preload, RPC params and catalog, method registration) is wiring.

The commits are split by topic in the same order, so the PR can also be reviewed commit by commit.

Linked Issue

Fixes #10849

Related:

• Feature: Fork existing agent sessions (context branching) #2026: native conversation fork, which the transcript fork in Fork agent sessions from terminal context menu #3976 only approximated.
• [Bug]: Codex app-server daemon keeps the pane key of the first session, so every later session's status lands on that one pane #23643 / fix(codex): attribute shared-daemon Codex hooks to the session's own worktree #23411: Codex shared app-server daemon. See Notes.

Visual Proof

Screenshots use the Spanish locale; a video of the full flow follows.

Before	After
Terminal-only fork dialog: top-level workspace, transcript as a draft	Workspace context menu: Fork Agent Session...
(screenshot)	(screenshot)
	Dialog: name, child switch, uncommitted changes with counts, Advanced base
	(screenshot)

Testing

• I manually tested these changes locally. On macOS, pnpm dev, real Claude Code 2.1.282 and Codex 0.159.3:
  • Forked with and without uncommitted changes.
  • The child agent recalled the parent conversation.
  • The parent stayed intact.
  • Opened the dialog from the sidebar and from the terminal.
  • Opened it on a workspace with no session (branch-only).
  • Picked another base in Advanced (carry disabled with the reason).
• Automated tests added/updated: 32 test files.
  • Carry core against real git repos: binary files, symlinks, nested repos, rename rollback, collisions, a concurrent commit in the parent, git add -N, size caps, and the source left untouched.
  • The relay handler and the IPC path checks.
  • The runtime RPC, the capability, and the web shim.
  • The native fork argv and quoting for POSIX, PowerShell and cmd.
  • The ownership guard against bypass shapes.
  • Session selection and identity checks.
  • The flow at every failure stage.
  • The dialog (happy-dom).
  • The context menu and the terminal entry points.
• Gates on this branch:
  • pnpm typecheck, pnpm lint and check:code-quality:changed pass.
  • pnpm build:desktop builds the relay, the CLI, electron-vite and the web client. The mobile web bundle step was skipped locally because the mobile/ workspace dependencies aren't installed in my checkout; this PR doesn't touch mobile/, and CI covers it.
  • The full pnpm test passes for everything this PR touches. The only failures are in files it doesn't touch and fail the same on main in my environment: SQLite FTS5 under Node 22, real-binary integration tests, and cross-version tags missing in a fork.
• Linux, Windows and SSH were not tested on real machines. They are covered by unit tests, all git commands are Git 2.25-safe, and all host work goes through the existing local, relay and runtime providers.

AI Disclosure

Built with Claude Code (Claude Opus 5.5, plus Claude Sonnet 5 for some implementation steps).

• Process: a written design and plan, then per-task implementation with an independent AI review of each task. That was followed by a whole-branch review and a second three-area branch review; every finding was fixed and re-reviewed.
• Accountability: I directed the design decisions, tested the feature by hand, and I am responsible for the change.

Review

The AI code review explicitly covered:

• Cross-platform: paths via path.join, and quoting per shell (POSIX, PowerShell, cmd). The symlink copy is guarded and fails honestly on Windows without symlink privilege.
• SSH/remote: the carry runs on the execution host via the relay and runtime RPC. The SSH timeout or lost contact maps to "uncertain". The runtime method is capability-gated, and the web client checks the capability first.
• Agents: only Claude and Codex fork natively. Other agents keep the transcript fallback. Launch config reuse is identity-checked, and no resume claim is made on the source session.
• Performance: selectors are scoped to the open dialog, and nothing runs on hot paths.
• UI: it follows STYLEGUIDE.md and existing primitives (Dialog, Switch, Collapsible, CreateFromPicker). Strings are in all six locales.
• Security: both carry roots are resolved as registered worktrees. No writes go through symlinked folders. The orca.yaml trust gate is kept, and the session ownership guard was not weakened.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Codex shared daemon ([Bug]: Codex app-server daemon keeps the pane key of the first session, so every later session's status lands on that one pane #23643, fix in fix(codex): attribute shared-daemon Codex hooks to the session's own worktree #23411). Codex ≥ 0.157 runs hooks in a shared app-server daemon with the first pane's environment, so Orca never learns other panes' Codex session ids. The Codex fork therefore needs fix(codex): attribute shared-daemon Codex hooks to the session's own worktree #23411, or --no-daemon in Codex's launch args as a workaround. Claude is not affected.
• Known limitations:
  • Codex account switch: after switching Codex accounts, codex fork doesn't pin the source session's account home.
  • Setup timing: in wait-for-setup repos the agent starts alongside setup, and with the ask setup policy the fork is created without setup.
  • Native chat: native-chat forks open as a terminal agent.
  • Submodules: submodule pointer changes are not carried.
  • Staging: the staging state is not preserved; carried changes land unstaged.
• Backwards compatibility: new optional fields only. The new runtime method is capability-gated, and old hosts get the switch disabled. The relay method ships with the client build.
• Mobile: no change. The new method is not on the mobile allowlist.

Author

X: @totigm8

Checklist

• This PR is small and focused. It is one feature end to end; commits are topic-separated for review.
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred). Local exceptions are listed under Testing; CI covers them.

🤖 Generated with Claude Code