From e3ffdbfa3afda8fde522281a7b4a57b6d08d204f Mon Sep 17 00:00:00 2001 From: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:05:08 -0700 Subject: [PATCH] Clarify terminal vs worktree creation for fresh local agents (#5549) - Document and update the CLI help, specs, and tests to explicitly guide users toward `orca terminal create --worktree active --command ` to launch a fresh agent session in the current checkout. - Update orchestration and orca-cli skills to prefer active-worktree terminals when dependent on uncommitted files or active branch state, distinguishing them from separate worktree creation. --- skills/orca-cli/SKILL.md | 2 ++ skills/orchestration/SKILL.md | 17 ++++++++++++----- src/cli/help.ts | 6 ++++++ src/cli/index.test.ts | 29 +++++++++++++++++++++++++++++ src/cli/specs/core.ts | 5 ++++- 5 files changed, 53 insertions(+), 6 deletions(-) diff --git a/skills/orca-cli/SKILL.md b/skills/orca-cli/SKILL.md index 1b9b0425e..7c04adb37 100644 --- a/skills/orca-cli/SKILL.md +++ b/skills/orca-cli/SKILL.md @@ -89,6 +89,7 @@ orca worktree create --name task --run-hooks --json - `--agent`, `--activate`, and `--run-hooks` reveal the new worktree. Plain create stays in the background. - Let Orca choose setup terminal placement from repo settings, including tab vs split behavior. Do not manually create extra setup terminals. - If an older installed CLI rejects `--agent`, `--prompt`, or `--setup`, create the worktree normally, then run `orca terminal create --worktree --command "codex"` and `orca terminal send` if a prompt is needed. +- `worktree create` creates a new checkout/workspace. For a fresh agent in the current checkout, use `orca terminal create --worktree active --command "codex" --json`. ## Worktree Comments @@ -133,6 +134,7 @@ Terminal rules: - Use `terminal read` before `terminal send` unless the next input is obvious. - Use `terminal send` only for direct terminal input or one-off prompts where no task state, inbox, or reply tracking is needed. - For structured coordination, invoke the `orchestration` skill; it uses `orca orchestration ...` commands for messages, handoffs, task DAGs, dispatches, inbox/reply flows, and coordinator loops. +- Use `terminal create --worktree active --command ""` for a fresh agent in the current worktree. Use `worktree create --agent ` only for a separate checkout. - Use `terminal wait --for tui-idle` for agent CLIs such as Claude Code, Gemini, and Codex; always pass `--timeout-ms`. - Terminal handles are runtime-scoped. If Orca restarts or returns `terminal_handle_stale`, reacquire with `terminal list`. - For long output, use cursor reads. After a limited tail preview, page from `oldestCursor`; after a cursor read, continue with `nextCursor` while `limited` is true and `nextCursor !== latestCursor`. diff --git a/skills/orchestration/SKILL.md b/skills/orchestration/SKILL.md index 089cce6e9..82df82df6 100644 --- a/skills/orchestration/SKILL.md +++ b/skills/orchestration/SKILL.md @@ -109,7 +109,15 @@ Recovery only: `orca orchestration reset --tasks|--messages|--all --json` clears ## Worker Terminals -For tracked orchestration work, create the worker without a prompt, wait for idle, then dispatch with `--inject`: +Choose the worker location before creating a terminal. `Fresh worker` means a fresh agent session, not a new git worktree. If the task says current worktree only, depends on uncommitted files/artifacts, or must validate/PR the current branch, create the worker in the active worktree: + +```bash +orca terminal create --worktree active --title --command "codex" --json +orca terminal wait --terminal --for tui-idle --timeout-ms 60000 --json +orca orchestration dispatch --task --to --inject --json +``` + +Reuse an idle agent in the required worktree only if the prompt allows reuse; otherwise create a fresh terminal there. Use a new worktree only when explicitly requested or when independent isolated checkout state is intended: ```bash orca worktree create --name --agent codex --json @@ -118,7 +126,7 @@ orca terminal wait --terminal --for tui-idle --timeout-ms 60000 --json orca orchestration dispatch --task --to --inject --json ``` -Read the new worktree id from `worktree create`, then use `terminal list` to get the agent terminal handle. Omit `--repo` only when running inside an Orca-managed worktree; otherwise pass `--repo `. `--agent` reveals the new worktree and launches the selected agent in its first terminal, so do not create a separate startup terminal. Use `--setup run|skip|inherit` when setup behavior matters, and `--no-parent` for independent work. +For new-worktree workers, read the id from `worktree create`, then use `terminal list` to get the agent handle. Omit `--repo` only inside an Orca-managed worktree; otherwise pass `--repo `. `--agent` reveals the new worktree and launches the selected agent in its first terminal, so do not create a separate startup terminal. Do not run `worktree create` when the task must stay in the current worktree. Use `orca worktree create --prompt ...` or `orca terminal send ...` only for untracked/lightweight prompts. Those paths do not attach `taskId`/`dispatchId`; the worker should not send lifecycle messages unless the prompt supplies a live orchestration preamble. @@ -146,13 +154,12 @@ Wait for `tui-idle` before dispatching. Always pass `--timeout-ms`; real coding - If blocked before completion, use `ask`; use `escalation` only when ownership is valid and the coordinator must intervene. - Treat preambles inherited through terminal history or full handoffs as stale unless the current prompt explicitly keeps that coordinator in the loop. - Coordinators should use `task-list --ready` as external memory, dispatch parallel waves, and avoid dependency chains deeper than 3-4 steps. -- Prefer inter-worktree workers for parallel implementation; use split panes in one worktree only for complementary tasks that will not edit the same files. +- Prefer inter-worktree workers only for independent work that does not need current uncommitted state. When same-worktree work is required, create fresh terminals in that worktree and keep edit ownership clear. ## Example ```bash -orca worktree create --name login-css-worker --agent claude --json -orca terminal list --worktree id: --json +orca terminal create --worktree active --title login-css-worker --command "claude" --json orca terminal wait --terminal --for tui-idle --timeout-ms 60000 --json orca orchestration task-create --spec "Fix the login button CSS" --json orca orchestration dispatch --task --to --inject --json diff --git a/src/cli/help.ts b/src/cli/help.ts index 8becabf16..6c42337d2 100644 --- a/src/cli/help.ts +++ b/src/cli/help.ts @@ -254,6 +254,11 @@ Behavior: Remote runtime access can also be supplied with ORCA_PAIRING_CODE or ORCA_ENVIRONMENT. Use selectors for discovery and handles for repeated live terminal operations. +Agent Sessions And Worktrees: + \`worktree create --agent\` creates a new checkout/workspace with an agent. + To start a fresh agent in the current worktree, use: + orca terminal create --worktree active --command "codex" + Browser Workflow: 1. Create or navigate: orca tab create --url https://example.com orca goto --url https://example.com @@ -303,6 +308,7 @@ Examples: $ orca worktree ps --limit 10 $ orca file open-changed --mode diff $ orca file open src/App.tsx + $ orca terminal create --worktree active --command "codex" $ orca terminal list --worktree path:/Users/me/orca/workspaces/orca/cli-test-1 --json $ orca terminal send --terminal term_123 --text "hi" --enter $ orca terminal wait --terminal term_123 --for exit --timeout-ms 60000 --json diff --git a/src/cli/index.test.ts b/src/cli/index.test.ts index 093bceec0..e9e2592f6 100644 --- a/src/cli/index.test.ts +++ b/src/cli/index.test.ts @@ -153,6 +153,13 @@ describe('orca root help', () => { expect(logSpy.mock.calls[0][0]).toContain( 'project setup-delete Remove a project host setup' ) + expect(logSpy.mock.calls[0][0]).toContain('Agent Sessions And Worktrees:') + expect(logSpy.mock.calls[0][0]).toContain( + '`worktree create --agent` creates a new checkout/workspace with an agent.' + ) + expect(logSpy.mock.calls[0][0]).toContain( + 'orca terminal create --worktree active --command "codex"' + ) expect(callMock).not.toHaveBeenCalled() }) @@ -213,6 +220,28 @@ describe('orca root help', () => { expect(setHelp).toContain('--linear-issue Linked Linear issue identifier or URL') expect(callMock).not.toHaveBeenCalled() }) + + it('distinguishes new worktrees from fresh agent terminals in command help', async () => { + const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {}) + logSpy.mockClear() + + await main(['worktree', 'create', '--help'], '/tmp/repo') + + expect(String(logSpy.mock.calls[0][0])).toContain('This creates a new checkout/workspace') + expect(String(logSpy.mock.calls[0][0])).toContain( + 'orca terminal create --worktree active --command "codex"' + ) + + logSpy.mockClear() + await main(['terminal', 'create', '--help'], '/tmp/repo') + + const terminalHelp = String(logSpy.mock.calls[0][0]) + expect(terminalHelp).toContain('Use this, not worktree create') + expect(terminalHelp).toContain( + 'orca terminal create --worktree active --command "codex" --json' + ) + expect(callMock).not.toHaveBeenCalled() + }) }) describe('orca cli worktree awareness', () => { diff --git a/src/cli/specs/core.ts b/src/cli/specs/core.ts index 57d57249c..6ce508016 100644 --- a/src/cli/specs/core.ts +++ b/src/cli/specs/core.ts @@ -124,6 +124,7 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [ 'activate' ], notes: [ + 'This creates a new checkout/workspace. For a fresh agent in an existing worktree, use `orca terminal create --worktree active --command "codex"` instead.', 'By default, Orca records the new worktree as a child of the caller workspace when it can infer one from the Orca terminal or current directory.', 'If --repo is omitted, Orca infers the repo from the current Orca-managed worktree.', 'Use --project with --host to create on a ready project host setup without spelling the backing repo id.', @@ -239,10 +240,12 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [ 'orca terminal create [--worktree ] [--title ] [--command ] [--focus] [--json]', allowedFlags: [...GLOBAL_FLAGS, 'worktree', 'command', 'title', 'focus'], notes: [ - 'Creates a visible terminal tab without switching focus when possible; falls back to a background handle if the UI cannot adopt it. Pass --focus to switch to it.' + 'Creates a visible terminal tab without switching focus when possible; falls back to a background handle if the UI cannot adopt it. Pass --focus to switch to it.', + 'Use this, not worktree create, for a fresh agent in the current checkout.' ], examples: [ 'orca terminal create --json', + 'orca terminal create --worktree active --command "codex" --json', 'orca terminal create --worktree path:/projects/myapp --title "RUNNER" --command "opencode"', 'orca terminal create --worktree path:/projects/myapp --command "opencode" --focus' ]