/download-grants` after fresh active-link
evaluation.
- [x] Generate a five-minute V4 signed GET URL for the exact immutable key and stored generation.
- [x] Set only response content type and safe attachment filename overrides.
- [x] Grant no list or write capability.
- [x] Return expected archive identity and byte count beside the grant for runtime verification.
- [x] Test revocation immediately blocks new grants while already issued URLs expire within five
minutes.
### Cloud tests
- [x] Test anonymous latest/pinned preview and download grants without an Authorization header.
- [x] Test missing, expired, revoked, and deleted shares all fail without disclosure.
- [x] Test authenticated owner management remains protected.
- [x] Test anonymous per-IP rate limiting without recording raw IP addresses.
- [x] Test the authenticated owner-only active-link inventory and ensure responses are not cached.
- [x] Test expired, reused, wrong-tenant, wrong-key, wrong-size, and wrong-hash uploads.
- [x] Test malformed, oversized, and resource-exhausting archives during finalization.
- [x] Test finalization semaphore saturation and retry behavior.
- [x] Test concurrent idempotent mutations and partial database/GCS failures.
- [x] Test tenant-scoped deduplication without cross-tenant timing or response disclosure. Orca
Cloud `ddbd4e2` proves identical archives use distinct tenant-hashed GCS keys and independent
PostgreSQL object identities.
- [x] Test quota and rate limits.
- [x] Test durable shares resolving intended latest and pinned immutable versions.
- [x] Test update, rollback, revocation, deletion, soft-delete recovery, and orphan reconciliation.
## 8. Implement desktop Cloud client and UX
### Cloud client
- [x] Make share resolution and share-scoped download-grant calls anonymous while keeping upload,
package/version management, share creation, revocation, and deletion authenticated.
- [x] Keep desktop contracts storage-provider-neutral.
- [x] Implement bounded progress, cancellation, retry, and idempotency behavior.
- [x] Redact signed policies, URLs, credentials, private paths, and package contents at creation.
### Share experience
- [x] Read and apply `docs/STYLEGUIDE.md`; use canonical CSS tokens and shadcn primitives.
- [x] Add **Share skill** to eligible installed and workspace skills.
- [x] Show name, description, author, file count, total size, scripts, executable files, and the
unlisted-link warning before upload.
- [x] Remove organization and selected-person audience controls from bearer-link publishing.
- [x] Accept optional release label and notes.
- [x] Package the exact previewed bytes and invalidate preview after source drift.
- [x] Show bounded upload and finalization progress with cancellation.
- [x] Return a copyable durable Orca URL after publication.
- [x] Remove access editing from the bearer-share workflow; keep version publishing, revoke, and
package deletion actions.
- [x] Make clear that unsharing blocks future installs but does not remove installed copies.
- [x] Add **Share skills**, **Install from link**, and installed-package **Manage** to the existing
Skills page header; expose active link copy/revocation in Settings → **Share Skills** so links
remain manageable even when the source was never a managed install.
- [x] Add selection mode whose selection survives search/filter changes and an explicit **Select
all results** action; never select all implicitly.
- [x] Keep the per-card share action as a one-skill bundle shortcut.
- [x] Disable ineligible skills with visible, screen-reader-linked reasons and block duplicate
skill names before review.
- [x] Review bundle name, skill/file/byte counts, script/executable warnings, expandable per-skill
details, unlisted-link behavior, and release notes.
- [x] Add Settings → **Share Skills** with artifact-like explanation and a route to the Skills page.
- [x] Show named preparation, upload, verification, and link-publication progress and return one
durable link for the bundle. Preparation uses **Preparing preview…**; publication advances
through **Uploading…**, **Verifying package…**, and **Publishing link…** before rendering the
single durable share URL. Cancellation reaches both upload and link publication.
### Install experience
- [x] Show description, version, digest, file summary, scripts, and executable files without
exposing internal publisher or organization identifiers.
- [x] Treat the package as code from its author and require an explicit install action.
- [x] Show current-machine global installation as the default.
- [x] Allow selection of connected machine, Git worktree, or plain folder workspace.
- [x] Show detected-agent coverage and canonical/provider topology before commit.
- [x] Show installed-state conflicts and explicit resolution choices.
- [x] Show phase progress without exposing grants or local private paths.
- [x] Render installed, unchanged, updated, partial, conflict, unsupported, cancelled, and failed
results with actionable recovery.
- [x] Add incomplete-coverage retry.
- [x] Open deep links in inspection mode without starting installation.
- [x] Show immutable version, skill count, scripts/executables, and release notes before selection;
V1 omits publisher identity from the public response and recipient UI.
- [x] Let the recipient select all or a subset, then choose local, paired runtime, WSL, or SSH and
global or workspace scope.
- [x] Preview new, unchanged, update, and conflict counts and resolve all per-skill conflicts in one
surface with **Keep local** as the default.
- [x] Label the primary action **Install N skills** and show aggregate progress plus current skill.
The destination-owned installer emits the current name and one-based bundle position. Local
installs forward it directly; paired and SSH hosts expose a capability-gated read-only
progress method, with phase-only fallback for mixed-version older hosts.
- [x] Group results into installed, unchanged, kept local, and failed; retry failed items only.
### Skills page lifecycle
- [x] Show installed package/version identity and update availability.
- [x] Offer clean update, modified-copy choices, prior-version rollback, and safe local removal.
- [x] Show whether a package came from Orca Cloud and its accessible version history.
- [x] Refresh discovery and installation state after local or remote actions.
- [x] Keep Cloud deletion, share revocation, and local removal clearly separate.
- [x] Add installed-bundle update, rollback, install-on-another-machine, inspect, and remove actions.
An active unlisted link opens the existing destination-aware installer for another machine.
- [x] Add shared-bundle copy-link, access, revoke, publish-version, and Cloud-delete actions. Exact
full-bundle version publishing reuses its package; ambiguous or partial managed-bundle
selections create a new package rather than mutating the wrong history.
- [x] Protect locally modified skills during bundle update and removal, including when only part of
a bundle remains managed. Keep-local is the default and destructive replacement is explicit.
### UX validation
- [x] Test keyboard shortcuts and labels with platform-aware macOS versus Windows/Linux behavior.
Skill sharing adds no modifier shortcut or shortcut label. Renderer coverage proves its
platform-neutral Escape navigation closes the page, leaves editable controls alone, and
remains owned by open dialogs; the compatibility scan found no hardcoded Meta-only binding,
macOS glyph, or platform-specific accelerator in the feature.
- [x] Test loading, error, cancellation, partial, conflict, and stale-preview states. Renderer
coverage includes scan loading, unavailable links, upload/install cancellation, partial
provider results, keep-local conflicts, capability loss after preview, and selection
reconciliation after a changed discovery scan; package tests cover source drift.
- [x] Test screen-reader names, focus order, progress announcements, and destructive confirmations.
The link field receives initial focus, Tab reaches the enabled primary action, Escape closes
the dialog, and machine, destination, WSL, and workspace selectors have programmatic names.
Upload progress exposes its phase and numeric value from 0 through publication; dialog-level
install tests announce authorization, installation, and current-skill position. Link revoke,
Cloud deletion, and local removal retain focus while switching to exact confirmation names.
- [x] Test long names, release notes, paths, organization names, and localized copy. Renderer
coverage exercises the 64-character bundle/skill-name boundary, a 10,000-character multiline
release note, long Unicode descriptions and organization IDs, long Windows-style skill paths,
and long workspace labels. Review copy wraps without losing full values, selectors constrain
labels to dialog width, and localization catalog, extraction, and coverage gates pass.
- [ ] Review trust and privacy wording with security and design.
## 9. Implement paired runtime installation
### Runtime and IPC surface
- [x] Register preview, install, update, and remove through runtime RPC and desktop IPC.
- [x] Add bounded `beginUpload`, `uploadChunk`, `commitUpload`, and `cancelUpload` methods.
- [x] Route every request to the runtime that owns the selected host and workspace.
- [x] Keep transfer separate from installation so grants, relayed chunks, and local files converge
at the validated ingress boundary.
- [x] Make upload sessions bounded by count, total bytes, idle lifetime, and chunk size.
- [x] Require monotonic offsets and idempotent acknowledged-chunk retry or full restart. A stable
transfer ID and host-acknowledged offset resume a lost begin response or interrupted upload.
- [x] Release staging bytes after cancellation, disconnect, timeout, and runtime restart. Active
idle timers remove abandoned archives even when no later upload arrives.
### Direct and client-mediated transfer
- [x] Prefer destination-runtime direct download when it can reach approved Orca Cloud storage.
- [x] Verify origin, redirects, generation, byte count, archive hash, and package digest on the
destination runtime.
- [x] Fall back to authenticated client-mediated chunk transfer when the host cannot reach GCS.
- [x] Never pass the desktop's local path as a remote package source.
- [x] Preserve the same inspection, transaction, provenance, and result behavior for both
transports.
- [x] Retry an idempotent install after a recoverable lost final response; rebuild a staged
transfer before retrying so a consumed upload is never reused.
- [x] Run the real Electron client against a paired desktop host for global, Git-worktree, and
plain-folder install, unchanged preview, inventory, and removal.
- [x] Run the same contract against a paired headless `orca serve` host for global and
Git-worktree install, unchanged preview, inventory, and removal.
- [x] Verify paired installation creates files only in host-owned roots and never falls back to the
client's isolated home.
- [ ] Test connection loss and resumption or restart behavior at every transfer boundary. Lost
final install-response convergence is covered for direct and staged paired-runtime paths;
deterministic cancellation now settles in-flight and queued paired calls across every
transport without leaking request admission or disrupting peers. Client-mediated transfer
also cancels and cleans a fully uploaded session when cancellation interrupts the commit RPC.
Restart and the remaining physical disconnect boundaries are still open.
### Mixed versions
- [x] Advertise additive bundle installation separately on paired and SSH hosts; never send the
bundle method to an older peer that lacks `skills.install.bundle.v1`.
- [x] Hide or disable remote install when `skills.install.v1` is absent.
- [x] Show a specific host-update-required message instead of attempting the RPC.
- [x] Test new client/old server and old client/new server.
- [x] Test optional-field omission in both directions.
- [x] Test a capability changing after preview but before execution.
- [x] Confirm older servers retain skill discovery and ignore no unknown stream opcode because none
is introduced.
## 10. Validate native Windows and WSL on `windows 2`
The connected Orca environment `windows 2` was reachable on 2026-08-11 and ran Orca `1.4.180` with
runtime ID `68b5e70d-baaf-40a5-b384-be09cc088880`. Validation used the isolated checkout
`C:\Users\neil\orca\skills-share-validation` and WSL distro `Ubuntu-24.04`; no production skill
directory was used for destructive failure injection.
The final combined run used workspace `skills-share-staging-validation` at
`C:\Users\neil\orca\workspaces\orca\skills-share-staging-validation` on branch
`OrcaWin/skills-share-staging-validation`. At `44d1266641`, native-Windows, real-process, and real
WSL coverage ran together: 67 files passed, 449 tests passed, and 17 intentional platform skips
remained. The Windows checkout was clean afterward, and WSL `/tmp` contained no remaining
`orca-skill-*` directory.
The 2026-08-11 host inventory recorded Windows 11 Pro `10.0.26200` build `26200`, x64, healthy
NTFS, Windows Defender, `LongPathsEnabled=0`, no Developer Mode registry grant, and an expected
`UnauthorizedAccessException` for an unprivileged directory-symlink probe. The current user home
is `C:\Users\neil` and the temp root is under that profile. WSL `2.7.11.0` uses kernel
`6.18.33.2-microsoft-standard-WSL2`; its only installed distro is the running default
`Ubuntu-24.04` WSL2 instance, with default user `neil`, home `/home/neil`, x86_64, and an ext-family
distro filesystem. No standalone Orca CLI is installed inside that distro; WSL skill operations
are owned by the connected Windows Orca runtime. A reproducible second-distro setup is
`wsl --install -d Debian --no-launch`, followed by first launch and an isolated Orca test user/home
record before the multi-distro gate.
At commit `1e2d2e806f`, the opt-in real-Windows workspace harness created an actual Git linked
worktree and a plain non-Git folder under owner-controlled temporary roots containing spaces and
non-ASCII characters. It installed globally and into both workspace kinds through host-owned IDs,
then removed the complete fixture tree. The full native `src/main/skills` slice passed 284 tests
with 21 intentional platform skips across 43 files, and the Node typecheck passed. Two discovery
fixtures uncovered by that run now use Windows junctions instead of privileged directory symlinks,
matching Orca's supported Windows placement topology.
At commit `cdafe43542`, the opt-in WSL semantics harness used real provider detection and installed
through the selected distro after converting UNC verification paths to distro-native paths. The
run passed both cases: Linux case sensitivity was preserved, regular files were `0600`, executable
files were `0700`, and the packaged script executed successfully. Existing real transaction
coverage also verified POSIX provider alias creation inside the distro.
At commit `92c8c6a4c6`, the exact portable package golden passed 26/26 focused tests from a native
WSL filesystem using an isolated user-owned Node 24 toolchain. The package digest and archive
SHA-256 matched macOS, native Windows, and Linux container results; the temporary WSL toolchain,
source snapshot, dependencies, and package-manager store were removed after the run.
Commit `97b831dd17` stabilized the physical Windows recovery harness by asserting parsed JSON paths
instead of shell-escaped text and by using a fake clock for upload ownership expiry. The combined
run then exposed a real WSL placement bug: native UNC `lstat` could miss an existing distro symlink,
so GNU `ln -s` followed it and created a self-link inside the canonical skill. Commit `44d1266641`
now asks the WSL filesystem whether the alias already targets the canonical path before native
existence checks and uses `ln -sT` for safe creation.
Only `Ubuntu-24.04` is installed on this host. A second-distro permutation is a post-launch
resilience follow-up, not a first-release gate. On 2026-08-12, the owner accepted the additional
live WSL-to-staging journey as duplicate evidence after the physical Windows/WSL matrix and native
Windows Cloud lifecycle passed; the remaining disconnect/cancellation boundaries stay recorded as
residual follow-up work.
### Host preparation
- [x] Confirm `windows 2` is saved and reachable through `orca environment list` and
`orca status --environment "windows 2" --json`.
- [x] Confirm the host provides both a native Git checkout and a native plain folder workspace.
- [x] Record Windows edition/build, architecture, filesystem type, long-path policy, current user
home, temp root, antivirus status, and developer-mode/symlink policy without collecting
secrets.
- [x] Discover installed WSL version and distros, each distro's running state, default user, home,
filesystem, and Orca host support.
- [x] Ensure at least two WSL distros are available or record a reproducible second-distro setup
for the multi-distro test.
- [x] Create isolated test skills and destination roots under explicit test workspaces; never use
production user skill directories for destructive failure injection.
- [x] Record exact Orca client/server versions and capabilities with each test run.
### Native Windows package and destination tests
- [x] Package on macOS and install on native Windows; compare manifest and digest. The physical
staging journey installed the macOS-published archive with the exact published digest, and
the portable golden independently matched manifest, package digest, and archive SHA-256.
- [ ] Package on native Windows and install on macOS/Linux; compare identity and executable-mode
policy.
- [x] Test global home resolution without constructing the path on the macOS client.
- [x] Test a host-owned real Git worktree and plain folder workspace independently.
- [ ] Test path joining, drive prefixes, UNC rejection/handling policy, reserved names, trailing
dots/spaces, long paths, Unicode normalization, and case collisions.
- [x] Test source and destination paths containing spaces and non-ASCII characters.
- [x] Test junction creation succeeds for a detected provider.
- [x] Force junction denial and verify an independently copied, digest-verified fallback.
- [x] Test an unowned junction, external link, broken junction, and provider parent that is already
linked. All four real NTFS junction cases passed on `windows 2` at `c7c8a2e32d`; Orca repairs
only its receipt-owned broken junction and preserves unowned links.
- [x] Test copy-fallback drift during update and removal. Real Windows coverage at `b4f5b6c119`
proves a locally modified independent copy is skipped during reconciliation and refused
during removal without changing its bytes.
- [x] Hold destination files open to simulate antivirus/indexer contention and verify bounded
`EPERM`, `EACCES`, and `EBUSY` rename retries. A real `FileShare.None` lock on `windows 2`
proved transient recovery and bounded exhaustion at `18fe31f107`.
- [x] Verify retry exhaustion restores the old version and yields an actionable result. The
transaction preserves the old bytes and returns retryable
`skill-install-filesystem-failed`; the real Windows source remains intact for retry.
- [x] Terminate the runtime before and after each journal boundary and verify startup recovery.
The combined physical Windows run passed the real-process extraction, install, removal, and
upload restart suites, including begun, partial, fully uploaded, and committed upload states.
- [ ] Test permission-denied, read-only, disk-full, cancellation, runtime disconnect, and partial
provider-coverage paths. Deterministic `EACCES` and `ENOSPC` transaction injection now proves
the prior installed version remains intact; physical read-only/disk-full and disconnect
journeys remain open.
### WSL tests
- [x] Execute package ingress, extraction, home resolution, installation, provenance, and discovery
inside the selected distro.
- [x] Prove the Windows client never constructs a Linux home or mutates the distro through a
translated Windows path.
- [ ] Post-launch: test global installs for a second distro with a different default user/home.
- [x] Test Linux case sensitivity and executable modes inside the installed distro. Real
`Ubuntu-24.04` coverage passed at `cdafe43542` with `0600` regular files and `0700`
executable files.
- [x] Install a multi-skill bundle selectively into a distro-owned home and prove unselected skills
are absent. The first `windows 2` run found missing filesystem preparation; the fix at
`70b847c38e` passed all 3 real `Ubuntu-24.04` tests and the temporary worktree was removed.
- [ ] Post-launch: repeat Linux case-sensitivity and executable-mode coverage in a second distro.
- [ ] Test a distro-owned Git worktree and plain folder workspace.
- [x] Test a workspace on the distro filesystem and document behavior for `/mnt/c` separately.
- [x] Test provider detection and POSIX alias creation inside the distro. Real `Ubuntu-24.04`
provider detection passed at `cdafe43542`; the transaction harness also verified the Claude
placement as a distro-owned POSIX symlink.
- [ ] Test concurrent native Windows and WSL installs of the same package without provenance or
lock collision across host identities.
- [ ] Test distro stopped, distro removed, default user changed, home moved, and runtime restarted
between preview and install.
- [ ] Block outbound GCS access inside WSL and verify client-mediated chunk transfer.
- [ ] Disconnect the macOS client during transfer and commit; verify bounded cleanup and recovery.
### Windows/WSL mixed-version tests
- [ ] Use `windows 2` as old host with a newer client and verify capability-gated UI.
- [ ] Upgrade `windows 2` only through the normal supported update path, then test an older client
against the newer host.
- [ ] Verify folder-workspace IDs, runtime-owned paths, and results survive client/host version
skew.
- [x] Capture structured test evidence without signed URLs, tokens, skill contents, or private
absolute paths beyond approved test fixtures.
### Windows/WSL release gate
- [x] Real native Windows passes junction success, junction denial, verified copy fallback,
antivirus contention, long paths, crash recovery, Git worktree, and folder-workspace tests.
The final combined run passed 449 tests across 67 files at `44d1266641`.
- [ ] Real WSL passes distro-owned paths, Linux semantics, provider placement, cancellation, and
crash recovery tests. Distro-owned paths, semantics, provider placement, and interrupted
update recovery passed in the combined physical matrix. The owner accepted the additional
live WSL-to-staging journey as duplicate release evidence on 2026-08-12; physical
disconnect/cancellation injection remains open, and a second distro is post-launch.
- [x] Temporary local test installations, workspaces, and packages are removed through verified,
recoverable cleanup. The final checkout was clean and WSL `/tmp` had no `orca-skill-*` debris.
## 11. Implement and validate SSH targets
The 2026-08-11 live Orca inventory contained only the connected `windows 2` environment and no
non-local worktree or repository. Later staging journeys registered disposable Ubuntu 20.04 and
native macOS ARM64 hosts directly through Orca's SSH provider and removed them afterward. A
supported Windows SSH target remains required for its platform-specific gate.
The Docker-backed Linux SSH harness exercises the production Electron → SSH provider → relay →
remote installer path. Its loopback package origin is unreachable from the container, forcing
client-mediated chunk upload. The test independently verifies Cloud request receipts and remote
files for global, Git-worktree, and plain-folder installs, unchanged preview, listing, and removal.
Physical staging journeys additionally passed the supported Ubuntu 20.04/glibc 2.31 floor and
native macOS ARM64; supported Windows remains open.
- [x] Define a host-side installer command that invokes the same installer core and structured
result contract.
- [x] Transfer immutable packages through the existing SSH/SFTP provider into bounded private
staging.
- [x] Invoke installation on the SSH host so it owns home, path, provider, and filesystem
resolution.
- [x] Add capability/version detection for the required host component.
- [x] If unsupported, offer a package download or explicit command; never install into the
desktop's home as fallback.
- [x] Propagate cancellation and clean partial SSH transfers and staging.
- [x] Route selective bundle installs through an additive SSH method with direct download,
client-mediated fallback, per-skill results, and old-host capability fencing.
- [ ] Test SSH-only macOS, Linux at the supported floor, and Windows where the existing provider
supports it. Ubuntu 20.04/glibc 2.31 and native macOS ARM64 passed the full live staging
lifecycle; supported Windows remains open.
- [x] Test Git worktree and folder-workspace scope over SSH through the disposable Docker Linux
target and verify the host-owned paths independently.
- [ ] Test connection loss during upload, extraction, commit, provenance, and result return. Lost
result-return recovery is covered for direct and staged SSH installs; the other physical
boundaries remain open.
- [x] Prove SSH and paired runtimes return the same result and error-category contracts. The full
nine-category matrix now passes through both transports with exact code and retryability
preservation. This exposed and fixed SSH's numeric JSON-RPC code taking precedence over its
validated structured skill failure; arbitrary error data remains rejected by the strict
schema.
## 12. Add observability, operations, and security controls
### Metrics and dashboards
- [x] Record bounded package byte/file counts and package, upload, finalization, download, transfer,
install, placement, and recovery durations.
- [x] Record outcomes by error category, OS, destination kind, transport, conflict type, and
placement topology.
- [x] Record junction, alias, copy-fallback, rollback, recovery, capability-absence, and orphan
reconciliation counts.
- [x] Add dashboards for grant/finalize/share rates, authorization and rate limits, finalization
saturation, archive rejection, and digest mismatch.
- [x] Add Cloud Run 5xx, CPU, memory, instance, and skill-route latency panels and alerts.
- [x] Add GCS quarantine/published bytes, object count, and lifecycle failure panels and alerts.
- [x] Add PostgreSQL connection, storage, query latency, migration, and transaction panels and
alerts.
- [x] Add signed-policy/URL generation and IAM Credentials failure alerts. Grant-signing failures
are mapped to a stable application category so the alert does not depend on project-wide
Data Access audit logging; evidence is in Orca Cloud `69b388e`.
- [ ] Add budget alerts for GCS storage/egress, Cloud Run growth, and Cloud SQL storage.
Dashboard evidence in Orca Cloud `41ef335` and `f67ee2c`: upload-grant, finalize, share, and
download-grant success; bounded security failures; Cloud Run CPU, memory, instances, and latency;
GCS bytes and object count; and Cloud SQL connections, disk use, p99 skill-principal query latency,
and skill-database transaction rate. Cloud PR `#344` passed both required checks and merged as
`fcf8655a`; it adds privacy-bounded migration-ready/failure metrics, a migration lifecycle panel,
and a zero-tolerance migration-failure alert. Its targeted staging plan creates the two metrics and
alert, updates only the dashboard, reruns descriptor propagation, and destroys no infrastructure.
Cloud PR `#345` passed both required checks and merged as `06a5c729`; it normalizes malformed
compression failures to the bounded `skill_package_archive_invalid` category, adds explicit
finalization-saturation and archive-rejection metrics, and displays successful and failed API
operations as rates. The broader unchecked items still require the listed split metrics, lifecycle
visibility, budget coverage, and reviewed alert thresholds. Cloud PR `#346` passed both required
checks and merged as `8199c048`; it adds privacy-bounded per-route latency distributions, sustained
80% CPU/memory and near-instance-ceiling alerts, separate five-second interactive and 30-second
finalization p99 latency alerts, and a route-template p99 dashboard without bearer identifiers.
Cloud PR `#347` passed both required checks and merged as `65320475`; it adds a six-hour
aggregate-only storage inventory job, fixed quarantine/published bytes and object-count metrics,
an overdue-quarantine metric, two storage panels, and an overdue-or-job-failure alert. The monitor
identity has only `storage.objects.list`, while the scheduler can invoke only that job. The reviewed
targeted staging apply added 18 observability resources, updated the existing dashboard, and
replaced only the inert descriptor-propagation timer. A manual run emitted only aggregate fixed-
namespace measurements with zero overdue objects; the post-apply targeted plan is zero-diff, SQL
remained `NEVER`/`STOPPED`, all Relay MIG targets remained zero, and production remained disabled.
Desktop operations now emit local diagnostic spans for package creation, direct upload,
finalization, grant download, client-mediated runtime/SSH transfer, single and bundle install,
provider placement, transaction rollback settlement, and startup recovery. Package bytes/files,
OS, destination kind, transport, conflicts, placement topology/mechanism, copy fallback,
capability absence, recovered transactions, stale extraction/lock cleanup, and failure categories
use fixed or bounded values; bundle error-category cardinality is capped at 32. The implementation
adds no product telemetry event, RPC field, persisted schema, or remote opcode. The skill-sharing
release suite passes 427 tests with 29 expected platform skips, the focused affected matrix passes
102 tests with one expected skip, typecheck and the full lint pipeline pass, and the real-process
macOS recovery matrix passes all 17 crash boundaries. The final combined physical Windows/WSL run
passes 449 tests across 67 files with 17 intentional platform skips; live WSL staging and physical
disconnect boundaries remain separate gates below.
### Logging and privacy
- [x] Log package/version IDs, phases, destination labels, placement outcomes, and bounded error
categories only.
- [x] Exclude package contents, filenames, manifests, raw local paths, ACL membership, durable share
URLs, upload policies, download grants, and credentials.
- [x] Redact sensitive network values before logger invocation, not after ingestion.
- [x] Audit authorization and lifecycle events without instruction or script contents.
- [x] Verify diagnostics and support bundles preserve the same exclusions. Desktop install spans
map requests and results to bounded labels before the tracer boundary; regression coverage
proves raw paths, filenames, manifests, ACL values, durable share URLs, upload policies,
download grants, credentials, and raw error text never enter the collected bundle.
### Security review
- [x] Threat-model package creation, archive ingestion, manifest trust, path containment, local
conflicts, grants, redirects/SSRF, authorization, tenant isolation, and instruction/script
trust in `docs/reference/agent-skill-sharing-threat-model.md`; keep approval and residual-risk
acceptance as separate human gates.
- [x] Verify owner-private staging permissions on supported hosts. POSIX download, package,
extraction, upload-session, provenance, and lock tests require `0700` directories and `0600`
files; real WSL verifies owner-private executable modes; and the native-Windows privacy suite
verifies staging remains under the owning profile without broad ACL disclosure.
- [x] Rate-limit uploads, finalization, downloads, share resolution, and remote transfer sessions.
- [x] Test malicious redirects, DNS/host confusion, expired grants, mismatched generations, and
oversized streaming bodies. Exact HTTPS origins, manual same-origin redirects, URL
credentials, suffix/port confusion, streamed byte bounds, expiry-before-fetch, and immutable
GCS generation pinning are covered in Orca `534abb8908` and Orca Cloud `81a581d`.
- [x] Test archive and filesystem race conditions, including source drift and destination changes
after preview. Package creation re-observes staged bytes, and install commit re-observes the
locked canonical destination before its first destructive rename.
- [ ] Review organization departure, deletion, retention, soft-delete, and operator recovery.
- [ ] Complete privacy and security sign-off before external rollout.
### Runbooks and kill switches
- [x] Add independent server-side flags for upload grants, download grants, and remote
installation.
- [x] Verify disabling Cloud grants does not break skill discovery or already installed skills.
- [x] Document finalization saturation, GCS/IAM signing failure, database outage, corrupt package,
orphan reconciliation, and rollback response.
- [x] Document coordinated PostgreSQL point-in-time and GCS generation/soft-delete restoration.
- [x] Document package/share deletion, organization departure, legal retention, and audit handling.
- [x] Document how and when to split finalization into its own service.
## 13. Complete automated and end-to-end validation
### Transaction matrix
- [x] Test fresh install, identical reinstall, clean update, rollback, explicit replacement, and
safe removal.
- [x] Test modified and unowned canonical and provider conflicts.
- [ ] Test canonical/provider paths as regular files, directories, aliases, junctions, external
links, and broken links. Deterministic native coverage now preserves canonical regular-file
name collisions, unowned provider files/directories, external and broken unowned links,
Orca-owned broken-link repair, aliases, and verified copy fallback. Physical Windows
junction coverage remains open.
- [ ] Test concurrent desktop, headless runtime, CLI, SSH, and recovery attempts.
The shared transaction core now serializes two simultaneous installs into one installed and
one unchanged result, one receipt, and no staging residue. The host request service also
serializes simultaneous download-grant and trusted-local ingress requests with the same
guarantees. A real multi-process harness proves an on-disk destination lock returns a
retryable busy result without residue, then converges to unchanged after the owning process
commits and releases; the release gate runs it on macOS, native Windows, and Ubuntu 20.04.
Named desktop/headless/CLI/SSH/recovery process combinations remain open.
- [ ] Test permission and read-only failures, disk exhaustion, cancellation, process termination,
and host disconnect. Simulated `EACCES` and `ENOSPC` preservation plus lost-response retry are
covered; physical failure and termination journeys remain open.
- [x] Test independent-copy drift and incomplete provider coverage. Deterministic transaction
coverage preserves modified independent copies, retains canonical success when an unowned,
failed, or cancelled provider placement cannot be reconciled, reports the exact partial
placement outcome, and repairs interrupted coverage on retry.
### Platform and target matrix
- [ ] Run macOS ARM64 and x64 behavior where supported.
- [x] Run Linux against Ubuntu 20.04/glibc 2.31 and verify bundled native binaries respect the
floor. The exact x64 directory package passed its 18-binary ABI scan and packaged
`node-pty` load/spawn smoke inside Ubuntu 20.04 at `f1dccb4f42`. The exact ARM64 directory
package at `abe92d565b` passed the same 18-binary floor scan and emitted
`orca-node-pty-floor-ok` from an ARM64 Ubuntu 20.04 container on native `aarch64` hardware.
- [x] Run native Windows and WSL scenarios on `windows 2`.
- [x] Run local and remote Git worktrees and plain folder workspaces. Native Windows covered a
linked worktree and folder; paired desktop and Docker SSH covered host-owned worktrees and
folders; physical Ubuntu SSH covered the global lifecycle.
- [x] Run same-build paired desktop and headless runtimes through client-mediated transfer; headed
coverage includes global, Git-worktree, and plain-folder scopes, while headless coverage
includes global and Git-worktree scopes.
- [ ] Run paired runtimes with both client-newer and server-newer combinations.
- [ ] Run supported SSH-only macOS, Linux, and Windows targets. Native macOS ARM64 and Ubuntu
20.04/glibc 2.31 passed full staging lifecycles; supported Windows remains open.
- [x] Run a remote target without outbound Cloud connectivity through chunk transfer. The Docker
SSH target could not reach the loopback package origin and completed global, worktree, and
folder installation through client-mediated upload.
### Required journeys
- [ ] Share on machine A, install globally on machine B, launch a detected agent, and discover the
skill.
- [ ] Share on machine A, install into a folder workspace on a connected runtime, and discover it
only in that workspace.
- [x] Modify installed bytes, publish an update, and prove Orca refuses silent replacement. The
browser-free macOS staging lifecycle preserved the modified v1 copy before applying v2 only
after the explicit test decision.
- [ ] Disconnect during commit, reconnect, recover, and prove either the old or new version is
complete.
- [x] Revoke a share, prove a new install fails, and prove the existing local install remains.
Bearer-route tests and staging smoke reject revoked resolution/grants; macOS, native Windows,
paired, and SSH lifecycles independently preserve already installed bytes.
- [x] Publish a new immutable version, update one machine, leave another pinned, then rollback the
updated machine. The physical Windows staging journey updated only the remote host to v2,
retained the local machine's independent version, and rolled Windows back to v1.
- [x] Remove local installation without deleting its Cloud package, then delete/revoke Cloud
access without mutating another local installation. Staging lifecycles separate host/local
removal from package deletion, and revocation never mutates either installed copy.
### CI and test evidence
- [x] Add deterministic fixtures authored for Orca without copying upstream fixtures.
- [x] Add failure-injection hooks available only to tests/development harnesses.
- [x] Add a CLI-only developer harness for local and remote integration tests.
- [x] Keep CI commands compatible with macOS, Linux, Windows PowerShell/cmd, and WSL.
- [x] Archive bounded test results and security evidence without secrets or private contents. The
required release jobs archive bounded machine-readable results; privacy-safe Cloud field
inventories, load aggregates, and recovery evidence contain no grants or package contents.
- [x] Make package safety, transaction recovery, platform, and mixed-version suites required release
checks. Release publication now depends on focused macOS, real native-Windows, and Ubuntu
20.04/glibc 2.31 jobs that archive bounded machine-readable results.
## 14. Stage and release
### Staging
- [x] Apply reviewed Terraform and migrations to staging.
- [x] Deploy `orca-cloud-api` skill routes disabled by server-side flags.
- [x] Enable all four staging controls and pass the GitHub OIDC owner plus anonymous bearer-link
lifecycle smoke, including owner management, immutable versions, local/remote grants,
rollback selection, expiry, revocation, deletion, and object cleanup.
- [x] Run staging upload/finalize/download smoke for anonymous denial, oversize, corruption,
expiry, revocation, deletion, and cleanup; retain tenant-deduplication coverage in the API
integration suite.
- [x] Run desktop-to-local, paired-runtime, `windows 2`, WSL-equivalent host ingress, and SSH
journeys in staging.
Browser-free macOS run `31569902499` passed publish, install, conflict preservation, update,
rollback, revocation, installed-copy preservation, removal, and Cloud deletion. Physical
native Windows passed the same lifecycle through run `31591275227`, including remote-owned
path and digest verification with no macOS fallback. A disposable Ubuntu 20.04/glibc 2.31
host passed the same SSH lifecycle after guarded wake `31603249983`; guarded sleep
`31604391897` restored the low-cost state. An isolated headless host passed the paired
non-Windows lifecycle after guarded wake `31605729090`; guarded sleep `31606600532` restored
the low-cost state. The physical Windows/WSL matrix separately passed 449 tests on real NTFS
and Ubuntu 24.04 filesystems. On 2026-08-12, the owner accepted another WSL Cloud lifecycle as
duplicate evidence rather than a launch gate.
- [x] Give the live staging E2E an owner-private persisted test profile or a short-lived
non-interactive test credential so reruns do not open PKCE login tabs or copy a user's
primary Orca session.
- [x] Verify staging application logs contain only route templates, method, status, duration, and
standard process metadata, with zero credential or private-content matches. Exclude per-link
Cloud Run platform request logs through Terraform and verify zero are retained.
- [x] Verify logs, metrics, traces, diagnostics, and support bundles contain no grants or private
package data. The physical SSH window emitted 27 structured route-template events whose
complete application field inventory was only duration, event, hostname, level, method,
process ID, route template, status, and time; it emitted zero API error logs. Install traces
retain only bounded IDs, counts, labels, and enums. The support-bundle suite injects private
paths, filenames, contents, share URLs, signed grants, policies, ACLs, and credentials and
proves none survive collection. No skill-sharing product telemetry event is registered.
- [x] Load-test finalization and choose the fixed semaphore from observed memory, CPU, request
latency, and database usage. Run `31585710645` kept the existing semaphore: its 12 concurrent
30-skill bundles produced two immediate successes and ten explicit saturation responses,
1,514 ms client p95, 8.95% API CPU, 26.95% API memory, one API instance, 10.89% database CPU,
25.59% database memory, and seven database connections.
- [ ] Exercise at least one quarantine lifecycle deletion and published-object soft-delete
recovery. Published-object recovery passed run `31580071168`; the one-day quarantine
lifecycle deletion remains time-gated.
### Production infrastructure and launch
- [x] Apply the approved production Terraform plan and verify no unrelated replacement. The saved
skill-only plan added 40 resources with zero updates, replacements, or deletions; the
storage-monitor follow-up added one narrow IAM binding with zero changes or deletions. The
final hardening used two reviewed targeted phases: 13 additions plus one WIF update, followed
by exactly five broad-IAM deletions. A separate targeted apply made nine in-place
observability updates. No full plan or unrelated Relay drift was applied.
- [x] Run production database migrations before routing skill traffic. Disabled-route bootstrap
run `31648015091` completed the skill schema migration before any skill route was enabled.
- [x] Deploy the API with all skill flags disabled. Bootstrap revision `orca-cloud-api-00016-yem`
received 100% traffic and returned `404` for the disabled skill route while Artifact and Auth
health remained green.
- [x] After every first-release gate passes, enable the feature for all accounts in one launch.
Production run `31650178315` initially enabled upload, download, remote install, and sharing
together. Hardening run `31661421728` then passed candidate and canonical authenticated
artifact plus skill smoke and promoted `orca-cloud-api-00025-qup` at 100% traffic with digest
`sha256:e4f044105ff2345574bdceb36eec1629761428cc2edf9d743939390b857d61e0`.
- [ ] Verify one complete share, local install, remote install, update, rollback, revoke, local
removal, Cloud deletion, upload expiry, and soft-delete recovery journey. Production CI has
verified the server-side share/version/grant/revoke/delete lifecycle; the signed-in desktop
and real-host production journey remains manual.
- [ ] Verify upload, download, and remote-install kill switches independently.
- [ ] Review error budgets, cost, authorization denials, saturation, orphan counts, and support
signals. The hardened production revision has zero post-deploy error logs. All eight skill
alerts route to the enabled dedicated `Orca skill sharing alerts` channel, and aggregate
monitor execution `orca-cloud-skill-storage-monitor-lfd26` passed on the serving API digest
with zero overdue objects. Sustained-usage review remains post-launch.
### Launch operations
- [x] Keep upload grants, download grants, and remote installation independently controllable.
Separate Terraform-owned Cloud Run variables gate upload/finalize/share publication,
download grants, and remote-target grants. Route tests prove each narrow control while local
grants remain available when only remote installation is disabled; staging advertises all
three explicit controls.
- [ ] Disable the affected operation on unexplained digest mismatch, archive containment failure, data leak,
unrecoverable local mutation, or cross-tenant authorization defect.
- [x] Publish user documentation for sharing, access, install destinations, updates, rollback,
removal, retention, and trust in
[`docs/reference/sharing-agent-skills.md`](./reference/sharing-agent-skills.md).
- [x] Publish admin documentation for organization access, user departure, deletion, and retention
in [`docs/reference/admin-agent-skill-sharing.md`](./reference/admin-agent-skill-sharing.md).
- [ ] Remove rollout flags only after sustained healthy usage and a reviewed decision.
### First-release gate
- [ ] Threat model and privacy review are approved.
- [x] Cross-platform package and transaction suites are required and green. Release publication
requires focused macOS, native-Windows, and Ubuntu 20.04/glibc 2.31 jobs with bounded archived
results; the latest recorded release and platform passes are green.
- [ ] `windows 2` native Windows and WSL release gates pass on real filesystems. The combined run
passed 449 tests across 67 files, and the owner accepted the additional live WSL Cloud
journey as duplicate evidence on 2026-08-12. Physical WSL disconnect/cancellation injection
remains open.
- [x] Real SSH paths and host-owned resolution pass. Native macOS ARM64 and Ubuntu 20.04/glibc
2.31 independently passed SSH-owned global install, update, rollback, managed inventory,
revocation preservation, removal, and Cloud cleanup without local fallback.
- [x] Mixed-version tests pass in both directions. Bundle/install capabilities are additive, the
cross-version wire suite passes client-newer and host-newer, and capability-loss tests prove
execution is blocked after a stale preview.
- [ ] Cancellation and crash recovery pass during transfer and every commit boundary.
- [x] Durable-share authorization, revocation lag, retention, deletion, and recovery are documented
and tested. The user/admin guides document the lifecycle; Cloud route, integration, restore,
and cleanup suites cover the implemented contract. Automatic one-day quarantine deletion
remains a separate time-gated infrastructure observation.
- [x] The UI identifies scripts and executable content before install without exposing internal
publisher or organization identifiers. Renderer coverage asserts script and executable
summaries, digest, release notes, and long-content behavior before the primary install
action.
- [x] Telemetry, logs, and diagnostic bundles contain no credentials or private contents. Cloud
field-inventory and sensitive-value scans, bounded install-span attributes, and adversarial
support-bundle collection tests cover the complete first-release data path.
- [x] Kill switches are tested without affecting discovery or existing installations. Cloud PR
`#342` proves unlisted-link preview remains available with upload, download, and remote
installation controls disabled; existing route coverage proves remote-off retains local
grants. Existing installations and local discovery use only host-owned files and receipts.
## 15. Post-release multi-machine management and reconciliation
- [ ] Measure sharing, installation, update, conflict, fallback, failure, and multi-machine demand
without collecting private contents.
- [ ] Add **Install on another machine** and bounded multi-machine progress.
- [ ] Add optional desired-version policy for selected personal or organization machines.
- [ ] Add opt-in drift and missing-install reconciliation that never overwrites modifications.
- [ ] Evaluate an explicit, reviewable project desired-state manifest.
- [ ] Evaluate direct machine-to-machine transfer if Cloud persistence is not appropriate.
- [ ] Define offline convergence without durable shared credentials.
- [x] Document organization removal, user departure, package retention, and reconciliation
semantics before enabling policy-driven installs. The admin guide explicitly leaves legal
retention and ownership-transfer approval as human release gates.
## 16. Agent and Orca CLI publishing
- [x] Add a separate `agentSkillSharingEnabled` capability that defaults off and accepts only an
exact persisted `true` value. Manual desktop publishing remains independent.
- [x] Let only the local desktop Settings → Share Skills switch grant the capability. Runtime
`settings.get` exposes a fail-closed read-only projection; `settings.update`, paired web,
mobile, agents, and the CLI cannot enable it.
- [x] Add `orca skills installed --json` with discovery IDs and names but no local filesystem paths.
- [x] Add `orca skills share` with repeated explicit `--skill` selectors, a required bundle name,
one unlisted link for multi-skill bundles, and no `--all` or arbitrary-path input.
- [x] Resolve exact discovery IDs before unambiguous names; fail missing, ambiguous, and duplicate
bundle-folder names with actionable errors.
- [x] Enforce the capability in the executing runtime before discovery, before package reads, and
again before publishing. CLI preflight is an optimization, not the authority.
- [x] Reject forwarded WSL, SSH, and paired-runtime CLI contexts before discovery so native file
APIs cannot read a path belonging to another machine. Native runtimes remain supported on
macOS, Linux, and Windows.
- [x] Reuse the reviewed bundle preparation and Cloud publisher, propagate RPC cancellation into
upload, and remove per-operation preparation files after success, denial, cancellation,
authentication failure, or Cloud failure.
- [x] Admit one agent bundle preparation/publish at a time per host so concurrent agents cannot
multiply the bounded per-bundle disk and CPU budget.
- [x] Keep CLI JSON limited to the unlisted URL, public share/package/version IDs, bundle name, and
selected skill summaries; never return auth tokens or source paths.
- [x] Add gate, persistence, RPC grant-denial, selector, archive-content, cancellation, cleanup,
web mirror, Windows-path contract, CLI parser/help, and Settings UI tests.
- [ ] Complete a live signed-in production publish through the dev CLI, resolve the returned link,
revoke it, and confirm a later resolution fails while the local source skills remain intact.
- [ ] Complete independent OpenCode and release-readiness review, full repository validation, PR
CI, and an ad hoc build from the final commit.
---
### Automated Setup Tab Astra Review (`docs/automated-setup-tab-astra-review.md`)
# Independent review: automated Setup tab
## Current review verdict
Reviewed product source head `d96ae2ca6afdca919b4d7f8d85308363abe8b28b`, based on the merged PR 1 commit `7f9b51cf5cc1de8769baa646b40c0c93af76be81`, then the documentation-only head and CI corrections described in Rounds 6–8. **P0: none found. P1: none unresolved. Design and actual source diff have converged, with concrete existing paths and no known smaller adequate implementation.** Review only; this report is my only edited file. The numbered rounds below are historical checkpoints, including questions and pending checks that were subsequently resolved.
The implementation retains the existing Setup-tab creation paths and removes only automated setup split placement and its unreachable state. It retires the setting through the existing settings stripper, accepts old-host layouts, preserves manual/issue splits and generic lifecycle behavior, and leaves PR 1's native-chat provisioning change intact. No publication, sibling reattachment, generalized retry, or ownership repair was added.
Product-behavior local validation is complete. Lead's consolidated post-rebase run reports 34 Node suites / 1816 passing tests, two retained expected-failure cases, and two skips on the reviewed source; node/web typechecks and the changed-code gate passed. Rebuilt hidden paired probes passed setup output, independent Setup tab placement, background selection, manual splitting, actual native-chat surface creation, fixture terminal-agent output, and hidden/unfocused host/client windows. I inspected the proof assertions and before/after/native-chat screenshots; I did not independently rerun tests under the lead's exclusive runtime lease. The E2E typecheck comparison reports 261 baseline and 261 final errors, with no new or removed file/error-code pairs; that project remains non-clean. CI subsequently found a fixture-naming ratchet failure; its reviewed correction changes no product behavior, and lead reports both affected ratchets, 23 focused consumer suites (187 passing tests plus two retained expected failures), repeated node/web typechecks and the changed-code gate all passed.
Accepted **P2** limitations: automatic side-by-side setup placement is removed by design; old hosts can still return splits; the conditional ownership fixture does not prove the incident root cause or a publication/reattachment fix; native-chat proof submits no prompt, the terminal agent is a fixture CLI, and platform construction tests do not prove Windows/WSL/SSH execution. The generated English catalog conservatively retains 20 removed-callsite strings (1,136 uncompressed bytes), without restoring settings/search UI. Its remaining nonnative preflight checks passed per the Round 7 receipt. No unresolved source-review question or local correction-validation item remains. The correction commit, exact-head full PR workflow aggregate, and parent merge decision remain separate gates; this report is not merge authorization. Worker settlement awaits the lead's explicit request.
The latest CI correction changes only a stale counterfactual listener-count expectation: the actual 15-listener budget already passed and remains unchanged. The lead reproduced the failing arithmetic under the CI Bun test path, then all four tests and the changed-code gate passed after correction. Round 8 records the independent code/history evidence; no product behavior or performance limit was changed.
## Round 1 — historical design and control-flow review
Reviewed 2026-10-16 in this worktree at `54bb885bbd391642adecdaef262e87c3424f46e6`. Review only; this report is my only owned file. Implementation/final-diff approval is outstanding. Tests and native builds were not run: the coordinator explicitly reserves the shared native-runtime lease for PR 1.
**P0: none found. P1: no demonstrated unresolved design defect in the scoped tab-only approach.** This is not approval of an implementation or proof of the incident's cause. The changes below need concrete checks after PR 1 is merged and this branch is rebased onto that baseline.
### Evidence and scope
- `src/shared/worktree-first-surface.ts:11–17` explicitly seeds a primary shell for either split setting, even with `callerProvidesSurface`. Removing these two conditions removes a real split-anchor dependency without changing startup or issue-command requirements.
- Existing tab implementations are sufficient: renderer `worktree-setup-issue-command-queue.ts:27–45`, host `runtime-worktree-terminal-provisioning.ts:155–197`, and IPC `worktree-remote.ts:368–411`. Keep these command/env/wrapper/handle paths; do not invent a coordinator, ownership store, or retry mechanism.
- The IPC function is actually `spawnLocalStartupAndSetupTerminals` (`worktree-remote.ts:298`), not `spawnCreatedWorktreeStartup`. It is invoked in the local worktree flow at line 1697 despite the filename. Its no-startup/default-tabs early return at lines 308–310 matters when asserting reachability. Label this surface accurately in the design.
- Host success suppresses fallback: `runtime-local-worktree-terminal-startup.ts:203–214` omits returned setup after provisioning, while `worktree-remote.ts:1741–1749` returns only unconsumed setup. Preserving this control flow is smaller and safer than command deduplication. A failed wrapped setup retains `command` at `worktree-remote.ts:421–428`; the renderer prioritizes it at `worktree-setup-issue-command-queue.ts:28–32`.
- `setup-split-activation-single-owner.test.ts:13–18` describes a conditional reconstruction, and its host fixture deliberately returns no session tabs at lines 103–114 while terminal census returns two orphan records at 117–123. That establishes behavior under those premises, not the original missing-binding cause. Keep manual/saved or old-host split coverage without advertising this policy change as a binding/publication repair.
### Native-chat reachability: do not inflate the first-terminal concern
The desktop structured route sets `backendStartup` to undefined (`worktree-creation-flow-execute.ts:63–68`), routes explicit setup through the background seeding branch (`244–269`), and only then launches structured chat (`289–302`). IPC's early return above therefore returns setup for renderer execution. On the ordinary local route, `resolveWorkspaceTerminalHostAuthority` returns `none` (`workspace-terminal-host-authority.ts:124–127`), so it does **not** enter the first-terminal wait at `worktree-initial-terminal-seeding.ts:136–169`. It can use the existing null-primary Setup-tab branch at lines 172–196.
The host-authority branch really does couple returned setup to a first terminal. However, the host native-chat route normally consumes setup (`runtime-local-worktree-terminal-startup.ts:174–187,203–214`), and the paired `agent.launch` test already exercises a real request (`worktree-agent-first-surface.test.ts:155–180`). A P1 claim needs a request that actually returns fallback setup while host authority is live and no terminal will arrive. A constructed `ensureWorktreeHasInitialTerminal` call alone is insufficient. Keep generic delayed delivery unchanged in PR 2 unless PR 1's actual merged route demonstrates that necessity; ask the parent to resolve any overlap first.
### Settings compatibility
Delete the live setting and type; add only a retired-key entry/destructure to `stripRetiredGlobalSettings` (`terminal-settings-migrations.ts:59–91`). The existing function covers loading (`normalize-loaded-global-settings.ts:68`), updates (`settings-update.ts:62`), and serialization (`state-serialization-secret-handling.ts:262`). A separate settings migration/normalization layer has no demonstrated need.
Current paired read/write types omit this key (`runtime-client-settings-shape.ts:7–40,52–75`), and strict RPC `SettingsUpdate` omits it (`client-settings-params.ts:87–131`). Independent bounded named-path history found:
1. `b1973657ea6` introduces `SettingsUpdate` in `src/main/runtime/rpc/methods/client-ui.ts` on 2026-05-21. Its explicit strict allowlist and `getClientSettings`/`updateClientSettings` projection in `orca-runtime.ts:1142–1193` exclude setup location; the same revision uses setup location privately in host provisioning at lines 7006–7009.
2. `c84007c541d^` predates the generated RPC parameter move. `rpc/methods/client-settings-schemas.ts:81–129` remains a strict allowlist without the key, and the then-inline types/projection in `runtime-client-settings.ts` omit it.
3. Targeted `git log -SsetupScriptLaunchMode` over the current/previous schema and client-settings paths found no introduction of the key into those schemas. Historical matches in `orca-runtime.ts` are host provisioning uses, not paired settings fields.
This supports removal without an ignored paired field or wire-schema relaxation. Old hosts still own their placement: accept their returned split layouts without replay, flattening, migration, or interpreting a missing new preference as proof of unexecuted setup.
### Explicit P2 items and acceptance details
- **P2 product tradeoff:** automatic side-by-side placement disappears. Manual and issue splits remain. Users of old hosts can still receive split layouts until that host updates.
- **P2 design precision:** fix the IPC function name and distinguish local IPC from actual remote-host ownership. Replace the missing Electron-skill claim with the coordinator's discovered `agent-browser skills get core` / `electron` capability and pending hidden-CDP validation.
- **P2 coverage retention:** do not delete generic remount/restore/purge/PTY ownership assertions just because their fixtures mention setup. Convert them to manual/issue/old-host splits. Preserve startup identity consumption. Remove only setup-specific geometry gating (`terminal-pane-mount-preparation.ts:222–225`, `pty-resize-geometry.ts:219–226,242–244`); the visible startup-grid settle at lines 211–218 and 228 onward is broader than setup.
- **P2 selection precision:** renderer Setup creation restores the primary only when activation is allowed (`worktree-setup-issue-command-queue.ts:35–43`). Host `createTerminal` does not default to focused: `orca-runtime-core.ts:240–251` and `terminal/launch/terminal-create.ts:252–279` distinguish focus from selection-if-empty. Missing `activate:false` in the host's existing tab branch is not itself proof of focus theft. Assert primary/background selection through the real route instead of changing generic focus machinery.
- **P2 setup-only/templates:** simplify the mode predicate in both `worktree-creation-flow-execute.ts:173–177` and `runtime-worktree-terminal-provisioning.ts:129–138`, while preserving explicit `setupOnly` intent and no-setup fallback. Do not suppress templates for ordinary blank/native-chat creation. The existing failure fallback at provisioning lines 204–221 remains necessary when Setup was the only owed surface.
### Smaller alternatives and convergence
A default-only change is already inadequate: the default is already `new-tab`, while persisted split values still enter three separate branches and create an anchor shell. Ignoring the setting but retaining queues and geometry leaves dead lifecycle state and fails the requested removal. Replacing the three setup placement branches with their existing tab arm, removing only now-unreachable setup plumbing, and retiring the setting through the existing stripper is the smallest adequate design found.
Before declaring design convergence, lead should confirm the corrected route labels, the historical-settings evidence above, and that no first-terminal or publication/reattach work will slip into PR 2 without actual post-PR-1 reachability evidence. No unresolved P0/P1 is currently demonstrated. Final convergence remains conditional on reviewing actual code and meaningful tests, including old-host no-replay, remount one-shot execution, setup-only/defaults, native-chat/terminal/background routes, sequencing failure fallback, and preserved manual/issue splits. Windows/WSL/SSH command tests establish construction behavior only; do not claim those platforms were executed unless they were.
## Round 2 — design convergence
Re-read the revised design after durable message `msg_bf91c03835ff`. The lead incorporated the correct local-IPC function/route, historical paired-schema evidence, first-terminal reachability qualification, and the PR 1/publication/reattachment boundaries. The design retains generic startup-grid settling and requires retargeting generic split fixtures. The Electron capability statement now identifies the installed specialization and keeps validation pending.
**Design converged: no unresolved P0/P1, concrete implementation paths identified, and no known smaller adequate design.** The P2 product tradeoff and old-host behavior are explicit and accepted within scope. This permits scoped source implementation; it does not approve unreviewed code, tests, or merging. Re-evaluate against PR 1's exact merged baseline before final review.
## Implementation review
At this historical checkpoint, lead revision, PR 1 baseline, actual final diff and test results were pending; their resolution appears in the later rounds and current verdict above. Do not interpret this report as a merge authorization.
### Interim fixture review
At the lead's request (`msg_76639d99e47e`), inspected the retargeted delayed-primary/sibling-fallback test in `pty-connection-split-spawn.spec.ts:235–338`. Its CWD promise is a real generic delay (`run-deferred-connect.ts:74–103`), but then it waits for visible startup-grid settling; 20 shared animation callbacks are not necessarily 12 primary settle ticks when the sibling has its own resize callbacks. Recommended making both explicit-startup panes hidden, retaining the CWD gate and shared transport registry, then asserting sibling-first ownership before resolving the primary CWD. Existing `pty-connection-deliberate-sleep-guard.spec.ts:183–213` demonstrates this hidden CWD gate. This preserves the ownership regression purpose without changing production reattachment or restoring removed setup geometry. Lead must verify the proposed fixture correction; reviewer did not run tests or edit source.
### Round 3 — implementation review before PR 1 rebase
Reviewed the restored working diff after `msg_065efb1f75ff` (base remains `54bb885bbd391642adecdaef262e87c3424f46e6`). **No production P0/P1 found.** A final post-PR-1-baseline verdict remains outstanding.
- All three placement changes retain the existing tab arm. Runtime retains completion-token registration, default-tab dressing, explicit setup-only suppression and failed-Setup fallback. IPC retains its wrapper, platform/shell builder, env, inactive/background options, and consumed-result behavior. No setup execution authority or retry mechanism was introduced.
- The removed state is setup-specific. Issue-command queues/consumption remain; `terminal-pane-mount-bootstrap.test.ts` checks the surviving primary-anchor split, env, focus policy and one-shot command clearing. `terminal-pane-pane-created.ts` still passes the captured raw startup identity to `createQueuedStartupConsumer` after removal of the setup-wait copy.
- `terminal-startup-grid-settle.ts` removes only the now-unused readiness predicate and its frame counter. With no predicate, old `readyFrame` and `frame` advanced together, and `usesReadinessGate` was false; the remaining algorithm therefore preserves the former generic branch. Grid stability/cap/cancellation tests and hidden-window start tests remain.
- Compared old and new PTY test-case names: only the obsolete setup-geometry case was deleted; delayed-primary was retargeted, and remount, resize/mobile locks, hidden startup, and replay cases remain. The final hidden-CWD delayed-primary fixture explicitly proves sibling ownership before release and then asserts a distinct primary PTY; lead reports 78/78 passing.
- Existing old-host first-activation reconstruction retains its layout/ownership assertions and now asserts an empty pending-startup map. Its expected-failure branch remains an acknowledged existing limitation, not a claimed fix. Purge/sleep tests retain issue-queue and generic startup coverage while removing only the deleted map's assertions.
- Stale settings are removed on load, update and save/reload by meaningful persistence tests; remaining setup-location references are deliberate stale-profile test input or the stripper. No paired RPC schema change or saved-layout migration was introduced.
- Inspected `setup-before.png` and `setup-after.png` directly in `.bench-fixtures/setup-split-removal-proof`: before has a split inside one terminal tab, after has Terminal 1 and Setup tabs with one visible Setup pane; both display the setup completion marker. Screenshots alone do not prove hidden/focus state; the proof's explicit BrowserWindow assertions and lead's execution receipt cover that separately.
**P2 correction requested (`msg_ce3248db323b`):** `host-split-and-sleep-journeys.ts:56` calls public `terminal.split`, whose RPC handler (`terminal-lifecycle-methods.ts:96–101`) does not forward inactive options; `terminal-split-surface.ts:129,169` defaults activation to true. Thus the renamed `host-split-first-activation` journey can activate during fixture creation and overstates its coverage. Preserve inactive-first-open through an existing internal test seam, or explicitly navigate away and label this a reactivation fixture, retaining genuine old-host first-open coverage in the unit test. Do not broaden production RPC for the fixture. Also asked the lead to format/check the new proof spec and replace its unchecked result cast.
Validation reported by lead: 34 Node files / 1799 tests with two existing expected-fail cases and two skipped; a separate 78-test PTY fixture run; node/web typechecks; changed-file quality gate. Reviewer has not independently executed these under the lead's exclusive native lease. Final logs/results, E2E typecheck baseline comparison, corrected P2 fixture, PR 1 merged-base adaptation, and exact-head workflow gates remain to be assessed.
Round 3 follow-up: verified the P2 fixture correction after `msg_b7784f689bca`: `host-split-and-sleep-journeys.ts:57` returns to the seeded workspace and the oracle scenario is now `host-split-reactivation`. The old-host first-activation unit assertions remain. This resolves the misleading-coverage finding without broadening production scope. The lead will keep the one-off before/after probe under ignored proof artifacts, not in the PR. Lead also reports both hidden before/after probes passed output, tab/pane count, retained manual split, background-selection and hidden/unfocused-window assertions. No unresolved P0/P1 in the currently reviewed PR 2 diff; post-PR-1 review is still required.
### Round 4 — exact PR 1 merged baseline
Verified locally that `merge-base(64fbb53d8a4c92e17c5aa19a8aa86cd1869979bc, 7f9b51cf5cc1de8769baa646b40c0c93af76be81)` is the exact PR 1 merge `7f9b51cf5cc1de8769baa646b40c0c93af76be81`. The PR 2 diff does not modify PR 1's production `runtime-local-worktree-terminal-startup.ts`: its shared `callerProvidesInitialSurface` predicate still supplies the host's background agent ownership decision, and host success still suppresses returned setup at lines 202–209.
Reviewed the only uncommitted overlap adaptation, `src/main/runtime/orca-runtime-tests/worktree-native-chat-setup.spec.ts`. It retains renderer payload construction → strict RPC parse → runtime argument builder → actual managed-worktree create (lines 72–91), and expands the Claude/Codex setup-only-host assertion across both stale split values, new-tab, and absent settings (95–113). It checks command/env, running setup receipt, consumed setup and absence of an invented startup terminal. Former split-anchor controls now request a real startup and verify distinct startup/Setup tab identities (132–143). Blank, activating attribution, run-hooks, skipped setup and default-command controls remain. The stale field is fixture-only and no deleted live type remains.
**Post-rebase semantic review: no unresolved P0/P1, no duplicated PR 1 production change, and no smaller adequate alternative identified.** The accepted P2 product/old-host limitations remain as documented. Final post-rebase checks/proof and the eventual exact-head CI/merge authorization are still separate gates; reviewer is awaiting their receipts and the lead's explicit settlement request.
### Round 5 — committed-head confirmation
Verified the clean tracked worktree at `d96ae2ca6afdca919b4d7f8d85308363abe8b28b`. Its only change from the Round 4 checkpoint is the already-reviewed native-chat setup test adaptation above; no additional production changes were introduced. **P0: none found. P1: none unresolved. The actual PR 2 diff has converged, with no known smaller adequate implementation.**
Post-rebase validation receipt from lead (`msg_87e2f64711ef`): 1443 focused/runtime tests passed with one existing skip; node/web typechecks and the changed-code gate passed; the rebuilt paired hidden placement proof passed two tabs/one Setup pane, actual setup output, retained background selection, manual splitting, and hidden/unfocused BrowserWindow assertions. These are lead-executed results under the exclusive runtime lease, not independently rerun tests. The extra native-chat `agent.launch` probe and final E2E typecheck comparison remain pending and must not be described as passed yet.
Accepted P2 limitations remain: automatic side-by-side setup placement is intentionally removed; old hosts may still publish split layouts; the preserved conditional ownership fixture is not incident root-cause proof or a publication/reattachment fix; Windows/WSL/SSH construction tests do not establish execution on those platforms. The E2E typecheck has a reported baseline of 261 pre-existing file/code failures, with the final comparison still outstanding. This confirms source review on the named head, not exact-head CI or merge authorization. Worker settlement remains pending the lead's explicit request.
Round 5 validation follow-up (`msg_b865b628c0e7`): lead reports the additional final-baseline hidden probe passed. Independently read its actual paired `agent.launch` calls and assertions: background Claude creates a structured chat, the rendered workspace contains exactly one agent-session and one terminal, and the terminal-agent route creates two terminal tabs and displays the fixture CLI marker. Directly inspected `native-chat-after.png`, which shows Setup and Claude Chat with an empty composer. This proves native-chat surface creation, not a model turn; no prompt was submitted. The terminal-agent check uses a fixture CLI, not a real Codex session. The probe asserts every host/client BrowserWindow is hidden and unfocused.
Read `e2e-typecheck-comparison.json`: baseline and final each have 261 errors, with empty new/removed file-and-TypeScript-code lists. Thus no new errors were found by that comparison, while the E2E project itself is not typecheck-clean. These receipts resolve the two pending validation items above. **Final source-review verdict on `d96ae2ca6afdca919b4d7f8d85308363abe8b28b`: no unresolved P0/P1; accepted P2 limitations are explicit; no known smaller adequate design.** Awaiting explicit settlement or any CI-driven source revision.
Final consolidated receipt (`msg_6734645deb90`): the lead reran all 34 selected Node suites after rebasing, reporting 1816 passing tests, two retained expected failures and two skips on the same source head. This supersedes the earlier focused-test counts as the final consolidated local result. All requested local validation items are resolved with the limitations stated in the current verdict; exact-head PR CI and parent merge approval remain outstanding.
### Round 6 — CI fixture classification correction
Verified documentation-only head `c6cdb67aaaf1cc7e0a2b5befa7e6e8b7cbb8cab2` preserved the reviewed product source. CI then rejected two fixture calls to `getDefaultSettings` under the focus-read ratchet. These calls replaced incomplete asserted settings during the setup preference removal; they did not add production execution-host routing.
Independently inspected both fixtures and all repository references before and after the staged correction. Both modules import Vitest, and every discovered consumer is a `.test.ts` file. `check-focus-read-ratchet.mjs:357–359` already excludes `.test-fixture.ts`, with direct coverage at `check-focus-read-ratchet.test.mjs:244`. Renaming to `worktree-activation-created-agent.test-fixture.ts` and `worktree-activation.test-fixture.ts` therefore applies the existing test/product distinction. The staged renames are 100% content-identical; every import edit is test-only. The existing layout detector also excludes fixtures (`check-layout-writer-ratchets.mjs:161–165`), so the correction deletes the one obsolete 21-writer baseline row for the old filename. Neither detector nor any allowance was expanded.
**No new P0/P1/P2 finding in this correction; prior accepted P2 limitations remain.** Conventional fixture naming is smaller and more accurate than a detector change, a suppression, duplicating defaults, restoring unchecked settings casts, or adding baseline allowances. Final correction receipt (`msg_b98097cf4ff3`): both ratchets passed, 23 focused consumer suites passed 187 tests with two retained expected failures, node/web typechecks passed, and the changed-code gate against the exact PR 1 baseline passed. Existing product-behavior and rendered proof receipts remain applicable; a hidden-app rebuild is unnecessary for content-identical fixture renames and test import changes. No local correction-validation item remains pending. Fresh exact-head full PR CI and parent merge approval are still required.
### Round 7 — generated English catalog correction
Verified clean committed fixture-correction head `fe855b8c97ddf90c0d2ad273f1355cf711ee5d8e` exactly matched Round 6. CI then failed catalog verification: removing the Setup UI/search callsites leaves English catalog entries without literal defaults. The existing `collectRuntimeRequiredKeys` contract (`generate-runtime-required-english-catalog.mjs:45–82`) conservatively retains such entries because they may be dynamically referenced; it does not attempt dead-key reachability analysis. The verifier prescribes the existing `sync:localization-runtime-catalog` generator.
Independently compared flattened JSON before/after generation and the deleted callsites: exactly 20 added entries, zero removed or changed entries, all 20 keys present in the removed setup UI/search code. The uncompressed generated file grows by 1,136 bytes. There is no unrelated generator churn and no restored UI or search registration. Regenerating this single derived catalog is the smallest conservative correction; pruning locale translations requires a broader dynamic-key/locale audit, and changing the verifier would weaken an unrelated contract.
**No new P0/P1; accepted P2:** some obsolete English text remains in the boot catalog under its existing conservative policy. This does not restore setup split behavior. Lead's final receipt (`msg_83f4e9157231`) reports the remaining nonnative gates passed: localization catalogs/extraction/coverage using the CI Bun commands, feature-wall budget, macOS entitlements, and preload/shared declaration guard. The unit-plan script completed its local full-reference fallback, which is not itself proof of the CI plan; lead separately reports the actual CI plan and all static steps preceding catalog verification, including Typecheck, had passed. No local correction-validation item remains pending. Fresh exact-head full PR CI and parent merge approval remain required after the correction commit.
### Round 8 — stale listener-savings arithmetic
Verified committed catalog head `35f132ba2547422cb6e11e00d1b631528fdab424` matched Round 7. A required unit shard then failed `terminal-pane-store-subscription-budget.test.tsx`. Independently traced the exact assertions: the live per-pane budget remains 15 and its assertion passes; the failure is the later equation `45 - 15 = actionKeys.length + 6`, where the action list is now 23, making the right side 29 rather than 30. It is not a measured increase to 30 live subscriptions.
PR 2 removed `consumeTabSetupSplit` from the stable `useMemo`/`getState` action binding and removed a `useState` initializer that reads `pendingSetupSplitByTabId` through `getState`. Neither opened a subscription. The `PRE_FOLD_LISTENERS_PER_PANE` comment defines a counterfactual current mount with one listener per bound action, not an immutable historical observation. Bounded history corroborates its intended updates: `3e25fe70f6b` lowered 46 to 45 for removal of `readTerminalPaneOnInput`; `93baa828be9` lowered 50 to 46 for four removed actions. Both retained the actual live budget.
The reviewed correction changes only `PRE_FOLD_LISTENERS_PER_PANE` from 45 to 44 and makes the stale action-count comment count-neutral. The exact 15-listener assertion, linear scaling, zero-listener stable-action binding and action identity assertions remain unchanged. This is smaller than introducing a retired-action offset or changing the test model, and does not loosen any live performance limit. **No new P0/P1/P2; prior accepted P2 limitations remain.**
Lead's receipt (`msg_278eaae4e38e`): the exact Bun path reproduced one savings-equation failure with three tests passing before the change; all four passed afterward, and the changed-code gate against the exact PR 1 baseline passed. No product source changed. Existing product validation remains applicable; fresh exact-head full CI and parent merge approval remain separate pending gates.
---
### Automated Setup Tab Design (`docs/automated-setup-tab-design.md`)
# Automated workspace setup: dedicated Setup tab
Status: design converged; implementation, local validation, and independent source review complete. Exact-head CI and merge authorization are tracked by [PR #29819](https://github.com/stablyai/orca/pull/29819).
## Decision and boundary
Run terminal-backed automated workspace setup in its own **Setup** tab using the existing new-tab path. Remove automated setup split placement, its preference/control, and its one-shot split/geometry state. Keep manual splits, issue-command splits, generic startup consumption, saved layouts, default-tab policy, and setup-to-agent sequencing.
This is PR 2. [PR 1 (#29810)](https://github.com/stablyai/orca/pull/29810) separately fixed background native-chat setup provisioning and merged first as `7f9b51cf5cc1de8769baa646b40c0c93af76be81`. This branch was rebased onto that exact merge before final review and relevant checks. Parent chat-publication and sibling-reattachment fixes, broad terminal ownership, corrupt saved-binding repair, and retries are outside this PR.
## Evidence and severity
* Confirmed pre-change mechanism: `shouldSeedWorktreePrimaryTerminal` treated split setup as a reason to create a shell even when the caller supplies native chat. Renderer `queueSetupAndIssueCommands`, runtime `provisionWorktreeTerminals`, and `spawnLocalStartupAndSetupTerminals` in `worktree-remote.ts` each branched on setup location. This PR reuses their existing dedicated-tab arms.
* The supplied incident investigation observed two leaves bound to one PTY and an independent equal-count chat-publication failure. This worktree does not establish the original missing-binding cause or two setup executions. Removing placement complexity is the user-requested product policy; it is not proof of fixing every frozen terminal.
* No demonstrated P0. P1 acceptance risks are replaying setup after host provisioning, losing requested startup/setup sequencing, or changing primary selection/background workspace selection. The validation below exercises actual creation routes and the preserved one-shot startup mechanisms.
* P2 tradeoff: automatic side-by-side setup placement disappears; manual splitting remains. Older execution hosts can still return existing split layouts, which updated clients must accept without moving/replaying setup.
* The first-terminal delayed delivery coupling exists in `ensureWorktreeHasInitialTerminal` for runtime-owned fallback commands. Ordinary desktop structured creation passes no backend startup and returns setup through local IPC, then uses host authority `none`, so its null-primary Setup path is already independent. The host native-chat route normally consumes setup before returning. Keep delayed delivery unchanged: no actual request proves the alleged native-chat P1. The post-PR-1 semantic review found no reason to expand this scope. The conditional STA-9417 expected-failure fixture does not establish the original incident's cause.
## Surfaces and selection
| Intent | Surfaces owed by this create with setup |
| --- | --- |
| Native chat | Requested chat plus Setup, without a split-anchor shell. |
| Terminal agent | Requested agent terminal plus Setup. |
| Plain terminal | Normal primary terminal plus Setup. |
| Setup only | Setup alone; preserve current suppression of default tabs. |
| Explicit default tabs | Existing template allocation/commands/title/color policy plus Setup. |
| No setup | Existing behavior. |
Issue automation retains its independent split from the normal primary pane, command/env, one-shot behavior, and focus policy. Setup stays unselected when another primary surface exists. Setup-only can select Setup when creation is still in view. Background creates/navigation away preserve workspace/tab selection and never reveal/focus a native window.
## Small existing mechanisms
1. Renderer: always create Setup with `pendingStartup`, title it through `setTabCustomTitle`, and preserve active primary/background options. Remove the location input from primary-shell and setup-only decisions. Retain host-spawn-result handling: `runtime-local-worktree-terminal-startup.ts` and local IPC omit consumed setup from fallback results, and remount restores its existing surface.
2. Runtime host: always `createTerminal` titled Setup; retain command construction, env, completion token/returned handle, fallback surface, `surfaceOwner`, and default-tab dressing. Remove setup's use of `splitTerminal` without changing generic split APIs.
3. Local IPC creation (`spawnLocalStartupAndSetupTerminals` in `worktree-remote.ts`): always use the existing new-tab branch; preserve platform runner/shell selection, sequencing wrapper, `activate: false`, and host authority. Accept old-host startup/layout evidence as authoritative.
4. Delete `pendingSetupSplitByTabId`, queue/consume actions, setup props/captured refs/bootstrap branch, setup-only geometry waits. Preserve generic geometry/resize functions used elsewhere and startup identity consumption. Do not remove regression purpose when updating fixtures: use manual/saved or issue-command splits for generic restore, purge, remount, and PTY ownership coverage.
5. Remove the Setup Script Location section and search registration. No new style/token/component is needed; follow `docs/STYLEGUIDE.md`.
## Settings and mixed versions
The implementation deletes `setupScriptLaunchMode` from live `GlobalSettings`, defaults, and launch types, and adds it to existing `stripRetiredGlobalSettings` so stale load/update/save keys are dropped. Remaining setting inputs are deliberate legacy-profile regression fixtures. There is no dead normalization or shared type retained for an unproven peer requirement.
Current `SettingsUpdate` is a strict explicit client-settings allowlist without this key; `RuntimeClientSettings` and `RuntimeClientSettingsUpdate` also omit it. Independent bounded history confirms the initial paired schema/projection at `b1973657ea6` (2026-05-21) and the pre-generated schema/types at `c84007c541d^` omit it; targeted key-history finds no paired-field introduction (see the Astra report for paths). Retire through the existing stripper, which already covers load, update and serialization; do not add a new normalization layer. Hosts own placement: an updated host ignores retired settings, and an old host may still produce a split. Updated clients accept returned layouts without replay or migration. Removing a client setting cannot force old hosts to adopt the new policy.
No protocol field/opcode, live-layout migration, scheduler, ownership store, command-string deduplication, or retry machinery is proposed. Runner arguments/env/cwd, Windows batch/shebang, WSL/SSH paths, and setup completion remain with existing functions.
## Alternatives
Changing only the default retains legacy split behavior and lifecycle complexity. Keeping the setting while ignoring it retains an unused contract unless actual old-peer evidence requires it. Moving all setup provisioning into a new service duplicates existing working paths and crosses PR 1. General binding enforcement and saved-layout repair solve broader problems and need separate evidence/design. Independent design and actual-diff review found no known smaller adequate approach; this is a scoped engineering judgment, not a mathematical optimality claim.
## Validation and review gates
Before implementation: Astra round 1 found no demonstrated unresolved P0/P1 in this scoped design, with concrete route/settings evidence and no known smaller adequate approach. Round 2 confirms the corrected local-IPC label, historical settings evidence, unchanged first-terminal delivery and strict PR 1/publication/reattachment boundary. The independent report is `docs/automated-setup-tab-astra-review.md`; implementation review remains separate.
Meaningful automated coverage: renderer/native-chat/terminal/setup-only/default-tab/background actual requests, host/remote no-split command/env preservation, sequencing/failure fallback, old-host returned layout/no replay, remount one-shot startup, issue-command/manual split/restore/purge regression intent. Run relevant tests with `ORCA_BACKGROUND_LAUNCH=1`, node/web typechecks, changed-file code-quality and format checks. Preserve platform-specific runner tests; report platforms actually exercised.
Rendered checks require rebuilt hidden Electron plus Playwright CDP; inspect tab count/selection/setup output and retained manual splits, with before/after evidence. The installed agent-browser CLI provides the version-matched Electron skill (`agent-browser skills get core`, then `agent-browser skills get electron`), now read; use it alongside Playwright CDP. The coordinator serialized the shared native-runtime lease after an initial local rebuild failure; the supported rebuilt hidden-app checks subsequently passed.
After implementation: Astra reviews actual final diff/tests and semantic overlap after PR 1 rebase. No merge until PR 1 confirmation, exact-head full `.github/workflows/pr.yml` successful aggregate `verify` / PR checks passed and all required checks, and parent approval through the mandatory blocking merge-gate ask. Use `--match-head-commit` and confirm the merge.
## Implemented validation record
Reviewed source head: `d96ae2ca6afdca919b4d7f8d85308363abe8b28b`, based on the exact PR 1 merge above. The follow-up documentation commit changes no source behavior. The independent review records no unresolved P0/P1 and explicit P2 tradeoffs.
- **Node tests:** final consolidated post-rebase selection passed 34 suites and 1,816 tests; two existing conditional expected-failure cases and two skips remain visible. The selection includes composed native-chat create payload/RPC/host routes for Claude and Codex, retired locations, setup-only/default tabs, wrapper/env/shell construction, failure fallback, one-shot startup, old-host layouts, manual/issue splits, remount, restore, sleep and purge behavior.
- **Types and static checks:** node/web typechecks, changed-file code-quality gate and staged Oxlint/format checks passed. The extra e2e project still reports 261 baseline diagnostics; baseline/final comparison by file and TypeScript error code found none added. This is not a clean e2e-project typecheck. A Bun `node:sqlite` suite-loader failure was avoided by executing the complete selected suites with the supported `test:node` command; no test-routing refactor is included.
- **Real rendered before/after:** rebuilt e2e-mode Electron host and paired client, both hidden, legacy vertical-split preference. Before: one terminal tab and two panes. After: Terminal 1 and Setup tabs, one Setup pane. Both displayed the real setup completion marker, retained background tasks selection, and supported another manual split. Post-rebase after-proof passed again. Screenshots are attached to the PR outside the source diff.
- **Rendered agent surfaces:** actual paired `agent.launch` created Claude native chat plus Setup with no shell anchor; the empty chat composer rendered and no prompt/model turn was submitted. A terminal-agent fixture CLI launched separately beside Setup and displayed its marker. Every native window was asserted hidden and unfocused.
- **Coverage retention:** the public `terminal.split` API activates by design, so its host layout fixture explicitly navigates away and tests reactivation. Genuine conditional old-host first-activation ownership/no-replay assertions remain in the unit fixture. Its expected-failure reconstruction is not presented as incident-cause proof.
- **Platforms actually executed:** macOS local Electron host plus paired desktop client. Windows/WSL command construction is tested, while live Linux, Windows, WSL and SSH execution were not performed. Existing saved layouts remain intact, and old execution hosts can still publish split layouts until upgraded.
Design/Astra artifacts are intentionally preserved in this PR. One-off probe sources and raw local logs live under ignored `.bench-fixtures/setup-split-removal-proof`; no images, profiles, auth data, or temporary test spec are committed. Merge still requires the exact current head's full PR workflow aggregate and all required checks, then the parent's mandatory blocking merge-gate approval.
---
### Native Chat Setup Provisioning Design (`docs/native-chat-setup-provisioning-design.md`)
# Native-chat background setup provisioning
## Problem and evidence
A structured native-chat creation deliberately omits terminal startup in `worktree-creation-flow-execute.ts`, while passing the selected agent as `createdWithAgent`. `buildRuntimeWorktreeCreateParams` and the RPC `buildManagedWorktreeCreateArgs` preserve that agent and leave activation false when startup is absent. The execution host therefore handles this as background creation, even when the renderer later opens the chat.
The host already treats a submitted agent as a caller-provided surface for background creation without setup. With setup/default tabs, `provisionArgs` instead recognizes only the internal `promisedAgentChat` flag. In new-tab setup mode this inconsistency creates an idle shell before Setup. Renderer-only tests returning unprovisioned setup do not exercise that host decision.
## Proposed policy
Use one host-local caller-surface predicate for terminal provisioning and fallback shell seeding: explicit `promisedAgentChat` always counts; submitted `createdWithAgent` counts only when neither `activate` nor `runHooks` is true. These are transient inputs to this create, not persisted workspace metadata. Apply the same predicate whether or not setup/default tabs exist.
Continue using `shouldSeedWorktreePrimaryTerminal`: a real startup, issue work, existing default terminal, setup-only choice, and split setup anchors retain their existing precedence. Activated attribution-only requests still owe a primary terminal; attribution must not become an activation promise. Preserve every setup split mode and current setup sequencing, surfacing, completion, and failure behavior.
## Scope and compatibility
Change only the host startup policy and regression coverage. No new RPC field, surface store, ownership/retry redesign, split removal, process command change, or UI styling. Renderer and RPC already transmit enough information for the existing background policy; a new wire intent would duplicate that policy and leave older clients unfixed. Old clients benefit when connected to the updated execution host; updated clients connected to old hosts retain the old behavior. Nothing changes execution-host ownership or introduces client-local SSH fallback.
Folder creation has its own matching no-setup background policy and no automated setup provisioning path; retain it and cover its existing contract. The shared host policy is platform independent and leaves macOS/Linux/Windows/WSL runner construction unchanged. Manual splits, explicit commands, issue automation, default tabs, and startup failures remain owned by their existing mechanisms.
Background attribution-only callers intentionally inherit their established no-setup policy. The pre-existing conditional issue-only/first-terminal coupling and asynchronous setup failure reporting are P2 follow-ups outside this change; successful setup/default provisioning still supplies the terminal used for queued issue work. Independent Astra design review accepted this scope with no P0/P1 before implementation.
## Verification
Add coverage that feeds actual structured renderer creation arguments through the production payload builder, RPC schema/argument mapping, host startup, and real terminal provisioner, recording created terminals. New-tab setup should create Setup alone for background native chat, while blank/background creation still receives its shell. Cover both agents, activated attribution-only creation, run-hooks, promised chat, explicit startup, default tabs, split anchors, and setup-only/failure behavior using existing tests where adequate.
Demonstrate the regression failing against the original policy and passing after the change. Run relevant renderer/runtime/RPC/provisioning/folder tests, node and web typechecks, and changed-file format/lint checks with `ORCA_BACKGROUND_LAUNCH=1`. No platform or rendered UI result is claimed without an actual run. Independent Astra review must converge before implementation and review the final diff with no unresolved P0/P1; record P2 dispositions in the review report.
## Results
The original policy failed both agent regressions by spawning an undefined-command shell before Setup; nine controls passed. With the fix, seven selected suites passed 1,451 tests with one existing skip; 15 focused route/promised-chat controls and four first-surface tests also passed. Node/web typechecks, changed-file lint, formatting, and the Electron e2e build passed on macOS ARM64.
A temporary Playwright probe used isolated hidden host/client apps, the production renderer create action with `createdWithAgent: codex` and no startup, real RPC/PTY provisioning, host terminal inventory, and DOM tab-strip assertions. The baseline host rendered two terminal tabs; the fixed host rendered Setup alone. Both runs passed hidden/unfocused-window assertions and captured CDP screenshots. This verifies the terminal provisioning behavior, without claiming a real structured-agent launch or live SSH/Windows/Linux/WSL run. Probe source, logs, and screenshots are retained locally under `.bench-fixtures/native-chat-setup-proof/`; screenshots are attached to the PR, not committed. Final source was restored and rebuilt after the baseline capture.
---
### Native Chat Setup Provisioning Review (`docs/native-chat-setup-provisioning-review.md`)
# Independent native-chat setup provisioning review
## Design verdict
Accepted before implementation and after final diff/test review: no unresolved P0/P1 findings. All P2 concerns have explicit dispositions below.
The reviewed design is `docs/native-chat-setup-provisioning-design.md`. Review is confined to this worktree; this report is the reviewer's only edited file.
## Root cause and simplest mechanism
The structured route in `worktree-creation-flow-execute.ts` deliberately omits terminal startup and startup draft, but supplies the selected agent. `worktree-create-payload.ts`, the RPC schema, and `worktree-create-args.ts` preserve that attribution. No startup means no activation request from this payload builder.
`runtime-local-worktree-terminal-startup.ts` already suppresses a fallback shell for a background create with either `promisedAgentChat` or `createdWithAgent`. Its setup/default provisioning branch supplies only `promisedAgentChat` to `callerProvidesSurface`. The extra shell is therefore a disagreement between two branches of the same host policy.
Use the existing background policy consistently. Keep explicit `promisedAgentChat` unconditional, and count submitted agent attribution only when neither `activate` nor `runHooks` is true. A new RPC flag is unnecessary: it duplicates existing intent and would leave older clients' requests unfixed. Do not infer this from persisted worktree metadata or introduce a surface store.
## Challenges and dispositions
| Concern | Severity | Disposition |
| --------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attribution is weaker than an explicit chat promise. | P2 | Accepted existing background policy, not a new universal interpretation. Activated/run-hooks attribution-only creates must retain a primary surface. |
| A new unconditional chat promise could strand renderer issue commands waiting for a terminal. | P1 candidate | Withdrawn for the chosen design: no-setup policy is unchanged, while successful setup/default provisioning supplies a mirrored terminal. No new wire promise is being added. |
| Renderer-only setup tests cannot catch the execution host's extra shell. | P2 | Require a regression through production payload/schema/mapper and host startup/provisioner, with real creation argument evidence. |
| Older clients and hosts may differ. | P2 | No wire change: new hosts apply the corrected policy to existing requests; old hosts retain the known extra shell. No capability negotiation or client-local fallback needed. |
| Setup spawn failure and renderer issue-only delivery have existing asynchronous limitations. | P2 | Keep out of this policy correction; do not claim these are repaired. Preserve current setup receipt/return behavior and failure controls. |
## Invariants checked during design review
- Execution host retains terminal provisioning and setup ownership; navigation does not choose another execution host.
- The shared first-surface predicate still requires anchors for both setup split orientations and real terminal startup.
- Configured default tabs remain explicit work; they are not discarded to make the terminal count smaller.
- Setup runner construction, quoting, environment, sequencing, completion observation, and shell selection remain untouched across macOS/Linux/Windows/WSL.
- Native IPC returns setup to the renderer; paired/runtime creation reaches the host policy under review. No direct SSH fallback is introduced.
- Folder workspace creation has a separate background no-setup policy and no corresponding setup-provisioning branch; preserve it.
- Manual splits and issue command queuing remain in their existing paths. No claim is made that a setup terminal is itself a structured agent surface.
## Final verification
Final review requested and performed on the production predicate, route regression, renderer assertions, explicit promised-chat controls, and node typecheck inclusion. No unresolved P0/P1 found. Final `git diff --check` passed.
The sole production change replaces both branch-specific decisions with `callerProvidesInitialSurface`. The original no-setup branch can execute only when activation/run-hooks are false, so adding those guards to the common predicate does not change its behavior. Setup/default provisioning is the only newly affected branch. Explicit startup still supplies `startupNeedsTerminal`; successful startup/default terminals still count as existing primary surfaces; split modes still override suppression.
The route regression invokes the production renderer payload builder, RPC schema/mapper, runtime creation, and terminal provisioner. The renderer test separately checks the actual execute call's selected agent, absent startup, and absent startup draft. This is composed route evidence, not a rendered end-to-end UI test. The runtime fixture waits for provisioning to observe terminal calls deterministically.
Reviewed the lead's pre-fix log `/tmp/orca-native-chat-before.log`: both agent cases failed on the unexpected `undefined` command preceding Setup, while nine controls passed. Reviewed `/tmp/orca-native-chat-tests.log`: seven files passed, 1,451 tests passed and one skipped. Supplemental validation is attributed below.
P2 test hardening resolved during final review: the split control now asserts that `ORCA_TAB_ID` is a nonempty string before comparing the two panes' values.
Independent baseline run: `ORCA_BACKGROUND_LAUNCH=1 pnpm test` for `runtime-local-worktree-terminal-startup.test.ts`, `runtime-worktree-terminal-provisioning.test.ts`, `runtime-folder-worktree-create.test.ts`, and `rpc/methods/worktree-create-args.test.ts` passed all 37 tests in four files. These existing tests establish controls; they do not demonstrate the new regression fix.
The added node typecheck include names only the pure, type-only-importing renderer payload builder used by the regression; it follows existing cross-layer fixture includes and introduces no runtime renderer dependency.
Lead-reported supplemental validation: 15 focused promised-chat/route controls and four `worktree-agent-first-surface` controls passed; node/web typechecks exited zero and changed-file lint passed. The reviewed final source contains the corrected predicate and the strengthened split assertion.
The coordinator explicitly closed the independent code review after these checks. Any hidden-renderer before/after proof is lead-owned and is not an independently verified claim in this report. The reviewer launched no application or visible window. No live SSH, Windows, or WSL validation is claimed; compatibility conclusions concern the unchanged routing, wire contract, and runner code.
---
### Cloud Docs Relay Security 2026 10 21 (`cloud/docs/relay-security-2026-10-21.md`)
# Relay security review — 2026-10-21
This review covers the checked-in Cloud workspace, its production and development
dependencies, relay/push/fence-broker container images, the Cloud SQL Auth Proxy,
Terraform provider binaries, and the configured COS host release. No deployment,
Terraform apply, or live resource mutation was performed.
The relay and push runtime images have zero reported vulnerabilities. The broker
has one advisory without an upstream fix. **The complete stack is not free of
known findings:** the latest official proxy and Terraform providers still embed
vulnerable dependencies. See the complete dated
[finding inventory](../security/findings-2026-10-21.json).
## Scan results
Counts are package/advisory instances, not unique CVEs or confirmed reachable
exploits. Container and provider scans target Linux amd64, matching the current
Cloud deployment. Trivy's advisory database was updated at
`2026-10-21T19:18:22Z`.
| Surface | Scanner | Before | After |
| --- | --- | --- | --- |
| Cloud production and development dependency graph | pnpm audit | 0 | 0 |
| Dependency graph, independent advisory source | OSV Scanner 2.7.0 | 0 | 0 (174 packages) |
| Relay runtime image | Trivy 0.76.1 | 12 | 0 |
| Push runtime image | Trivy 0.76.1 | Not captured | 0 |
| Fence broker runtime image | Trivy 0.76.1 | Vulnerable Debian, npm, Python and Terraform dependencies | 1 UNKNOWN, no fix |
| Cloud SQL Auth Proxy | Trivy 0.76.1 | 109 | 3: 1 HIGH, 2 UNKNOWN |
| Installed Terraform providers | Trivy 0.76.1 rootfs | 241 | 49: 12 HIGH, 32 MEDIUM, 3 LOW, 2 UNKNOWN |
| Cloud source snapshot secrets | Gitleaks 8.30.1 | 0 | 0 |
| Cloud source static security analysis | Semgrep 1.181.0 | 0 | 0 |
The final Semgrep scan ran `p/security-audit`, `p/javascript`, and
`p/typescript`: 101 applicable rules, 668 files, approximately 99.9% parsing.
A retry of 26 files resolved rule timeouts with a two-worker, 60-second
per-rule limit. Two partial-parser warnings affected tests (`apns-session-replacement.test.ts`
and `host-whereabouts-app.test.ts`). This is automated source analysis, not a
claim that every execution path was manually audited.
Trivy's source/configuration scan reported four LOW configuration findings:
three Dockerfiles without Docker HEALTHCHECK instructions, and a GCS bucket
without customer-managed encryption keys. GCP supplies the runtime health checks;
changing the bucket's encryption policy is an infrastructure policy decision.
Terraform scans with default inputs do not establish the live IAM/network policy.
## Updates
- Digest-pin Node 24.22.1 Alpine runtime/build images. Remove global npm,
Corepack, Yarn and pnpm plus their caches after installing production modules.
Exclude nested Terraform caches/state, node_modules, dist and environment files
from Docker contexts so a local build cannot embed stale providers or secrets.
Relay's twelve original image findings were entirely in the bundled npm tree.
- Upgrade Cloud workspace libraries and tooling to the current releases:
Hono/node-server 2.1.5, Hono 4.13.13, pg 8.23.1,
pg-connection-string 2.14.1, google-auth-library 11.3.1, Zod 4.6.7,
TypeScript 7.0.2 and Vitest 5.0.5, with current compatible type packages.
Keep Node typings on 24 and the compiler API test alias on TypeScript 6.0.3;
TypeScript 7 no longer provides that API. Adapt Zod record/introspection calls
and explicitly include Node types. Wire contract fields and versions stay the same.
- Pin the broker to Google Cloud CLI 590.0.0 Alpine and Terraform 1.17.0.
Upgrade the SDK's actual vendored certifi/urllib3 using hash-locked requirements.
Remove unused bq/gsutil, pip/wheel, and the vulnerable compiled CRC helper.
Use gcloud's Python checksum implementation instead. Install libstdc++ for the
Alpine Node runtime. The broker continues to run as uid 10001.
- Pin the official Cloud SQL Auth Proxy v2.26.2 by digest, replacing the old
image. Its existing Unix socket, private IP and Cloud Run options are retained.
- Upgrade all Cloud workflow Terraform installations to 1.17.0. Lock Google
provider 8.8.0, external 2.4.2 and random 3.9.1, including Linux/macOS/Windows
checksums. Review the Google provider
[v7](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/version_7_upgrade)
and [v8](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/version_8_upgrade)
migration notes before rollout. Preserve the prior instance-template disk
defaults explicitly; load balancer schemes were already explicit.
- Update staging, production, and newly generated Asia cell inputs to
`cos-121-18867-638-13`, the October 19 security release on the existing COS 121
LTS milestone. Accept versioned LTS image names as well as legacy `cos-stable`
names in validation. COS 121 remains supported through March 2027. This is
release-note verification, not a scan of a running host or boot disk.
## Remaining upstream findings
- `GO-2026-5932`: the Go OpenPGP package is unmaintained and unsafe by design.
Trivy reports the containing `golang.org/x/crypto` module in Terraform,
the proxy, and two providers. No fixed module version is published; module
presence alone does not establish that the affected OpenPGP functions execute.
- Proxy `CVE-2026-111943` (HIGH): official v2.26.2 embeds Go 1.27.2; the
advisory requires Go 1.27.3 or 1.26.10. Proxy `DSA-6572-1` (UNKNOWN): the
official distroless image predates the Debian ca-certificates rebuild.
No newer official proxy release was available at review time.
- The latest external/random provider binaries embed Go 1.26.8; Google 8.8.0
embeds Go 1.26.9. Additional findings affect their embedded x/net, x/crypto,
and OpenTelemetry SDK versions. Updating a Terraform lockfile cannot patch
dependencies inside signed upstream executables. External has 19 instances,
Google 10, and random 20; all are itemized in the inventory.
Govulncheck 1.9.0 additionally analyzed the exact Linux amd64 Terraform, proxy,
and provider executables in binary symbol mode. The inventory records its
strongest evidence for each matching Go finding. OpenPGP is module-only in the
proxy, while its affected symbols are linked into Terraform, Google and random.
The proxy's affected `crypto/x509.Certificate.Verify` symbol is linked. These
checks establish linked code, not runtime exploitability or a production call
trace; the original Trivy findings remain visible.
| Binary | Unique Go advisories at module level | With affected linked symbols |
| --- | --- | --- |
| Terraform 1.17.0 | 1 | 1 |
| Cloud SQL Proxy 2.26.2 | 2 | 1 |
| Google provider 8.8.0 | 10 | 9 |
| External provider 2.4.2 | 13 | 13 |
| Random provider 3.9.1 | 14 | 14 |
CI retains unfiltered JSON and CycloneDX inventories for every runtime image and
installed Terraform providers, including these findings. Runtime image checks
reject advisories with available fixes at every severity. Only the two specific
proxy rebuild findings have a documented exception, expiring **2026-11-04** in
[the proxy exception file](../security/cloud-sql-proxy.trivyignore.yaml).
Unfixed runtime findings remain in the full reports. Provider scanning is
report-only while upstream binaries retain the findings above; it is not a
provider security approval gate. No global severity exclusions were added.
## Reproduce
Run from a fresh checkout; this is an independent pnpm workspace.
```sh
pnpm --dir cloud install --frozen-lockfile
pnpm --dir cloud audit
pnpm --dir cloud audit --prod
osv-scanner scan --lockfile cloud/pnpm-lock.yaml
gitleaks dir cloud --config cloud/.gitleaks.toml --redact
semgrep scan --config p/security-audit --config p/javascript --config p/typescript --metrics off --jobs 2 --timeout 60 --timeout-threshold 0 cloud
docker build --platform linux/amd64 -f cloud/apps/relay/Dockerfile -t orca-relay-security cloud
trivy image --scanners vuln --ignorefile '' orca-relay-security
```
Cloud Verify additionally builds push and broker (supplying the exact checkout
SHA as `ORCA_RELAY_FENCE_IMAGE_COMMIT`), resolves the proxy from Terraform, tests
nonroot runtime imports and broker tools, and scans installed provider binaries
after backend-free initialization. It needs no GCP credentials and publishes no
images. The existing full-history Gitleaks and snapshot TruffleHog checks remain.
## Validation and rollout
Cloud build and typecheck passed. Relay unit tests passed 1,249 tests with one
existing skip; all 217 PostgreSQL tests passed on a fresh, dedicated database
in an isolated run. Other Cloud packages passed 561 tests, Cloud pretests/runner
passed 233 tests, deployment scripts passed 889 tests, and the root secret-history
workflow tests passed 2 tests. Earlier concurrent runs encountered load-sensitive
contention assertions; reusing their database also exposed retained test fixtures.
No test assertions or timeouts were weakened. The isolated database suite passed
all 44 files. YAML/shell linting of the new workflow steps and the changed-code
quality check passed; Cloud source was additionally checked with Oxlint. The
installed actionlint predates the existing background/wait workflow syntax, so
that unchanged syntax was removed only from a temporary lint input.
Broker checks include Node module loading, gcloud startup, a known CRC32C value
through the Python fallback, Terraform version, backend-free initialization, and
configuration validation. Provider initialization validates signed checksums for
Linux amd64/arm64, macOS amd64/arm64, and Windows amd64; execution was tested on
Linux amd64. No native-focus or desktop UI testing is needed for these changes.
The local GCP session requires reauthentication. Live image inventory, live COS
versions, Cloud SQL maintenance state, deployed IAM/network configuration and
state-backed Terraform plans were therefore **not verified**. No assertion is
made that the deployed fleet already contains these updates.
Before deploying, recheck proxy/provider releases and the remaining advisories.
Build and publish the updated relay, push and broker images through the existing
release process and bind their immutable digests to the rollout inputs. Review
fresh staging and production Terraform plans with valid credentials, paying
particular attention to provider schema changes, the proxy digest, and expected
COS instance-template replacements. Canary staging before rolling production
cells through the existing drain/fencing flow. Preserve prior immutable images
and the versioned Terraform state for recovery; a provider downgrade after
state migration requires its own review. This PR does not perform those steps.
Sources: [Node releases](https://nodejs.org/dist/index.json),
[Cloud SQL Proxy releases](https://github.com/GoogleCloudPlatform/cloud-sql-proxy/releases),
[COS 121 release notes](https://docs.cloud.google.com/container-optimized-os/docs/release-notes/m121),
[COS support policy](https://docs.cloud.google.com/container-optimized-os/docs/concepts/versioning),
[OpenPGP advisory](https://vuln.go.dev/ID/GO-2026-5932.json).
---
### Bug Reproductions Daemon Async Io Stall (`docs/bug-reproductions/daemon-async-io-stall.md`)
# Terminal daemon asynchronous I/O stall
Observed on macOS arm64 on 2026-10-15. The installed app was
`1.4.227-hourly.202610150643`; the preserved v45 daemon was
`1.4.225-adhoc.20261012205540`, running Node 24.21.0 and libuv 1.52.1.
## What was proved
- The affected daemon answered authenticated control RPCs and its existing
`ptySpawnHealth` probe. It owned 213 running sessions.
- Input sent through the CLI and directly through the daemon's `write` RPC did
not appear in a selected terminal. Its native `CustomWriteStream` retained
141 queued chunks / 1,250 bytes, with no retry timer. The shell-ready gate
was open, and the native handle was neither dead nor marked I/O-failed.
- A synchronous write to that same nonblocking master fd immediately appeared
in the agent's input. The diagnostic text was removed without submitting it.
Resizing also reached the real terminal, and output was still received.
- Independent asynchronous filesystem stat and crypto requests did not complete
while timers and socket RPCs continued working. Process samples showed all
four libuv workers idle. This is evidence of stalled asynchronous work or
completion delivery, **not proof of thread-pool saturation**.
- The production `DaemonAsyncIoProbe`, evaluated in that affected daemon,
returned `stalled` at 5,000.8 ms. The debugger was closed afterwards.
## Cause and remaining investigation
The immediate failure is below the renderer: native asynchronous writes stop
completing, and later keystrokes accumulate behind the first pending write.
New terminals can also block on asynchronous working-directory checks.
The initial runtime/native trigger is **not established**. No evidence yet ties
it to a specific patch, an update, sleep/resume, workload size, or a protocol
version mismatch. Increasing the thread pool, replaying queued input, replacing
the writer with synchronous calls, or restarting healthy daemons is not a
validated prevention fix.
An older build remained alive intentionally: bundle freshness must not terminate
existing terminal processes. This explains why an app update did not replace
this daemon; it does not explain what first stopped its asynchronous work.
## Isolated symptom reproduction
On macOS/Linux, with dependencies prepared for the Node runtime:
```sh
ORCA_BACKGROUND_LAUNCH=1 node config/scripts/ensure-native-runtime.mjs --runtime=node
ORCA_BACKGROUND_LAUNCH=1 UV_THREADPOOL_SIZE=1 node config/scripts/repro-daemon-async-io-stall.mjs
```
The script owns an isolated real PTY and blocks its one filesystem worker with a
FIFO open. It proves that native spawn/exit still passes while asynchronous input
and a working-directory stat stop completing, synchronous input still arrives,
and the production detector reports `stalled`. Releasing the FIFO delivers queued
input and restores `healthy`. It has a 15-second watchdog and never connects to
the user's daemon or sessions. This passed on macOS arm64 (Node 24.20.0), with
detection at 5,000.8 ms.
This reproduces the symptoms by fault injection, **not the original trigger**:
the incident's workers were idle, whereas this reproduction deliberately blocks
a worker. The asynchronous completion boundary is the shared failure surface.
## Detection and recovery contract
`terminal-daemon.async-io-progress`: a responding daemon whose asynchronous work
does not complete must not be represented as fully healthy solely because it
can start and exit a native shell. Detection must never infer process exit,
replay user input, or restart a daemon automatically.
The daemon probes an asynchronous stat of its own executable. Completion,
including completion with an errno, proves progress. A five-second deadline
reports a stall; the original operation stays owned until it actually completes.
Concurrent requests share it, so polling a permanently stalled daemon never
adds another filesystem request. Successful checks are cached for 30 seconds.
The daemon logs transitions as `async-io-stalled` and `async-io-recovered`.
The desktop checks every 30 seconds while the sidebar is mounted and the document
is visible, plus on focus/visibility changes. Checks coalesce and never enumerate
sessions or start terminals. A notice directs the user to the existing Manage
Sessions restart review, which requires confirmation before ending processes.
The new unary RPC is optional: old daemons return `unsupported`; lost contact or
an invalid response is `unverifiable`. Neither proves a stall. An affected old
daemon needs a deliberate restart onto a build with the probe before automatic
detection is available. Updating only the client cannot add instrumentation to
its already running daemon.
## Coverage and gaps
The experimental gate covers stalled/completing work, recovery, deduplication,
bounded timers/requests, old-peer compatibility, disconnected peers, notice
behavior, visibility gating, and unmount cleanup. The production probe also
identified this incident in the affected live daemon.
Local/daemon macOS evidence is covered. The probe is platform-independent, but
physical Linux, Windows, WSL and SSH deployments remain gaps. The notice describes
only this computer's current daemon. Paired web clients explicitly decline local
daemon inspection; remote/legacy daemon notices and hidden-sidebar surfacing are
not covered. Initial-trigger reproduction and a prevention fix remain open.
---
### Bug Reproductions Delayed Agent Launch (`docs/bug-reproductions/delayed-agent-launch.md`)
# Delayed terminal agent launches
## Reproduction (2026-10-12, macOS)
An isolated Orca dev instance ran off screen with `ORCA_BACKGROUND_LAUNCH=1`.
In a folder workspace, `terminal create --command 'sleep 30 && claude'` launched
real Claude Code 2.1.296 after the delay. SessionStart, working and done hooks
arrived, and a prompt requesting `DELAYED_LAUNCH_OK` completed. A blanket Claude
hook failure was **not** reproduced on this machine.
The same delayed command was captured through
`config/scripts/capture-agent-pty-transcript.mjs`. Its startup emits
`OSC 0;✳ Claude Code`, terminal capability queries, and the normal composer.
The capture was scanned for identifiers and credentials; raw output is kept
outside the repository.
Deterministic reproductions found these failures:
- All 45 configured harnesses lost hidden startup query eligibility behind
`sleep 30 &&`. The renderer query-delivery test also reproduced the drop.
- Delayed OpenCode 2 selected and installed OpenCode v1 hooks. Disabling the
requested version could install the other version instead.
- Delayed Pi, OMP and Prime launches lost explicit preparation of their own
integration. Managed OpenCode/Devin accounts and MiMo overlays also relied on
first-executable classification.
- Once foreground discovery exhausted its initial read window, a captured late
Claude startup title did not restart confirmation. The connection test left
process routing unset at 30 seconds.
After the fix, a fresh `sleep 30 && claude` launch gained process-confirmed
routing. Real turns running `sleep 8` and `sleep 20` completed with the requested
replies. CDP screenshots showed the working indicator during a turn and the done
indicator with the completed reply. Blocked, waiting and interrupted turns were
not exercised.
## Change and invariant
`agent-session.delayed-terminal-launch` in `config/reliability-gates.jsonc`
tracks this contract: a delayed launch retains harness preparation and hidden
terminal replies, while only the execution host can confirm a live process.
A shared, bounded scanner removes literal numeric `sleep … &&` prefixes **only
from preparation hints**. The shell receives the original command, including
the delay, arguments and conditional operator. Existing setup-sequence hints,
explicit harness choices, disabled integrations and account ownership retain
precedence. Process-table command recognition still treats the waiting shell
as a shell.
Callers use shared launch-token and launch-recognition APIs. Prefix handling is
contained in `src/shared/agent-command-line-intent.ts`; the setup-sequence resolver
continues to return its supplied command. Launch recognition reuses the existing
agent registry and headless filters without changing strict process recognition.
Fresh agent startup titles request one additional bounded confirmation sequence
when initial discovery has finished. A title never supplies process identity or
input-routing authority. An active read is preserved; title storms, cancellation
and close are covered by deterministic read-count tests. No recurring timer or
sleep-length polling was added.
## Coverage and remaining gaps
| Surface | Evidence |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| Local and daemon preparation | Plugin files, account environment and host spawn tests |
| Renderer replies and routing | Hidden query-delivery and captured late-title tests |
| macOS real Claude | Hidden Electron/CDP launch and completed prompt |
| SSH/remote-runtime | Shared classification; existing fenced process reads retained; no physical delayed launch |
| WSL | Shared Pi/OMP and OpenCode preparation; physical guest launch unproved |
| Linux/Windows | Platform-neutral classification and existing mock coverage; physical delayed launch unproved |
The scanner intentionally does not parse arbitrary shell programs, variables,
pipelines or background jobs. A late agent emitting neither a recognizable title
nor hooks still needs a later input or visibility observation. No RPC field or
stream opcode changed; mixed-version wire behavior is unchanged.
---
### Readme README.Es (`docs/readme/README.es.md`)
English · 中文 · 日本語 · 한국어 · Français · Português
El orquestador de IA para desarrolladores 100x.
## Características
### App companion móvil
Supervisa y dirige a tus agentes desde el teléfono — recibe una notificación cuando un agente termine y envía instrucciones de seguimiento desde cualquier lugar.
[App Store de iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [APK para Android](https://www.onorca.dev/download/android) · [Docs →](https://www.onorca.dev/docs/mobile)
### Worktrees en paralelo
Lanza un mismo prompt a cinco agentes, cada uno en su propio worktree de git aislado — compara los resultados y haz merge del ganador.
[Docs →](https://www.onorca.dev/docs/model/worktrees)
### Terminales divididas
Terminales de nivel Ghostty con renderizado WebGL, divisiones infinitas y un scrollback que sobrevive a los reinicios.
[Docs →](https://www.onorca.dev/docs/terminal)
### Modo diseño
Haz clic en cualquier elemento de UI en una ventana real de Chromium para enviar su HTML, su CSS y una captura recortada directo al prompt de tu agente.
[Docs →](https://www.onorca.dev/docs/browser/design-mode)
### GitHub y Linear, nativos
Explora PRs, issues y tableros de proyecto dentro de la app — abre un worktree desde cualquier tarea y revisa sin cambiar de contexto.
[Docs →](https://www.onorca.dev/docs/review/linear)
### Worktrees por SSH
Ejecuta agentes en una máquina remota potente con edición completa de archivos, git y terminales — con reconexión automática y reenvío de puertos incluidos.
[Docs →](https://www.onorca.dev/docs/ssh)
### Anotar diffs de IA
Deja comentarios en cualquier línea de un diff y envíalos de vuelta al agente — revisa, edita y haz commit sin salir de Orca.
[Docs →](https://www.onorca.dev/docs/review/annotate-ai-diff)
### Arrastra archivos a los agentes
El editor de VS Code con autoguardado en todas partes — arrastra archivos o imágenes directo al prompt de un agente.
[Docs →](https://www.onorca.dev/docs/editing/file-explorer)
### Orca CLI
Los agentes también manejan Orca — automatiza cualquier flujo de trabajo con `orca worktree create`, `snapshot`, `click` y `fill`.
[Docs →](https://www.onorca.dev/docs/cli/overview)
**También incluye:**
- **[Apertura rápida](https://www.onorca.dev/docs/model/quick-open)** — Busca entre worktrees, archivos, agentes, comandos y contexto del repo sin salir de tu flujo.
- **[Cambio de cuenta y seguimiento de uso](https://www.onorca.dev/docs/agents/usage-tracking)** — Consulta el uso de Claude y Codex y los reinicios de límites de uso, y cambia de cuenta al instante sin volver a iniciar sesión.
- **[Previews ricos del repo](https://www.onorca.dev/docs/editing/markdown)** — Previsualiza Markdown, imágenes, PDFs y documentos del repo en el workspace.
- **[Computer Use](https://www.onorca.dev/docs/cli/computer-use)** — Deja que los agentes manejen apps de escritorio y UI visible cuando un flujo de trabajo necesita interacción real.
- **[Notificaciones y estado de no leído](https://www.onorca.dev/docs/notifications)** — Entérate cuando un agente termine o necesite tu atención, y marca hilos como no leídos para retomarlos después.
- **Y muchas, muchas más** — lanzamos a diario, así que esta lista siempre va atrasada. El [changelog](https://github.com/stablyai/orca/releases) es la verdadera lista de funciones.
---
## Agentes compatibles
Funciona con **cualquier agente CLI** — si corre en una terminal, corre en Orca.
+ any CLI agent
---
## Instalación
### Escritorio — macOS, Windows, Linux
- **[Descarga desde onOrca.dev](https://onorca.dev/download)**
- O descarga un build directamente: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [Todos los builds](https://github.com/stablyai/orca/releases/latest)
_O mediante un gestor de paquetes:_
```bash
# macOS (Homebrew)
brew install --cask stablyai/orca/orca
# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin
```
### App companion móvil — iOS, Android
Vincúlala con tu app de escritorio para supervisar y dirigir a tus agentes desde el teléfono.
- **iOS:** [Descargar desde App Store](https://apps.apple.com/us/app/orca-ide/id6766130217)
- **Android:** [Descargar el APK](https://www.onorca.dev/download/android)
---
## Comunidad y soporte
- **Discord:** Únete a la comunidad en **[Discord](https://discord.gg/fzjDKHxv8Q)**.
- **Twitter / X:** Sigue a **[@orca_build](https://x.com/orca_build)** para novedades y anuncios.
- **Feedback e ideas:** Lanzamos rápido. ¿Te falta algo? [Pide una nueva feature](https://github.com/stablyai/orca/issues).
- **Privacidad:** Consulta la [documentación de privacidad y telemetría](https://www.onorca.dev/docs/telemetry) para saber qué datos anónimos de uso recopila Orca y cómo desactivar su envío.
- **Muéstranos tu apoyo:** Dale una [estrella](https://github.com/stablyai/orca) a este repo para seguir nuestros lanzamientos diarios.
---
## Desarrollo
¿Quieres contribuir o ejecutar Orca localmente? Consulta nuestra guía [CONTRIBUTING.md](../../.github/CONTRIBUTING.md).
## Licencia
Orca es libre y de código abierto bajo la [Licencia MIT](../../LICENSE).
---
### Readme README.Fr (`docs/readme/README.fr.md`)
English · 中文 · 日本語 · 한국어 · Español · Português
L'orchestrateur d'IA pour les builders 100x.
Sous Windows ? Prenez la dernière RC — elle inclut des correctifs Windows.
## Fonctionnalités
### Companion mobile
Surveillez et pilotez vos agents depuis votre téléphone — soyez notifié quand un agent termine, et envoyez des instructions de suivi où que vous soyez.
[App Store iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [APK Android](https://www.onorca.dev/download/android) · [Docs →](https://www.onorca.dev/docs/mobile)
### Worktrees parallèles
Lancez un même prompt sur cinq agents, chacun dans son propre worktree git isolé — comparez les résultats et mergez le gagnant.
[Docs →](https://www.onorca.dev/docs/model/worktrees)
### Splits de terminal
Terminaux de niveau Ghostty avec rendu WebGL, splits infinis et un scrollback qui survit aux redémarrages.
[Docs →](https://www.onorca.dev/docs/terminal)
### Mode Design
Cliquez sur n'importe quel élément d'UI dans une vraie fenêtre Chromium pour envoyer son HTML, son CSS et une capture recadrée directement dans le prompt de votre agent.
[Docs →](https://www.onorca.dev/docs/browser/design-mode)
### GitHub & Linear, natifs
Parcourez PRs, issues et boards de projet dans l'app — ouvrez un worktree depuis n'importe quelle tâche et reviewz sans changer de contexte.
[Docs →](https://www.onorca.dev/docs/review/linear)
### Worktrees SSH
Faites tourner des agents sur une machine distante costaude, avec édition de fichiers, git et terminaux complets — reconnexion auto et port forwarding inclus.
[Docs →](https://www.onorca.dev/docs/ssh)
### Annoter les diffs IA
Posez des commentaires sur n'importe quelle ligne de diff et renvoyez-les à l'agent — review, édition et commit sans quitter Orca.
[Docs →](https://www.onorca.dev/docs/review/annotate-ai-diff)
### Glisser-déposer vers les agents
L'éditeur VS Code avec autosave partout — glissez fichiers ou images directement dans le prompt d'un agent.
[Docs →](https://www.onorca.dev/docs/editing/file-explorer)
### Orca CLI
Les agents pilotent aussi Orca — scriptez n'importe quel workflow avec `orca worktree create`, `snapshot`, `click` et `fill`.
[Docs →](https://www.onorca.dev/docs/cli/overview)
**Aussi dans la boîte :**
- **[Quick open](https://www.onorca.dev/docs/model/quick-open)** — Cherchez parmi worktrees, fichiers, agents, commandes et contexte du repo sans quitter votre flow.
- **[Sélecteur de comptes & suivi d'usage](https://www.onorca.dev/docs/agents/usage-tracking)** — Suivez l'usage Claude et Codex et les resets de rate limit, et basculez de compte à chaud sans vous reconnecter.
- **[Aperçus riches du repo](https://www.onorca.dev/docs/editing/markdown)** — Prévisualisez Markdown, images, PDF et docs du repo dans le workspace.
- **[Computer Use](https://www.onorca.dev/docs/cli/computer-use)** — Laissez les agents piloter des apps desktop et l'UI visible quand un workflow demande une vraie interaction.
- **[Notifications et non-lus](https://www.onorca.dev/docs/notifications)** — Sachez quand un agent termine ou a besoin d'attention, puis marquez des fils comme non lus pour y revenir plus tard.
- **Et bien plus encore** — on ship tous les jours, donc cette liste est toujours en retard. Le [changelog](https://github.com/stablyai/orca/releases) est la vraie liste des features.
---
## Agents pris en charge
Fonctionne avec **n'importe quel agent CLI** — s'il tourne dans un terminal, il tourne dans Orca.
+ n'importe quel agent CLI
---
## Installation
### Desktop — macOS, Windows, Linux
- **[Télécharger depuis onOrca.dev](https://onorca.dev/download)**
- Ou récupérez un build directement : [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/download/v1.4.147-rc.3/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [Tous les builds](https://github.com/stablyai/orca/releases/latest)
- **Sous Windows :** utilisez la [dernière RC (`v1.4.147-rc.3`)](https://github.com/stablyai/orca/releases#release-v1.4.147-rc.3) — elle inclut des correctifs Windows absents de la stable.
_Ou via un gestionnaire de paquets :_
```bash
# macOS (Homebrew)
brew install --cask stablyai/orca/orca
# Arch Linux (AUR) — ou stably-orca-git pour compiler depuis les sources
yay -S stably-orca-bin
```
### Companion mobile — iOS, Android
Associez-la à l'app de bureau pour surveiller et piloter vos agents depuis votre téléphone.
- **iOS :** [Télécharger sur l'App Store](https://apps.apple.com/us/app/orca-ide/id6766130217)
- **Android :** [Télécharger l'APK](https://www.onorca.dev/download/android)
---
## Communauté & support
- **Discord :** Rejoignez la communauté sur **[Discord](https://discord.gg/fzjDKHxv8Q)**.
- **Twitter / X :** Suivez **[@orca_build](https://x.com/orca_build)** pour les news et annonces.
- **WeChat :** Le groupe 11 est complet. Scannez pour rejoindre le groupe WeChat 12 de la communauté Orca.
## Builds signés
Signature de code Windows sponsorisée / fournie par [SignPath.io](https://signpath.io), certificat par [SignPath Foundation](https://signpath.org).
## Licence
Orca est libre et open source sous la [licence MIT](../../LICENSE).
---
### Readme README.Ja (`docs/readme/README.ja.md`)
English · 中文 · 한국어 · Español · Français · Português
100x ビルダーのための AI オーケストレーター。
## 機能
### モバイル Companion
スマートフォンからエージェントを監視・操作 — エージェントの完了を通知で受け取り、どこからでもフォローアップを送信できます。
[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [Android APK](https://www.onorca.dev/download/android) · [ドキュメント →](https://www.onorca.dev/docs/mobile)
### 並列ワークツリー
1 つのプロンプトを 5 つのエージェントに展開し、それぞれを独立した git ワークツリーで実行 — 結果を比較して、最良のものをマージできます。
[ドキュメント →](https://www.onorca.dev/docs/model/worktrees)
### ターミナル分割
WebGL レンダリング、無制限の分割、再起動後も残るスクロールバックを備えた Ghostty クラスのターミナル。
[ドキュメント →](https://www.onorca.dev/docs/terminal)
### デザインモード
実際の Chromium ウィンドウで任意の UI 要素をクリックすると、その HTML、CSS、切り抜いたスクリーンショットがそのままエージェントのプロンプトに送られます。
[ドキュメント →](https://www.onorca.dev/docs/browser/design-mode)
### GitHub & Linear をネイティブに
PR、Issue、プロジェクトボードをアプリ内で閲覧 — 任意のタスクからワークツリーを開き、コンテキストスイッチなしでレビューできます。
[ドキュメント →](https://www.onorca.dev/docs/review/linear)
### SSH ワークツリー
強力なリモートマシン上でエージェントを実行 — ファイル編集、git、ターミナルをフルに使え、自動再接続とポートフォワーディングも付属します。
[ドキュメント →](https://www.onorca.dev/docs/ssh)
### AI Diff に注釈
任意の Diff 行にコメントを付けてエージェントへ送り返せます — Orca から離れずにレビュー、編集、コミットまで完結します。
[ドキュメント →](https://www.onorca.dev/docs/review/annotate-ai-diff)
### ファイルをエージェントへドラッグ
オートセーブが全面的に効く VS Code のエディタ — ファイルや画像をそのままエージェントのプロンプトへドラッグできます。
[ドキュメント →](https://www.onorca.dev/docs/editing/file-explorer)
### Orca CLI
エージェント自身も Orca を操作できます — `orca worktree create`、`snapshot`、`click`、`fill` であらゆるワークフローをスクリプト化できます。
[ドキュメント →](https://www.onorca.dev/docs/cli/overview)
**さらに同梱:**
- **[クイックオープン](https://www.onorca.dev/docs/model/quick-open)** — フローを離れずに、ワークツリー、ファイル、エージェント、コマンド、リポジトリコンテキストを横断検索できます。
- **[アカウント切り替えと使用量トラッキング](https://www.onorca.dev/docs/agents/usage-tracking)** — Claude と Codex の使用量やレート制限のリセットを確認し、再ログインなしでアカウントを切り替えられます。
- **[リッチなリポジトリプレビュー](https://www.onorca.dev/docs/editing/markdown)** — Markdown、画像、PDF、リポジトリ文書をワークスペース内でプレビューできます。
- **[Computer Use](https://www.onorca.dev/docs/cli/computer-use)** — 実際の操作が必要なワークフローでは、エージェントにデスクトップアプリや画面上の UI を操作させられます。
- **[通知と未読ステータス](https://www.onorca.dev/docs/notifications)** — エージェントの完了や要対応をすぐに把握し、スレッドを未読に戻して後で確認できます。
- **その他、まだまだたくさん** — 毎日リリースしているので、このリストは常に追いついていません。本当の機能一覧は[チェンジログ](https://github.com/stablyai/orca/releases)です。
---
## 対応するエージェント
**あらゆる CLI エージェント**で動作します — ターミナルで動くものなら、Orca でも動きます。
+ any CLI agent
---
## インストール
### デスクトップ — macOS, Windows, Linux
- **[onOrca.dev からダウンロード](https://onorca.dev/download)**
- またはビルドを直接入手: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [すべてのビルド](https://github.com/stablyai/orca/releases/latest)
_パッケージマネージャーからもインストールできます:_
```bash
# macOS (Homebrew)
brew install --cask stablyai/orca/orca
# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin
```
### モバイル Companion — iOS, Android
デスクトップアプリとペアリングして、スマートフォンからエージェントを監視・操作できます。
- **iOS:** [App Store からダウンロード](https://apps.apple.com/us/app/orca-ide/id6766130217)
- **Android:** [APK をダウンロード](https://www.onorca.dev/download/android)
---
## コミュニティとサポート
- **Discord:** **[Discord](https://discord.gg/fzjDKHxv8Q)** のコミュニティに参加してください。
- **Twitter / X:** アップデートやお知らせは **[@orca_build](https://x.com/orca_build)** をフォローしてください。
- **フィードバックとアイデア:** 私たちは高速にリリースしています。足りない機能がありますか？[機能リクエストを送信](https://github.com/stablyai/orca/issues)してください。
- **プライバシー:** Orca が収集する匿名の利用データとオプトアウトの方法については、[プライバシーとテレメトリーのドキュメント](https://www.onorca.dev/docs/telemetry)をご覧ください。
- **応援する:** 毎日のリリースを追うために、このリポジトリに[スター](https://github.com/stablyai/orca)を付けてください。
---
## 開発について
貢献したい、またはローカルで実行したいですか？ [CONTRIBUTING.md](../../.github/CONTRIBUTING.md) ガイドをご覧ください。
## ライセンス
Orca は [MIT License](../../LICENSE) の下で無料かつオープンソースです。
---
### Readme README.Ko (`docs/readme/README.ko.md`)
English · 中文 · 日本語 · Español · Français · Português
100x 빌더를 위한 AI 오케스트레이터.
## 기능
### 모바일 Companion
휴대폰에서 에이전트를 모니터링하고 조종하세요 — 에이전트가 완료되면 알림을 받고 어디서든 후속 지시를 보낼 수 있습니다.
[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [Android APK](https://www.onorca.dev/download/android) · [문서 →](https://www.onorca.dev/docs/mobile)
### 병렬 Worktree
하나의 프롬프트를 다섯 에이전트에 동시에 보내세요. 각 에이전트는 격리된 자체 git worktree에서 실행됩니다 — 결과를 비교하고 가장 좋은 것을 머지하세요.
[문서 →](https://www.onorca.dev/docs/model/worktrees)
### 터미널 분할
WebGL 렌더링, 무한 분할, 재시작 후에도 유지되는 스크롤백을 갖춘 Ghostty급 터미널.
[문서 →](https://www.onorca.dev/docs/terminal)
### 디자인 모드
실제 Chromium 창에서 UI 요소를 클릭하면 해당 HTML, CSS, 잘라낸 스크린샷이 에이전트 프롬프트로 바로 전송됩니다.
[문서 →](https://www.onorca.dev/docs/browser/design-mode)
### GitHub & Linear 네이티브
PR, issue, 프로젝트 보드를 앱 안에서 탐색하세요 — 어떤 작업에서든 worktree를 열고 컨텍스트 전환 없이 리뷰할 수 있습니다.
[문서 →](https://www.onorca.dev/docs/review/linear)
### SSH Worktree
강력한 원격 머신에서 에이전트를 실행하세요. 파일 편집, git, 터미널을 모두 지원하며 자동 재연결과 포트 포워딩도 포함됩니다.
[문서 →](https://www.onorca.dev/docs/ssh)
### AI Diff 주석
diff의 어느 줄에든 코멘트를 남기고 에이전트에게 바로 보내세요 — Orca를 떠나지 않고 리뷰하고 수정하고 커밋할 수 있습니다.
[문서 →](https://www.onorca.dev/docs/review/annotate-ai-diff)
### 에이전트로 파일 드래그
어디서나 자동 저장되는 VS Code 에디터 — 파일이나 이미지를 에이전트 프롬프트로 바로 드래그하세요.
[문서 →](https://www.onorca.dev/docs/editing/file-explorer)
### Orca CLI
에이전트도 Orca를 조작할 수 있습니다 — `orca worktree create`, `snapshot`, `click`, `fill`로 모든 워크플로를 스크립팅하세요.
[문서 →](https://www.onorca.dev/docs/cli/overview)
**그 밖에 기본으로 제공되는 기능:**
- **[빠른 열기](https://www.onorca.dev/docs/model/quick-open)** — 작업 흐름을 벗어나지 않고 worktree, 파일, 에이전트, 커맨드, 리포지토리 컨텍스트를 검색하세요.
- **[계정 전환 및 사용량 추적](https://www.onorca.dev/docs/agents/usage-tracking)** — Claude와 Codex의 사용량과 rate limit 초기화 시점을 확인하고, 다시 로그인하지 않고 계정을 바로 전환하세요.
- **[풍부한 리포지토리 미리보기](https://www.onorca.dev/docs/editing/markdown)** — Markdown, 이미지, PDF, 리포지토리 문서를 워크스페이스에서 미리 볼 수 있습니다.
- **[Computer Use](https://www.onorca.dev/docs/cli/computer-use)** — 워크플로에 실제 상호작용이 필요할 때 에이전트가 데스크톱 앱과 화면에 보이는 UI를 직접 조작하게 하세요.
- **[알림과 읽지 않음 상태](https://www.onorca.dev/docs/notifications)** — 에이전트가 완료되거나 주의가 필요할 때 알림을 받고, 스레드를 읽지 않음으로 표시해 나중에 다시 확인하세요.
- **그리고 훨씬 더 많은 기능** — 새로운 기능이 매일 출시되므로 이 목록은 늘 한 발 늦습니다. 진짜 기능은 [체인지로그](https://github.com/stablyai/orca/releases)에서 확인하세요.
---
## 지원 에이전트
**모든 CLI 에이전트**와 함께 작동합니다 — 터미널에서 실행되는 에이전트라면 Orca에서도 실행됩니다.
+ any CLI agent
---
## 설치
### 데스크톱 — macOS, Windows, Linux
- **[onOrca.dev에서 다운로드](https://onorca.dev/download)**
- 또는 빌드를 직접 받기: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [전체 빌드](https://github.com/stablyai/orca/releases/latest)
_또는 패키지 매니저로 설치:_
```bash
# macOS (Homebrew)
brew install --cask stablyai/orca/orca
# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin
```
### 모바일 Companion — iOS, Android
데스크톱 앱과 페어링해 휴대폰에서 에이전트를 모니터링하고 조종하세요.
- **iOS:** [App Store에서 다운로드](https://apps.apple.com/us/app/orca-ide/id6766130217)
- **Android:** [APK 다운로드](https://www.onorca.dev/download/android) · [설치 가이드](https://www.onorca.dev/docs/android-apk)
---
## 커뮤니티와 지원
- **Discord:** **[Discord](https://discord.gg/fzjDKHxv8Q)** 커뮤니티에 참여하세요.
- **Twitter / X:** 업데이트와 공지는 **[@orca_build](https://x.com/orca_build)** 를 팔로우하세요.
- **WeChat:** 그룹 11은 정원이 찼습니다. QR 코드를 스캔해 Orca 커뮤니티 WeChat 그룹 12에 참여하세요.
## 서명된 빌드
Windows 코드 서명은 [SignPath.io](https://signpath.io)가 후원·제공하며, 인증서는 [SignPath Foundation](https://signpath.org)에서 제공합니다.
## 라이선스
Orca는 [MIT 라이선스](../../LICENSE)에 따라 자유롭게 사용할 수 있는 오픈 소스입니다.
---
### Readme README.Pt (`docs/readme/README.pt.md`)
English · 中文 · 日本語 · 한국어 · Español · Français
O orquestrador de IA para builders 100x.
## Recursos
### Companion móvel
Monitore e conduza seus agentes pelo celular — receba uma notificação quando um agente terminar e envie instruções de acompanhamento de qualquer lugar.
[App Store para iOS](https://apps.apple.com/us/app/orca-ide/id6766130217) · [APK Android](https://www.onorca.dev/download/android) · [Docs →](https://www.onorca.dev/docs/mobile)
### Worktrees paralelos
Envie um mesmo prompt para cinco agentes, cada um em seu próprio worktree git isolado — compare os resultados e faça merge do vencedor.
[Docs →](https://www.onorca.dev/docs/model/worktrees)
### Terminais divididos
Terminais no nível do Ghostty com renderização WebGL, divisões infinitas e scrollback que sobrevive a reinicializações.
[Docs →](https://www.onorca.dev/docs/terminal)
### Modo Design
Clique em qualquer elemento de UI em uma janela real do Chromium para enviar HTML, CSS e uma captura recortada direto para o prompt do seu agente.
[Docs →](https://www.onorca.dev/docs/browser/design-mode)
### GitHub e Linear nativos
Navegue por PRs, issues e quadros de projeto dentro do app — abra um worktree a partir de qualquer tarefa e revise sem trocar de contexto.
[Docs →](https://www.onorca.dev/docs/review/linear)
### Worktrees por SSH
Execute agentes em uma máquina remota potente com edição completa de arquivos, git e terminais — com reconexão automática e encaminhamento de portas incluídos.
[Docs →](https://www.onorca.dev/docs/ssh)
### Anotar diffs de IA
Deixe comentários em qualquer linha de diff e envie-os de volta ao agente — revise, edite e faça commit sem sair do Orca.
[Docs →](https://www.onorca.dev/docs/review/annotate-ai-diff)
### Arraste arquivos para agentes
O editor do VS Code com salvamento automático em todos os lugares — arraste arquivos ou imagens direto para o prompt de um agente.
[Docs →](https://www.onorca.dev/docs/editing/file-explorer)
### Orca CLI
Agentes também controlam o Orca — automatize qualquer fluxo de trabalho com `orca worktree create`, `snapshot`, `click` e `fill`.
[Docs →](https://www.onorca.dev/docs/cli/overview)
**Também incluído:**
- **[Abertura rápida](https://www.onorca.dev/docs/model/quick-open)** — Pesquise entre worktrees, arquivos, agentes, comandos e contexto do repositório sem sair do seu fluxo.
- **[Troca de contas e acompanhamento de uso](https://www.onorca.dev/docs/agents/usage-tracking)** — Veja o uso de Claude e Codex, os reinícios de limites e troque contas instantaneamente sem fazer login de novo.
- **[Prévias ricas do repositório](https://www.onorca.dev/docs/editing/markdown)** — Pré-visualize Markdown, imagens, PDFs e documentos do repositório no workspace.
- **[Computer Use](https://www.onorca.dev/docs/cli/computer-use)** — Deixe agentes operarem apps de desktop e UI visível quando um fluxo de trabalho precisa de interação real.
- **[Notificações e estado de não lido](https://www.onorca.dev/docs/notifications)** — Saiba quando um agente termina ou precisa de atenção, depois marque conversas como não lidas para voltar depois.
- **E muito, muito mais** — lançamos novidades todos os dias, então esta lista vive atrasada. O [changelog](https://github.com/stablyai/orca/releases) é a lista real de recursos.
---
## Agentes compatíveis
Funciona com **qualquer agente CLI** — se roda em um terminal, roda no Orca.
+ qualquer agente CLI
---
## Instalação
### Desktop — macOS, Windows, Linux
- **[Baixe em onOrca.dev](https://onorca.dev/download)**
- Ou baixe um build diretamente: [macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [Todos os builds](https://github.com/stablyai/orca/releases/latest)
_Ou por um gerenciador de pacotes:_
```bash
# macOS (Homebrew)
brew install --cask stablyai/orca/orca
# Arch Linux (AUR) — ou stably-orca-git para compilar a partir do código-fonte
yay -S stably-orca-bin
```
### Companion móvel — iOS, Android
Conecte ao app desktop para monitorar e conduzir seus agentes pelo celular.
- **iOS:** [Baixar na App Store](https://apps.apple.com/us/app/orca-ide/id6766130217)
- **Android:** [Baixar APK](https://www.onorca.dev/download/android)
---
## Comunidade e suporte
- **Discord:** Entre na comunidade no **[Discord](https://discord.gg/fzjDKHxv8Q)**.
- **Twitter / X:** Siga **[@orca_build](https://x.com/orca_build)** para atualizações e anúncios.
- **Feedback e ideias:** Lançamos rápido. Sentiu falta de algo? [Peça um novo recurso](https://github.com/stablyai/orca/issues).
- **Privacidade:** Veja a [documentação de privacidade e telemetria](https://www.onorca.dev/docs/telemetry) para saber quais dados anônimos de uso o Orca coleta e como desativar.
- **Mostre apoio:** Dê uma [estrela](https://github.com/stablyai/orca) neste repositório para acompanhar nossos lançamentos diários.
---
## Desenvolvimento
Quer contribuir ou rodar localmente? Veja nosso guia [CONTRIBUTING.md](../../.github/CONTRIBUTING.md).
## Licença
Orca é livre e de código aberto sob a [Licença MIT](../../LICENSE).
---
### Readme README.Zh CN (`docs/readme/README.zh-CN.md`)
English · 日本語 · 한국어 · Español · Français · Português
面向 100x 构建者的 AI 编排器。
## 特性
### 移动 Companion 应用
用手机监控并指挥你的智能体 — 智能体完成时收到通知，随时随地发送后续指令。
[iOS App Store](https://apps.apple.com/us/app/orca-ide/id6766130217) · [Android APK](https://www.onorca.dev/download/android) · [文档 →](https://www.onorca.dev/docs/mobile)
### 并行 Worktree
把一个提示同时分发给五个智能体，每个都在自己隔离的 git worktree 中运行 — 比较结果，合并最佳方案。
[文档 →](https://www.onorca.dev/docs/model/worktrees)
### 终端分屏
Ghostty 级终端，支持 WebGL 渲染、无限分屏，以及重启后依然保留的滚动历史。
[文档 →](https://www.onorca.dev/docs/terminal)
### 设计模式
在真实的 Chromium 窗口中点击任意 UI 元素，把它的 HTML、CSS 和裁剪好的截图直接发送到智能体的提示中。
[文档 →](https://www.onorca.dev/docs/browser/design-mode)
### GitHub & Linear 原生集成
在应用内浏览 PR、issue 和项目看板 — 从任意任务打开 worktree，无需切换上下文即可完成评审。
[文档 →](https://www.onorca.dev/docs/review/linear)
### SSH Worktree
在高性能远程机器上运行智能体，完整支持文件编辑、git 和终端 — 自动重连与端口转发一应俱全。
[文档 →](https://www.onorca.dev/docs/ssh)
### 标注 AI Diff
在任意 diff 行上添加评论并发回给智能体 — 评审、编辑、提交，全程无需离开 Orca。
[文档 →](https://www.onorca.dev/docs/review/annotate-ai-diff)
### 拖文件给智能体
VS Code 的编辑器，处处自动保存 — 把文件或图片直接拖入智能体提示。
[文档 →](https://www.onorca.dev/docs/editing/file-explorer)
### Orca CLI
智能体也能驱动 Orca — 用 `orca worktree create`、`snapshot`、`click` 和 `fill` 把每个工作流脚本化。
[文档 →](https://www.onorca.dev/docs/cli/overview)
**开箱即用的还有：**
- **[快速打开](https://www.onorca.dev/docs/model/quick-open)** — 在 worktree、文件、智能体、命令和仓库上下文之间搜索，不打断你的心流。
- **[账号切换与用量追踪](https://www.onorca.dev/docs/agents/usage-tracking)** — 查看 Claude 和 Codex 的用量与限额重置时间，并且无需重新登录即可热切换账号。
- **[丰富仓库预览](https://www.onorca.dev/docs/editing/markdown)** — 在工作区中预览 Markdown、图片、PDF 和仓库文档。
- **[Computer Use](https://www.onorca.dev/docs/cli/computer-use)** — 当工作流需要真实交互时，让智能体操作桌面应用和可见 UI。
- **[通知与未读状态](https://www.onorca.dev/docs/notifications)** — 第一时间知道智能体何时完成或需要关注，并可将会话标记为未读，稍后再回来处理。
- **还有很多很多** — 我们每天发布新功能，这个列表永远跟不上。[更新日志](https://github.com/stablyai/orca/releases)才是真正的功能列表。
---
## 支持的智能体
适配**任何 CLI 智能体** — 只要能在终端里运行，就能在 Orca 里运行。
+ 任何 CLI 智能体
---
## 安装
### 桌面端 — macOS、Windows、Linux
- **[从 onOrca.dev 下载](https://onorca.dev/download)**
- 或直接获取安装包：[macOS Apple Silicon](https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg) · [macOS Intel](https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg) · [Windows (.exe)](https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe) · [Linux AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) · [全部构建](https://github.com/stablyai/orca/releases/latest)
_也可以通过包管理器安装：_
```bash
# macOS (Homebrew)
brew install --cask stablyai/orca/orca
# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin
```
### 移动 Companion 应用 — iOS、Android
与桌面应用配对，用手机监控并指挥你的智能体。
- **iOS:** [从 App Store 下载](https://apps.apple.com/us/app/orca-ide/id6766130217)
- **Android:** [下载 APK](https://www.onorca.dev/download/android)
---
## 社区与支持
- **Discord:** 加入 **[Discord](https://discord.gg/fzjDKHxv8Q)** 社区。
- **Twitter / X:** 关注 **[@orca_build](https://x.com/orca_build)** 获取更新和公告。
- **微信:** 第 11 群已满。扫码加入 Orca 社区微信第 12 群。
## 许可证
Orca 是自由且开源的软件，遵循 [MIT 许可证](../../LICENSE)。
---
### Readme Release Source Sharing (`docs/readme/release-source-sharing.md`)
# Shared historical source for cross-version tests (P2)
Cross-version tests extract historical releases under each worktree's
`tests/e2e/.cross-version-checkouts`. Previously, branches testing the same release each
retained a full copy. Local tests now prepare one read-only source seed and share its file
data with each worktree's independent import directory.
## How it works
Seeds live under `/orca-cache/release-source/format-8/`.
The resolved commit and extraction format identify the source, including its rewritten imports.
The common Git directory lets sibling worktrees reuse the same seed without scanning them.
Existing local checkouts remain in place; the new format creates fresh import directories.
Missing-package stand-ins depend on the current branch's dependencies, so each worktree
creates those locally. Mutable copies of current-branch modules also remain local.
The existing lock, staging directory, and rename transaction publishes complete seeds and
import directories. Invalid stamps, missing protocol source, or invalid package metadata
cause rebuilding or ordinary local extraction.
macOS uses APFS clones. Linux tries reflinks, then read-only hardlinks. Copies preserve the
seed's read-only permissions; these historical files are never edited by the harness.
Windows uses independent copies because removing read-only hardlinks can change permissions
on surviving links. Unsupported sharing falls back to a private copy. If the optional shared
cache fails, the harness extracts locally and continues the test.
The current format retains at most eight seeds, ordered by recent use. A shared lock covers
publication, copying, and eviction, so cleanup cannot delete a source while another test
copies it. Copying and permission changes are asynchronous so the lock heartbeat keeps running.
Interrupted staging directories are removed on the next use. Retention only touches the
current format; older implementations may still be using other formats. Eviction leaves
already-created import directories usable.
## Controls and scope
Sharing is enabled for ordinary local cross-version tests. Set
`ORCA_DISABLE_SHARED_RELEASE_CACHE=1` to keep ordinary local extraction. CI and explicit
`cacheRoot` options remain isolated unless a caller explicitly supplies `sharedCacheRoot`.
This only changes test tooling. It adds no development-server task or background worktree
scan. Sharing does not migrate or delete existing local caches. Tests running on a remote host use that
host's repository and filesystem; no client filesystem or remote protocol is involved.
Folder contexts without a Git repository cannot provide a historical release checkout.
## Cleaning up older historical caches
First stop cross-version tests in all this repository's worktrees, then preview historical-cache
cleanup across the registered local worktrees and shared source cache:
```sh
pnpm reclaim-space --tests-stopped
```
The default selects stamped release checkouts older than 30 days, including previous extraction
formats. Answer `Y` after the preview to apply it, or run the same selection directly:
```sh
pnpm reclaim-space --apply --tests-stopped
```
Use `--release-cache-min-age-days 7` for a shorter retention window, or `--release-cache-min-age-days 0` to select all
recognised completed release checkouts. `--repo DIRECTORY` selects another local repository.
Each run rescans and rechecks eligibility; it does not apply a saved preview.
This is manual because older harnesses do not hold a lease while importing source. Locks prevent
deletion during publication or shared-source copying, but do not prove that a completed checkout
is unused. Local checkout age uses directory modification time, which ordinary reuse does not
refresh; shared seed timestamps reflect recent copying. `--tests-stopped` acknowledges that the
caller has stopped consumers; it does not detect them.
The script checks matching commit/format stamps, skips symlinked cache paths and future formats,
and leaves mutable `working-tree` copies, source, dependencies, and worktree registrations alone.
It reports logical bytes rather than promised disk savings: another clone may retain the same
blocks. Deleted historical source rebuilds on the next test run. Run the command on the execution
host for SSH repositories. The same manual command also performs P1's Electron maintenance;
automatic dev-bundle sweeps exclude historical test cache cleanup.
## Measurement and validation
A disposable macOS/APFS run against `v1.4.190` compared ordinary extraction with two separate
local caches using one shared seed. Each import tree contained 8,175 files. APFS private file
allocation was measured after all three views existed, without following symlinks.
| Method | Elapsed time | Private file data per import directory |
| -------------------------------- | ------------ | -------------------------------------- |
| Ordinary extraction | 4.64 s | 68.79 MiB |
| Shared source, creating the seed | 22.06 s | 44 KiB |
| Shared source, reusing the seed | 1.33 s | 44 KiB |
Shared blocks still occupy approximately one source copy. Private bytes exclude those blocks
and filesystem metadata, so they are not the total footprint. The cold seed costs extra work;
one timing sample on a busy machine does not establish a speed guarantee. Deleting the seed
left the other import directory readable. No existing worktrees were cleaned up.
Tests cover concurrent publication, lock heartbeats and eviction, independent branch stand-ins,
corrupt seeds, fallback, the opt-out, and preserved read-only files. Run them with:
```sh
ORCA_BACKGROUND_LAUNCH=1 pnpm test tests/e2e/cross-version-wire/release-source-cache.unit.test.ts tests/e2e/cross-version-wire/release-source-retention.unit.test.ts tests/e2e/cross-version-wire/release-checkout.unit.test.ts tests/e2e/cross-version-wire/release-checkout-tree.unit.test.ts tests/e2e/cross-version-wire/release-missing-packages.unit.test.ts config/scripts/space-sharing-copy.test.ts
```
## P3 remains an experiment
P3 shares the tracked source of new Orca worktrees. It requires independent writable files,
Git indexes, and matching checkout settings, and has more compatibility risk than P2's
immutable test source. The APFS experiment demonstrated substantial storage savings but
variable creation time and stays out of this change. Its code, measurements, and design notes
are preserved on `nwparker/tracked-source-sharing-experiment`; [the draft PR is closed](https://github.com/stablyai/orca/pull/27618).
---
### Readme Worktree Storage Maintenance (`docs/readme/worktree-storage-maintenance.md`)
# Worktree storage maintenance
Run one command from the repository to preview maintenance across its locally registered Git worktrees:
```sh
pnpm reclaim-space
```
In an interactive terminal, the preview offers `Apply this cleanup? [y/N]`; enter `Y` to apply it.
Redirected input or output remains preview-only. To apply without a prompt, use `pnpm reclaim-space --apply`.
Historical test caches are retained by default. After stopping cross-version tests in all this
repository's worktrees, preview the same selection with:
```sh
pnpm reclaim-space --tests-stopped
```
Answer `Y` to apply that preview, or use `pnpm reclaim-space --apply --tests-stopped` to apply directly.
The command reuses the historical test cache, Electron distribution, dev bundle, and Vite cache cleanup scripts.
It shares complete Electron distributions through the repository cache and removes idle
`out/electron-dev` bundles, which development rebuilds on demand. It also removes tracked
`.cache/vite` dependency caches unused for 30 days. With `--tests-stopped`, it also
removes stamped historical test checkouts and shared seeds older than 30 days; tests regenerate them when needed. It leaves source files,
dependency installs, worktree registrations, and other build output alone. Reported sizes are
logical file data; APFS clones and hardlinks mean actual disk savings can be smaller.
Use `--release-cache-min-age-days 7` to shorten historical-cache retention, or `0` to select all
recognised completed historical checkouts. This age option applies only to test caches. Local
checkout age uses directory modification time, which ordinary reuse does not refresh. The
`--tests-stopped` flag acknowledges stopped tests; older harnesses cannot prove a completed
checkout is unused. Without that flag, historical caches are excluded from both preview and apply.
Cache cleanup skips symlinks, malformed stamps, future formats, and publication/copy locks.
See [release source sharing](./release-source-sharing.md) for the cache and locking details.
Vite dev servers record cache use at startup and shutdown. Cleanup retains recent caches,
caches owned by a live process, and caches whose ownership cannot be verified, including caches
created before tracking was added. A maintenance lock prevents cleanup racing with server startup.
Desktop and web caches are reclaimed together; the next dev launch regenerates them as needed.
Use `--repo DIRECTORY` to choose another local repository. Git's worktree list determines scope,
including registered worktrees outside Orca's workspace directory. Folder workspaces without Git
have no repository-wide sweep. These commands run on the local host: they do not inspect or delete
anything on SSH hosts. Run maintenance on the execution host when maintaining remote repositories.
## Keeping installs shared
Healthy Electron installs join the shared distribution cache during native dependency setup,
without waiting for an Electron upgrade. The manual command migrates older installs immediately.
Read-only Electron package directories are retained and reported as skipped. Cache publication
or copying failures are also reported as skipped rather than silently omitted.
`pnpm dev` and `pnpm dev-stable-name` start an automatic repository-wide Electron and Vite cleanup worker
in the background after the dev process starts. It never prompts or waits before launching the app.
The worktree being launched is excluded from Electron sharing, dev bundle removal, and Vite cleanup; active
sibling apps and recent unfinished builds remain protected by the existing bundle checks.
Background sweep output is suppressed; worker start or exit failures are reported without stopping dev. Set `ORCA_SKIP_DEV_STORAGE_RECLAIM=1` to opt out.
The worker finishes independently if the dev app exits, and each cleanup operation has a ten-minute limit.
Historical test cache cleanup runs only in the explicit manual command with `--tests-stopped`.
Automatic invocations exclude it because tests may still be importing source.
The repository lock prevents competing cleanup commands. Dev bundle removal checks active
processes and recent unfinished builds, then rechecks eligibility immediately before deletion.
An unreadable process table prevents removal.
To retain older bundles during a manual sweep, run the underlying command with an age limit:
```sh
node config/scripts/reclaim-dev-electron-bundles.mjs --min-age-days 7 --apply
```
That limit uses the bundle directory's modification time. The underlying command also accepts
`--exclude-worktree DIRECTORY` to protect an entire worktree. A missing exclusion path is an error;
filesystem aliases resolve to the same worktree. Neither option schedules cleanup.
---
### Reference Agent Browser Focus Isolation (`docs/reference/agent-browser-focus-isolation.md`)
# Agent browser input and the user's keyboard focus
Read this before changing how agent browser commands deliver mouse, key or text input to a
browser page, or before adding a `webContents.focus()` call on a page an agent drives. Background:
issue [#20595](https://github.com/stablyai/orca/issues/20595), with #16674, #12912, #16410, #19297,
#20533, #26338 and #8139.
## The rule
Agent input reaches the page it targets and nothing else. It never moves the user's keyboard focus,
and it never lands in whatever the user is typing into. Only an explicit user-facing focus request
(`tab switch --focus`) may reveal a page, and even that does not hand it OS focus.
## Why `` makes this hard (measured, Electron 43)
A `` guest is an inner WebContents in the window's frame tree. Chromium routes input by
that tree's focus, not by which debugger the command arrived on. A hidden-window probe (host
` 
Orca
Claude Code
Muse
DeepSeek Harness
ZCode
OpenClaude
Pi
oh-my-pi
Freebuff
Droid
Kilocode
- **Feedback & Ideas:** We ship fast. Missing something? [Request a new feature](https://github.com/stablyai/orca/issues).
- **Privacy:** See the [privacy & telemetry docs](https://www.onorca.dev/docs/telemetry) for what anonymous usage data Orca collects and how to opt out.
- **Show Support:** [Star](https://github.com/stablyai/orca) this repo to follow along with our daily ships.
---
## Developing
Want to contribute or run locally? See our [CONTRIBUTING.md](.github/CONTRIBUTING.md) guide.
The relay that pairs the mobile app with a desktop host is also in this repository under
[`cloud/`](cloud/README.md), with a separate pnpm workspace and setup guide.
