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

config/tsconfig.tc.web.json

@@ -24,6 +24,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/packages/process-host/src/__fixtures__/**/*",
     "../src/main/gitlab/mappers.ts",
     "../src/main/runtime/sidebar-inputs/sidebar-clock.ts",

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

@@ -4,6 +4,7 @@ import {
   isMethodNotFoundRefusal,
   isStreamingOpenerReply,
   requireRpcResultOrThrowCodedError,
+  requireRpcResultOrThrowMessage,
   rpcObjectResultOrNull
 } from './rpc-acceptance-policies'
 
@@ -162,3 +163,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'
 
 // Keep acceptance policies distinct until every caller is proven compatible with any widened/narrowed reply set.
 
@@ -32,7 +33,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 { selectorAmbiguityRecovery } from './selector-ambiguity-recovery'
 import type { RuntimeRpcFailure } from './runtime-client'
@@ -64,7 +65,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 = contextRecovery(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/account-runtime-capabilities'
+
+/**
+ * `--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,103 @@
+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/account-runtime-capabilities'
+
+describe('orchestration worker-start --account', () => {
+  beforeEach(() => {
+    callMock.mockReset()
+    process.exitCode = undefined
+  })
+
+  const invokeWorkerStart = (flags: Map<string, string | boolean>) =>
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: worker-start reads only flags, client.call, cwd and json.
+    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,10 +10,17 @@ 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 }) => {
     const terminal = getPresentStringFlag(flags, 'terminal')
+    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 model = getOptionalStringFlag(flags, 'model')
     const effort = getOptionalStringFlag(flags, 'effort')
     if (model || effort) {
@@ -29,6 +36,11 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record<string, CommandHandler>
         )
       }
     }
+    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')
@@ -63,6 +75,7 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record<string, CommandHandler>
       agent: getOptionalStringFlag(flags, 'agent'),
       model,
       effort,
+      ...(account ? { account } : {}),
       terminal,
       retryOf: getOptionalStringFlag(flags, 'retry-of'),
       timeoutMs: getOptionalPositiveIntegerValueFlag(flags, 'timeout-ms'),

src/cli/handlers/worktree-create-agent-launch.ts

@@ -20,6 +20,7 @@ import { printLineageSummary } from './worktree-lineage-summary'
 import { printHookWarning } from './worktree-removal-warnings'
 import { withSetupDecisionRecovery } from './worktree-setup-decision-recovery'
 import { withCliAgentLaunchRecovery } from '../agent-launch-recovery'
+import { readClaudeLaunchAccountFlag } from './claude-launch-account-flag'
 
 type WorktreeAgentLaunchResult = Pick<
   RuntimeWorktreeCreateResult,
@@ -39,8 +40,17 @@ export async function createWorktreeWithAgent(args: {
   rawArgs?: readonly string[]
 }): Promise<void> {
   const { client, flags, create, launch, json, rawArgs } = args
-  const capabilities = await getAgentLaunchCapabilities(client)
+  // Why: only the create's startup terminal can run Claude on a non-active account.
+  const claudeAccount = await readClaudeLaunchAccountFlag(flags, client, launch.agent)
+  if (claudeAccount && (launch.operationId || launch.surface || hasLaunchModelFlags(flags))) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      '--account cannot be combined with --model, --effort, --surface or --retry-launch.'
+    )
+  }
+  const capabilities = claudeAccount ? undefined : await getAgentLaunchCapabilities(client)
   if (
+    claudeAccount ||
     !capabilities?.includes(AGENT_LAUNCH_LOCAL_PRESENTATION_RUNTIME_CAPABILITY) ||
     (launch.prompt && !capabilities.includes(AGENT_LAUNCH_PROMPT_CARRY_RUNTIME_CAPABILITY))
   ) {
@@ -63,7 +73,8 @@ export async function createWorktreeWithAgent(args: {
       ...create,
       startupAgent: launch.agent,
       startupPrompt: launch.prompt?.text ?? '',
-      launchSource: 'cli'
+      launchSource: 'cli',
+      ...(claudeAccount ? { startupClaudeAccount: claudeAccount } : {})
     }
     const created = await withSetupDecisionRecovery(
       withCliAgentLaunchRecovery(

src/cli/handlers/worktree.ts

@@ -58,8 +58,8 @@ import {
 function getOptionalStartupAgent(flags: Map<string, string | boolean>): TuiAgent | undefined {
   const agent = getPresentStringFlag(flags, 'agent')
   if (agent === undefined) {
-    const needsAgent = ['prompt', 'model', 'effort', 'surface', 'retry-launch'].find((name) =>
-      flags.has(name)
+    const needsAgent = ['prompt', 'model', 'effort', 'surface', 'retry-launch', 'account'].find(
+      (name) => flags.has(name)
     )
     if (needsAgent) {
       throw new RuntimeClientError('invalid_argument', `--${needsAgent} requires --agent`)