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 <agent>`
  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

@@ -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 <selector> --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 "<agent>"` for a fresh agent in the current worktree. Use `worktree create --agent <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`.

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 <task-name> --command "codex" --json
+orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
+orca orchestration dispatch --task <task_id> --to <handle> --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 <task-name> --agent codex --json
@@ -118,7 +126,7 @@ orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
 orca orchestration dispatch --task <task_id> --to <handle> --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 <selector>`. `--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 <selector>`. `--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:<newWorktreeId> --json
+orca terminal create --worktree active --title login-css-worker --command "claude" --json
 orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
 orca orchestration task-create --spec "Fix the login button CSS" --json
 orca orchestration dispatch --task <task_id> --to <handle> --inject --json

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

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 <id|url|null> 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', () => {

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 <selector>] [--title <name>] [--command <text>] [--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'
     ]