[odmrs]

ELI5

The sidebar has a Sleep action that closes a workspace's terminals, browser tabs and agents to free memory and CPU. Scripts and agents had no way to do the same from the terminal. This adds orca worktree sleep.

What Changed

• Before: sleeping a workspace needed a right-click in the sidebar. The runtime already had a worktree.sleep RPC, but no CLI command called it.
• After: orca worktree sleep --worktree <selector> [--force] [--json] calls that RPC and takes the same selectors as worktree show.

Mechanism. This is CLI-only. There is no new RPC and no runtime change.

• Spec: specs/worktree-sleep.ts. It lives in its own file so core.ts stays under the max-lines budget.
• Handler: handlers/worktree-sleep.ts, wired into WORKTREE_HANDLERS and the handler manifest.
• Self-sleep guard. When the command runs from an Orca terminal (ORCA_WORKTREE_ID) against the local runtime, it resolves the target with worktree.show. If the target is the caller's own worktree, it refuses with invalid_argument, because sleeping it would kill the terminal running the command. --force skips the check, and remote targets skip it too.
• Older hosts. method_not_found maps to incompatible_runtime, the same way terminal close --all does.
• --force help text. The shared line used to read "Force worktree removal…", which was also wrong for project, serve and managed-server. It is now generic and points at each command's notes.
• Help, skill guide and docs. I updated the root help, skill-guides/orca-cli.md (and regenerated bundled-skill-guides.ts) and the CLI docs. The notes say plainly that with a desktop window, success means the sleep was accepted. The renderer finishes it right after. Headless runtimes only succeed once every PTY is confirmed stopped.

Why

It lets automations and agents free a finished workspace's resources without touching the UI. #22571 asks for exactly this command shape.

I reused the existing RPC instead of adding a new one. That keeps the change small and leaves the server-side sleep path to the ongoing main-process sleep work (#31564).

#30832 also proposes sleep plus a new worktree.wake RPC. This PR is narrower: sleep only, no runtime change, plus the self-sleep guard. If maintainers prefer #30832, I'm happy to close this or port the guard there.

Linked Issue

Fixes #22571

Visual Proof

N/A — CLI-only change with no UI change. The terminal output is under Testing.

Testing

I tested on macOS against Orca 1.4.237 (desktop window open), using the CLI built from this branch (pnpm build:cli, node out/cli/index.js). I made a throwaway worktree and ran sleep 3000 in a terminal there.

Case	Result
worktree sleep --worktree id:<…> --json from another worktree	ok: true, { worktreeId }; the sleep 3000 process is gone a few seconds later
Run again on the already-slept worktree, text output	sleep requested: <id>, exit 0 (no-op)
ORCA_WORKTREE_ID=<target> (caller inside the target)	invalid_argument, exit 1; the process keeps running
Same, with --force	sleeps; the process is gone
--worktree name:does-not-exist	standard selector_not_found with next steps

Automated: src/cli/index-worktree-sleep.test.ts covers the sleep call and output, another worktree from an Orca terminal, the self-sleep refusal, --force, and the method_not_found → incompatible_runtime mapping. Removing the guard makes the refusal test fail.

Local checks: pnpm lint, pnpm typecheck, the full src/cli suite (179 files), pnpm build:cli, generate-rpc-params-catalog --check, generate-bundled-skill-guides --check, oxfmt --check and the max-lines ratchet all pass. In the full pnpm test run, the only failures are daemon, shell-startup and native-chat tests outside src/cli, which fail the same way on a clean main checkout on this machine. pnpm build builds main, preload and renderer; only the mobile web step fails here, because I don't have the mobile workspace dependencies installed. CI should cover both.

Not tested by hand: Linux, Windows, SSH and paired remote hosts. The command only forwards a selector to an existing RPC, and the guard is skipped for remote clients.

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

AI Disclosure

Implemented with Claude (Opus 5.5) via Claude Code. I directed the change, and I reviewed and tested it myself.

Review

AI review summary:

• Security: no new RPC or permission. worktree.sleep keeps its workspace permission. The guard only reads ORCA_WORKTREE_ID, and only makes one read-only worktree.show call.
• Cross-platform: no paths, shells or process handling in the CLI code. The guard compares the runtime id that Orca itself puts in ORCA_WORKTREE_ID, so the format is identical on every platform.
• SSH/remote: selectors and --environment/--pairing-code behave as in worktree show. The guard is skipped for remote clients, because a local terminal can't belong to a remote host's worktree. Older hosts get incompatible_runtime.
• Mobile: N/A. The phone already sleeps through the same RPC.
• Performance: one extra worktree.show call, only when the command runs inside an Orca terminal without --force.
• Backwards compatibility: additive command. The only other change is the shared --force help string.

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

I checked security, cross-platform, remote SSH, mobile, backwards compatibility and performance; details are in the Review section above.

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) — see Testing for the environment-only failures

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3c06db61-b731-4fe1-9545-a8ecdc76c66c

📥 Commits

Reviewing files that changed from the base of the PR and between 43312a4 and 697bf87.

📒 Files selected for processing: 1

• src/cli/specs/core.ts

🚧 Files skipped from review as they are similar to previous changes: 1

• src/cli/specs/core.ts

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

The CLI adds orca worktree sleep with worktree selection, --force, and JSON output. The handler prevents sleeping the invoking local worktree unless --force is set, requests sleep, and reports the result. It reports incompatible_runtime when the runtime does not provide worktree.sleep. Tests and documentation cover the command and its behavior.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 697bf

No merge-blocking issue is established for this change; it is ready for normal merge checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 9 files.	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 identifies the main change: adding the worktree sleep CLI command.
Description check		The description covers the required sections, user-facing behavior, implementation details, rationale, linked issue, testing, limitations, AI disclosure, review considerations, and checklist status. I…
Linked Issues check		Issue #22571 requests a scriptable worktree sleep command that uses the existing sleep capability. WORKTREE_SLEEP_COMMAND_SPEC registers `orca worktree sleep --worktree [--force] [--json]…
Out of Scope Changes check		The changes support issue #22571. They add the CLI specification, handler registration, manifest entry, tests, help, skill-guide content, and CLI documentation. The generic --force help text is rela…

Full details: Description check

Explanation

The description covers the required sections, user-facing behavior, implementation details, rationale, linked issue, testing, limitations, AI disclosure, review considerations, and checklist status. It also explains the reported environment-specific test and build failures.

Full details: Linked Issues check

Explanation

Issue #22571 requests a scriptable worktree sleep command that uses the existing sleep capability. WORKTREE_SLEEP_COMMAND_SPEC registers orca worktree sleep --worktree <selector> [--force] [--json]. worktreeSleepHandler calls worktree.sleep, protects the local caller worktree unless --force is set, and maps method_not_found to incompatible_runtime. The added test covers command output, sleep requests, the self-sleep guard, --force, and the compatibility error. Help and documentation describe the command.

Full details: Out of Scope Changes check

Explanation

The changes support issue #22571. They add the CLI specification, handler registration, manifest entry, tests, help, skill-guide content, and CLI documentation. The generic --force help text is related because the new command uses the flag and the previous text described worktree removal. No new RPC or runtime feature is included.

• 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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: a721b25b-6fec-4abf-be4d-74570cd2c3df

📥 Commits

Reviewing files that changed from the base of the PR and between b128cbb and 43312a4.

📒 Files selected for processing: 13

• docs/site/content/docs/cli/overview.mdx
• docs/site/content/docs/cli/reference.mdx
• skill-guides/orca-cli.md
• src/cli/bundled-skill-guides.ts
• src/cli/flag-help-text.ts
• src/cli/handler-group-manifest.ts
• src/cli/handlers/worktree-sleep.ts
• src/cli/handlers/worktree.ts
• src/cli/index-worktree-sleep.test.ts
• src/cli/root-help-text-primary.ts
• src/cli/root-help-text-secondary.ts
• src/cli/specs/core.ts
• src/cli/specs/worktree-sleep.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.