orca/docs/agent-skill-sharing-implementation-checklist.md

Agent skill sharing implementation checklist

Status: implementation and validation in progress.

Last updated: 2026-08-12.

Implementation baselines captured by this checklist update:

• Orca implementation: skills-share through 607e31dd04; no PR.
• Orca Cloud: bundle smoke PR #329 merged as eddb144afe; generation-aware recovery PR #330 merged as 8045c85dad; encrypted physical-host credential PR #336 merged as 8fce3298ef; kill-switch discovery PR #342 merged as c2bef2ff20fb. Windows device-name validation PR #343 merged as dbb14a658cbc; explicit disabled production bootstrap PR #352 merged as 2a23f6ace5; publisher-identity omission PR #355 merged as b3213bd34d1b224d8a3b11527eceaac883965400; production enablement PR #357, bounded OIDC smoke PR #358, monitor IAM PR #359, and monitor release-ownership PRs #360/#361 are merged through d8605edde72229c5d00d22c8bd6853a13c1a4aaa.

Validated so far:

• Current release hardening cancels bundle extraction after partial bytes exist and removes the extraction directory, durable journal, and managed-install state. Four repeated focused runs and the real SIGKILL recovery test passed. Signed GCS uploads use the earlier of signed-policy expiry and a 15-minute cap, including their archive read stream, so slow valid uploads can finish while stalled uploads remain bounded.
• Local and headless managed-skill operations now wait for the one startup transaction-recovery promise before reading or changing install state. Codex uses its documented global ~/.agents/skills root, and provider removal derives allowed roots from the registry so aliases remain removable after an agent is no longer detected. The combined focused suite passed 74 tests across 12 files, including fake-timer slow-upload and controlled-recovery regressions.
• The reported desktop install failure was a strict main-process IPC schema rejecting the renderer's additive providers selection before bundle verification. All four install schemas now accept the bounded field, and focused schema/provider tests pass. The original production link resolves as a valid one-skill bundle and returns a fresh same-version local download grant; the signed URL and private metadata were not logged or printed during verification.
• The final reliability hardening at 607e31dd04 adds a 60-second Cloud request deadline; cancellable, journaled bundle extraction; bounded package creation, verification, and preview fanout; atomic share-preparation admission and abandoned-archive cleanup; process-owned download staging; SSH startup recovery; and additive paired-client cancellation-result negotiation. The focused suite passed 78 ordinary tests plus a real process-death recovery test. Full Node, CLI, and web typechecks, repository lint and reliability gates, changed-file formatting, and diff checks passed. Mobile-facing wire changes remain additive, and no mobile app surface changed.
• A final performance and React lifecycle review found one stale-response race in managed-install inventory: a slower previous machine could overwrite the newly selected machine's list. The generation fence and regression test now preserve destination ownership; bundle busy state also reaches the parent close guard in the initiating event instead of a mirror effect. The complete renderer skill/settings slice passed 122 tests across 18 files, all Node/CLI/web typechecks, focused Oxlint, changed-code quality, max-lines, diff, and localization gates.
• The final local readiness pass at 9fcd72e327 passed 489 skill-domain tests across 73 files with 11 intentional platform skips, all Node/CLI/web typechecks, localization catalog, extraction and coverage, max-lines, changed-code quality, React Doctor, formatting, and diff checks. No new P0, P1, or P2 finding was proven by the crash/retry, security, performance, functional, mobile-backcompat, or Windows/Linux review.
• Multi-select sharing now preserves hidden selections, reconciles changed discovery scans, visibly explains ineligible skills, and blocks duplicate names before review. Exact complete managed bundles publish a new immutable version to their existing package; ambiguous or partial selections safely create a new package. Managed bundles with an active link can reopen the destination-aware installer for another machine; the final renderer slice passed 114 tests.
• The mobile/backcompat review found no persisted mobile keys, routes, deep links, or required legacy fields changed. Skill RPC methods and capabilities are additive and capability-gated; the cross-platform review found production paths use host path APIs and platform checks, with POSIX-only literals confined to tests or WSL guest execution.
• Final bearer-link changes pass 143 Orca Cloud API tests with one opt-in skip; 58 focused Orca tests; four mixed-version wire tests; desktop/node/web typecheck; localization catalog, extraction, and coverage; changed-code quality; max-lines; and diff checks.
• The final Cloud change passed PR run 31564069382 and merged-main run 31564235724, including the full monorepo build, lint, typecheck, tests, Terraform format, and Terraform validation.
• The opt-in desktop staging harness now publishes a bearer share without retired audience fields; Node typecheck and Playwright test discovery pass without starting Orca or a browser login flow.
• Local Node and web typechecks, changed-code quality gates, 94 skill-domain files with 770 tests passed and 3 skipped, 134 Orca Cloud API tests with one opt-in integration skip, the full Cloud monorepo test/typecheck/lint/build gates, and isolated Terraform formatting and validation.
• Final Orca validation passed repository-wide lint, all Node/CLI/web typechecks, the production desktop/native build, the Node 18 Relay bundle contract, 78 focused skill files with 557 tests passed and 10 platform skips, and the mixed-version wire suite. The full repository run passed 49,977 tests with 112 skips; its three environment/timeout failures passed as a 124-test rerun after removing Orca-injected Git config variables and rerunning the slow macOS PTY case.
• Skill sharing and installation renderer copy now passes the localization catalog, extraction, and coverage gates without a max-lines exception.
• Remote upload sessions actively expire abandoned bytes after their bounded idle lifetime, and begin/chunk/commit retries resume from the host-acknowledged offset under one stable transfer ID.
• Paired skill install and upload cancellation now reaches queued calls, capability probes, one-shot sockets, cached request sockets, and shared-control requests instead of waiting for the five-minute transfer timeout. Focused coverage proves queued work never starts, pending request admission is released, late responses are ignored, one-shot sockets close, and unrelated cached or shared-control requests survive; 84 transport/service tests and Node typecheck passed.
• Standalone and bundled package names reject Windows reserved device names in both Orca and Cloud, preventing a package published on macOS/Linux from failing only when installed on Windows.
• Identical archives are deduplicated only within an owner tenant. PostgreSQL object identity and tenant-hashed GCS keys prevent cross-tenant existence or finalization-timing disclosure.
• Native Windows package/install/recovery/copy-fallback tests and Node typecheck on windows 2; the current slice passed 284 tests with 21 intentional platform skips across 43 files.
• The final combined physical windows 2 run at 44d1266641 enabled native-Windows, real-process, and Ubuntu 24.04 WSL coverage together: 67 files passed, 449 tests passed, and 17 intentional platform skips remained. Commit 97b831dd17 made Windows recovery assertions path-semantic and time-deterministic. Commit 44d1266641 fixed WSL alias reconciliation after proving native UNC lstat can miss an existing distro symlink; WSL now inspects the alias in-distro and creates new aliases with ln -sT. The checkout remained clean and no orca-skill-* directory remained in WSL /tmp.
• Native Windows transaction validation passed all 21 cases at 6d3ce582aa, including a real canonical install beyond MAX_PATH while the host's LongPathsEnabled policy remained disabled.
• Real Ubuntu 24.04 WSL global, guest-workspace, and /mnt/c workspace transactions, including alias placement, interrupted update recovery, conflict preservation, update, and removal.
• Real Ubuntu 24.04 WSL provider detection and POSIX semantics, including case-sensitive names, 0600 regular files, and 0700 executable files.
• Exact portable package digest and archive SHA-256 goldens passed on macOS and native Windows despite different bundled zlib versions (1.2.12 and 1.3.1).
• The focused deterministic package suite passed 26/26 tests in Debian Bullseye/glibc 2.31 on native Linux ARM64 and emulated Linux x64, plus the real Ubuntu 24.04 WSL distro on windows 2; every host produced the same package digest and archive SHA-256 golden.
• The same 26/26 portable package suite passed at 109272dab1 on a disposable native x86_64 Ubuntu 22.04 GCE host using Linux 6.8 and Node 24.18. The VM had no service account or scopes; its boot disk, uploaded Git bundle, and temporary project SSH metadata were removed afterward.
• The exact x64 Electron directory package at f1dccb4f42 passed its after-pack ABI scan for all 18 bundled native binaries, then loaded packaged node-pty and spawned /bin/sh inside an Ubuntu 20.04/glibc 2.31 container. The physical run corrected the gate to use Linux's actual orca-ide executable and resources/node_modules layout. A native ARM64 package built from exact commit abe92d565b on an isolated aarch64 GCE host then passed the same 18-binary Ubuntu 20.04/glibc 2.31 ABI gate and packaged node-pty load/spawn smoke. The ARM64 VM had no service account or scopes; its auto-delete boot disk was verified absent, and its local Git bundle was moved to Trash after the clean-checkout proof.
• Real native Windows global, linked Git-worktree, and plain folder installs with spaces and non-ASCII paths, plus privacy-safe install diagnostics and owner-private staging tests.
• Docker-backed SSH relay installation from the real Electron client passed global, remote Git worktree, and remote plain-folder scopes, including client-mediated upload, unchanged preview, managed-install listing, safe removal, and remote-target Cloud authorization.
• Real paired-runtime installation passed from an isolated Electron client to both a headed desktop host and headless orca serve host. The host owned global and Git-worktree installs; the headed host also owned a plain-folder install. The client's home remained untouched.
• A fresh post-resilience E2E run passed all three headed paired-runtime, headless orca serve, and Docker SSH journeys. Focused failure injection also proves invalid gzip classification, old-version preservation after EACCES and ENOSPC, bounded recovery from a lost final install response, and validated structured SSH failure data without arbitrary error-data disclosure.
• Isolated staging bucket, IAM, orca_skills database and principal, enabled secret version, 11 log metrics, four alerts, and one dashboard in onorca-cloud-staging. The complete targeted skill-infrastructure plan is zero-diff at Cloud 41ef335.
• PostgreSQL migration startup is serialized by a transaction-scoped advisory lock. Transactional DDL rollback and eight concurrent startup callers passed against ephemeral PostgreSQL 16 and 17, with exactly one recorded schema version.
• Cloud PR #349 merged as 6a812c5e11 after proving an older API migration runner preserves a newer additive column/table and continues using its existing SQL. Build, lint, typecheck, tests, Terraform initialization, and validation passed; no service or infrastructure was deployed.
• Cloud PR #350 merged as c22007384a and added a required disposable PostgreSQL 16/17 drill. Real old and future-additive Node processes coexist and write against one database, the database is dumped and restored, and both processes write again after restoration. PR run 31624484826 and merged-main run 31624717796 passed every code, Terraform, and database job; no staging or production resource was accessed or deployed.
• The immutable API deploy path stamps every artifact and skill literal variable plus exactly one approved skill-database secret, and rejects secret, Cloud SQL, service-account, scaling, CPU, memory, volume, mount, probe, or unexpected-environment drift before traffic promotion. Staging intentionally carries all four skill controls as true; production remains false.
• The route-disabled baseline, API revision orca-cloud-api-staging-00039-rek, first proved the database-ready startup and anonymous 401/404 boundaries with zero revision errors.
• Cloud PR #313 passed run 31533988351, merged as d0bf926, and passed main run 31534229437. Guarded wake run 31534564230 restored exactly the two configured Relay cells.
• Auth deploy run 31535179937 promoted revision orca-cloud-auth-staging-00017-dug at 100% traffic. Health, JWKS, exact GitHub OIDC claim constraints, and zero deployment-window errors passed.
• The historical ACL-era API deploy run 31535438327 promoted revision orca-cloud-api-staging-00042-hef at 100% traffic with authenticatedSmoke: true and skillSmoke: true. The smoke covered artifact lifecycle; skill upload/finalize/download; two immutable versions; recipient and outsider authorization; local and remote grants; rollback selection; expiry; revocation; package deletion; and signed-object cleanup.
• Cloud PR #317 passed both required checks and merged as be00db10. Its historical ACL-era deploy run 31546194596 promoted revision orca-cloud-api-staging-00048-xom at 100% traffic with authenticatedSmoke: true and skillSmoke: true; canonical health and the immutable image digest independently matched after promotion.
• The signed-in macOS desktop staging journey reached upload, finalize, durable share creation, and global install after replacing an invalid colon in the audience-derived idempotency key. The retry test now requires a stable path-safe key, and the live test records the package ID before publication so a failed share can still clean up its finalized package. Its update phase uncovered same-name discovery ambiguity; the harness now selects the exact workspace source directory instead of the first same-named global skill. A final full live rerun remains open.
• The serving API has all four controls true, zero revision errors, and privacy-safe structured request logs. The log field inventory contains no principals, credentials, signed URLs, object paths, or private contents; a sensitive-value scan returned zero matches.
• Cloud PR #314 removed deploy-owned Auth release metadata from Terraform ownership, passed run 31536141357, merged as 4e91cf9, and passed main run 31536329459. The targeted Auth/API plan then reported zero intended changes. Known SQL and artifact-bucket drift was excluded and never applied.
• Cloud PR #320 passed both required checks and merged as 0579cc1a71. Targeted Terraform added only google_logging_project_exclusion.skill_share_bearer_request_urls in staging: one addition, zero changes, and zero deletions. This prevents per-link Cloud Run request URLs from entering log storage while retaining route-template application telemetry.
• Guarded wake run 31564370807 prepared the reviewed staging topology. Deploy run 31564803943 promoted orca-cloud-api-staging-00051-yoq at 100% traffic with immutable image digest sha256:511c0196511d2079bd9138092ad3cf065304b46a089b02d8df9318e0ae2e656a and reported authenticatedSmoke: true and skillSmoke: true.
• Candidate and canonical smoke produced 60 privacy-safe route-template events covering owner upload/finalize/share creation/inventory/revocation and anonymous pinned/latest preview, local/remote download grants, version selection, expiry, uniform unavailable responses, package deletion, and object cleanup. Anonymous requests with no Authorization header and an invalid header both returned the same 404 skill_share_not_found response with no-store. The serving revision had zero error logs and Cloud Logging retained zero per-link platform request logs.
• Guarded sleep run 31546908228 stopped all three Relay cells after the physical staging work. Independent GCP reads verified Cloud SQL policy NEVER, every MIG target at zero, and both managed Cloud Run minimums at zero.
• Final guarded sleep run 31565009141 restored the same low-cost state after the bearer rollout; independent reads found Cloud SQL NEVER/STOPPED and C1, C2, and C3 at target size zero.
• Cloud PR #329 passed required checks, merged as eddb144afe, and passed merged-main run 31569732482. Browser-free desktop run 31569902499 then passed bundle publish v1, install, local modification preservation, v2 update, rollback, revoke, installed-copy preservation, local removal, and Cloud package deletion without opening a login page.
• Cloud PR #330 passed required run 31578720429, merged as 8045c85dad, and passed merged-main run 31578942857. Guarded wake 31579195133 brought SQL and all three Terraform-owned cells up; deploy 31579844413 promoted orca-cloud-api-staging-00057-kat at 100% traffic with immutable digest sha256:f61745b21d00b111087620ab1108c9a96e9863ec9e902a424aaad01e9e945605.
• Recovery smoke 31580071168 published an isolated bundle, soft-deleted the exact published GCS generation, restored it with ifGenerationMatch=0, verified immutable metadata, transactionally repointed every matching database reference, verified the unlisted bearer download, and deleted the probe. No ephemeral recovery job or live probe object remained.
• Guarded sleep 31580339694 returned staging to low cost. Independent reads verified Cloud SQL NEVER/STOPPED, C1/C2/C3 target size zero and stable, and API/Auth min scale zero. Production was not touched.
• Cloud PRs #332 through #335 added the staging-only 12-by-30 finalization load gate, narrowly authorized its OIDC identity, fixed deterministic fixture ordering, and made retry settlement cleanup-safe. Their merge commits were ac85d0690e, 53559bd644, 7e1d50a84b, and bb8bf8b9ac; merged-main verification passed through run 31586525326.
• Auth deploy 31584318896 promoted orca-cloud-auth-staging-00021-tuq with digest sha256:e17075d69dca36df427f02fa515481f359c8f67397c5ab16de9759f7f949c6be; candidate and canonical smoke passed with one 100%-traffic revision and no remaining candidate tag.
• Load run 31585710645 exercised 12 concurrent bundles with 30 skills and 3,949,317 extracted bytes each. Two finalized immediately and ten returned explicit saturation; client p95 was 1,514 ms. Aggregate utilization stayed bounded: request p95 1,401.06 ms, API CPU 8.95%, API memory 26.95%, one API instance, database CPU 10.89%, database memory 25.59%, and seven connections. A saved, exact one-add Terraform plan restored the declared roles/monitoring.viewer binding for the staging deploy identity before those aggregate metrics were read; it changed no service, traffic, SQL, storage, Relay, or production resource.
• Cleanup run 31586684354 removed the exact failed-wave package set through normal package DELETE routes. The two remaining quarantine archives were manifest-proven as 30-skill fixtures for suffix 013756ec4740 and deleted with exact GCS generation preconditions; no live object from that run window remained. GCS soft delete keeps the operation recoverable.
• Guarded sleep 31587083752 returned staging to low cost. Independent reads verified Cloud SQL NEVER/STOPPED, C1/C2/C3 target size zero and stable with no current actions, and API, Auth, and Relay active-revision minimums at zero. Production was not touched.
• Cloud PR #336 added a browser-free physical-host credential handoff restricted to the exact main-branch staging workflow identity. It encrypts only the ten-minute owner token to a one-time RSA-3072 key, grants no GCP permissions, retains ciphertext for at most one day, and passed PR run 31588982191 plus merged-main run 31589194501 as merge 8fce3298ef.
• Guarded wake 31589384191 restored SQL and the two configured Relay cells without waking C3. Auth deploy 31589963244 promoted orca-cloud-auth-staging-00025-zuz at 100% traffic with immutable digest sha256:2b5cb04060a871f372298786dbed681054a076f5cf75966ea5e2130403db7254.
• The physical windows 2 staging journey passed in 27.6 seconds using credential run 31591275227. It installed v1 into the Windows-owned global path with the published digest and no macOS fallback, updated only that host to v2, preserved independent local version selection, rolled Windows back to v1, proved revocation left its installed copy intact, removed both host and local installs, and deleted the Cloud package. The encrypted artifact and local one-time key material were deleted immediately after use.
• The staging skill bucket independently reports the exact age-one-day Delete lifecycle restricted to uploads/, seven-day soft deletion, uniform bucket access, and public-access prevention. Its oldest live quarantine object was created at 2026-08-11T22:49:34Z, so lifecycle execution—not configuration—is still time-gated.
• Guarded sleep 31592709817 completed at Cloud 8fce3298ef. Independent reads verified SQL NEVER/STOPPED, all three Relay MIGs stable at target zero with no active actions, and API, Auth, and Relay active-service minimums at zero.
• Real process-death recovery now kills the transaction process after partial extraction and immediately before and after every durable install/removal journal transition. All 17 macOS cases passed, including extraction cleanup, dead-lock reclamation, receipt/filesystem agreement, and absence of transaction debris; the release workflow requires the same suite on macOS, native Windows, and Ubuntu 20.04/glibc 2.31.
• Guarded wake 31603249983 restored only the two configured staging cells. A disposable no-service-account Ubuntu 20.04/glibc 2.31 VM then passed the browser-free SSH staging lifecycle in 31.3 seconds: publish v1, host-owned install with exact digest, v2 update, managed-install verification, rollback, revocation with installed-copy preservation, local removal, and Cloud package deletion. The remote install, Orca SSH target, encrypted credential artifact, one-time keys, and VM were removed. Guarded sleep 31604391897 passed; independent reads verified SQL NEVER/STOPPED and C1/C2/C3 target zero, stable, and reached. Production was untouched.
• Guarded wake 31634214856 restored the two configured cells at Cloud dfb8359ff5. An isolated native Darwin arm64 OpenSSH target with a separate temporary home then passed the full staging lifecycle in 20.1 seconds: publish v1, SSH-owned install, v2 update, managed-version checks, rollback, revocation with installed-copy preservation, removal, and Cloud package deletion. This corrected the staging oracle to accept absolute POSIX homes outside /home. The GitHub ciphertext artifact was deleted immediately; the SSH service, relay, install, temporary home, and one-time keys were removed. Guarded sleep 31635145830 passed; independent reads verified SQL NEVER/STOPPED, all three MIGs stable and reached at zero with no active actions, and API/Auth/Relay minimum scale zero. Production was untouched.
• Guarded wake 31605729090 restored the same configured topology. An isolated headless Orca host with a separate home/profile then passed the full paired-runtime staging lifecycle in 12.5 seconds, proving host-owned install, update, managed-install state, rollback, revocation preservation, removal, and Cloud deletion without local fallback. The paired environment, install, package, encrypted credential artifact, and one-time keys were removed. Guarded sleep 31606600532 passed; independent reads again verified SQL NEVER/STOPPED and all MIGs at stable, reached target zero.
• Guarded wake retry 31630802215 succeeded at Cloud dfb8359ff5; the additional physical WSL Cloud journey was then waived as duplicate release evidence. The first guarded sleep attempt 31631288043 failed closed during Terraform provider initialization on a transient upstream 503, before the mutation step. Retry 31631379891 succeeded. Independent reads verified SQL NEVER/STOPPED, all three MIGs stable and reached at target zero with no active actions, and the API, Auth, and Relay active-revision minimums at zero. Production was untouched.
• Cloud PR #355 removed internal publisher and organization identifiers from anonymous skill responses, passed every code, Terraform, and PostgreSQL 16/17 check, and merged as b3213bd34d1b224d8a3b11527eceaac883965400. Guarded wake 31639920301 prepared staging. Deploy 31640677572 promoted orca-cloud-api-staging-00060-qay at 100% traffic with immutable digest sha256:31cb0a91a7abf1f82e4de08bd31e98fbd71519adc731a005fc95f60480658f73; authenticated and skill candidate/canonical smoke passed. The unrelated post-promotion storage-monitor image update lacked iam.serviceAccounts.actAs; the unchanged prior monitor image remains serving, and the API promotion and verification completed successfully. Guarded sleep 31640935616 passed in 8m51s. Independent reads verified SQL NEVER/STOPPED, C1/C2/C3 stable and reached at target zero, and the API at minimum scale zero with revision 00060-qay retaining 100% traffic. Production was untouched.

Rollout gate: staging infrastructure, OIDC owner identity exchange, anonymous bearer lifecycle, owner management, browser-free desktop bundle lifecycle, privacy-safe logging, published-object recovery, bounded finalization load, and guarded rollback-capable deployment passed. Production infrastructure and the unlisted-link API are live with all four controls enabled after successful authenticated candidate and canonical lifecycle smoke. Native Windows, real Ubuntu 24.04 WSL filesystems, physical Ubuntu 20.04 and macOS ARM64 SSH, and paired non-Windows staging passed. On 2026-08-12, the owner accepted the remaining live WSL-to-staging journey as duplicate evidence after the combined 449-test physical Windows/WSL run and native-Windows staging lifecycle; this does not treat WSL semantics as identical to macOS. The user-driven signed-in desktop and real-host production journey, supported Windows SSH, and the quarantine lifecycle deletion remain. The shared staging data plane is asleep.

This checklist turns the architecture plan into ordered implementation and release work. A checked item means evidence exists in code, tests, reviewed infrastructure, or release documentation; it does not mean the surrounding phase is complete.

Definition of done

• A user can select one or many private local skills, publish one immutable Skill Bundle, and receive one durable Orca share URL.
• Anyone with an active unlisted link can inspect a bundle without signing in, choose all or a subset of its skills, and install them globally or into a Git worktree or plain folder workspace.
• Installation works on local macOS, Linux, native Windows, WSL, paired Orca runtimes, and supported SSH targets.
• The portable archive root conforms to Agent Plugins 1.0.0 for skills-only packages and keeps Orca integrity metadata in dev.orca.skill-sharing/manifest.json.
• One canonical .agents/skills/<skill-name> copy is installed for each selected skill; provider-specific placements are reconciled for explicitly selected agents, defaulting to detected agents when no selection is supplied.
• Install, update, rollback, and removal preserve modified or unowned local content unless the user explicitly approves replacement.
• Package ingestion rejects unsafe archives before any destination mutation.
• Interrupted operations recover to a complete previous or requested version.
• Private package bytes remain access-controlled, published versions persist until deletion, and incomplete uploads expire automatically.
• Mixed-version clients and remote hosts fail safely through capability negotiation.
• Cloud resources are Terraform-owned, monitored, recoverable, and protected by independent upload, download, and remote-install kill switches. Targeted Terraform is zero-diff; staged generation recovery passed; dashboards, alerts, and runbooks cover the data plane; and Cloud PR #342 proves all three mutation controls can be disabled independently while unlisted preview remains available.
• The existing Skills page supports multi-select sharing, selective installation, per-skill conflicts/results, and installed-bundle management; Settings → Share Skills provides the authenticated owner inventory for copying and revoking active links.

0. Confirm scope and ownership

Product and legal decisions

• Record vercel-labs/skills as a behavioral reference only.
• Record upstream baseline commit c6f69c631292444cc541ac6d91e2226b0ff247da.
• Decide not to copy upstream source, tests, fixtures, registry data, or path tables.
• Decide Orca will not depend on the upstream CLI or an unsupported programmatic API.
• Decide V1 accepts Orca package sources only; Git, npm, and community registries remain with existing tools.
• Decide every Skill Bundle share is unlisted and reachable only through its durable link; do not add search, browsing, organization-library, marketplace, or contained-skill indexes.
• Record Agent Plugins 1.0.0 commit bd383552095128f6effe895b9257cfd580a6d179 as the portable-format reference.
• Decide to implement from the specification without copying its CC BY prose or vendoring its Apache-licensed schemas.
• Treat the archive as a Skill Bundle, not an Orca plugin product or executable plugin runtime.
• Limit V1 bundles to skills; exclude MCP servers, hooks, processes, connectors, and permissions.
• Review the architecture decision record covering the reference-only boundary with engineering and legal owners.
• Add a review check that flags any proposed copied or mechanically translated upstream material so attribution and licensing can be reconsidered before merge.
• Assign desktop, runtime, Cloud API, Terraform, security, design, and release owners.
• Confirm the first release ends after WSL and SSH support; keep team reconciliation as a later product milestone.

Product semantics

• Confirm private means unlisted and protected by an unpredictable revocable bearer link, not end-to-end encryption from Orca Cloud operators.
• Confirm a published immutable version persists until package or version deletion; it has no age-based object expiry.
• Confirm an unfinished upload grant expires after 15 minutes and its quarantine object is deleted after one day.
• Confirm a durable share URL contains a bearer credential for a revocable authorization record, not a GCS object or permanent blob grant.
• Confirm a signed download grant lasts five minutes and is the maximum share-revocation lag.
• Confirm updates create immutable versions and never mutate existing package objects.
• Confirm rollback installs a selected prior immutable version.
• Confirm revoking or deleting a Cloud share does not silently remove existing local installs.
• Confirm sharing and updating use an artifact-like flow—preview, upload, unlisted durable link, update, revoke/delete—while retaining skill-specific version, trust, and install semantics.
• Confirm recipients do not sign in; publishing and managing owned links still require sign-in.
• Confirm revocation blocks future resolution/download grants but does not remove installed copies.
• Add a Settings section named Share Skills, parallel to Artifacts, without adding any index or discoverability surface.
• Treat the authenticated owner-only active-link inventory as management, not recipient discoverability; never expose it anonymously or through browse/search APIs.
• Confirm V1 has no checked-in workspace desired-state lockfile and no automatic fleet-wide installation.
• Confirm one skill is a one-item bundle and a bundle may contain large selections such as 30 skills behind one durable link.
• Keep bundle identity, access, versions, transport, update/rollback, revocation, and deletion at bundle scope.
• Keep installation selection, conflicts, provenance, modification protection, and outcomes at skill scope.
• Keep loose-skill installation as the universal/default path and treat provider-native plugin adapters as optional compatibility outputs.

Existing-code and provider research

• Inventory current skill discovery, observeSkillPackage, package identity, topology, and freshness code; record reusable contracts and missing behavior.
• Inventory plugin staging, provenance, lock serialization, and Windows rename retry designs; extract only primitives that both domains can name and test accurately.
• Inventory current desktop IPC and remote skill RPC registration.
• Inventory existing SSH execution and file-transfer providers and identify the host-side installer entry point.
• Research official documentation for every initially supported agent's global and project skill directories.
• Verify each provider path with a real installation on every supported platform.
• Record whether each provider reads .agents/skills directly, how it is detected, and which alias mechanisms it supports.
• Add a normal reviewed maintenance process for provider registry changes; do not create an upstream synchronization job.

1. Define package and install contracts

Bundle contract replacement

• Replace the unpublished single-skill envelope with root plugin.json, skills/<name>/, and dev.orca.skill-sharing/manifest.json; do not add an outer bundle/ directory.
• Define SkillBundleManifestV1 with stable package/version identity, bundle metadata, ordered skill entries, per-skill identity and file lists, globally unique archive paths, and a bundle digest.
• Validate Agent Plugins 1.0.0 plugin.json fields from independently authored local rules; never fetch a schema during loading.
• Create fresh staging roots and reject unknown, malformed, or conflicting imported dev.orca.skill-sharing namespaces without overwriting them. The extractor now exclusively creates its staging root, preserves a pre-existing namespace on conflict, rejects unknown top-level extension entries, and removes only staging it created.
• Keep the detailed manifest inside the archive for export, remote/SSH transport, and offline validation; keep GCS metadata compact and PostgreSQL limited to exact link/ownership lookup.
• Add selected skill IDs and per-skill conflict choices to preview/install requests.
• Return aggregate status plus ordered installed, unchanged, kept-local, and failed per-skill outcomes; support retrying failed items only.
• Add skills.install.bundle.v1 and additive bundle RPC methods so mixed-version peers fail before transfer.
• Decide to dispose of the unpublished staging-only single-skill records before changing the Cloud schema; there is no production compatibility commitment to the unpublished single-skill format.

Shared package manifest

• Add src/shared/skill-package-manifest.ts.
• Define the original single-skill SkillPackageManifestV1 prototype with schema version, stable package ID, immutable version ID, name, description, creation time, file identities, and package digest.
• Normalize manifest paths to / while keeping filesystem conversion host-owned.
• Define the canonical digest algorithm over normalized paths, file identity, executable state, and classification.
• Require skill/SKILL.md, valid frontmatter, and agreement between skill and package names.
• Specify deterministic serialization so identical inputs produce identical identities across macOS, Linux, Windows, and WSL.
• Version the schema and require additive changes or a new schema version.
• Reject unknown schema versions with a stable error category.

Package limits and file policy

• Enforce maximum path depth 16.
• Enforce maximum 2,048 archive entries.
• Enforce maximum 512 regular files.
• Enforce maximum 4 MiB per file.
• Enforce maximum 32 MiB total extracted bytes.
• Enforce maximum 40 MiB compressed bytes.
• Reject absolute, parent-traversal, NUL-containing, and Windows drive-prefixed paths.
• Reject duplicate normalized paths and Unicode or case-fold collisions.
• Reject symlinks, hardlinks, devices, FIFOs, sockets, encrypted entries, and other special files in V1.
• Preserve executable modes represented by the package manifest.
• Document that install never executes package scripts.

Install request, preview, and result

• Add src/shared/skill-install-contract.ts.
• Define requests with operation ID, immutable package identity, ingress kind, destination, and optional conflict resolution.
• Support download-grant, staged-upload, and trusted in-process local-file ingress.
• Ensure arbitrary remote RPC callers cannot supply a local filesystem path.
• Model global, Git worktree, and folder-workspace destinations without assuming Git exists.
• Define preview output for destination, current state, provider coverage, conflicts, and trust metadata.
• Define structured installed, updated, unchanged, conflict, partial, and failed results.
• Define stable error categories for admission, transport, archive, filesystem, conflict, recovery, provider placement, and compatibility failures.
• Ensure responses never include grants, credentials, ACL membership, or private package contents.

Capability and wire compatibility

• Add src/shared/skill-install-capability.ts with skills.install.v1 and an update-required compatibility message.
• Read and apply docs/reference/remote-wire-compatibility.md before changing RPC contracts.
• Add new methods without changing existing discovery behavior.
• Keep new request and response fields optional until all supported peers understand them.
• Do not add a terminal stream opcode for skill installation.
• Define behavior for new client/old host, old client/new host, and capability loss during an operation.

Phase 1 contract gate

• Review package, ingress, conflict, result, and capability contracts. Shared schema, runtime method, Relay handler, ingress, planner, and stable-failure suites now form the release-gated contract evidence; no existing discovery method or stream opcode changed.
• Freeze stable V1 error categories used by desktop, runtime, SSH, and Cloud tests.

2. Build and validate packages

Package creation

• Add src/main/skills/skill-package-creation.ts.
• Accept a specific skill directory rather than an arbitrary parent tree.
• Observe and validate the source before staging.
• Copy the source into an owner-private staging directory.
• Observe the staged copy again and fail if its identity differs from the source snapshot.
• Generate a deterministic tar archive with manifest.json and a skill/ envelope.
• Include only skill/ contents in the eventual installed directory.
• Bind the user-visible share preview to the final staged digest.
• Clean staging files on success, cancellation, source drift, and error.
• Accept a non-empty ordered selection of skill directories and support at least 30 within the global entry/file/byte limits. Focused local creation/extraction now covers one 30-skill archive; staging load run 31585710645 finalized the same maximum selection through Cloud.
• Reject duplicate normalized skill names and preserve selection across search/filter changes in the caller. The picker keeps hidden selections, unions explicit filtered selection, and disables a second same-name source before review.
• Generate deterministic plugin.json, skills/, and Orca extension metadata.
• Bind the share review to every staged skill digest and the final bundle digest.

Bounded extraction

• Add src/main/skills/skill-package-extraction.ts.
• Stream archive inspection and extraction without buffering the entire package.
• Validate manifest.json before trusting archive file metadata.
• Enforce compressed, extracted, entry, file, depth, and per-file limits during extraction, not only after it.
• Create extraction staging on the same filesystem as the canonical destination.
• Convert manifest paths with the destination runtime's path APIs.
• Re-observe extracted skill/ and compare every file identity and package digest.
• Delete partial extraction bytes on cancellation or failure.
• Validate the portable root, Orca extension namespace, bundle manifest, and every selected skills/<name> subtree before destination mutation.
• Extract selected skill subtrees without requiring installation of unselected skills.

Package tests

• Test deterministic manifests, archives, and digests on macOS and native Windows. The exact golden passed on both hosts at 8be7275d0d after replacing zlib-dependent streaming output with bounded deterministic stored DEFLATE blocks.
• Repeat the portable package golden on native Linux and inside WSL. The focused golden passed in Debian Bullseye/glibc 2.31 containers on native ARM64 and emulated x64, and inside the real Ubuntu 24.04 WSL distro, at 92c8c6a4c6. The same 26/26 suite passed at 109272dab1 on a disposable native x86_64 Ubuntu 22.04 GCE host; the VM, boot disk, uploaded bundle, and temporary SSH metadata were removed after validation.
• Test source changes during packaging.
• Test CRLF/LF behavior explicitly and document whether byte identity changes.
• Test executable-mode preservation and Windows's mode limitations.
• Test missing, malformed, and identity-mismatched SKILL.md files.
• Test every size, count, and depth boundary at limit, one below, and one above.
• Test traversal, absolute paths, drive paths, Unicode/case collisions, duplicate paths, all rejected link and special-file types, and encrypted entries.
• Test truncated archives and invalid tar and content checksums.
• Test invalid gzip bytes and map zlib-specific errors to the stable non-retryable archive category.
• Fuzz archive path normalization and envelope parsing with bounded resources.

Phase 2 package gate

• Prove invalid archive classes fail before destination mutation.
• Prove the same source bytes produce the same digest on macOS, Linux, native Windows, and WSL.
• Prove package creation and extraction require no npx, external Node installation, or upstream CLI runtime.

3. Implement the local installer transaction

Destination resolution

• Add src/main/skills/skill-install-destinations.ts.
• Resolve global canonical roots as <host-home>/.agents/skills/<skill-name> on the executing host.
• Resolve workspace canonical roots from runtime-owned worktree or folder-workspace identity.
• Reject client-supplied remote paths that do not resolve to the selected workspace identity.
• Resolve WSL home, paths, and target distro inside the selected distro.
• Keep all path joins platform-native and reject destination escapes after realpath-aware containment checks.
• Support long Windows paths and case-insensitive destination collision checks.

Admission, locking, and ingress

• Add src/main/skills/skill-package-download.ts.
• Add src/main/skills/skill-install-service.ts.
• Validate request shape, schema, capability, package identity, scope, destination, and policy before download or mutation.
• Recover prior journals for the same destination before planning a new operation.
• Acquire a filesystem-backed cross-process lock keyed by canonical destination.
• Bound lock wait time and return a retryable busy result.
• Stream ingress to an owner-private bounded temporary file and hash it while downloading.
• Require HTTPS whenever the configured Cloud endpoint uses HTTPS.
• Allow only configured Orca skill-bucket origins and reject credential-bearing cross-host redirects.
• Check expected compressed bytes, archive SHA-256, package digest, cancellation, grant expiry, and disconnects.
• Delete partial ingress bytes on every incomplete path.

Planning and conflict handling

• Add src/main/skills/skill-install-planner.ts.
• Classify missing canonical destinations as installable.
• Classify an identical requested digest as unchanged and continue placement repair.
• Permit clean updates only when installed bytes still match Orca provenance.
• Return a modified conflict when installed bytes drift from their receipt.
• Return an unowned conflict when a destination exists without Orca provenance.
• Return topology conflicts for files, external links, broken links, and name collisions.
• Classify every requested provider placement independently.
• Repeat current-state inspection immediately before commit and invalidate stale previews.
• Require explicit confirmation before discarding local modifications or unowned content.

Durable commit and recovery

• Add src/main/skills/skill-install-transaction.ts.
• Copy extracted bytes into a hidden sibling staging directory and verify the digest again.
• Preserve executable modes where the host supports them.
• Keep staging, replacement, and backup on the destination filesystem.
• Write and durably flush a versioned transaction journal before moving the current destination.
• Move an approved existing destination to a journal-owned backup.
• Rename verified staging into the canonical path.
• Add bounded retries for Windows EPERM, EACCES, and EBUSY rename races caused by antivirus or indexing.
• Observe the committed destination and require the requested digest.
• Restore the backup after failed commit and retain sufficient journal state after a crash.
• Never remove a path based only on a filename pattern; require journal ownership, containment, and expected identities.
• Run bounded recovery at startup and before later operations for the destination. Startup scans at most 64 install and 64 removal journals, bounds each read to 4 MiB, validates the journal filename against the canonical-path state key, and recovers removal before install under the destination lock. Dead-PID locks are reclaimed immediately after a killed runtime; malformed locks retain the bounded stale-age safeguard. Corrupt or conflicting journals are preserved and reported by path-free failure code for manual recovery.

Provenance

• Add src/main/skills/skill-install-provenance.ts.
• Store versioned receipts outside installed skill directories.
• Record package/version IDs, digest, scope, destination identity, canonical identity, placements, previous version, timestamp, and runtime identity.
• Exclude credentials, grants, share values, manifests, and package contents.
• Serialize receipt updates across processes.
• Write receipt updates through durable temporary-file replacement.
• Support aggregate-index reconstruction from bounded per-install receipts.
• Mark the journal complete only after receipt publication, then remove transaction backups and staging.

Verification and discovery

• Re-run skill discovery on the destination after commit.
• Verify the canonical skill and successful provider placements are observable.
• Determine success from installed bytes and discovery, not process exit alone.
• Invalidate renderer skill caches and refresh the Skills page.
• Return canonical success with partial when an optional provider placement fails.

4. Implement provider placements

Provider registry

• Add src/main/skills/skill-provider-destinations.ts.
• Add data-only records for Orca agent ID, canonical-root support, global/project resolvers, detection evidence, and platform alias support.
• Populate only provider paths independently verified from official documentation and real installations.
• Detect an agent before creating its provider-specific configuration root.
• Avoid modifying roots for agents that consume .agents/skills directly.
• Keep loose-skill placement as the universal/default installation path.
• Do not add Cursor-specific placement in V1; keep the Agent Plugins-compatible root as the portable archive shape while installing contained skills through canonical loose-skill paths.
• Do not generate .claude-plugin/plugin.json or .codex-plugin/plugin.json adapters in V1; native plugin installation remains a separately reviewed follow-up if it becomes useful.
• Use loose skills for plugin clients, including the current Codex IDE extension, and retain bundle/version provenance for every installed skill.

Placement reconciliation

• Add src/main/skills/skill-placement-reconciliation.ts.
• Create relative directory aliases from real parent directories on POSIX.
• Create directory junctions with absolute canonical targets on Windows.
• Detect provider parents already linked to canonical storage.
• Fall back to an independently copied and verified directory when aliases are unavailable or denied and policy allows it.
• Record each canonical copy, provider alias, junction, or independent-copy topology.
• Reconcile placements idempotently after install and update.
• Repair broken Orca-owned aliases.
• Leave unowned or modified provider placements untouched unless explicitly replaced.
• Preserve canonical success when a provider placement fails and make coverage retryable.

Provider validation

• Confirm every initial provider discovers a global canonical or reconciled install.
• Confirm every initial provider discovers a workspace install only in that workspace.
• Test symlink, junction, and copy fallback behavior after provider and canonical parent paths are moved or linked.
• Test provider release upgrades against the registry through the normal review process.

5. Implement update, rollback, and removal

Update and rollback

• Resolve the latest accessible immutable Cloud version without mutating local state.
• Compare the requested digest with provenance and observe current bytes before offering an update.
• Route clean updates through the same install transaction.
• Offer keep-local, authorized publish-as-new-version, and explicit discard-and-replace choices for modified installs.
• Reconcile recorded aliases, junctions, and independent copies during updates.
• Implement rollback as installation of a selected retained immutable version.
• Never invoke npx skills update or write ownership metadata for the community CLI.

Local removal

• Observe the canonical destination and every receipt-owned placement before mutation.
• Remove only aliases or junctions that still target the recorded canonical path.
• Remove independent copies only when they match their receipt unless discard is explicit.
• Remove the canonical copy only when Orca owns it, it is unmodified, and no retained receipt depends on it.
• Publish provenance changes durably before completing removal.
• Leave changed or unowned paths intact and report exactly what remains.

Recovery failure injection

• Inject failure before and after every journal transition.
• Verify partial downloads and extraction staging are deleted.
• Verify a moved destination is restored from backup.
• Verify a placed destination without a receipt is completed or restored according to journal state.
• Verify a published receipt with an incomplete journal is finalized safely.
• Verify a restarted process discovers orphaned install and removal journals without a later user operation. Deterministic startup tests prove a committed update publishes provenance and cleans its dead lock, while an interrupted removal restores both bytes and receipt.
• Verify interrupted placement reconciliation preserves the canonical install and retries.
• Test cancellation during download, extraction, staging copy, commit, provenance, and placement reconciliation.

6. Provision GCP infrastructure

Environment and Terraform prerequisites

• Inspect the active onorca-cloud project read-only and record the existing Cloud Run, GCS, Cloud SQL, IAM, and enabled-service baseline.
• Locate the authoritative Orca Cloud Terraform worktree, state, modules, and deployment pipeline.
• Confirm or create a separate staging GCP project before exercising new lifecycle and IAM behavior.
• Confirm production names and quotas, including availability of onorca-cloud-skill-packages. A read-only 2026-08-12 check returned 404 for the global bucket name, found no production orca_skills database or skill-database secret collision, and confirmed the intended existing API service and runtime identity. Cloud Run exposes a 1,000-job regional quota and 180 job runs per minute, while V1 reuses the existing API at a 20-instance ceiling and existing Cloud SQL instance; no quota increase is required.
• Confirm US storage satisfies initial residency requirements.
• Confirm Cloud SQL connection and PostgreSQL user provisioning conventions.
• Keep Firestore, Cloud Tasks, and new Pub/Sub dependencies out of V1.
• Declare every durable resource and IAM binding in Terraform; do not provision them manually with gcloud.

Dedicated GCS bucket

• Declare private bucket onorca-cloud-skill-packages, subject to Terraform validation.
• Set location to US for parity with current artifact storage.
• Enforce uniform bucket-level access and public-access prevention.
• Configure seven-day soft delete.
• Keep object versioning disabled and record object generations in PostgreSQL.
• Add a one-day deletion lifecycle for uploads/ quarantine objects only.
• Add exact approved production and development Orca origins to CORS; never use *.
• Allow only required signed POST upload and GET/HEAD download behavior and response headers.
• Keep the bucket off public custom domains.
• Define immutable final keys as packages/v1/tenants/<tenant-hash>/sha256/<prefix>/<archive-sha256>/package.tar.gz, with the logical package digest verified in object metadata and PostgreSQL.
• Define tenant-bound random quarantine keys as uploads/<upload-id>/package.tar.gz.

Database and secret

• Declare database orca_skills on existing regional PostgreSQL 17 instance orca-cloud-auth-db.
• Declare dedicated principal orca_skills_app with access only to orca_skills.
• Store its connection URL in Secret Manager as orca-cloud-skills-database-url.
• Attach the existing Cloud SQL instance to orca-cloud-api without replacing the service.
• Inject only the skill database secret into the API service.
• Verify backups and point-in-time recovery cover the new database. orca_skills shares the Terraform-managed Cloud SQL instance whose live staging and production settings both have backups, replication-log archiving, seven retained backups, and seven-day PITR enabled.

IAM

• Grant orca-cloud-api@onorca-cloud.iam.gserviceaccount.com bucket-scoped roles/storage.objectUser.
• Grant the API service account roles/cloudsql.client for the existing instance.
• Grant service-account-scoped IAM Credentials signBlob for self-signing V4 policies and URLs.
• Grant Secret Manager accessor only for skill-specific secrets.
• Verify bucket IAM contains neither allUsers nor allAuthenticatedUsers.
• Do not grant desktop, remote runtime, or end-user identities direct bucket IAM.
• Do not create or distribute long-lived GCP service-account keys.
• Keep deployment-account permissions unchanged except for reviewed Terraform management requirements. Skill sharing adds no deployment-account IAM binding: immutable API and monitor-image updates use its existing roles/run.developer, while storage inventory and scheduling use separate least-privilege service accounts.

Cloud Run configuration

• Extend orca-cloud-api in us-central1; do not create a separate V1 worker service.
• Configure bucket, 40 MiB compressed limit, 15-minute upload TTL, five-minute download TTL, fixed finalize concurrency, and skill database URL.
• Reuse existing auth base URL and application CORS configuration.
• Stream validation with fixed buffers under the existing 512 MiB memory limit.
• Add a small per-instance finalization semaphore and retryable 429 or 503 with Retry-After when saturated.
• Preserve current service scaling initially and tune only from measured CPU, latency, database, and error data.
• Define criteria for splitting finalization into a worker service if it harms existing API traffic.
• Make immutable API candidates atomically replace the complete Terraform-owned literal environment and the exact ORCA_SKILLS_DATABASE_URL Secret Manager reference.
• Reject serving or candidate drift in the runtime service account, Cloud SQL attachment, scaling, CPU, memory, volumes, mounts, ports, and probes before moving traffic.
• Keep all four skill controls explicit in both deploy workflows. Staging changed to true only with the authenticated OIDC smoke gate; production remains false.

Terraform review and apply

• Format and validate Terraform.
• Produce and review a staging plan.
• Verify the plan does not replace the existing artifact bucket, Cloud SQL instance, Cloud Run services, or unrelated IAM.
• Apply to staging and capture resource and IAM verification evidence.
• Produce and review the production plan after staging gates pass.
• Apply the approved production plan only during the rollout phase.
• Verify production with read-only bucket, Cloud Run, database, IAM, lifecycle, and CORS commands without printing secret payloads or signed values.

7. Implement Cloud metadata and APIs

PostgreSQL migrations

• Serialize concurrent Cloud Run startup migrations with a transaction-scoped PostgreSQL advisory lock before migration-table inspection.
• Prove failed DDL records no schema version and eight concurrent callers converge on one version against real PostgreSQL 16 and 17.
• Add skill_packages with owner organization, slug/name, creator, timestamps, and deletion state.
• Add immutable skill_package_versions with package and archive identities, GCS key and generation, sizes, manifest, release notes, creator, and publication state.
• Add tenant/user-bound skill_package_uploads with quarantine identity, expiry, finalization state, and failure category.
• Add skill_package_acl for organization and user principals and permissions.
• Add unpredictable, revocable, optionally version-pinned skill_share_records.
• Add bounded skill_package_audit_events without contents, filenames, or signed values.
• Add unique package slug per organization, immutable version and digest constraints, and tenant-scoped archive and final GCS key/generation constraints.
• Add active-share, ACL-principal, and pending-upload expiration indexes. The ACL index remains legacy storage and is not used for bearer resolution.
• Add foreign keys preventing blob-reference deletion while a published version uses it.
• Accept and stream-validate both the pre-release single-skill envelope and the new Agent Plugins skills-only bundle envelope during the desktop migration.
• Store the detailed bundle manifest in the existing immutable version record; expose it only after exact-link bearer authorization or to owners.
• Keep contained skills out of separate database rows and search indexes. Selective inspection reads the validated manifest attached to the exact immutable version.
• Keep detailed file identity in the in-archive manifest rather than duplicating it into GCS custom metadata. Published-object metadata contains only aggregate archive/package digests and immutable generation identity; per-file paths, sizes, modes, and hashes remain inside the authorized archive manifest and immutable PostgreSQL version record.
• Test forward migration, rollback strategy, backup restoration, and migration compatibility during mixed API versions. Unit coverage proves atomic forward/idempotent migration, ignores an additive schema version written by a newer API, and leaves no recorded or partial schema after failure. PostgreSQL 16/17 integration coverage proves transactional DDL rollback and eight concurrent startup callers converge on one version. Cloud PR #349 additionally proves the older runner and its existing SQL preserve and operate beside a simulated newer additive column/table. Cloud PR #350 requires real old/new Node-process coexistence, writes before and after a pg_dump/pg_restore, and full cleanup on disposable PostgreSQL 16 and 17; both PR and merged-main runs passed.

Authorization and lifecycle model

• Allow share resolution and share-scoped download grants without an authenticated principal.
• Treat an unpredictable active, unexpired share ID as the bearer authorization; do not apply legacy package ACLs to recipients.
• Return the same non-disclosing 404 for missing, expired, revoked, or deleted shares.
• Keep authenticated owner checks on upload, finalize, package/version management, share creation, revocation, and deletion.
• Apply distributed per-IP abuse limits to anonymous resolution and grant requests without persisting raw requester addresses.
• Apply organization retention and legal deletion rules over product rollback retention.
• Make package deletion revoke shares before dereferencing immutable objects.
• Delete an object only after a transaction proves no retained version references it.
• Design metadata/object reconciliation for partial publication and deletion failures.

Upload and finalization APIs

• Implement POST /v1/skill-packages/uploads with existing authentication, organization membership, quota, rate, and concurrency checks.
• Insert a single-use pending upload before issuing a grant.
• Create a 15-minute V4 signed POST policy bound to exact key, content type, upload ID, expected archive SHA-256 metadata, and 40 MiB length range.
• Upload directly from the client to GCS without routing package bytes through Cloud Run.
• Implement idempotent finalize by upload ID and manifest identity.
• Validate GCS key, size, type, metadata, tenant, generation, and expiry before streaming.
• Stream once to calculate archive SHA-256 and validate envelope, manifest, paths, limits, and package digest.
• Promote with an if-absent generation precondition to the tenant-scoped, content-addressed final key.
• If the tenant's final key exists, verify recorded identity without exposing cross-tenant package existence.
• Publish the version and complete the upload in a PostgreSQL transaction.
• Delete quarantine bytes after success and rely on lifecycle cleanup for abandonment.
• Make all mutating endpoints accept idempotency keys.

Package, version, and share APIs

• Implement package creation and version publication under a stable package identity.
• Implement package details and paginated version history.
• Stop accepting organization/selected-user audience fields for new bearer shares; retain legacy ACL storage only as migration-compatible data.
• Implement durable share creation with optional pinned version and expiry.
• Implement anonymous bearer-link metadata preview.
• Implement immediate share revocation for new grant requests.
• Implement Cloud package/version deletion with retention and reference checks.
• Implement version update lookup and rollback selection.

Download grants

• Implement anonymous POST /v1/skill-shares/<share-id>/download-grants after fresh active-link evaluation.
• Generate a five-minute V4 signed GET URL for the exact immutable key and stored generation.
• Set only response content type and safe attachment filename overrides.
• Grant no list or write capability.
• Return expected archive identity and byte count beside the grant for runtime verification.
• Test revocation immediately blocks new grants while already issued URLs expire within five minutes.

Cloud tests

• Test anonymous latest/pinned preview and download grants without an Authorization header.
• Test missing, expired, revoked, and deleted shares all fail without disclosure.
• Test authenticated owner management remains protected.
• Test anonymous per-IP rate limiting without recording raw IP addresses.
• Test the authenticated owner-only active-link inventory and ensure responses are not cached.
• Test expired, reused, wrong-tenant, wrong-key, wrong-size, and wrong-hash uploads.
• Test malformed, oversized, and resource-exhausting archives during finalization.
• Test finalization semaphore saturation and retry behavior.
• Test concurrent idempotent mutations and partial database/GCS failures.
• 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.
• Test quota and rate limits.
• Test durable shares resolving intended latest and pinned immutable versions.
• Test update, rollback, revocation, deletion, soft-delete recovery, and orphan reconciliation.

8. Implement desktop Cloud client and UX

Cloud client

• Make share resolution and share-scoped download-grant calls anonymous while keeping upload, package/version management, share creation, revocation, and deletion authenticated.
• Keep desktop contracts storage-provider-neutral.
• Implement bounded progress, cancellation, retry, and idempotency behavior.
• Redact signed policies, URLs, credentials, private paths, and package contents at creation.

Share experience

• Read and apply docs/STYLEGUIDE.md; use canonical CSS tokens and shadcn primitives.
• Add Share skill to eligible installed and workspace skills.
• Show name, description, author, file count, total size, scripts, executable files, and the unlisted-link warning before upload.
• Remove organization and selected-person audience controls from bearer-link publishing.
• Accept optional release label and notes.
• Package the exact previewed bytes and invalidate preview after source drift.
• Show bounded upload and finalization progress with cancellation.
• Return a copyable durable Orca URL after publication.
• Remove access editing from the bearer-share workflow; keep version publishing, revoke, and package deletion actions.
• Make clear that unsharing blocks future installs but does not remove installed copies.
• 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.
• Add selection mode whose selection survives search/filter changes and an explicit Select all results action; never select all implicitly.
• Keep the per-card share action as a one-skill bundle shortcut.
• Disable ineligible skills with visible, screen-reader-linked reasons and block duplicate skill names before review.
• Review bundle name, skill/file/byte counts, script/executable warnings, expandable per-skill details, unlisted-link behavior, and release notes.
• Add Settings → Share Skills with artifact-like explanation and a route to the Skills page.
• 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

• Show description, version, digest, file summary, scripts, and executable files without exposing internal publisher or organization identifiers.
• Treat the package as code from its author and require an explicit install action.
• Show current-machine global installation as the default.
• Allow selection of connected machine, Git worktree, or plain folder workspace.
• Show detected-agent coverage and canonical/provider topology before commit.
• Show installed-state conflicts and explicit resolution choices.
• Show phase progress without exposing grants or local private paths.
• Render installed, unchanged, updated, partial, conflict, unsupported, cancelled, and failed results with actionable recovery.
• Add incomplete-coverage retry.
• Open deep links in inspection mode without starting installation.
• Show immutable version, skill count, scripts/executables, and release notes before selection; V1 omits publisher identity from the public response and recipient UI.
• Let the recipient select all or a subset, then choose local, paired runtime, WSL, or SSH and global or workspace scope.
• Preview new, unchanged, update, and conflict counts and resolve all per-skill conflicts in one surface with Keep local as the default.
• 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.
• Group results into installed, unchanged, kept local, and failed; retry failed items only.

Skills page lifecycle

• Show installed package/version identity and update availability.
• Offer clean update, modified-copy choices, prior-version rollback, and safe local removal.
• Show whether a package came from Orca Cloud and its accessible version history.
• Refresh discovery and installation state after local or remote actions.
• Keep Cloud deletion, share revocation, and local removal clearly separate.
• 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.
• 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.
• 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

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

• Register preview, install, update, and remove through runtime RPC and desktop IPC.
• Add bounded beginUpload, uploadChunk, commitUpload, and cancelUpload methods.
• Route every request to the runtime that owns the selected host and workspace.
• Keep transfer separate from installation so grants, relayed chunks, and local files converge at the validated ingress boundary.
• Make upload sessions bounded by count, total bytes, idle lifetime, and chunk size.
• 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.
• 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

• Prefer destination-runtime direct download when it can reach approved Orca Cloud storage.
• Verify origin, redirects, generation, byte count, archive hash, and package digest on the destination runtime.
• Fall back to authenticated client-mediated chunk transfer when the host cannot reach GCS.
• Never pass the desktop's local path as a remote package source.
• Preserve the same inspection, transaction, provenance, and result behavior for both transports.
• Retry an idempotent install after a recoverable lost final response; rebuild a staged transfer before retrying so a consumed upload is never reused.
• Run the real Electron client against a paired desktop host for global, Git-worktree, and plain-folder install, unchanged preview, inventory, and removal.
• Run the same contract against a paired headless orca serve host for global and Git-worktree install, unchanged preview, inventory, and removal.
• 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

• 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.
• Hide or disable remote install when skills.install.v1 is absent.
• Show a specific host-update-required message instead of attempting the RPC.
• Test new client/old server and old client/new server.
• Test optional-field omission in both directions.
• Test a capability changing after preview but before execution.
• 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

• Confirm windows 2 is saved and reachable through orca environment list and orca status --environment "windows 2" --json.
• Confirm the host provides both a native Git checkout and a native plain folder workspace.
• 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.
• Discover installed WSL version and distros, each distro's running state, default user, home, filesystem, and Orca host support.
• Ensure at least two WSL distros are available or record a reproducible second-distro setup for the multi-distro test.
• Create isolated test skills and destination roots under explicit test workspaces; never use production user skill directories for destructive failure injection.
• Record exact Orca client/server versions and capabilities with each test run.

Native Windows package and destination tests

• 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.
• Test global home resolution without constructing the path on the macOS client.
• 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.
• Test source and destination paths containing spaces and non-ASCII characters.
• Test junction creation succeeds for a detected provider.
• Force junction denial and verify an independently copied, digest-verified fallback.
• 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.
• 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.
• 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.
• 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.
• 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

• Execute package ingress, extraction, home resolution, installation, provenance, and discovery inside the selected distro.
• 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.
• 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.
• 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.
• Test a workspace on the distro filesystem and document behavior for /mnt/c separately.
• 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.
• Capture structured test evidence without signed URLs, tokens, skill contents, or private absolute paths beyond approved test fixtures.

Windows/WSL release gate

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

• Define a host-side installer command that invokes the same installer core and structured result contract.
• Transfer immutable packages through the existing SSH/SFTP provider into bounded private staging.
• Invoke installation on the SSH host so it owns home, path, provider, and filesystem resolution.
• Add capability/version detection for the required host component.
• If unsupported, offer a package download or explicit command; never install into the desktop's home as fallback.
• Propagate cancellation and clean partial SSH transfers and staging.
• 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.
• 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.
• 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

• Record bounded package byte/file counts and package, upload, finalization, download, transfer, install, placement, and recovery durations.
• Record outcomes by error category, OS, destination kind, transport, conflict type, and placement topology.
• Record junction, alias, copy-fallback, rollback, recovery, capability-absence, and orphan reconciliation counts.
• Add dashboards for grant/finalize/share rates, authorization and rate limits, finalization saturation, archive rejection, and digest mismatch.
• Add Cloud Run 5xx, CPU, memory, instance, and skill-route latency panels and alerts.
• Add GCS quarantine/published bytes, object count, and lifecycle failure panels and alerts.
• Add PostgreSQL connection, storage, query latency, migration, and transaction panels and alerts.
• 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

• Log package/version IDs, phases, destination labels, placement outcomes, and bounded error categories only.
• Exclude package contents, filenames, manifests, raw local paths, ACL membership, durable share URLs, upload policies, download grants, and credentials.
• Redact sensitive network values before logger invocation, not after ingestion.
• Audit authorization and lifecycle events without instruction or script contents.
• 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

• 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.
• 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.
• Rate-limit uploads, finalization, downloads, share resolution, and remote transfer sessions.
• 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.
• 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

• Add independent server-side flags for upload grants, download grants, and remote installation.
• Verify disabling Cloud grants does not break skill discovery or already installed skills.
• Document finalization saturation, GCS/IAM signing failure, database outage, corrupt package, orphan reconciliation, and rollback response.
• Document coordinated PostgreSQL point-in-time and GCS generation/soft-delete restoration.
• Document package/share deletion, organization departure, legal retention, and audit handling.
• Document how and when to split finalization into its own service.

13. Complete automated and end-to-end validation

Transaction matrix

• Test fresh install, identical reinstall, clean update, rollback, explicit replacement, and safe removal.
• 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.
• 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.
• 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.
• Run native Windows and WSL scenarios on windows 2.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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

• Add deterministic fixtures authored for Orca without copying upstream fixtures.
• Add failure-injection hooks available only to tests/development harnesses.
• Add a CLI-only developer harness for local and remote integration tests.
• Keep CI commands compatible with macOS, Linux, Windows PowerShell/cmd, and WSL.
• 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.
• 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

• Apply reviewed Terraform and migrations to staging.
• Deploy orca-cloud-api skill routes disabled by server-side flags.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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

• 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.
• Run production database migrations before routing skill traffic. Disabled-route bootstrap run 31648015091 completed the skill schema migration before any skill route was enabled.
• 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.
• 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

• 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.
• Publish user documentation for sharing, access, install destinations, updates, rollback, removal, retention, and trust in docs/reference/sharing-agent-skills.md.
• Publish admin documentation for organization access, user departure, deletion, and retention in docs/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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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

• Add a separate agentSkillSharingEnabled capability that defaults off and accepts only an exact persisted true value. Manual desktop publishing remains independent.
• 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.
• Add orca skills installed --json with discovery IDs and names but no local filesystem paths.
• 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.
• Resolve exact discovery IDs before unambiguous names; fail missing, ambiguous, and duplicate bundle-folder names with actionable errors.
• Enforce the capability in the executing runtime before discovery, before package reads, and again before publishing. CLI preflight is an optimization, not the authority.
• 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.
• 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.
• Admit one agent bundle preparation/publish at a time per host so concurrent agents cannot multiply the bounded per-bundle disk and CPU budget.
• 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.
• 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.