feat(cli): let environment add override the advertised pairing endpoint

A pairing offer embeds whatever address the host advertised. "Share this
Orca server" defaults its address picker to 127.0.0.1, so a link minted
for a LAN or Tailscale peer routinely carries a loopback endpoint that
the receiving machine dials against itself. The credentials are fine —
only the address is wrong — but the CLI had no way to correct it, leaving
hand-editing the base64 offer as the only path.

`environment add --endpoint <host>` redirects the offer while keeping the
deviceToken and pinned public key the host issued. Resolution reuses
resolveAdvertisedPairingEndpoint, so the flag accepts the same host,
host:port, and ws(s):// forms as the address field that produced the
link, inherits the port from the pairing code when omitted, and rejects
wildcard bind addresses no client can dial.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

config/tsconfig.cli.json

@@ -68,6 +68,7 @@
     "../src/main/kimi/kimi-hook-config-toml.ts",
     "../src/main/openclaude/hook-service.ts",
     "../src/main/rolling-file-backup.ts",
+    "../src/main/runtime/pairing-endpoint.ts",
     "../src/main/runtime/runtime-metadata.ts",
     "../src/main/win32-utils.ts"
   ],

src/cli/handlers/environment.ts

@@ -17,10 +17,12 @@ export const ENVIRONMENT_HANDLERS: Record<string, CommandHandler> = {
   'environment add': async ({ flags, json }) => {
     const name = getRequiredStringFlag(flags, 'name')
     const pairingCode = getRequiredStringFlag(flags, 'pairing-code')
+    const endpointAddress = getOptionalStringFlag(flags, 'endpoint')
     const environment = redactRuntimeEnvironment(
       addEnvironmentFromPairingCode(getDefaultUserDataPath(), {
         name,
-        pairingCode
+        pairingCode,
+        ...(endpointAddress ? { endpointAddress } : {})
       })
     )
     printResult(
@@ -55,6 +57,17 @@ export const ENVIRONMENT_HANDLERS: Record<string, CommandHandler> = {
   }
 }
 
+function getOptionalStringFlag(flags: Map<string, string | boolean>, name: string): string | null {
+  const value = flags.get(name)
+  if (value === undefined) {
+    return null
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new RuntimeClientError('invalid_argument', `--${name} requires a value`)
+  }
+  return value
+}
+
 function getRequiredStringFlag(flags: Map<string, string | boolean>, name: string): string {
   const value = flags.get(name)
   if (typeof value !== 'string' || value.length === 0) {

src/cli/help.ts

@@ -212,7 +212,7 @@ Common Commands:
   orca status [--json]
   orca diagnostics memory [--json]
   orca agent-context [--json]
-  orca environment add --name <name> --pairing-code <code> [--json]
+  orca environment add --name <name> --pairing-code <code> [--endpoint <host>] [--json]
   orca environment list [--json]
   orca environment show --environment <selector> [--json]
   orca environment rm --environment <selector> [--json]
@@ -505,6 +505,8 @@ export function formatFlagHelp(flag: string): string {
     'display-name': '--display-name <name>  Override the Orca display name',
     'element-index': '--element-index <n>   Element index from get-app-state',
     title: '--title <text>         Custom title for the terminal tab (omit to reset)',
+    endpoint:
+      '--endpoint <host>      Reachable host, host:port, or ws(s):// URL replacing the address advertised by the pairing code',
     enter: '--enter                Append Enter after sending text',
     force: '--force                Force worktree removal when supported',
     focus: '--focus                Reveal the created terminal session in Orca',

src/cli/runtime/environments.test.ts

@@ -81,4 +81,52 @@ describe('CLI runtime environments', () => {
     )
     expect(listEnvironments(userDataPath)[0]?.id).toBe(first.id)
   })
+
+  describe('endpointAddress override', () => {
+    function addWithEndpoint(endpointAddress: string, offerEndpoint = 'ws://127.0.0.1:6768') {
+      const userDataPath = mkdtempSync(join(tmpdir(), 'orca-env-store-'))
+      addEnvironmentFromPairingCode(userDataPath, {
+        name: 'workstation',
+        pairingCode: pairingCode(offerEndpoint),
+        endpointAddress,
+        now: 100
+      })
+      return resolveEnvironmentPairingOffer(userDataPath, 'workstation')
+    }
+
+    it('keeps the port from the pairing code for a bare host', () => {
+      expect(addWithEndpoint('100.64.0.2').endpoint).toBe('ws://100.64.0.2:6768')
+    })
+
+    it('accepts host:port and full ws(s):// forms', () => {
+      expect(addWithEndpoint('desktop.tailnet.ts.net:7000').endpoint).toBe(
+        'ws://desktop.tailnet.ts.net:7000'
+      )
+      expect(addWithEndpoint('wss://desktop.example.com/runtime').endpoint).toBe(
+        'wss://desktop.example.com/runtime'
+      )
+    })
+
+    it('preserves the credentials the host issued', () => {
+      const offer = addWithEndpoint('100.64.0.2')
+      expect(offer.deviceToken).toBe('device-token')
+      expect(offer.publicKeyB64).toBe(Buffer.from(new Uint8Array(32).fill(1)).toString('base64'))
+    })
+
+    it('rejects an unreachable wildcard bind address', () => {
+      expect(() => addWithEndpoint('0.0.0.0')).toThrow(/Invalid --endpoint "0\.0\.0\.0"/)
+    })
+
+    it('leaves the advertised endpoint alone when omitted', () => {
+      const userDataPath = mkdtempSync(join(tmpdir(), 'orca-env-store-'))
+      addEnvironmentFromPairingCode(userDataPath, {
+        name: 'workstation',
+        pairingCode: pairingCode('ws://10.0.0.5:6768'),
+        now: 100
+      })
+      expect(resolveEnvironmentPairingOffer(userDataPath, 'workstation').endpoint).toBe(
+        'ws://10.0.0.5:6768'
+      )
+    })
+  })
 })

src/cli/runtime/environments.ts

@@ -13,7 +13,8 @@ import type {
   KnownRuntimeEnvironment,
   PublicKnownRuntimeEnvironment
 } from '../../shared/runtime-environments'
-import type { PairingOffer } from '../../shared/pairing'
+import { parsePairingCode, type PairingOffer } from '../../shared/pairing'
+import { resolveAdvertisedPairingEndpoint } from '../../main/runtime/pairing-endpoint'
 import { RuntimeClientError } from './types'
 
 export type EnvironmentAddResult = {
@@ -32,9 +33,38 @@ export { getEnvironmentStorePath, listEnvironments }
 
 export function addEnvironmentFromPairingCode(
   userDataPath: string,
-  args: { name: string; pairingCode: string; now?: number }
+  args: { name: string; pairingCode: string; now?: number; endpointAddress?: string }
 ): KnownRuntimeEnvironment {
-  return translateStoreError(() => addEnvironmentFromPairingCodeInStore(userDataPath, args))
+  const { endpointAddress, ...rest } = args
+  const endpoint = endpointAddress
+    ? resolveEndpointOverride(args.pairingCode, endpointAddress)
+    : null
+  return translateStoreError(() =>
+    addEnvironmentFromPairingCodeInStore(userDataPath, {
+      ...rest,
+      ...(endpoint ? { endpoint } : {})
+    })
+  )
+}
+
+// Why: reuse the host's advertise grammar so --endpoint accepts the same hosts,
+// host:port, and ws(s):// forms the "Share this Orca server" address field does.
+function resolveEndpointOverride(pairingCode: string, address: string): string {
+  const offer = parsePairingCode(pairingCode)
+  if (!offer) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      'Invalid pairing code. Expected an orca://pair?... URL or bare pairing payload.'
+    )
+  }
+  const resolved = resolveAdvertisedPairingEndpoint(offer.endpoint, address)
+  if (!resolved.ok) {
+    throw new RuntimeClientError(
+      'invalid_argument',
+      `Invalid --endpoint "${address}". ${resolved.guidance}`
+    )
+  }
+  return resolved.endpoint
 }
 
 export function removeEnvironment(userDataPath: string, selector: string): KnownRuntimeEnvironment {

src/cli/specs/environment.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseArgs, validateCommandAndFlags } from '../args'
+import { ENVIRONMENT_COMMAND_SPECS } from './environment'
+
+describe('environment command specs', () => {
+  it('accepts --endpoint on environment add and carries its value through', () => {
+    const parsed = parseArgs([
+      'environment',
+      'add',
+      '--name',
+      'work-laptop',
+      '--pairing-code',
+      'orca://pair?code=abc',
+      '--endpoint',
+      '100.64.0.2'
+    ])
+
+    expect(() => validateCommandAndFlags(ENVIRONMENT_COMMAND_SPECS, parsed)).not.toThrow()
+    expect(parsed.flags.get('endpoint')).toBe('100.64.0.2')
+  })
+
+  it('rejects --endpoint on commands that do not resolve an address', () => {
+    for (const path of [
+      ['environment', 'list'],
+      ['environment', 'show', '--environment', 'work-laptop'],
+      ['environment', 'rm', '--environment', 'work-laptop']
+    ]) {
+      const parsed = parseArgs([...path, '--endpoint', '100.64.0.2'])
+      expect(() => validateCommandAndFlags(ENVIRONMENT_COMMAND_SPECS, parsed)).toThrow(
+        /Unknown flag --endpoint/
+      )
+    }
+  })
+})

src/cli/specs/environment.ts

@@ -5,9 +5,15 @@ export const ENVIRONMENT_COMMAND_SPECS: CommandSpec[] = [
   {
     path: ['environment', 'add'],
     summary: 'Save a remote Orca runtime environment from a pairing code',
-    usage: 'orca environment add --name <name> --pairing-code <code> [--json]',
-    allowedFlags: [...GLOBAL_FLAGS, 'name'],
-    examples: ['orca environment add --name work-laptop --pairing-code orca://pair?code=...']
+    usage: 'orca environment add --name <name> --pairing-code <code> [--endpoint <host>] [--json]',
+    allowedFlags: [...GLOBAL_FLAGS, 'name', 'endpoint'],
+    examples: [
+      'orca environment add --name work-laptop --pairing-code orca://pair?code=...',
+      'orca environment add --name work-laptop --pairing-code orca://pair?code=... --endpoint 100.64.0.2'
+    ],
+    notes: [
+      'Use --endpoint when the host advertised an address this machine cannot reach (for example a 127.0.0.1 link generated for a LAN or Tailscale peer). It accepts a host, host:port, or ws(s):// URL and keeps the port from the pairing code when omitted.'
+    ]
   },
   {
     path: ['environment', 'list'],

src/shared/runtime-environment-store.ts

@@ -41,15 +41,25 @@ export function listEnvironments(userDataPath: string): KnownRuntimeEnvironment[
 
 export function addEnvironmentFromPairingCode(
   userDataPath: string,
-  args: { name: string; pairingCode: string; now?: number; source?: RuntimeEnvironmentSource }
+  args: {
+    name: string
+    pairingCode: string
+    now?: number
+    source?: RuntimeEnvironmentSource
+    /** Already-resolved ws(s):// URL replacing the offer's advertised endpoint. */
+    endpoint?: string
+  }
 ): KnownRuntimeEnvironment {
-  const offer = parsePairingCode(args.pairingCode)
-  if (!offer) {
+  const parsed = parsePairingCode(args.pairingCode)
+  if (!parsed) {
     throw new RuntimeEnvironmentStoreError(
       'invalid_argument',
       'Invalid pairing code. Expected an orca://pair?... URL or bare pairing payload.'
     )
   }
+  // Why: a host that advertised loopback mints an offer no other device can dial;
+  // the token stays valid, so let the caller redirect it instead of re-pairing.
+  const offer = args.endpoint ? { ...parsed, endpoint: args.endpoint } : parsed
   const store = readEnvironmentStore(userDataPath)
   const now = args.now ?? Date.now()
   const existing = store.environments.find((entry) => entry.name === args.name)