feat(claude-accounts): per-project Claude account (ask on launch, remember per project)

config/tsconfig.tc.web.json

@@ -18,6 +18,7 @@
     "../src/preload/runtime-environment-subscriptions.ts",
     "../src/preload/usage-provider-api.ts",
     "../src/shared/**/*",
+    "../src/main/claude-accounts/project-claude-account-resolution.ts",
     "../src/main/gitlab/mappers.ts",
     "../src/main/ipc/deferred-emoji-shortcode-dataset.ts",
     "../src/main/ipc/worktree-branch-name.ts",

mobile/src/transport/rpc-acceptance-policies.test.ts

@@ -4,6 +4,7 @@ import {
   isMethodNotFoundRefusal,
   isStreamingOpenerReply,
   requireRpcResultOrThrowCodedError,
+  requireRpcResultOrThrowMessage,
   rpcObjectResultOrNull
 } from './rpc-acceptance-policies'
 
@@ -166,3 +167,18 @@ describe('isStreamingOpenerReply', () => {
     expect(isStreamingOpenerReply(response)).toBe(false)
   })
 })
+
+describe('requireRpcResultOrThrowMessage', () => {
+  it('shows a pinned Claude refusal without its renderer marker', () => {
+    const refusal: RpcResponse = {
+      id: 'rpc-1',
+      ok: false,
+      error: {
+        code: 'runtime_error',
+        message: 'Account a@b.c is in use. [claude_pinned:host-sessions email=a%40b.c terminals=1]'
+      },
+      _meta: meta
+    }
+    expect(() => requireRpcResultOrThrowMessage(refusal)).toThrow(/^Account a@b\.c is in use\.$/)
+  })
+})

mobile/src/transport/rpc-acceptance-policies.ts

@@ -1,4 +1,5 @@
 import type { RpcResponse, RpcSuccess } from './types'
+import { stripClaudePinnedLaunchMarker } from '../../../src/shared/claude/claude-pinned-launch-error'
 
 // Named acceptance policies for RPC replies. Call sites used to hand-roll these
 // predicates and did not agree with each other; each policy here preserves one
@@ -35,7 +36,7 @@ export function isStreamingOpenerReply(
 /** New-tab errors historically show the host message without its diagnostic code. */
 export function requireRpcResultOrThrowMessage(response: RpcResponse): unknown {
   if (!response.ok) {
-    throw new Error(response.error.message)
+    throw new Error(stripClaudePinnedLaunchMarker(response.error.message))
   }
   return response.result
 }

src/cli/cli-error-claude-pinned.test.ts

@@ -0,0 +1,18 @@
+import { expect, it } from 'vitest'
+import { formatCliError } from './cli-error'
+import { RuntimeRpcFailureError } from './runtime-client'
+
+it('prints a pinned Claude refusal without the renderer marker', () => {
+  const error = new RuntimeRpcFailureError({
+    id: 'request-1',
+    ok: false,
+    error: {
+      code: 'runtime_error',
+      message: 'That Claude account no longer exists. [claude_pinned:account-missing]'
+    },
+    _meta: { runtimeId: 'runtime-1' }
+  })
+  const output = formatCliError(error)
+  expect(output).toContain('That Claude account no longer exists.')
+  expect(output).not.toContain('claude_pinned')
+})

src/cli/cli-error.ts

@@ -4,6 +4,7 @@ import {
   stripAutomationOwnerConflictCode
 } from '../shared/automation-owner-conflict'
 import { automationOwnerConflictRecovery } from './automation-owner-conflict-recovery'
+import { stripClaudePinnedLaunchMarker } from '../shared/claude/claude-pinned-launch-error'
 import { worktreeSelectorRecovery } from './worktree-selector-recovery'
 import type { RuntimeRpcFailure } from './runtime-client'
 import { RuntimeClientError, RuntimeRpcFailureError } from './runtime/types'
@@ -35,7 +36,9 @@ function errorCode(error: unknown): string | undefined {
 }
 
 export function formatCliError(error: unknown, context: CliErrorContext = {}): string {
-  const message = error instanceof Error ? error.message : String(error)
+  const message = stripClaudePinnedLaunchMarker(
+    error instanceof Error ? error.message : String(error)
+  )
   const selector = selectorRecovery(errorCode(error), context)
   if (selector) {
     return formatMessageWithNextSteps(

src/cli/handlers/claude-launch-account-flag.ts

@@ -0,0 +1,38 @@
+import { getOptionalStringFlag } from '../flags'
+import { RuntimeClientError, type RuntimeClient } from '../runtime-client'
+import type { RuntimeStatus } from '../../shared/runtime-types'
+import { CLAUDE_LAUNCH_ACCOUNT_RUNTIME_CAPABILITY } from '../../shared/protocol-version'
+
+/**
+ * `--account <id|email>`: the managed Claude account a launch runs on, resolved by the host.
+ *
+ * Why the capability check: an older host strips the unknown field and would quietly start the
+ * agent on its active account — exactly what the caller asked not to happen.
+ */
+export async function readClaudeLaunchAccountFlag(
+  flags: Map<string, string | boolean>,
+  client: RuntimeClient,
+  agent: string | undefined
+): Promise<string | undefined> {
+  if (!flags.has('account')) {
+    return undefined
+  }
+  const account = getOptionalStringFlag(flags, 'account')?.trim()
+  if (!account) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      '--account requires a Claude account id or email.'
+    )
+  }
+  if (agent !== 'claude') {
+    throw new RuntimeClientError('invalid_argument', '--account requires --agent claude.')
+  }
+  const status = await client.call<RuntimeStatus>('status.get')
+  if (!status.result.capabilities?.includes(CLAUDE_LAUNCH_ACCOUNT_RUNTIME_CAPABILITY)) {
+    throw new RuntimeClientError(
+      'incompatible_runtime',
+      'The connected Orca runtime does not support --account for Claude launches. Update or restart Orca and try again.'
+    )
+  }
+  return account
+}

src/cli/handlers/orchestration-worker-account-cli.test.ts

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const callMock = vi.fn()
+
+vi.mock('../format', () => ({ printResult: vi.fn() }))
+vi.mock('../selectors', () => ({ getTerminalHandle: vi.fn() }))
+
+import { ORCHESTRATION_HANDLERS } from './orchestration'
+import { CLAUDE_LAUNCH_ACCOUNT_RUNTIME_CAPABILITY } from '../../shared/protocol-version'
+
+describe('orchestration worker-start --account', () => {
+  beforeEach(() => {
+    callMock.mockReset()
+    process.exitCode = undefined
+  })
+
+  const invokeWorkerStart = (flags: Map<string, string | boolean>) =>
+    ORCHESTRATION_HANDLERS['orchestration worker-start']({
+      flags,
+      client: { call: callMock },
+      cwd: '/tmp/repo',
+      json: true
+    } as never)
+
+  it('forwards --account to a host that resolves Claude launch accounts', async () => {
+    callMock
+      .mockResolvedValueOnce({
+        result: { capabilities: [CLAUDE_LAUNCH_ACCOUNT_RUNTIME_CAPABILITY] }
+      })
+      .mockResolvedValueOnce({
+        result: { runId: 'run_1', taskId: 'task_1', dispatchId: 'ctx_1', state: 'ready' }
+      })
+
+    await invokeWorkerStart(
+      new Map<string, string | boolean>([
+        ['task', 'task_1'],
+        ['agent', 'claude'],
+        ['account', 'pinned@example.com'],
+        ['from', 'term_coord']
+      ])
+    )
+
+    expect(callMock).toHaveBeenNthCalledWith(1, 'status.get')
+    expect(callMock).toHaveBeenNthCalledWith(
+      2,
+      'orchestration.workerStart',
+      expect.objectContaining({ agent: 'claude', account: 'pinned@example.com' })
+    )
+  })
+
+  it('fails before worker-start when --account would be stripped or misapplied', async () => {
+    callMock.mockResolvedValueOnce({ result: { capabilities: [] } })
+    const flags = (agent: string) =>
+      new Map<string, string | boolean>([
+        ['task', 'task_1'],
+        ['agent', agent],
+        ['account', 'acct-b'],
+        ['from', 'term_coord']
+      ])
+
+    await expect(invokeWorkerStart(flags('claude'))).rejects.toMatchObject({
+      code: 'incompatible_runtime'
+    })
+    await expect(invokeWorkerStart(flags('codex'))).rejects.toThrow(
+      '--account requires --agent claude.'
+    )
+    expect(callMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('never sends an account field when --account is absent', async () => {
+    callMock.mockResolvedValue({
+      result: { runId: 'run_1', taskId: 'task_1', dispatchId: 'ctx_1', state: 'ready' }
+    })
+    await invokeWorkerStart(
+      new Map<string, string | boolean>([
+        ['task', 'task_1'],
+        ['agent', 'claude'],
+        ['from', 'term_coord']
+      ])
+    )
+    expect(callMock).toHaveBeenCalledTimes(1)
+    expect(callMock.mock.calls[0]?.[1]).not.toHaveProperty('account')
+  })
+
+  it('refuses --account with --terminal before calling any host', async () => {
+    await expect(
+      invokeWorkerStart(
+        new Map<string, string | boolean>([
+          ['task', 'task_1'],
+          ['terminal', 'term_worker'],
+          ['account', 'acct-b'],
+          ['from', 'term_coord']
+        ])
+      )
+    ).rejects.toMatchObject({
+      code: 'invalid_argument',
+      message:
+        '--account cannot be combined with --terminal; the reused terminal keeps its own account.'
+    })
+    expect(callMock).not.toHaveBeenCalled()
+  })
+})

src/cli/handlers/orchestration/worker-launch-handler.ts

@@ -10,6 +10,7 @@ import { isDevCliInvocation } from './runtime-compatibility'
 import { resolveCoordinatorTerminalHandle } from './terminal-identity'
 import { formatWorkerStart } from './worker-output'
 import { renderResolvedOrchestrationCommand } from '../../orchestration-mutation-recovery'
+import { readClaudeLaunchAccountFlag } from '../claude-launch-account-flag'
 
 export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record<string, CommandHandler> = {
   'orchestration worker-start': async ({ flags, client, cwd, json }) => {
@@ -28,6 +29,17 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record<string, CommandHandler>
         )
       }
     }
+    if (flags.has('account') && flags.has('terminal')) {
+      throw new RuntimeClientError(
+        'invalid_argument',
+        '--account cannot be combined with --terminal; the reused terminal keeps its own account.'
+      )
+    }
+    const account = await readClaudeLaunchAccountFlag(
+      flags,
+      client,
+      getOptionalStringFlag(flags, 'agent')
+    )
     const task = getOptionalStringFlag(flags, 'task')
     const spec = getOptionalStringFlag(flags, 'spec')
     const taskTitle = getOptionalStringFlag(flags, 'task-title')
@@ -62,6 +74,7 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record<string, CommandHandler>
       agent: getOptionalStringFlag(flags, 'agent'),
       model,
       effort,
+      ...(account ? { account } : {}),
       terminal: getOptionalStringFlag(flags, 'terminal'),
       retryOf: getOptionalStringFlag(flags, 'retry-of'),
       timeoutMs: getOptionalPositiveIntegerValueFlag(flags, 'timeout-ms'),

src/cli/handlers/worktree.ts

@@ -26,6 +26,7 @@ import {
 import { isTuiAgent } from '../../shared/tui-agent-config'
 import { isWorkspaceKey, worktreeWorkspaceKey } from '../../shared/workspace-scope'
 import { printLineageSummary } from './worktree-lineage-summary'
+import { readClaudeLaunchAccountFlag } from './claude-launch-account-flag'
 import { projectWorktreePsTerminalVerdict } from '../worktree-ps-terminal-verdict'
 import {
   assertWorkspaceTargetFlagsCompatible,
@@ -185,6 +186,7 @@ export const WORKTREE_HANDLERS: Record<string, CommandHandler> = {
     const explicitParentWorktree = explicitParent.parentWorktree
     const explicitParentWorkspace = explicitParent.parentWorkspace
     const startupAgent = getOptionalStartupAgent(flags)
+    const claudeAccount = await readClaudeLaunchAccountFlag(flags, client, startupAgent)
     const setupDecision = getOptionalSetupDecision(flags)
     const noParent = flags.get('no-parent') === true
     const envParentWorkspace =
@@ -239,7 +241,8 @@ export const WORKTREE_HANDLERS: Record<string, CommandHandler> = {
           ? {
               startupAgent,
               startupPrompt: getPresentStringFlag(flags, 'prompt', { allowEmpty: true }) ?? '',
-              launchSource: 'cli'
+              launchSource: 'cli',
+              ...(claudeAccount ? { startupClaudeAccount: claudeAccount } : {})
             }
           : {})
       })

src/cli/index-worktree-create-claude-account.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest'
+import { CLAUDE_LAUNCH_ACCOUNT_RUNTIME_CAPABILITY } from '../shared/protocol-version'
+
+const {
+  callMock,
+  runtimeClientConstructorMock,
+  serveOrcaAppMock,
+  getDefaultUserDataPathMock,
+  addEnvironmentFromPairingCodeMock,
+  listEnvironmentsMock,
+  spawnMock
+} = vi.hoisted(() => ({
+  callMock: vi.fn(),
+  runtimeClientConstructorMock: vi.fn(),
+  serveOrcaAppMock: vi.fn(),
+  getDefaultUserDataPathMock: vi.fn(() => '/tmp/orca-user-data'),
+  addEnvironmentFromPairingCodeMock: vi.fn(),
+  listEnvironmentsMock: vi.fn(),
+  spawnMock: vi.fn()
+}))
+
+vi.mock('./runtime-client', async () => {
+  const { createRuntimeClientModuleMock } = await import('./index-test-harness.js')
+  return createRuntimeClientModuleMock({
+    callMock,
+    runtimeClientConstructorMock,
+    serveOrcaAppMock,
+    getDefaultUserDataPathMock
+  })
+})
+
+vi.mock('./runtime/environments', () => ({
+  addEnvironmentFromPairingCode: addEnvironmentFromPairingCodeMock,
+  listEnvironments: listEnvironmentsMock,
+  removeEnvironment: vi.fn(),
+  resolveEnvironment: vi.fn()
+}))
+
+vi.mock('child_process', async () => {
+  const { createChildProcessModuleMock } = await import('./index-test-harness.js')
+  return createChildProcessModuleMock(spawnMock)
+})
+
+import { main } from './index'
+import { buildWorktree, okFixture, queueFixtures, worktreeListFixture } from './test-fixtures'
+import { useWorktreeAwarenessEnvironment } from './index-test-harness'
+
+describe('orca worktree create --account', () => {
+  useWorktreeAwarenessEnvironment({
+    callMock,
+    serveOrcaAppMock,
+    getDefaultUserDataPathMock,
+    addEnvironmentFromPairingCodeMock,
+    listEnvironmentsMock,
+    spawnMock
+  })
+
+  const createArgs = ['worktree', 'create', '--repo', 'id:repo-1', '--name', 'pinned', '--json']
+
+  it('sends the account selector to a host that advertises support', async () => {
+    queueFixtures(
+      callMock,
+      okFixture('req_status', { capabilities: [CLAUDE_LAUNCH_ACCOUNT_RUNTIME_CAPABILITY] }),
+      worktreeListFixture([buildWorktree('/tmp/repo', 'main', 'abc', 'repo-1')]),
+      okFixture('req_create', {
+        worktree: buildWorktree('/tmp/repo/pinned', 'pinned', 'abc', 'repo-1')
+      })
+    )
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await main([...createArgs, '--agent', 'claude', '--account', 'pinned@example.com'], '/tmp/repo')
+
+    expect(callMock).toHaveBeenNthCalledWith(1, 'status.get')
+    expect(callMock).toHaveBeenNthCalledWith(
+      3,
+      'worktree.create',
+      expect.objectContaining({
+        startupAgent: 'claude',
+        startupPrompt: '',
+        startupClaudeAccount: 'pinned@example.com'
+      })
+    )
+  })
+
+  it('refuses an older host instead of launching on its active account', async () => {
+    queueFixtures(callMock, okFixture('req_status', { capabilities: [] }))
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    await main([...createArgs, '--agent', 'claude', '--account', 'acct-b'], '/tmp/repo')
+
+    expect(process.exitCode).toBe(1)
+    expect(callMock).not.toHaveBeenCalledWith('worktree.create', expect.anything())
+  })
+
+  it('requires --agent claude', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    await main([...createArgs, '--agent', 'codex', '--account', 'acct-b'], '/tmp/repo')
+
+    expect(process.exitCode).toBe(1)
+    expect(callMock).not.toHaveBeenCalled()
+  })
+})