diff --git a/docs/site/content/docs/cli/reference.mdx b/docs/site/content/docs/cli/reference.mdx index 11d9186e9ee..149321a6c42 100644 --- a/docs/site/content/docs/cli/reference.mdx +++ b/docs/site/content/docs/cli/reference.mdx @@ -165,7 +165,7 @@ orca reference find STA-1234 --json - **Writes:** full URLs only; no custom shorthand. `remove --key` supports older entries without URLs. Source-unknown legacy links cannot match an exact URL; native issue keys remain searchable when stored. Duplicate adds and absent removals are no-ops. Unrelated links and current selection are preserved. Older hosts without safe delta merging refuse writes. - **Create:** repeat `--reference`; incompatible with `--pr`, `--issue`, `--linear-issue`, `--gitlab-issue`, and `--gitlab-mr`. References persist before setup or agent startup. - **Find:** a full URL or native issue key; bare numbers are rejected. Keys search all matching sources. Reads stored metadata, without provider requests or conversation searches. Use `orca search` for conversation text. -- **Scope:** `--worktree` selects a worktree or folder workspace. Find also accepts `--repo` instead, plus `--include-archived` and `--limit` (default 50 workspaces). `truncated: true` means more matched. Remote selectors refer to the execution host; `current` is local only. +- **Scope:** `--worktree` selects a worktree or folder workspace. Find also accepts `--repo` instead, plus `--include-archived` and `--limit` (default 50 workspaces). `truncated: true` means more matched. With `--server`, selectors refer to that server; `current` is local only. - **Output:** list returns `references` with opaque `key` and `selected`; writes also return `changes`. Worktree show/list/ps retain `linkedItems`. Find returns workspace matches and agents with `linked`, `liveness`, and available `terminal`/`mailbox` addresses. `linked: false` means ownership is unknown; sharing a workspace is insufficient evidence. Choose an agent from `find`, then use its exact address: diff --git a/skill-guides/orca-cli.md b/skill-guides/orca-cli.md index 8c34cb4b761..c6a128747fc 100644 --- a/skill-guides/orca-cli.md +++ b/skill-guides/orca-cli.md @@ -184,9 +184,9 @@ ORCA worktree create --name fix --parent-worktree active --reference https://git ORCA reference find STA-1234 --json ``` -- Add/remove require explicit `--worktree`, including `current` or a folder selector. Add and create accept full URLs or bare Jira keys. Keys resolve on the selected execution-host Jira site; use `--reference-site ` from `ORCA jira connection` to choose one. Other providers require full URLs, which need no Jira authentication. Every input must validate and each Jira key must resolve before writing. `remove --key` also accepts opaque keys from list for URL-less entries. Source-unknown legacy links cannot match exact URLs; stored native issue keys remain searchable. Duplicate adds and absent removals do nothing; unrelated links and selection survive concurrent edits. Unsupported older hosts refuse writes. +- Add/remove require explicit `--worktree`, including `current` or a folder selector. Add and create accept full URLs or bare Jira keys. Keys resolve on the selected server's Jira site; use `--reference-site ` from `ORCA jira connection` to choose one. Other providers require full URLs, which need no Jira authentication. Every input must validate and each Jira key must resolve before writing. `remove --key` also accepts opaque keys from list for URL-less entries. Source-unknown legacy links cannot match exact URLs; stored native issue keys remain searchable. Duplicate adds and absent removals do nothing; unrelated links and selection survive concurrent edits. Unsupported older hosts refuse writes. - Repeat create `--reference` to seed links before setup/agent startup. Do not combine it with legacy `--pr`, `--issue`, `--linear-issue`, `--gitlab-issue`, or `--gitlab-mr` flags. Legacy `worktree set --pr` still appends/selects; `linkedItems` remains the worktree output field. -- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. Remote selectors refer to the execution host; never use local `current` for a paired host. +- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. With `--server`, selectors refer to that server; never use local `current` for another server. - Find returns all known agents in each matching workspace. `linked: true` requires recorded reference/session evidence; `linked: false` means ownership is unknown. Check `liveness` (`live`, `unverifiable`, `exited`) and choose the intended agent; never infer ownership merely from workspace membership. - Send through the returned exact `terminal` handle or `mailbox` (`dispatch:` / `orca_session_id:`). If it returns a `dispatch:` mailbox, the agent is a supervised worker: use the mailbox, not terminal input. A `run:` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership. diff --git a/src/cli/args.ts b/src/cli/args.ts index aaae0440869..d627d7a600d 100644 --- a/src/cli/args.ts +++ b/src/cli/args.ts @@ -1,9 +1,11 @@ import { RuntimeClientError } from './runtime/types' import { unknownCommandData, unknownFlagData } from './command-suggestion' import { INPUT_ONLY_FLAGS, specPaths, type CommandSpec } from './command-spec' +import { canonicalizeFlagAliases, canonicalizeGroupAlias } from './legacy-spelling-canonicalization' + +export { canonicalizeLegacyFlagArgv } from './legacy-spelling-canonicalization' import { CLI_BOOLEAN_FLAGS, - CLI_FLAG_ALIASES, CLI_GLOBAL_FLAGS, CLI_GLOBAL_VALUE_FLAGS, findCliCommandIndex @@ -174,65 +176,6 @@ export function isCommandGroup(specs: CommandSpec[], commandPath: string[]): boo ) } -/** Raw argv with old flag spellings renamed, so commands rebuilt from argv print only canonical flags. */ -export function canonicalizeLegacyFlagArgv(argv: readonly string[]): string[] { - const end = argv.indexOf('--') - return argv.map((token, index) => { - if ((end !== -1 && index >= end) || !token.startsWith('--')) { - return token - } - const [name, ...value] = token.slice(2).split('=') - const canonical = CLI_FLAG_ALIASES[name] - return canonical === undefined ? token : [`--${canonical}`, ...value].join('=') - }) -} - -/** Renames old flag spellings so every later reader sees only canonical flags. */ -function canonicalizeFlagAliases(parsed: ParsedArgs): ParsedArgs { - if (!Object.keys(CLI_FLAG_ALIASES).some((alias) => parsed.flags.has(alias))) { - return parsed - } - const flags = new Map() - const conflicts: { flag: string; alias: string }[] = [] - for (const [name, value] of parsed.flags) { - const canonical = CLI_FLAG_ALIASES[name] - if (canonical === undefined) { - flags.set(name, value) - } else if (!parsed.flags.has(canonical)) { - flags.set(canonical, value) - } else if (parsed.flags.get(canonical) !== value) { - conflicts.push({ flag: canonical, alias: name }) - } - } - return { - ...parsed, - flags, - ...(conflicts.length > 0 ? { flagAliasConflicts: conflicts } : {}) - } -} - -/** A group typed under an alias (`orca environment`) names the canonical group (`orca server`). */ -function canonicalizeGroupAlias(specs: CommandSpec[], parsed: ParsedArgs): ParsedArgs { - const path = parsed.commandPath - if (path.length === 0 || isCanonicalPrefix(specs, path)) { - return parsed - } - for (const spec of specs) { - for (const alias of [...(spec.aliases ?? []), ...(spec.legacyAliases ?? [])]) { - if (alias.length > path.length && matches(alias.slice(0, path.length), path)) { - return { ...parsed, commandPath: spec.path.slice(0, path.length) } - } - } - } - return parsed -} - -function isCanonicalPrefix(specs: CommandSpec[], path: string[]): boolean { - return specs.some( - (spec) => spec.path.length >= path.length && matches(spec.path.slice(0, path.length), path) - ) -} - export function normalizeCommandPositionals(specs: CommandSpec[], input: ParsedArgs): ParsedArgs { const parsed = canonicalizeFlagAliases(input) for (const spec of specs) { @@ -269,7 +212,7 @@ export function normalizeCommandPositionals(specs: CommandSpec[], input: ParsedA return { ...parsed, commandPath: spec.path, flags, positionalFlagConflicts } } } - return canonicalizeGroupAlias(specs, parsed) + return { ...parsed, commandPath: canonicalizeGroupAlias(specs, parsed.commandPath) } } export function findCommandSpec( @@ -310,7 +253,7 @@ export function validateCommandAndFlags(specs: CommandSpec[], parsed: ParsedArgs if (aliasConflict) { throw new RuntimeClientError( 'invalid_argument', - `--${aliasConflict.flag} and --${aliasConflict.alias} name different values; pass only --${aliasConflict.flag}.` + `--${aliasConflict.flag} was given two different values; pass it once.` ) } diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index 7d82e351f74..b3f0cbf00e7 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -412,9 +412,9 @@ const ORCA_CLI_MARKDOWN = [ "ORCA reference find STA-1234 --json", "```", "", - "- Add/remove require explicit `--worktree`, including `current` or a folder selector. Add and create accept full URLs or bare Jira keys. Keys resolve on the selected execution-host Jira site; use `--reference-site ` from `ORCA jira connection` to choose one. Other providers require full URLs, which need no Jira authentication. Every input must validate and each Jira key must resolve before writing. `remove --key` also accepts opaque keys from list for URL-less entries. Source-unknown legacy links cannot match exact URLs; stored native issue keys remain searchable. Duplicate adds and absent removals do nothing; unrelated links and selection survive concurrent edits. Unsupported older hosts refuse writes.", + "- Add/remove require explicit `--worktree`, including `current` or a folder selector. Add and create accept full URLs or bare Jira keys. Keys resolve on the selected server's Jira site; use `--reference-site ` from `ORCA jira connection` to choose one. Other providers require full URLs, which need no Jira authentication. Every input must validate and each Jira key must resolve before writing. `remove --key` also accepts opaque keys from list for URL-less entries. Source-unknown legacy links cannot match exact URLs; stored native issue keys remain searchable. Duplicate adds and absent removals do nothing; unrelated links and selection survive concurrent edits. Unsupported older hosts refuse writes.", "- Repeat create `--reference` to seed links before setup/agent startup. Do not combine it with legacy `--pr`, `--issue`, `--linear-issue`, `--gitlab-issue`, or `--gitlab-mr` flags. Legacy `worktree set --pr` still appends/selects; `linkedItems` remains the worktree output field.", - "- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. Remote selectors refer to the execution host; never use local `current` for a paired host.", + "- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. With `--server`, selectors refer to that server; never use local `current` for another server.", "- Find returns all known agents in each matching workspace. `linked: true` requires recorded reference/session evidence; `linked: false` means ownership is unknown. Check `liveness` (`live`, `unverifiable`, `exited`) and choose the intended agent; never infer ownership merely from workspace membership.", "- Send through the returned exact `terminal` handle or `mailbox` (`dispatch:` / `orca_session_id:`). If it returns a `dispatch:` mailbox, the agent is a supervised worker: use the mailbox, not terminal input. A `run:` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.", "", diff --git a/src/cli/index.ts b/src/cli/index.ts index 734c7383a2c..ff225f91eb9 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -73,7 +73,12 @@ export async function main( COMMAND_SPECS, parseArgs(argv, COMMAND_PATHS, COMMAND_SPECS) ) - const helpPath = resolveHelpPath(parsed) + const rawHelpPath = resolveHelpPath(parsed) + // `orca help environment` names the same group as `orca environment --help`. + const helpPath = + rawHelpPath && + normalizeCommandPositionals(COMMAND_SPECS, { commandPath: rawHelpPath, flags: new Map() }) + .commandPath if (helpPath !== null) { printHelp(COMMAND_SPECS, helpPath) if ( diff --git a/src/cli/legacy-server-spellings.test.ts b/src/cli/legacy-server-spellings.test.ts index d477e5cde78..f6f68f5e91c 100644 --- a/src/cli/legacy-server-spellings.test.ts +++ b/src/cli/legacy-server-spellings.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { canonicalizeLegacyFlagArgv, normalizeCommandPositionals, @@ -8,6 +8,7 @@ import { import { unknownCommandData } from './command-suggestion' import { ignoresRemoteSelection } from './remote-selection-scope' import { COMMAND_SPECS } from './specs' +import { main } from './index' function normalize(argv: string[]) { return normalizeCommandPositionals(COMMAND_SPECS, parseArgs(argv, undefined, COMMAND_SPECS)) @@ -67,4 +68,19 @@ describe('old server spellings are input only', () => { expect(ignoresRemoteSelection(['server', 'name'])).toBe(false) expect(ignoresRemoteSelection(['server', 'list'])).toBe(true) }) + + it('prints the canonical group for `help environment` as for `environment --help`', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + await main(['help', 'environment']) + await main(['environment', '--help']) + const [viaHelp, viaFlag] = log.mock.calls.map((call) => String(call[0])) + log.mockRestore() + expect(viaHelp).toBe(viaFlag) + expect(viaHelp.startsWith('orca server\n')).toBe(true) + expect(viaHelp).not.toContain('environment') + }) + + it('names the canonical group when an old-spelling subcommand is unknown', () => { + expect(normalize(['environment', 'stp']).commandPath).toEqual(['server', 'stp']) + }) }) diff --git a/src/cli/legacy-spelling-canonicalization.ts b/src/cli/legacy-spelling-canonicalization.ts new file mode 100644 index 00000000000..3c33e6d48aa --- /dev/null +++ b/src/cli/legacy-spelling-canonicalization.ts @@ -0,0 +1,78 @@ +import { CLI_FLAG_ALIASES } from '../shared/cli-argument-boundary' +import type { CommandSpec } from './command-spec' + +type ParsedFlags = { + commandPath: string[] + flags: Map + flagAliasConflicts?: { flag: string; alias: string }[] +} + +function matches(actual: readonly string[], expected: readonly string[]): boolean { + return ( + actual.length === expected.length && actual.every((value, index) => value === expected[index]) + ) +} + +/** Raw argv with old flag spellings renamed, so commands rebuilt from argv print only canonical flags. */ +export function canonicalizeLegacyFlagArgv(argv: readonly string[]): string[] { + const end = argv.indexOf('--') + return argv.map((token, index) => { + if ((end !== -1 && index >= end) || !token.startsWith('--')) { + return token + } + const [name, ...value] = token.slice(2).split('=') + const canonical = CLI_FLAG_ALIASES[name] + return canonical === undefined ? token : [`--${canonical}`, ...value].join('=') + }) +} + +/** Renames old flag spellings so every later reader sees only canonical flags. */ +export function canonicalizeFlagAliases(parsed: Parsed): Parsed { + if (!Object.keys(CLI_FLAG_ALIASES).some((alias) => parsed.flags.has(alias))) { + return parsed + } + const flags = new Map() + const conflicts: { flag: string; alias: string }[] = [] + for (const [name, value] of parsed.flags) { + const canonical = CLI_FLAG_ALIASES[name] + if (canonical === undefined) { + flags.set(name, value) + } else if (!parsed.flags.has(canonical)) { + flags.set(canonical, value) + } else if (parsed.flags.get(canonical) !== value) { + conflicts.push({ flag: canonical, alias: name }) + } + } + return { + ...parsed, + flags, + ...(conflicts.length > 0 ? { flagAliasConflicts: conflicts } : {}) + } +} + +/** + * A group typed under an alias (`orca environment`, or `orca environment stp`) names the canonical + * group (`orca server`), so help, errors and suggestions print only canonical words. + */ +export function canonicalizeGroupAlias(specs: CommandSpec[], path: string[]): string[] { + for (let length = path.length; length > 0; length -= 1) { + const prefix = path.slice(0, length) + if (isCanonicalPrefix(specs, prefix)) { + return path + } + for (const spec of specs) { + for (const alias of [...(spec.aliases ?? []), ...(spec.legacyAliases ?? [])]) { + if (alias.length > length && matches(alias.slice(0, length), prefix)) { + return [...spec.path.slice(0, length), ...path.slice(length)] + } + } + } + } + return path +} + +function isCanonicalPrefix(specs: CommandSpec[], path: string[]): boolean { + return specs.some( + (spec) => spec.path.length >= path.length && matches(spec.path.slice(0, path.length), path) + ) +} diff --git a/src/cli/row-owner-server.test.ts b/src/cli/row-owner-server.test.ts index bdeae11418c..142f516d935 100644 --- a/src/cli/row-owner-server.test.ts +++ b/src/cli/row-owner-server.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'vitest' import { - formatOwnerToken, ownerOfHostId, + ownerOfMirrorHostId, ownerOfWorkerHost, type OwnerContext, type WorkspaceServer @@ -22,9 +22,17 @@ describe('the server that owns a row', () => { expect(ownerOfHostId('local', context(BUILD_BOX))).toEqual({ server: BUILD_BOX }) }) - it("names a runtime owner only from the local answer's own store", () => { - expect(ownerOfHostId('runtime:env-1', context(LOCAL))).toEqual({ server: BUILD_BOX }) - expect(ownerOfHostId('runtime:env-9', context(LOCAL))).toEqual({ + it("never names a stored row's runtime stamp, which another client may have written", () => { + expect(ownerOfHostId('runtime:env-1', context(LOCAL))).toEqual({ + server: null, + unknown: 'unverified-owner', + stored: 'runtime:env-1' + }) + }) + + it("names a terminal mirror's runtime owner only from the local answer's own store", () => { + expect(ownerOfMirrorHostId('runtime:env-1', context(LOCAL))).toEqual({ server: BUILD_BOX }) + expect(ownerOfMirrorHostId('runtime:env-9', context(LOCAL))).toEqual({ server: null, unknown: 'unverified-owner', stored: 'runtime:env-9' @@ -32,7 +40,7 @@ describe('the server that owns a row', () => { }) it("never joins a remote server's runtime stamp against this computer's store", () => { - expect(ownerOfHostId('runtime:env-1', context(BUILD_BOX))).toEqual({ + expect(ownerOfMirrorHostId('runtime:env-1', context(BUILD_BOX))).toEqual({ server: null, unknown: 'unverified-owner', stored: 'runtime:env-1' @@ -54,13 +62,6 @@ describe('the server that owns a row', () => { }) }) - it('prints a known owner by name and an unknown one as server=unknown', () => { - expect(formatOwnerToken(ownerOfHostId('runtime:env-1', context(LOCAL)))).toBe( - 'server=build-box' - ) - expect(formatOwnerToken(ownerOfHostId('ssh:box', context(LOCAL)))).toMatch(/^server=unknown /) - }) - it('names federated workers by their saved id and the home coordinator as answering', () => { expect(ownerOfWorkerHost({ kind: 'local', id: 'local' }, context(BUILD_BOX))).toEqual({ server: BUILD_BOX @@ -77,7 +78,7 @@ describe('the server that owns a row', () => { describe('workspace annotation JSON', () => { it('names the owner and route under server keys', () => { - const [mirror, stranger] = annotateWorkspaces( + const [stamped, stranger] = annotateWorkspaces( [ { id: 'repo::/srv/app', hostId: 'runtime:env-1', identityKey: 'wt2:a' }, { @@ -93,8 +94,9 @@ describe('workspace annotation JSON', () => { ], { owners: context(LOCAL), localInstallationId: 'mine' } ) - expect(mirror).toEqual({ - server: BUILD_BOX, + expect(stamped).toEqual({ + server: null, + serverUnknown: 'unverified-owner', address: { server: 'local', worktree: 'identity:wt2:a', diff --git a/src/cli/row-owner-server.ts b/src/cli/row-owner-server.ts index bae1e635809..4613a9edbbc 100644 --- a/src/cli/row-owner-server.ts +++ b/src/cli/row-owner-server.ts @@ -68,7 +68,27 @@ function savedServerInAnswerNamespace( return context.answering.id === LOCAL_ENVIRONMENT ? context.savedServer(id) : undefined } +/** + * The owner of a stored catalog row (workspace or project setup). A runtime stamp there may have been + * written by another client in its own namespace, so it is never named; see {@link ownerOfMirrorHostId}. + */ export function ownerOfHostId(hostId: string | null | undefined, context: OwnerContext): RowOwner { + return ownerOf(hostId, () => undefined, context) +} + +/** The owner of a terminal: a mirror's stamp is written by the local Orca from this computer's store. */ +export function ownerOfMirrorHostId( + hostId: string | null | undefined, + context: OwnerContext +): RowOwner { + return ownerOf(hostId, (id) => savedServerInAnswerNamespace(id, context), context) +} + +function ownerOf( + hostId: string | null | undefined, + savedServer: (id: string) => WorkspaceServer | undefined, + context: OwnerContext +): RowOwner { const stored = hostId?.trim() || null if (!stored) { return { server: null, unknown: 'owner-not-reported', stored } @@ -83,10 +103,7 @@ export function ownerOfHostId(hostId: string | null | undefined, context: OwnerC if (parsed?.kind === 'ssh') { return { server: null, unknown: 'legacy-ssh-row', stored } } - const saved = - parsed?.kind === 'runtime' - ? savedServerInAnswerNamespace(parsed.environmentId, context) - : undefined + const saved = parsed?.kind === 'runtime' ? savedServer(parsed.environmentId) : undefined return saved ? { server: saved } : { server: null, unknown: 'unverified-owner', stored } } @@ -132,7 +149,8 @@ export function formatOwnerToken(owner: RowOwner): string { /** A row's `server=` token, or none when no owner context was given. */ export function ownerTokenOf( hostId: string | null | undefined, - context: OwnerContext | undefined + context: OwnerContext | undefined, + resolve: (hostId: string | null | undefined, context: OwnerContext) => RowOwner = ownerOfHostId ): string { - return context ? ` ${formatOwnerToken(ownerOfHostId(hostId, context))}` : '' + return context ? ` ${formatOwnerToken(resolve(hostId, context))}` : '' } diff --git a/src/cli/runtime/environment-pairing-exchange.ts b/src/cli/runtime/environment-pairing-exchange.ts index 3a9a777aad2..59114379d84 100644 --- a/src/cli/runtime/environment-pairing-exchange.ts +++ b/src/cli/runtime/environment-pairing-exchange.ts @@ -7,13 +7,13 @@ import type { RuntimeRpcResponse } from '../../shared/runtime-rpc-envelope' import type { RuntimeStatus } from '../../shared/runtime-session-contracts' import { RuntimeClientError } from './types' -// `environment add` works offline; a short probe keeps an unreachable host from stalling it. +// `server add` works offline; a short probe keeps an unreachable server from stalling it. const STATUS_PROBE_TIMEOUT_MS = 5_000 function pairingCodeRefused(): RuntimeClientError { return new RuntimeClientError( 'unauthorized', - 'The host refused this pairing code. It may have expired or already been used by another device. Show a new pairing code on the host (`orca pair`, or Settings → Remote Orca Servers in Orca) and run `orca server add` again.' + 'The server refused this pairing code. It may have expired or already been used by another device. Show a new pairing code on the server (`orca pair`, or Settings → Remote Orca Servers in Orca) and run `orca server add` again.' ) } diff --git a/src/cli/runtime/transport.test.ts b/src/cli/runtime/transport.test.ts index d53dac4788e..755e6209bd8 100644 --- a/src/cli/runtime/transport.test.ts +++ b/src/cli/runtime/transport.test.ts @@ -8,7 +8,6 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import type { RuntimeMetadata } from '../../shared/runtime-bootstrap' import { MAX_TIMER_DELAY_MS } from '../../shared/timer-delay' import { sendRequest } from './transport' -import { formatCliError } from '../cli-error' import { RuntimeClient } from './client' import { getRuntimeMetadataPath } from '../../shared/runtime-bootstrap' import { requestWorktreeRemoval } from '../handlers/worktree-removal-request' @@ -74,7 +73,7 @@ describe('runtime transport timeout validation', () => { // These fixtures create Unix domain sockets rather than Windows named pipes. describe.skipIf(process.platform === 'win32')('runtime transport', () => { - it('rejects a responding replacement runtime with retry advice in human output', async () => { + it('rejects a responding replacement runtime as unavailable', async () => { const userDataPath = mkdtempSync(join(tmpdir(), 'orca-runtime-transport-')) roots.push(userDataPath) const endpoint = join(userDataPath, 'runtime.sock') @@ -108,7 +107,6 @@ describe.skipIf(process.platform === 'win32')('runtime transport', () => { ) expect(error).toMatchObject({ code: 'runtime_unavailable' }) - expect(formatCliError(error)).toContain('\nNext step: Retry the command.') }) it.each(['preflight', 'mutation'] as const)( diff --git a/src/cli/selector-ambiguity-recovery.ts b/src/cli/selector-ambiguity-recovery.ts index 5379a8dace2..155523803ec 100644 --- a/src/cli/selector-ambiguity-recovery.ts +++ b/src/cli/selector-ambiguity-recovery.ts @@ -8,13 +8,13 @@ export type SelectorAmbiguityRecovery = { const EXACT_FORMS = { repo: { forms: - 'id: or path:; if two hosts share that id or path, use --project --host where the command takes them', + 'id: or path:; if the project is set up for more than one server here, use --project with --server where the command takes them', list: 'orca repo list --json', noun: 'project' }, worktree: { forms: - 'identity: (host-qualified), id::: when only one server has that checkout, or folder: for a folder workspace', + 'identity: (unique to one row), id::: when only one row has that checkout, or folder: for a folder workspace', list: 'orca worktree ps --json', noun: 'workspace' } @@ -45,7 +45,7 @@ export function selectorAmbiguityRecovery(selectors: { return [ `${matched} Pass an exact selector: ${exact.forms}.`, selectors.remoteServerSelected - ? `List the exact values with \`${exact.list}\`, passing the same server flag (--server, --pairing-code or --host runtime:) as this command.` + ? `List the exact values with \`${exact.list}\`, passing the same --server or --pairing-code as this command.` : `List the exact values with \`${exact.list}\`.` ] }) diff --git a/src/cli/specs/account.ts b/src/cli/specs/account.ts index c7c5e465f40..df5845436bc 100644 --- a/src/cli/specs/account.ts +++ b/src/cli/specs/account.ts @@ -16,7 +16,7 @@ export const ACCOUNT_COMMAND_SPECS: CommandSpec[] = [ 'Use --integration to skip the OpenCode integration picker; --label names the saved OpenCode or Devin profile.', 'Use --method and repeated --answer to pass OpenCode its login method and form answers, so sign-in can finish without an interactive terminal.', 'Antigravity accounts are saved from the current `agy` login in Orca Settings > AI Provider Accounts.', - 'OpenCode and Devin profiles apply to new explicit host agent launches. Direct SSH relay and Windows-hosted WSL selection are not supported; run the command on a headless Orca runtime on that host.', + 'OpenCode and Devin profiles apply to new explicit agent launches on this server. Direct SSH relay and Windows-hosted WSL selection are not supported; run the command on a headless Orca server on that computer.', 'Sign in with the account you want to add (e.g. use a private/incognito browser window for a second account).', '--agent defaults to claude. Requires Orca to be running on this computer.' ], diff --git a/src/cli/terminal-format.ts b/src/cli/terminal-format.ts index 2a6f0e92490..690fd594f65 100644 --- a/src/cli/terminal-format.ts +++ b/src/cli/terminal-format.ts @@ -4,7 +4,7 @@ import { } from '../shared/terminal/pty/lifecycle/pty-liveness-verdict' import { describeTerminalWaitBlockedReason } from '../shared/terminal/runtime-policy/terminal-wait-blocked-reason-legacy-alias' import { formatListingHostScope, type WithAnnotatedHostScope } from './omitted-host-scope-selectors' -import { ownerTokenOf, type OwnerContext } from './row-owner-server' +import { ownerOfMirrorHostId, ownerTokenOf, type OwnerContext } from './row-owner-server' import type { RuntimeTerminalClose, RuntimeTerminalCreate, @@ -34,7 +34,7 @@ export function formatTerminalList( const body = result.terminals .map( (terminal) => - `${terminal.handle} ${terminal.paneTitle ?? terminal.title ?? '(untitled)'} ${terminal.connected ? 'connected' : 'disconnected'}${terminal.orphaned ? ' orphaned' : ''}${ownerTokenOf(terminal.executionHostId, owners)} ${terminal.worktreePath}\n${terminal.preview ? `preview: ${terminal.preview}` : 'preview: '}` + `${terminal.handle} ${terminal.paneTitle ?? terminal.title ?? '(untitled)'} ${terminal.connected ? 'connected' : 'disconnected'}${terminal.orphaned ? ' orphaned' : ''}${ownerTokenOf(terminal.executionHostId, owners, ownerOfMirrorHostId)} ${terminal.worktreePath}\n${terminal.preview ? `preview: ${terminal.preview}` : 'preview: '}` ) .join('\n\n') const visualLayout = formatTerminalVisualLayouts(result.visualLayouts) diff --git a/src/main/orcad/orcad-cli-launcher.integration.test.ts b/src/main/orcad/orcad-cli-launcher.integration.test.ts index 2513f878d06..610477bb8ef 100644 --- a/src/main/orcad/orcad-cli-launcher.integration.test.ts +++ b/src/main/orcad/orcad-cli-launcher.integration.test.ts @@ -144,9 +144,7 @@ it.skipIf(skip)( timeoutMs: 15_000 }) expect(person.code).not.toBe(0) - expect(`${person.stdout}${person.stderr}`).toContain( - 'Unknown environment: stale-shell-selection' - ) + expect(`${person.stdout}${person.stderr}`).toContain('stale-shell-selection') } finally { await recordProfileDaemons(userData) await killChildAndWait(child) diff --git a/src/shared/remote-runtime/host-store/runtime-environment-store-unreadable-records.test.ts b/src/shared/remote-runtime/host-store/runtime-environment-store-unreadable-records.test.ts index 93beaea6deb..1ece31d25d8 100644 --- a/src/shared/remote-runtime/host-store/runtime-environment-store-unreadable-records.test.ts +++ b/src/shared/remote-runtime/host-store/runtime-environment-store-unreadable-records.test.ts @@ -178,13 +178,17 @@ describe('runtime environment store with records this build cannot read', () => const { pinned, other } = setup() expect(listEnvironments(userDataPath)).toEqual([other]) - expect(() => resolveEnvironment(userDataPath, pinned.id)).toThrow('Unknown environment') - expect(() => removeEnvironment(userDataPath, pinned.id)).toThrow('Unknown environment') + expect(() => resolveEnvironment(userDataPath, pinned.id)).toThrow( + expect.objectContaining({ code: 'invalid_argument' }) + ) + expect(() => removeEnvironment(userDataPath, pinned.id)).toThrow( + expect.objectContaining({ code: 'invalid_argument' }) + ) expect(() => updateEnvironmentFromPairingCode(userDataPath, pinned.id, { pairingCode: encodePairingOffer(pairing) }) - ).toThrow('Unknown environment') + ).toThrow(expect.objectContaining({ code: 'invalid_argument' })) expect(() => readCurrentRuntimeEnvironmentSidecarEntry(userDataPath, pinned)).toThrow( 'newer version of Orca' ) diff --git a/src/shared/remote-runtime/host-store/runtime-environment-store.ts b/src/shared/remote-runtime/host-store/runtime-environment-store.ts index 4c6f35bd1f0..61223f6f65f 100644 --- a/src/shared/remote-runtime/host-store/runtime-environment-store.ts +++ b/src/shared/remote-runtime/host-store/runtime-environment-store.ts @@ -309,8 +309,11 @@ export function resolveEnvironmentFromStore 1) { throw new RuntimeEnvironmentStoreError( 'invalid_argument', - `Environment name "${selector}" is ambiguous; use the environment id.` + `Server name "${selector}" is ambiguous; use the server id.` ) } - throw new RuntimeEnvironmentStoreError('invalid_argument', `Unknown environment: ${selector}`) + throw new RuntimeEnvironmentStoreError( + 'invalid_argument', + `Unknown server: ${selector}. Run \`orca server list\`.` + ) }