Skip to content

feat(T14500): launch guarded Claude leads inside Orca terminals - #2829

Open
kryptobaseddev wants to merge 3 commits into
mainfrom
task/T14500
Open

kryptobaseddev wants to merge 3 commits into
mainfrom
task/T14500

Conversation

@kryptobaseddev

@kryptobaseddev kryptobaseddev commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Inside a local POSIX Orca session, cleo orchestrate lead now opens a Claude Code terminal using the native provider's production guard builder. The launch carries the denied/allowed tools, permission mode, empty setting sources, strict MCP file, settings hooks and allocated session unchanged. A private first-turn gate waits for the exact local runtime/workspace, visible terminal, fresh UI navigation and matching connected terminal, supervisor PID, mailbox admission and persisted PID. exec preserves that PID; the result supplies the exact terminal handle for supervision.

Orca refusals propagate their code, message, fix and nonzero CLI exit instead of becoming success:true with a failed status. Environment/workspace and startup refusals precede mailbox admission; failure after admission releases it. Known newly created terminals are closed. Lost create receipts never trigger a retry or a guessed close: deleting the private gate aborts that shell promptly. Partial Orca context hints without a terminal handle refuse loudly with a repair instruction; the native route remains available outside Orca. Inside Orca, --detached returns while --print runs in a visible terminal (focused to prove UI adoption), with mbx retained as its owner channel.

Refs: T14500 AC1,AC2

AC1 evidence:

  • The actual production preparation in lead-mcp.test.ts inspects argv, real --settings, strict runner/user-mbx configuration, provider session id and CLEO identity for both modes. It also proves coded refusals survive the adapter and generic setup failures receive actionable nonzero refusals.
  • The offline transport fixture in orca-execution.test.ts executes only an inert recording binary. It proves argument/environment quoting, awaited admission before first turn, early Windows/missing-handle/remote-workspace refusal, visibility loss after create, failed navigation, PID mismatch, disconnected terminals, changed runtime, lost receipt shutdown, exact-handle cleanup and reported unverified cleanup.
  • Core fixtures prove preflight refusals take no mailbox claim, post-admission refusal releases it, and successful leads retain their own session/record. CLI fixtures prove each refusal is success:false, preserves code/message/fix and sets exit status 63.
  • Inert local Orca probes confirmed that create returns surface:visible, show omits surface, switch returns an exact focus receipt with navigated:true, and close returns ptyKilled:true. The implementation checks fresh navigation and matching re-show identity, and rejects an explicitly hidden re-show. These probes launched no model or worker and their terminals were closed.
  • The opt-in live harness check remains unrun, as dispatched. Use a CI-built CLI from this PR in a fresh isolated project registered in local Orca, with a disposable verification-only epic, no ready workers and orchestrate.leadWorker.v1 enabled. Run cleo orchestrate lead <disposable-epic> --adapter claude-code. Capture data.leadTerminal and data.lead; inspect the returned handle with orca terminal show --terminal <handle> --json and orca terminal read --terminal <handle> --screen --json, and its PID with ps -p <pid> -o command=. Verify the denied/allowed tools, Manual permission mode, empty setting sources, strict MCP, --settings, provider session id, actual tool/server inventory and an owner question in that terminal. The fixture preserves pre-turn settings/MCP contents; SessionStart removes the MCP file. End the disposable session and confirm its claim/mailbox release. Do not use or interrupt the dogfood lead. Attach this evidence before AC1 closure.

AC2 evidence:

  • Unsupported Orca harnesses still refuse before querying the host or taking mailbox admission. Explicit backend worker preflight/start still refuses lead launches for every worker harness.
  • Windows, missing/partial identity, remote or mismatched workspaces, missing terminal capabilities, hidden/disconnected owner channels, failed navigation/PID proof and unsupported account placement fail closed. The lead path never queries account inventory or uses worker-start.

Validation on head d9d4872d336279b3c9d7cb6c2a098752fb87e67c (single files through cleo run --wait --class test -- pnpm exec vitest run <file>):

  • packages/adapters/src/__tests__/orca-execution.test.ts: 94 passed.
  • packages/adapters/src/providers/claude-code/__tests__/lead-mcp.test.ts: 21 passed.
  • packages/core/src/orchestrate/__tests__/lead.test.ts: 28 passed, with --config temp/vitest.lead-local.ts.
  • packages/cleo/src/cli/commands/__tests__/orchestrate-orca-routing.test.ts: 30 passed, with --config temp/vitest.orca-cli-local.ts.
  • The ignored local configs add exact bare-package source aliases for this unbuilt checkout; they do not mock package implementations. Required CI validates the built packages and full checks.
  • Changed-file Biome, diff whitespace, skills manifest/commands/coverage, contracts purity/subpaths and sync-invariant gates passed. The canonical changeset parser accepts the native task metadata. Local forge-ts filters exposed existing repository-wide debt; CI documentation coverage passed on the current head.
  • NEXUS impact is UNKNOWN because static coverage is partial; source callers were inspected. Imports preserve the contracts port, with no core-to-adapters runtime dependency or new package dependency. Process transport stays in adapters, orchestration in core and shared types in contracts per AGENTS.md.

Current-head CI: Linux/macOS builds and build verification, packed artifacts, full lint and typecheck, documentation coverage, Repo Lints, Post-build Checks and release readiness passed. All eight Ubuntu unit-test shards passed. macOS shards 1, 2 and 4 passed; shard 3 failed in the unchanged brain-search-readonly.test.ts (missing/stale FTS setup waits 1008–1430 ms under a held write lock, including the automatic rerun). The failure stack is confined to memory/brain-search and its existing test; this PR changes neither that path nor store code. Follow-up T14509 is filed under the existing epic T12956. CI failure log. The foreground CI watch finished with exit 1. The CI aggregate is red from that test dependency; cleo/merge-close is red because AC1 and AC2 have no independent verdict on this head.

Skipped additional harnesses and profile/plugin APIs. The unrelated BRAIN CI failure, live check and independent verdicts on the current head are unresolved; this partial-delivery PR intentionally does not close T14500.

CI check states captured after the foreground watch on this head:

Check Result
Build & Verify (macos-latest) success
Build & Verify (ubuntu-latest) success
Build (macos-latest) success
Build (ubuntu-latest) success
CI failure
Changeset Lint (T13281) success
Contracts Dep Lint success
Core Bundle Budget (T14257) success
Detect Changes success
Documentation Coverage (forge-ts) success
Flaky Quarantine Budget (T14257) success
Flaky Test Quarantine (T13145) skipped
Lint & Format success
PR names its tasks success
Packed CLI and Studio Artifact success
Post-build Checks success
Release Pipeline Matrix skipped
Release Readiness Preflight success
Repo Lints success
Scripts Tests skipped
Skills Depth Check / progressive-disclosure-depth success
Type Check success
Unit Tests (macos-latest, shard 1) success
Unit Tests (macos-latest, shard 2) success
Unit Tests (macos-latest, shard 3) failure
Unit Tests (macos-latest, shard 4) success
Unit Tests (ubuntu-latest, shard 1) success
Unit Tests (ubuntu-latest, shard 2) success
Unit Tests (ubuntu-latest, shard 3) success
Unit Tests (ubuntu-latest, shard 4) success
Unit Tests (ubuntu-latest, shard 5) success
Unit Tests (ubuntu-latest, shard 6) success
Unit Tests (ubuntu-latest, shard 7) success
Unit Tests (ubuntu-latest, shard 8) success
Worktree NAPI Prebuild Gate (T11127) / gate success
Worktree NAPI Prebuild Gate (T11127) / matrix.triple skipped
Worktree NAPI Prebuild Gate (T11127) / native source hash success
cant-napi build skipped
cleo-supervisor smoke skipped
cleo/merge-close failure

@github-actions github-actions Bot added the macos label Nov 12, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant