Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 2 additions & 28 deletions mobile/src/components/worktree-name-suggestion.ts
Original file line number Diff line number Diff line change
@@ -1,28 +1,2 @@
import {
normalizeSuggestedName,
selectSuggestedCreatureName,
suggestionPathBasename
} from '../../../src/shared/worktree-name-suggestion'
import {
EMPTY_RETIRED_NAME_REGISTRY,
type RetiredNameRegistry
} from '../../../src/shared/worktree/retired-name-registry'

// Share the desktop algorithm; collisions use the on-disk basename, not displayName.

// Retired names may retain conversation state keyed by cwd; exhaustedTiers covers compacted names the host no longer sends individually.
// Older hosts omit both fields, retaining deduplication against live paths only.
export function getSuggestedCreatureName(
existingPaths: readonly string[],
random: () => number = Math.random,
retired: RetiredNameRegistry = EMPTY_RETIRED_NAME_REGISTRY
): string {
const used = new Set<string>()
for (const path of existingPaths) {
used.add(normalizeSuggestedName(suggestionPathBasename(path)))
}
for (const retiredName of retired.names) {
used.add(normalizeSuggestedName(retiredName))
}
return selectSuggestedCreatureName(used, random, retired.exhaustedTiers)
}
// Share the desktop algorithm. Older hosts omit retired names and tiers, retaining deduplication against live paths only.
export { suggestCreatureNameForPaths as getSuggestedCreatureName } from '../../../src/shared/worktree-name-suggestion'
7 changes: 5 additions & 2 deletions skill-guides/orchestration/references/placement-and-remote.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,15 @@ sharing unsafe.
ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json

# Stacked child worktree.
ORCA orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json
ORCA orchestration worker-start --task <task_id> --worktree new-child --agent codex --setup run --json

# Independent top-level worktree.
ORCA orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json
ORCA orchestration worker-start --task <task_id> --worktree new-top-level --agent codex --setup run --json
```

`--name` is optional: without it Orca picks a name as it does for an unnamed
workspace, and the start output names the workspace it created.

Current and exact existing workspaces create a fresh terminal unless
`--terminal` is explicit. Folder workspaces are first-class; do not invoke Git
or require worktree lineage when the selected workspace is a folder.
Expand Down
7 changes: 5 additions & 2 deletions src/cli/bundled-skill-guides.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2846,12 +2846,15 @@ const ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN = [
"ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json",
"",
"# Stacked child worktree.",
"ORCA orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json",
"ORCA orchestration worker-start --task <task_id> --worktree new-child --agent codex --setup run --json",
"",
"# Independent top-level worktree.",
"ORCA orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json",
"ORCA orchestration worker-start --task <task_id> --worktree new-top-level --agent codex --setup run --json",
"```",
"",
"`--name` is optional: without it Orca picks a name as it does for an unnamed",
"workspace, and the start output names the workspace it created.",
"",
"Current and exact existing workspaces create a fresh terminal unless",
"`--terminal` is explicit. Folder workspaces are first-class; do not invoke Git",
"or require worktree lineage when the selected workspace is a folder.",
Expand Down
15 changes: 15 additions & 0 deletions src/cli/handlers/orchestration/worker-output.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,21 @@ describe('worker-start plain formatting', () => {
})
).toBe('Worker ctx_ready [ready] for task_1')
})

it('names the workspace a start created', () => {
expect(
formatWorkerStart({
taskId: 'task_1',
dispatchId: 'ctx_ready',
state: 'ready',
effects: [
{ kind: 'worktree', action: 'created_child', id: 'repo::/w/otter', name: 'otter' },
{ kind: 'terminal', id: 'term_worker' }
],
residualResources: []
})
).toBe('Worker ctx_ready [ready] for task_1\nCreated workspace: otter')
})
})

describe('worker-read plain formatting', () => {
Expand Down
21 changes: 21 additions & 0 deletions src/cli/handlers/orchestration/worker-output.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ export function formatWorkerStart(value: WorkerStartReceipt): string {
if (value.mode) {
lines.push(value.mode.detail)
}
const workspace = createdWorkspaceName(value.effects)
if (workspace) {
lines.push(`Created workspace: ${workspace}`)
}
if (value.lastError) {
lines.push(`${value.failedStage ?? 'start'}: ${value.lastError}`)
} else if (value.warning) {
Expand All @@ -46,6 +50,23 @@ export function formatWorkerStart(value: WorkerStartReceipt): string {
return lines.join('\n')
}

/** Only a created worktree's effect carries a name; older hosts omit it. */
function createdWorkspaceName(effects: unknown[] | undefined): string | undefined {
for (const effect of effects ?? []) {
if (
typeof effect === 'object' &&
effect !== null &&
'kind' in effect &&
effect.kind === 'worktree' &&
'name' in effect &&
typeof effect.name === 'string'
) {
return effect.name
}
}
return undefined
}

export function formatWorkerRead(
value: OrchestrationWorkerReadResult | LegacyWorkerReadResult
): string {
Expand Down
1 change: 1 addition & 0 deletions src/cli/specs/orchestration-worker-specs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ export const ORCHESTRATION_WORKER_COMMAND_SPECS: CommandSpec[] = [
'--agent takes an Orca agent id enabled on the worker server, such as claude, codex, cursor, antigravity, muse, zcode, opencode, or opencode2.',
'--model supports Claude, Codex, Cursor, Antigravity, and Muse opaque provider model ids; --effort requires --model. OMP accepts --model only; --effort is unsupported. Neither can combine with --terminal. OpenCode model selection requires an existing worktree, a verified execution-host CLI, and an available model; effort is unsupported. Other agents, including zcode, launch with the model from their own config.',
'New worktrees use agent-first creation and default --setup to run. Repository start-immediately runs setup beside the agent; wait-for-setup gates agent readiness and task input.',
'New worktrees without --name get the name Orca gives an unnamed workspace; the receipt names it. Servers older than this change still require --name.',
'Creation flags (--name, --repo, --base-branch, --display-name, --comment, --setup) are rejected for current/existing worktrees. Use exact --repo on the selected server; project/host convenience routing remains on worktree create.',
"How the worker runs follows the user's own setting for new agent tabs; there is no flag for it and no caller needs to ask. A dispatch the setting cannot apply to still starts, so the placement, agent, and launch options passed here are always the ones honoured.",
'Drive every worker the same way whichever way it was started: the same orchestration verbs, the same handle. Mail, dispatch, worker-show, worker-read and the whole lifecycle behave identically. The start receipt records which one ran, for operators and telemetry.',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import type { OrcaRuntimeService } from '../../../../orca-runtime'
import type { OrchestrationDb } from '../../../../orchestration/db'
import { WORKER_START_VOCABULARY } from '../../orchestration-worker-start-mode'
import type { WorkerSetupReceipt } from '../worker/worker-topology'
import { resolveWorkerWorktreeName } from '../worker/worker-worktree-creation'
import {
appendFederationSetupEffect,
appendFederationTerminalEffects,
Expand Down Expand Up @@ -59,10 +60,10 @@ export async function launchFederatedWorkerAgent(args: {
if (startupAgent === undefined) {
throw new Error(TERMINAL_ONLY_MESSAGE)
}
const { repo, name } = params
if (!repo || !name) {
const { repo } = params
if (!repo) {
// Validation refuses this before the attachment exists; this only narrows the types.
throw new Error('A remote new-top-level worktree requires --name and an explicit --repo.')
throw new Error('A remote new-top-level worktree requires an explicit --repo.')
}
db.recordRemoteAttachmentStage({
dispatchId: params.dispatchId,
Expand All @@ -71,7 +72,7 @@ export async function launchFederatedWorkerAgent(args: {
const setupDecision = params.setup ?? 'run'
const result = await runtime.createManagedWorktree({
repoSelector: repo,
name,
...(await resolveWorkerWorktreeName(runtime, repo, params.name)),
baseBranch: params.baseBranch,
displayName: params.displayName,
displayNameKind: params.displayNameKind,
Expand All @@ -91,7 +92,12 @@ export async function launchFederatedWorkerAgent(args: {
})
created = result.worktree
const terminalHandle = result.startupTerminal?.handle
effects.push({ kind: 'worktree', action: 'created_top_level', id: result.worktree.id })
effects.push({
kind: 'worktree',
action: 'created_top_level',
id: result.worktree.id,
name: result.worktree.displayName
})
const setup: WorkerSetupReceipt = {
requested: setupDecision,
effective: setupDecision,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ export type FederationEffect = {
action?: string
role?: string
id?: string
/** A created worktree's name. */
name?: string
state?: string
tabId?: string
leafId?: string
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ export function validateFederatedWorkerStartPlacement(
params: WorkerStartInput,
createsWorktree: boolean
): void {
if (createsWorktree && (!params.name || !params.repo)) {
if (createsWorktree && !params.repo) {
throw new OrchestrationError(
'invalid_argument',
'Remote new-top-level requires --name and an explicit --repo from remote discovery.'
'Remote new-top-level requires an explicit --repo from remote discovery.'
)
}
if (createsWorktree && params.terminal) {
Expand Down Expand Up @@ -68,9 +68,6 @@ export function prepareLocalWorkerStart(args: {
'--terminal cannot combine with new-worktree creation.'
)
}
if (createsWorktree && !params.name) {
throw new OrchestrationError('invalid_argument', 'New worktrees require --name.')
}
if (!createsWorktree && (params.name || params.repo || params.baseBranch || params.setup)) {
throw new OrchestrationError(
'invalid_argument',
Expand All @@ -97,10 +94,10 @@ export function prepareFederationAttachmentWorkerStart(args: {
}): { agent: TuiAgent | undefined; launch: WorkerStartLaunch } {
const { params, createsWorktree, runtime } = args
assertWorkerLaunchPreferencesCreateTerminal(params)
if (createsWorktree && (!params.name || !params.repo)) {
if (createsWorktree && !params.repo) {
throw new OrchestrationError(
'invalid_argument',
'A remote new-top-level worktree requires --name and an explicit --repo.'
'A remote new-top-level worktree requires an explicit --repo.'
)
}
if (createsWorktree && params.terminal) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ export type WorkerEffect = {
action?: string
role?: string
id?: string
/** A created worktree's name, so the coordinator can tell the user where the worker runs. */
name?: string
state?: string
tabId?: string
leafId?: string
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
import { describe, expect, it, vi } from 'vitest'
import { MARINE_CREATURES } from '../../../../../../shared/marine-creatures'
import { isAutoGeneratedCreatureBranchName } from '../../../../../../shared/branch-name-from-work'
import {
creatureNameAtTier,
creatureNameTier
} from '../../../../../../shared/worktree/retired-name-registry'
import { createWorkerWorktree, resolveWorkerWorktreeName } from './worker-worktree-creation'
import type { WorkerEffect } from './worker-topology'

const pool = MARINE_CREATURES.map((name) => name.toLowerCase())

function namingRuntime(livePaths: string[], retired: string[] = [], exhaustedTiers = 0) {
return {
listManagedWorktrees: vi.fn(async () => ({
worktrees: livePaths.map((path) => ({ path }))
})),
listRetiredWorktreeNames: vi.fn(async () => ({
retiredNamesByRepo: { repo: retired },
retiredNameTiersByRepo: { repo: exhaustedTiers }
}))
}
}

describe('resolveWorkerWorktreeName', () => {
it('keeps an explicit --name without generating one', async () => {
const runtime = namingRuntime([])
await expect(resolveWorkerWorktreeName(runtime, 'id:repo', 'billing-audit')).resolves.toEqual({
name: 'billing-audit'
})
expect(runtime.listManagedWorktrees).not.toHaveBeenCalled()
})

it('picks the one creature name no live or retired workspace holds', async () => {
const [free, ...taken] = pool
const half = Math.floor(taken.length / 2)
const runtime = namingRuntime(
taken.slice(0, half).map((name) => `/worktrees/other-repo/${name}`),
taken.slice(half)
)
await expect(resolveWorkerWorktreeName(runtime, 'id:repo', undefined)).resolves.toEqual({
name: free,
nameWasGenerated: true
})
expect(runtime.listRetiredWorktreeNames).toHaveBeenCalledWith('id:repo')
})

it('skips tiers the retired registry compacted as spent', async () => {
const result = await resolveWorkerWorktreeName(namingRuntime([], [], 2), 'id:repo', undefined)
expect(creatureNameTier(result.name)).toBe(3)
expect(isAutoGeneratedCreatureBranchName(result.name)).toBe(true)
})

it('moves to the next tier once every first-tier name is used', async () => {
const result = await resolveWorkerWorktreeName(namingRuntime([], pool), 'id:repo', undefined)
expect(pool.map((name) => creatureNameAtTier(name, 2))).toContain(result.name)
})
})

describe('createWorkerWorktree naming', () => {
async function create(name: string | undefined) {
const createManagedWorktree = vi.fn(async (_args: Record<string, unknown>) => ({
worktree: { id: 'repo::/worktrees/repo/otter', repoId: 'repo', displayName: 'otter' },
startupTerminal: { handle: 'term_worker' }
}))
const runtime = {
...namingRuntime([]),
createManagedWorktree,
listTerminals: vi.fn(async () => ({ terminals: [] }))
}
const effects: WorkerEffect[] = []
await createWorkerWorktree({
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: createWorkerWorktree reaches only the runtime methods faked above.
runtime: runtime as never,
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: createWorkerWorktree only records stages on the db.
db: { recordWorkerStage: vi.fn() } as never,
dispatchId: 'ctx_1',
requestedWorktree: 'new-child',
target: { repoSelector: 'id:repo', parentWorktreeId: 'repo::/repo' },
params: { name, from: 'term_coord' },
agent: 'codex',
withAgentTerminal: true,
effects
})
return { request: createManagedWorktree.mock.calls[0][0], effects }
}

it('creates a generated name the first-work rename may replace, and names it in effects', async () => {
const { request, effects } = await create(undefined)
expect(request.nameWasGenerated).toBe(true)
expect(isAutoGeneratedCreatureBranchName(String(request.name))).toBe(true)
expect(effects[0]).toEqual({
kind: 'worktree',
action: 'created_child',
id: 'repo::/worktrees/repo/otter',
name: 'otter'
})
})

it('passes an explicit --name through as a user name', async () => {
const { request } = await create('billing-audit')
expect(request.name).toBe('billing-audit')
expect(request).not.toHaveProperty('nameWasGenerated')
})
})
Loading
Loading