fix(skills): gate orchestration to Orca terminals

[tmchow]

Summary

Codex sessions outside Orca were activating the globally installed orchestration skill. The skill now treats Orca-managed terminal identity as a prerequisite at both discovery and execution time: it declines use before any orca command when neither Orca identity variable is present, briefly explains why, and continues with the current harness's native coordination tools.

The gate accepts either ORCA_WORKTREE_ID or ORCA_TERMINAL_HANDLE so local, WSL, and SSH agent terminals remain supported. Repository location, an orca binary on PATH, and a reachable runtime no longer count as proof. The skill remains globally discoverable; this is a fail-closed instruction boundary rather than an authentication mechanism or catalog filter.

Screenshots

No visual change.

Testing

• pnpm lint — blocked by existing switch-exhaustiveness failures in native-chat-session-option-labels.ts and skill-freshness-group.tsx; neither file is changed by this PR.
• pnpm run typecheck
• pnpm test — 31,224 passed; three unrelated failures remain in agent-exec-handler.test.ts (inherited Git config environment) and ssh-system-transport.integration.test.ts (timeout).
• pnpm build
• Added regression coverage for both discovery and execution gates, the SSH fallback, the visible fallback reason, and rejection of ambient repo, PATH, and runtime signals.
• pnpm exec vitest run config/scripts/orchestration-skill-guidance.test.mjs (12/12)
• pnpm run verify:bundled-skill-guides

AI Review Report

The review traced the skill from its canonical guide through generated projections and checked Orca identity propagation across local, WSL, and SSH agent terminals. It flagged that an ORCA_WORKTREE_ID-only gate would reject valid SSH sessions when remote hooks omit worktree identity, so the final gate retains ORCA_TERMINAL_HANDLE as the fallback.

The review also challenged the boundary against non-Orca harnesses, stale or spoofed environment values, and cross-platform behavior. The result is intentionally defense in depth: the selection description and early execution gate prevent accidental use, while existing runtime and lifecycle validation remains authoritative. No shortcuts, paths, platform-specific code, UI, or Electron behavior changed.

Security Audit

This PR changes runtime agent instructions and generated skill metadata only. It adds no command execution, path handling, authentication, secret, dependency, IPC, or network code.

The environment values are availability markers, not authentication credentials. Setting them manually can influence skill selection but does not bypass Orca runtime reachability or orchestration ownership checks. No follow-up security work is required for this instruction-layer fix.

Notes

• Local, WSL, and SSH agent behavior was reviewed; the dual identity gate preserves SSH terminals that lack worktree identity.
• The skill remains globally installed and discoverable in other harnesses; compliant harnesses now get an explicit refusal and native-tool fallback when outside Orca.
• X: @Trevin

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: a3aa40f5-3a33-4fe1-8957-2828954b93b0

📥 Commits

Reviewing files that changed from the base of the PR and between d6c466d and e8b658d.

📒 Files selected for processing (4)

• config/scripts/orchestration-skill-guidance.test.mjs
• skill-guides/orchestration.md
• skills/orchestration/SKILL.md
• src/cli/bundled-skill-guides.ts

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

• config/scripts/orchestration-skill-guidance.test.mjs

---

📝 Walkthrough

Walkthrough

Updated orchestration guidance to require ORCA_WORKTREE_ID or ORCA_TERMINAL_HANDLE in an Orca-managed terminal, with fallback to native coordination tools when neither is set. Clarified tool boundaries and provenance verification, synchronized the bundled guide, and added a Vitest test covering the required wording and section ordering.

🚥 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%.	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 is concise and accurately summarizes the main change: gating orchestration to Orca-managed terminals.
Description check	✅ Passed	The description follows the template and covers summary, screenshots, testing, review, security, and notes with useful detail.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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