[nwparker]

	Files	Added	Deleted	Net
Test	1	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​76	0	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​76
Prod	9	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​84	$\color{#cf222e}{\Huge{\mathbf{−}}}$​33	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​51

ELI5

Scripts can now choose whether a project's worktrees created outside Orca are shown, using the same setting as the app.

What Changed

Before, orca repo set was unknown and scripts had to open the GUI to change this setting. After:

orca repo set --repo path:/path/to/repo --external-worktree-visibility show
orca repo set --repo path:/path/to/repo --external-worktree-visibility hide
orca repo set --repo path:/path/to/repo --external-worktree-visibility inherit

The CLI validates the value and calls existing repo.update with only externalWorktreeVisibility; inherit sends null to clear the override. Repo selectors pass through unchanged. Root and command help and the generated CLI guide include the command. Existing repo specs move into their own module to stay under the file-size limit.

Why

Tooling that uses plain git worktree add can configure visibility without opening project settings. Reusing the existing setting and update method keeps the same persistence and visibility rules, with no new preferences or runtime changes.

Linked Issue

Fixes #22898

Visual Proof

Captured through CDP from a hidden macOS Orca instance with disposable home/profile and a real Git repo. One worktree is shown individually; the scripted worktree starts hidden. The after sidebar was refreshed by reopening the existing Non-Orca worktrees panel; the CLI list and GUI setting update immediately, but the existing sidebar cache needs a refetch.

Before: scripted-agent is hidden.

After show: scripted-agent appears; the individual rule remains.

GUI setting after the CLI update:

Testing

• I manually tested these changes locally
• Automated tests added/updated

macOS acceptance: create a disposable repo and two plain Git worktrees, register it through repo add, show one worktree individually, and run the three commands above. show lists all three checkouts; hide lists only the main and individually shown checkout. inherit clears the stored override and follows both global Hide and Show. Comparing repo results confirms only the visibility field changes; an invalid value fails before mutation. A public CLI terminal launch by the scripted worktree's path also succeeds.

ORCA_BACKGROUND_LAUNCH=1 pnpm test src/cli/handlers/repo-visibility.test.ts src/cli/handler-group-manifest.test.ts src/cli/skill-guide-cli-parity.test.ts src/cli/specs/bundled-guide-flags.test.ts — 22 passed. CLI typecheck/build, scoped oxlint, formatting, changed-code-quality, generated-guide verification, and git diff --check passed. The hidden dev app rebuilt main/preload successfully.

Combined CLI integration with the reviewed commits for #22714, #24747, and #24755 passed 119 tests across nine files, CLI typecheck, and regenerated-guide verification. The check covered command discovery, parsing, returned results, shared types, and guides; temporary peer changes were removed and this PR remains independent.

AI Disclosure

Codex-assisted implementation, independently reviewed and verified through public CLI and hidden CDP.

Review

Independent read-only review found no issues at 47037817d82229a1959a01990c868f1d1e0b64e7, including validation, selector forwarding, existing spec preservation, generated-guide scope, and persistence reuse.

Current-head CI is pending static analysis and typecheck. Fresh CodeRabbit review is blocked by the shared quota, Cursor Bugbot is disabled for this repository, and Pullfrog is still running; no actionable bot comments are outstanding.

Agent skill upstream boundary

• Not applicable; no upstream skill-installer material copied.

Notes

Credit to @KAPUIST's recent #23025 for the local CLI setter approach; included as co-author. This separate PR adapts that local material to the issue's repo set spelling and does not adopt or modify the mixed PR's cross-host changes.

Merge risk is low: only CLI registration, validation, help, docs, and tests change. No new user-facing tradeoffs are expected; existing per-worktree/source rules and sidebar refresh behavior remain. Native smoke checks passed on macOS, Linux, and Windows; Linux and Windows desktop acceptance was not run; SSH/remote behavior is unchanged and untested. No mobile, global-settings, hook, or selector-diagnostic changes.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, before/after, mechanism, and alternatives)
• Before/after screenshots attached
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered
• Scoped lint, CLI typecheck/build, and tests pass; full checks are covered by CI

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (1)

AGENTS.md — auto-discovered

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: abb590d5-d90a-437f-854c-122a4b58ec1d

📥 Commits

Reviewing files that changed from the base of the PR and between 2fc517c and 77d5bd8.

📒 Files selected for processing (10)

• 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/repo-visibility.test.ts
• src/cli/handlers/repo.ts
• src/cli/root-help-text-primary.ts
• src/cli/root-help-text-secondary.ts
• src/cli/specs/core.ts
• src/cli/specs/repo.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.

---

📝 Walkthrough

Walkthrough

The CLI adds orca repo set with a required repository selector and an --external-worktree-visibility option. It accepts show, hide, and inherit; the handler sends inherit to repo.update as null. Command specifications, handler registration, help text, and the Worktrees guide document the command. Tests cover accepted values, repository selectors, output, and invalid arguments.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 77d5b

The new command can set repository worktree visibility or clear the override with inherit. No issue requiring a fix before merge was identified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 77d5b

The command changes one existing repository setting through the established update interface. No introduced security issue was established, but remote access enforcement and interrupted-save behavior remain incompletely verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Each invocation changes visibility policy for one selected repository in the chosen runtime. Repeated invocations could affect multiple repositories reachable with that runtime's authority. Repository/host authorization limits were not fully verified, so the selected repository is an operation scope rather than a proven security isolation boundary.

Trust Boundaries and Controls

• observed — Local requests use the existing socket or named-pipe transport and transmit the runtime metadata token. Server admission rejects missing or mismatched tokens, and the Unix socket is restricted to mode 0600. The new handler uses the same client boundary and selector-forwarding pattern as existing repository commands; paired-remote enforcement remains only partially inspected.
• observed — Visibility projection occurs after repo.update mutates state. It demonstrates response/display policy, not authorization of the mutation, and should not be treated as proof of repository access enforcement.

Resilience and Maintainability Implications

• observed — The CLI reuses the existing persistence scheduler rather than introducing a separate writer. This preserves one state owner, but interruption between in-memory mutation and disk saving can leave durability uncertain; that behavior belongs to the existing update path rather than a newly demonstrated PR defect.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	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 8 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding per-repository external worktree visibility configuration to the CLI.
Description check	✅ Passed	The description explains the change, reason, linked issue, visual proof, testing, AI use, and compatibility considerations. The Review section is blank, but the rest of the description is complete.
Linked Issues check	✅ Passed	#22898 requests a CLI setter for repo-level non-Orca worktree visibility. repo set validates show, hide, and inherit, preserves the supplied repo selector, and calls repo.update with only `e…
Out of Scope Changes check	✅ Passed	The reported changes support #22898: command handling, validation, tests, CLI registration, help, and guide updates. The repo-spec module split preserves existing command specs and supports the CLI ch…

Full details: Docstring Coverage

Explanation

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 8 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

• Autopilot · 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.}

[nwparker]

@cursor review

Please review the focused CLI parity change at 4703781: show/hide/inherit through the existing repo.update field, unchanged selector forwarding, and command/help/guide registration. No remote or cross-host persistence changes are included.

[cursor]

Skipping Bugbot: Bugbot is disabled for this repository. Visit the Bugbot dashboard to update your settings.

[nwparker]

@coderabbitai review

Please review current head 4703781 after the stated review-limit reset. This is the focused local CLI parity entry point and guide registration; existing runtime persistence is unchanged.

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nwparker]

@coderabbitai review

Please review current head 4703781 after the stated review-limit reset. This is the focused local CLI parity entry point and guide registration; existing runtime persistence is unchanged.

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[pullfrog]

✅ No new issues found.

Reviewed changes

• New orca repo set command — reads --repo and required --external-worktree-visibility show|hide|inherit, rejects any other value before I/O, and forwards to the existing repo.update RPC with updates: { externalWorktreeVisibility } (inherit → null clear sentinel). Selectors pass through unchanged.
• Repo specs extracted — the five existing repo command specs move to src/cli/specs/repo.ts (spread back into CORE_COMMAND_SPECS), with the new repo set spec added.
• Discovery, help, docs — handler-group-manifest registers repo set; FLAG_HELP_TEXT, both root-help arrays, and skill-guides/orca-cli.md document it; the generated bundled-skill-guides.ts verifies current.
• Tests — repo-visibility.test.ts pins selector pass-through (id:/name: with spaces/path: incl. a Windows path), the inherit → null mapping, exact single repo.update call shape, and five pre-runtime validation failures.

I traced the full path CLI → RepoUpdate zod schema → RuntimeRepositorySettingsController.update → updateRepo persistence. The 'show'|'hide' enum is enforced again at the RPC boundary, null survives omitUndefined to clear the override exactly as the GUI's "Use global" does, and updateRepo bumps the local worktree scan generation so the issue's core worktree list / terminal create flows see the change. The author already documents that the running GUI sidebar needs a manual refetch; that is a pre-existing GUI-side refresh, not a regression introduced here.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[nwparker]

Final merge review at 47037817d82229a1959a01990c868f1d1e0b64e7: the complete changed source matches the independently reviewed commit, and the documented required repository checks pass: detect changes and check repository guards, verify.

Pass show/hide/inherit to the existing repository visibility update.

Merge risk and retained limits: Low: CLI extension through existing workspace-visibility RPC.

Related proposals/changes: #23025. The contributor proposal additionally changes execution-host persistence; that extra behavior is not assumed superseded by this CLI change.

Contributor authors and existing co-author credit will be preserved explicitly in the squash commit.

[nwparker]

Final review of conflict repair at 77d5bd87a0e609e5372b249cc50ff7dcc3867569:

repo set --external-worktree-visibility show|hide|inherit uses the existing repo settings update. Show and hide set the repo default; inherit clears its override and follows the global default. Existing per-worktree visibility rules retain priority. Invalid or missing values fail before RPC, and the update preserves unrelated metadata.

The repair retains all five moved repo command definitions and every earlier command field. It preserves #20036's linked-PR/GitLab flags and #22714's read/unread controls, plus the complete generated guides. Independent review binds all ten feature files to the actual fresh-main merge and confirms every other path is retained from that main revision.

All 157 fresh focused tests pass on the final source, along with generator, format, ordinary lint, and the full changed-code-quality gate including typed analysis. Canonical CI also passes full typecheck, static analysis, five test shards, Linux and Windows packaging, and Linux/Windows/macOS native smoke checks. Required checks for this exact published head: detect changes and check repository guards, verify.

Risk is low: optional CLI input to an existing setter. Source review covers persistence and precedence; mocked-runtime CLI tests do not prove a live sidebar update or native platform behavior. The isolated local typecheck limitation is recorded; canonical new-head CI is the merge gate.

KAPUIST's adapted local setter from #23025 and Neil's work will retain explicit co-author credit in the squash commit. #23025 remains open because its additional execution-host persistence behavior is outside this replacement.