feat(codex): pin accounts for native worker and worktree launches by treze13013-pixel · Pull Request #25762 · stablyai/orca

treze13013-pixel · 2026-10-06T02:26:10Z

ELI5

A coordinator can start one Codex worker on account A and another on account B while keeping the global account selection and existing sessions unchanged. Today these launches follow the selected account.

What Changed

Both entry points accept an explicit account for a fresh native Codex launch:

orca orchestration worker-start --task <task> --agent codex --account <id|email|system> --worktree current
orca worktree create --repo <repo> --name <name> --agent codex --account <id|email|system>

The shared launch path resolves an exact managed account ID, a unique case-insensitive native-host email, or system / "System default". Unknown, ambiguous, untrusted and unsupported accounts are rejected before worktree or Dispatch creation.

Existing managed-home preparation supplies CODEX_HOME only to the new process. It does not call account-switch setters or change activeCodexManagedAccountId. Pane attribution records the effective account and skips explicitly pinned panes when checking global-selection staleness. Launch receipts expose sanitized provider, requested and effective values without credentials or home paths.

If pinned terminal startup fails after worktree creation, the failure receipt retains the created worktree for explicit recovery; the launch stays pinned and the worktree is not deleted automatically.

CLI callers require the execution runtime's codex.launch-account.v1 capability before sending a mutation. Optional RPC fields preserve the omitted-account path. Authoritative agent-launch replay preserves the original account receipt and conflicts on changed intent; legacy create-cache requests with a pin are rejected.

Why

Per-launch selection addresses concurrent Codex account isolation using Orca's existing account, home and launch infrastructure. Switching global selection would affect unrelated launches. Automatic account or quota failover is explicitly outside this change.

Linked Issue

Addresses the explicit Codex launch portion of #9496. This does not close its broader per-worktree/provider requirements.

#20512 is a separate follow-up: no automatic quota failover. Claude account support in #22691 is unmerged and is not stacked into this PR.

Visual Proof

N/A — this adds a CLI/RPC launch contract and receipts; no renderer UI is changed.

Testing

Windows; Node 24.19.0, Bun 1.4.2, pnpm 12.8.1, ORCA_BACKGROUND_LAUNCH=1. Fake account fixtures and mocked providers; no real-account launches.

Account tests cover simultaneous A/B environments, unchanged global selection and existing sessions, system/ID/unique-email selectors, invalid/ambiguous selectors, omitted flags, sanitized receipts/replay, capability refusal and unsupported placements.
Pinned startup failure retains the created worktree in failure/residual-resource receipts, without fallback or deletion.
Positive installed-runtime multi-account proof: not performed.

Current reconciliation: exact head e2df927124305692434dea39a77d75973c5a1d13 incorporates upstream b75213100b5358bedb7e16b48afd30645e54de14 by an ordinary merge on the same branch, preserving all previous commits. The 48 incoming commits intersect 14 delivery files. The sole textual conflict joined the folder startup failure tests and the upstream headless-provisioning test; both remain. A duplicate execution-host type import produced by the automatic merge was removed.

CLI activation adopts upstream host-only navigation. Unpinned native chat now ignores custom terminal commands, as upstream requires; explicit pins still use a fresh native terminal and reject custom Codex commands before effects. Background worktree provisioning and recovery changes retain the pinned startup throw and the created worktree's identity. The extracted orchestration capability registry coexists with the additive codex.launch-account.v1 advertisement.

New/strengthened regressions cover managed A/B and system pins with a structured-chat default, rejection of custom commands for a pinned launch, and pinned startup failure under background provisioning without an unpinned fallback. The account receipt replay test uses upstream's declared Node-runtime pool because it exercises the host's durable Node SQLite ledger. No test assertion, timeout or native gate was relaxed. The managed-create account preparation was expressed without reassigning the request argument to keep the existing 300-line lint limit.

Current source results:

Node source runner: 156/156 focal tests passed (12 files).
Upstream's Bun runner with its Node-runtime pool: the 35-file focal/regression selection has 478 passed / 20 failed / 498 total. Every failed name reproduces on an exact upstream-only b752131... archive with the same frozen dependencies: two Windows recovery-command quoting assertions, nine prestart SQLite teardown failures, one durable worker-replay SQLite teardown failure, and eight authoritative metadata-pruning failures. The baseline has 57 passed / 20 failed / 77 total. These limitations remain visible.
Relevant mode/executor, shared launch intent, worker release/recovery, residual error mapping, folder/local creation, background provisioning, Codex config spelling and Node-pool boundary cases were included.
Earlier broader structured Windows failures remain in the previous reconciliation evidence; the full structured suite was not rerun.

Passed on the reconciled source:

pnpm tc:node
pnpm tc:cli
pnpm tc:web
pnpm run build:cli
pnpm exec oxlint <81 changed TypeScript files>
pnpm exec oxfmt --check <83 changed files>
ORCA_CODE_QUALITY_BASE=b75213100b5358bedb7e16b48afd30645e54de14 pnpm run check:code-quality:changed
git diff --check b75213100b5358bedb7e16b48afd30645e54de14 HEAD

Source tests use the current Vitest config, Bun/Node pools and real-home write guard. The normal test wrapper's native preflight remains blocked; the direct source runner results do not claim a packaged runtime proof. Native check-only rejects missing patched node-pty job exports, the windows-registry addon and synchronous process-tree CreationTime support.

Local commissioning is waiting for operator provisioning of the Windows toolchain. The earlier official native rebuild failed to find Visual Studio. During this reconciliation, vswhere detected a new Build Tools 2022 instance still marked incomplete/non-launchable; the operator confirmed installation is in progress. MSVC/MSBuild began appearing, while the Windows SDK was still absent at the last inventory. No rebuild, official Orca update, installed app replacement, credential change or positive installed acceptance was performed in this reconciliation. Recheck the completed toolchain before rebuilding the preserved exact source head.

AI Disclosure

Implemented and reviewed with Codex GPT-6.1-Sol, including coordinator review and independent source validation.

Review

The account primitive is shared by worker-start and worktree creation. Explicit pins use a fresh native terminal; a structured-chat preference receives the existing downgrade receipt with reason pinned_codex_account. SSH, WSL, forwarded workspaces, --on, resume, terminal reuse and custom Codex commands fail closed. Omitted --account retains the previous routing, mode and RPC behavior.

Agent skill upstream boundary

Not applicable; no upstream skill-installer source, fixtures or registry content is copied.

Notes

The capability is additive; it introduces no stream opcode or feature-specific protocol-version bump. Upstream daemon protocol 40 remains independently negotiated. No installed app, credentials or account selection was changed, and no positive installed-runtime proof is claimed.

Checklist

Focused outcome: explicit deterministic Codex launch-account pinning.
User behavior, mechanism, linked issue and scope explained.
Visual proof marked N/A with reason.
Self-reviewed for correctness, secrets, replay and existing-session isolation.
Cross-platform, SSH/remote and unsupported launch modes considered.
Full pnpm lint, pnpm test and packaged pnpm build all green: focused lint/quality, all three typechecks and CLI build passed; upstream CI and the Windows/native limitations above remain visible.

…eview

coderabbitai · 2026-10-06T02:41:28Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: 0f81f957-c192-44f9-bbf9-eba0634329f6

📥 Commits

Reviewing files that changed from the base of the PR and between c82fa48 and e2df927.

📒 Files selected for processing (13)

config/scripts/vitest-node-runtime-files.mjs
src/cli/handlers/worktree.ts
src/main/agent-launch/agent-launch-mode.ts
src/main/runtime/orca-runtime-create-managed-worktree.ts
src/main/runtime/runtime-codex-account-placement.test.ts
src/main/runtime/runtime-folder-worktree-create.test.ts
src/main/runtime/runtime-folder-worktree-create.ts
src/main/runtime/runtime-legacy-worker-terminal-recovery-types.ts
src/main/runtime/runtime-local-worktree-terminal-startup.test.ts
src/main/runtime/runtime-local-worktree-terminal-startup.ts
src/main/runtime/runtime-pty-controller-contract.ts
src/shared/agent-launch-intent.ts
src/shared/protocol-version.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 change adds explicit Codex account selection to worker-start and worktree creation. Requests validate the selector and runtime capability, then resolve an account and prepare its native Codex home for a fresh terminal launch. Account pins flow into terminal and worktree startup, pane records, and launch receipts. The change also adds placement restrictions, account-aware replay validation, CLI documentation, and tests for selection, launch, and replay behavior.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to e2df9

No actionable account-pinning issue remains in the reviewed evidence. Merge after the normal checks; installed-runtime launch validation remains unperformed.

Security Architecture Review

Security architecture risk: 🔵 Low · up to c82fa

The change includes controls that confine account selection to fresh local launches and prevent replay from changing account intent. No introduced security defect was established. Interrupted-launch recovery and deployed compatibility behavior remain partially verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

inferred — The new selection surface reaches native accounts already managed by the execution runtime and the credentials used by newly launched processes. Its scope includes concurrent workers and startup terminals on that host. The inspected placement controls do not authorize remote account use or expand execution to another host.

Trust Boundaries and Controls

observed — The caller-controlled selector is resolved to an exact managed ID, a unique case-insensitive native-host email, or the system selector. Unknown, ambiguous, and unsupported accounts are rejected. The process sink receives a canonical ID rather than a caller-supplied home path and validates home ownership independently.
observed — Pinned terminal validation rejects resume, session adoption, agent-session claims, and renderer-backed launch. Worktree preparation also rejects explicit startup commands, drafts, and unavailable native spawning. These checks constrain the new parameter to a fresh supported launch.

Resilience and Maintainability Implications

observed — In-flight authoritative launches share the same promise only when their fingerprints agree; changed account intent conflicts. Settled replay returns the original result before live account resolution. Focused tests assert that replay does not resolve accounts or spawn again after account removal.

Hardening Proposals

proposed — Consider durably linking the creating operation or dispatch to worktree metadata before terminal startup, allowing interrupted launches to recover resource ownership without automatic re-execution. This addresses the existing interruption window; it is not a demonstrated PR-introduced vulnerability.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 40 functions across 63 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the primary change: pinning accounts for native Codex worker and worktree launches.
Description check	✅ Passed	The description covers the required sections and explains the user-facing change, rationale, linked issues, testing, limitations, and scope. It also marks visual proof as not applicable with a reason.

Fix all pre-merge checks with AI

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

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: 94d26307-b868-4a2d-9abe-3d7216a5b647

📥 Commits

Reviewing files that changed from the base of the PR and between 08a970a and 7df09be.

📒 Files selected for processing (78)

docs/reference/codex-launch-account-pinning.md
src/cli/handlers/codex-launch-account-cli.test.ts
src/cli/handlers/codex-launch-account-flag.ts
src/cli/handlers/orchestration/worker-launch-handler.ts
src/cli/handlers/worktree.ts
src/cli/specs/core.ts
src/cli/specs/orchestration-worker-specs.ts
src/main/agent-launch/agent-launch-executor.ts
src/main/agent-launch/agent-launch-mode.ts
src/main/agent-launch/agent-launch-surface-factories.ts
src/main/codex-accounts/codex-launch-account.test.ts
src/main/codex-accounts/codex-launch-account.ts
src/main/codex-accounts/runtime-home-pinned-launch.test.ts
src/main/codex-accounts/runtime-home-service-launch.ts
src/main/codex-accounts/runtime-home-service-managed-home.ts
src/main/codex/codex-pane-account-registry-mutations.ts
src/main/codex/codex-pane-account-registry-types.ts
src/main/codex/codex-pane-account-registry.ts
src/main/codex/codex-pane-launch-account.ts
src/main/codex/codex-stale-pane-accounts.test.ts
src/main/codex/codex-stale-pane-accounts.ts
src/main/ipc/pty-runtime-codex-account-pin.test.ts
src/main/ipc/pty/host-env/codex-home.ts
src/main/ipc/pty/host-env/types.ts
src/main/ipc/pty/ipc/spawn-preflight.ts
src/main/ipc/pty/ipc/spawn-types.ts
src/main/ipc/pty/runtime/spawn-codex-home-selection.ts
src/main/ipc/pty/runtime/spawn-commit.ts
src/main/ipc/pty/runtime/spawn-options.ts
src/main/ipc/pty/runtime/spawn-preflight.ts
src/main/ipc/pty/runtime/spawn-state.ts
src/main/ipc/pty/runtime/spawn.ts
src/main/runtime/orca-runtime-create-managed-worktree.ts
src/main/runtime/orca-runtime-create-terminal-dependencies.ts
src/main/runtime/orca-runtime-create-terminal-desktop.ts
src/main/runtime/orca-runtime-create-terminal.ts
src/main/runtime/orca-runtime-resolve-browser-network-execution-host-for-worktree.ts
src/main/runtime/orca-runtime-resolve-worktree-removal-target.ts
src/main/runtime/rpc/methods/agent-launch-account-replay.test.ts
src/main/runtime/rpc/methods/agent-launch-surfaces.ts
src/main/runtime/rpc/methods/agent-launch-worktree-creation.ts
src/main/runtime/rpc/methods/agent-launch.test-fixture.ts
src/main/runtime/rpc/methods/agent-launch.ts
src/main/runtime/rpc/methods/orchestration-worker-start-mode.ts
src/main/runtime/rpc/methods/orchestration/worker/local-worker-start.ts
src/main/runtime/rpc/methods/orchestration/worker/worker-launch-preferences.ts
src/main/runtime/rpc/methods/orchestration/worker/worker-start-agent-placement.ts
src/main/runtime/rpc/methods/orchestration/worker/worker-topology.ts
src/main/runtime/rpc/methods/orchestration/worker/worker-worktree-creation.ts
src/main/runtime/rpc/methods/orchestration/worker/workers-codex-account.test.ts
src/main/runtime/rpc/methods/orchestration/worker/workers-new-worktree.test.ts
src/main/runtime/rpc/methods/orchestration/worker/workers.ts
src/main/runtime/rpc/methods/worktree-create-args.ts
src/main/runtime/runtime-account-controller.ts
src/main/runtime/runtime-agent-launch-account.ts
src/main/runtime/runtime-codex-account-placement.test.ts
src/main/runtime/runtime-codex-account-placement.ts
src/main/runtime/runtime-codex-account-pre-create.test.ts
src/main/runtime/runtime-folder-worktree-create.ts
src/main/runtime/runtime-legacy-worker-terminal-recovery-types.ts
src/main/runtime/runtime-local-worktree-terminal-startup.test.ts
src/main/runtime/runtime-local-worktree-terminal-startup.ts
src/main/runtime/runtime-managed-worktree-create-types.ts
src/main/runtime/runtime-pty-controller-contract.ts
src/main/runtime/runtime-service-command-surface.ts
src/main/runtime/runtime-terminal-contracts.ts
src/main/runtime/runtime-terminal-create-routing.ts
src/main/startup/codex-launch-preparation.ts
src/shared/agent-launch-account.ts
src/shared/agent-launch-intent.ts
src/shared/agent-launch-operation.ts
src/shared/protocol-version.ts
src/shared/rpc-contract/agent-launch-params.ts
src/shared/rpc-contract/launch-account-param.ts
src/shared/rpc-contract/orchestration-worker-start-params.ts
src/shared/rpc-contract/worktree-create-params.ts
src/shared/runtime-worktree-contracts.ts
src/shared/worktree/create-types.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.

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

🟡 Minor · Preserve the known worktree details in replay failure data. · agent-launch.ts:324-371

src/main/runtime/rpc/methods/agent-launch.ts:324-371
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Preserve the known worktree details in replay failure data.

When pinned worktree startup fails after registration, this handler leaves the operation outcome unknown but replaces WorktreeStartupError with a plain agent_session_operation_unknown error. The RPC mapper can no longer attach the known worktree ID, effects, or residual resources. A caller can find worktree IDs through worktree.list, but the failure and operation record do not identify which worktree this launch created. Preserve the known worktree details in the failure while keeping the operation outcome unknown.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: ea8338a3-8991-48ba-aca0-0dde2d4d2ded

📥 Commits

Reviewing files that changed from the base of the PR and between 7df09be and 3ea2a54.

📒 Files selected for processing (9)

src/main/runtime/rpc/errors.test.ts
src/main/runtime/rpc/errors.ts
src/main/runtime/rpc/methods/orchestration/worker/worker-worktree-creation.ts
src/main/runtime/rpc/methods/orchestration/worker/workers-codex-account.test.ts
src/main/runtime/runtime-folder-worktree-create.test.ts
src/main/runtime/runtime-folder-worktree-create.ts
src/main/runtime/runtime-local-worktree-terminal-startup.test.ts
src/main/runtime/runtime-local-worktree-terminal-startup.ts
src/shared/worktree/worktree-startup-error.ts

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

treze13013-pixel added 3 commits October 5, 2026 22:38

feat(codex): pin managed accounts for new native agent launches

a2691dc

Merge current upstream main into Codex account pinning

a2003cd

Merge latest upstream message rail fix before Codex account pinning r…

7df09be

…eview

coderabbitai Bot reviewed Oct 6, 2026

View reviewed changes

Comment thread src/main/runtime/runtime-local-worktree-terminal-startup.ts

treze13013-pixel added 4 commits October 5, 2026 23:54

Merge current upstream main before pinned worktree failure receipt fix

d492bca

fix(codex): retain created worktrees in pinned startup failure receipts

011e45f

Merge current upstream main after pinned startup failure receipt fix

3ea2a54

Merge current upstream main and preserve Codex account pinning contracts

c82fa48

coderabbitai Bot reviewed Oct 6, 2026

View reviewed changes

Merge upstream main and preserve Codex launch account contracts

e2df927

Navigation Menu

Repository navigation

feat(codex): pin accounts for native worker and worktree launches - #25762

feat(codex): pin accounts for native worker and worktree launches#25762
treze13013-pixel wants to merge 8 commits into
stablyai:mainfrom
treze13013-pixel:treze13013-pixel/upstream-codex-account-pinning

treze13013-pixel commented Oct 6, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 6, 2026 •

edited

Loading

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

treze13013-pixel commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ELI5

What Changed

Why

Linked Issue

Visual Proof

Testing

AI Disclosure

Review

Agent skill upstream boundary

Notes

Checklist

Uh oh!

coderabbitai Bot commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Security Architecture Review

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

treze13013-pixel commented Oct 6, 2026 •

edited

Loading

coderabbitai Bot commented Oct 6, 2026 •

edited

Loading