You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(orchestration): worker-start new worktrees default to a generated name - #35363
When a coordinating agent starts a worker in a new workspace, it no longer has to invent a name. Orca names the workspace the same way it does when you create one without typing a name, and renames it from the work once the worker starts, just like a workspace you made yourself.
What Changed
Before: orca orchestration worker-start --worktree new-child (or new-top-level) without --name failed with "New worktrees require --name." Coordinating agents often hit this on their first start and had to retry.
After:
With no --name, the runtime picks a sea-creature name with the same picker the new-workspace composer uses: it skips names already used by live workspaces and names retired by deleted workspaces in that project, and moves to the next tier when a tier is used up. The create request is marked as a generated name, so the existing create path applies the retired-name registry and collision fallback, and the existing "rename branch from work" flow renames the branch and title after the worker's first turn (when that setting is on). An explicit --name is passed through unchanged.
The worktree entry in the start receipt's effects now carries the created workspace's name, and the plain-text output prints Created workspace: <name>, so the coordinator can tell the user where the worker is running.
Connected-server starts (--on <server> --worktree new-top-level) no longer need --name either; the name is picked on the server that creates the worktree.
The composer's picker moved from the mobile app into the shared module so desktop runtime and mobile use one implementation. Mobile behavior is unchanged.
The orchestration placement guide and the worker-start help no longer show --name as needed.
Why
The name is generated on the host that creates the worktree, so it is checked against that host's live and retired names, including SSH projects. Reusing the composer's picker and marking the request as a generated name means the retirement registry and first-work rename apply without any new naming logic. The other option was to have the CLI make up a name before sending the request. That would not see the host's retired names and would still fail against an older server.
Older runtimes: a new CLI talking to an older runtime or connected server gets that runtime's existing clear error asking for --name, so nothing breaks. Folder projects are still refused with the existing folder message, which now appears instead of the --name error.
Linked Issue
N/A (maintainer change)
Visual Proof
N/A: CLI and runtime behavior only. The new receipt line is covered by a formatter test.
Testing
Automated tests added/updated
worker-worktree-creation.test.ts: no name gets a generated creature name that avoids live names in any project and retired names; spent tiers are skipped; an explicit name is passed through as typed; the receipt's worktree effect names the workspace.
runtime-local-worktree-create.test.ts: a workspace created from the worker's name request is marked Orca-created and is renamed (branch and title) by the real first-work rename flow.
worker-output.test.ts: plain output prints the created workspace.
Ran pnpm tc, typecheck:ci, mobile typecheck, oxlint (type-aware + anti-slop), check:code-quality:changed, and the pr.yml static check scripts locally. Tested on macOS.
Review
Agent skill upstream boundary
Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.
Notes
Two nameless starts launched at the same instant can pick the same name. That is the same race two composer creates have. If one create has already landed, the other falls back to the next tier. If both are mid-create, one can fail and the coordinator retries it. I did not add a reservation for this.
Checklist
This PR is small and focused
I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
Before/after screenshots or videos attached for UI changes, or N/A with reason
Self-reviewed for correctness, security, and performance
Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)
[Medium impact] The PR appears safe to merge; no actionable issues were found.
Summary
New orchestration worktrees can start without --name. The creating host picks a creature name and marks it as generated.
Nameless worker starts now get a name from the host creating the workspace.
Worker-start output now names the created workspace.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Worker start] --> B{Explicit name?}
B -->|Yes| E[Create worktree]
B -->|No| C[Creating host reads live and retired names]
C --> D[Pick creature name and mark generated]
D --> E
E --> F[Existing collision and retirement checks]
F --> G[Receipt includes created workspace name]
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.
Walkthrough
Worker worktree creation now accepts an omitted name and generates one from existing and retired worktree names. Created worktree effects include the name. Worker-start output reports the created workspace, and the orchestration guides describe the optional --name argument.
Priority: Normal
Merge Risk: Low · up to 8d839
Concurrent nameless starts can occasionally collide, requiring one start to be retried. The change is otherwise mergeable with awareness of this race.
Pre-merge checks: 4 · 1
Failed checks: 1 warning
Check name
Status
Explanation
Resolution
Docstring Coverage
Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…
Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed checks: 4 passed
Check name
Status
Explanation
Title check
The title clearly and concisely describes the main change: worker-start now assigns generated names to new worktrees when --name is omitted.
Description check
The description is complete and aligned with the template. It explains the user-visible behavior, implementation, rationale, compatibility, testing, documentation updates, known race behavior, and che…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Full details: Description check
Explanation
The description is complete and aligned with the template. It explains the user-visible behavior, implementation, rationale, compatibility, testing, documentation updates, known race behavior, and checklist status. The maintainer-specific Linked Issue exception is addressed with N/A.
Full details: Docstring Coverage
Explanation
Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 10 functions across 13 files. (1 skipped: 1 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
Finishing Touches: 💡 1
📝 Generate docstrings: 💡
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ELI5
When a coordinating agent starts a worker in a new workspace, it no longer has to invent a name. Orca names the workspace the same way it does when you create one without typing a name, and renames it from the work once the worker starts, just like a workspace you made yourself.
What Changed
Before:
orca orchestration worker-start --worktree new-child(ornew-top-level) without--namefailed with "New worktrees require --name." Coordinating agents often hit this on their first start and had to retry.After:
--name, the runtime picks a sea-creature name with the same picker the new-workspace composer uses: it skips names already used by live workspaces and names retired by deleted workspaces in that project, and moves to the next tier when a tier is used up. The create request is marked as a generated name, so the existing create path applies the retired-name registry and collision fallback, and the existing "rename branch from work" flow renames the branch and title after the worker's first turn (when that setting is on). An explicit--nameis passed through unchanged.effectsnow carries the created workspace'sname, and the plain-text output printsCreated workspace: <name>, so the coordinator can tell the user where the worker is running.--on <server> --worktree new-top-level) no longer need--nameeither; the name is picked on the server that creates the worktree.worker-starthelp no longer show--nameas needed.Why
The name is generated on the host that creates the worktree, so it is checked against that host's live and retired names, including SSH projects. Reusing the composer's picker and marking the request as a generated name means the retirement registry and first-work rename apply without any new naming logic. The other option was to have the CLI make up a name before sending the request. That would not see the host's retired names and would still fail against an older server.
Older runtimes: a new CLI talking to an older runtime or connected server gets that runtime's existing clear error asking for
--name, so nothing breaks. Folder projects are still refused with the existing folder message, which now appears instead of the--nameerror.Linked Issue
N/A (maintainer change)
Visual Proof
N/A: CLI and runtime behavior only. The new receipt line is covered by a formatter test.
Testing
worker-worktree-creation.test.ts: no name gets a generated creature name that avoids live names in any project and retired names; spent tiers are skipped; an explicit name is passed through as typed; the receipt's worktree effect names the workspace.runtime-local-worktree-create.test.ts: a workspace created from the worker's name request is marked Orca-created and is renamed (branch and title) by the real first-work rename flow.worker-output.test.ts: plain output prints the created workspace.pnpm tc,typecheck:ci, mobile typecheck, oxlint (type-aware + anti-slop),check:code-quality:changed, and the pr.yml static check scripts locally. Tested on macOS.Review
Agent skill upstream boundary
Notes
Two nameless starts launched at the same instant can pick the same name. That is the same race two composer creates have. If one create has already landed, the other falls back to the next tier. If both are mid-create, one can fail and the coordinator retries it. I did not add a reservation for this.
Checklist
N/Awith reasonpnpm lint,pnpm typecheck,pnpm test, andpnpm buildpass (or CI will cover; local preferred)