## Summary
- Add the unpublished, one-shot invocation uploader and commit-triggered detached wake for the existing core-owned local invocation queue.
- Keep receipt identity, queue admission, claims, leases, retries, acknowledgements, tombstones and uploader state under one LocalStateCoordinator.
- Keep the package private, dependency-free and dormant: no host observer exists, and the current unpublished package has no authenticated native credential-provider artifact.
## Why
AERIE-1856 established durable adapter admission and atomic invocation-queue creation, but it deliberately stopped before delivery. Later Claude Code, Codex and Pi adapters need one common local delivery contract rather than host-specific network or credential logic.
This slice closes the local path from a committed queue entry to one bounded upload pass while preserving the authority boundary: observers cannot select credentials, endpoints, paths, receipts, proofs, queue writers or uploader policy.
## Business value
This makes later host adapters small and fail-open. They can submit a bounded observation and continue host execution while core owns durable retry, deduplication, privacy and server-outcome handling. Offline operation, child-process loss and CLI overlap do not require a daemon or expose credentials to host configuration.
## Slice and scope
- Slice: AERIE-1857 — telemetry rollout 11/19
- Strict predecessor: AERIE-1856 / 5107e4b031fceb310ba2f94c92c4c5ee69b19d63
- Rebased onto current main: fcc9897bfe4fce1b3a2e6a3364795891d490bb6d
- Exact reviewed head: 89fe7e570419be5c0524c59f5dd2504f8c2c4d7e
- Package subtree: 781aa7350a38ee85bd9002373ad23974af1ee4b5
Owned surfaces are limited to packages/add-aerie-skill/**.
## Runtime design contract
### Queue and receipt authority
Invocation receipt IDs are canonical 43-character unpadded base64url encodings of exactly 32 random bytes. Core creates the exact seven-field wire payload only after capacity and current-binding checks. Retries reuse the committed ID, proof and payload.
The invocation queue and delivery metadata share the existing state generation and coordinator. Combined queue and delivery metadata are bounded to 4,096 records and 8 MiB. Attempt accounting occurs durably at claim time, before network I/O, so process loss cannot bypass the 255-attempt bound.
A 30-second lease and claim token protect acknowledgement. Expired or stale claimants cannot retry, acknowledge or terminalize a newer claim. Terminal paths remove proof-bearing payload even when tombstone capacity is full.
### Bounded one-shot delivery
One drain pass processes a finite batch and starts no work after its 25-second monotonic deadline. Each HTTP request is bounded to five seconds. Credential lookup is part of the same pass budget. Response reads are byte-bounded and cancel the underlying stream on overflow, malformed chunks, decoding failure, abort or read failure.
The transport posts only the exact invocation DTO to /skill-device/telemetry/invocations with the core-retrieved bearer. It maps:
- the five approved 200 outcomes to terminal acknowledgement;
- deterministic 400 and unavailable 404 to terminal rejection;
- 409 invocation_receipt_conflict to retained needs_repair evidence;
- 401/403 to durable auth_deferred retry for later foreground reauthentication;
- 429, 5xx, timeout, malformed response and transport failure to bounded retry.
Backoff is jittered and capped at six hours. Invocation payloads expire after 35 days or the attempt bound, leaving bounded content-free terminal evidence.
### Wake and credential boundary
Wake happens only after a new queue entry is durably committed. Duplicate, stale, rejected, capacity-full and other no-new-entry outcomes do not wake.
Core launches only process.execPath plus the fixed private argument, with shell: false, ignored stdio, detached execution, windowsHide, unref() and a closed minimal environment. The executable, entrypoint and working directory are package-owned and physically verified. No credential, payload, proof, endpoint, host value or caller-selected path enters arguments or environment.
The current private manifest intentionally has no runtime or optional dependency. It therefore does not trust ancestor modules, mutable package-local native code or runtime self-hashes as credential authority. Without an authenticated native provider, detached production dispatch fails closed before claim or network. The complete queue → wake → attempt → acknowledgement flow is exercised through a build-time test substitution that is absent from production JavaScript, declarations and the tarball.
A later packaging/publication slice may establish an optional native-provider dependency and external integrity authority. This PR does not invent that authority.
### Concurrency and recovery
Installer drain runs before the installer lock and uses the exact same coordinator/root identity as admission and uploader composition. Network runs outside the state lock. Independent coordinators over one root prove exclusive claims, close/reopen recovery, lease reclamation, stale-response rejection and one terminal settlement.
Platform state roots are canonical for Linux XDG, macOS Application Support and Windows LOCALAPPDATA; generic test/application bases retain the existing .aerie-skill convention. Windows remains fail-closed without the required platform security checker.
## Explicitly out of scope
This PR adds no:
- real Claude Code, Codex or Pi observer/producer;
- daemon, timer, scheduler, startup sweep or guaranteed detached completion;
- browser popup, background reauthentication or detached credential deletion;
- trusted-runtime queueing; AERIE-1958 remains the sole trusted-runtime path;
- public CLI flag or public uploader/queue/credential authority;
- authenticated native credential-provider artifact or runtime dependency;
- npm publication, registry mutation, deployment or production API call;
- generated Convex change or real-host/native manual campaign.
## Behavior and production effect
Dormant. The package is still @aerie/add-aerie-skill, private: true, UNLICENSED, unpublished and dependency-free. There is no real host producer, and unavailable credential authority causes the private child to exit without claiming or sending.
Ordinary import, startup, login and logout do not sweep the queue. Private disable/re-enable preserves queued records, installed Skills, credential state and installation lineage; it is not exposed as a public CLI flag.
The tarball contains only two bundled JavaScript entrypoints and the transitive public declaration allowlist. Private uploader, internal composition, adapter-runtime state and wake modules are not physically shipped as standalone deep modules.
## Test plan
- [x] Final focused independent validation: 6 files / 113 tests repeated three times.
- [x] Full package suite: 33 files / 428 tests.
- [x] Production and test TypeScript checks.
- [x] Exact Biome on all 49 changed TypeScript/JSON/script files.
- [x] Architecture-boundary, Convex-path, read-bound and test-architecture checks.
- [x] Direct HTTP transport matrix, bounded streaming and cancellation tests.
- [x] File-backed claim, close/reopen, lease reclaim, stale claimant, migration-through-drain and coordinator-overlap tests.
- [x] Real generation commit-before-wake and no-new-entry wake suppression tests.
- [x] Two byte-identical builds.
- [x] Deterministic build across root and contracts-local topologies: 40 files, SHA-256 6ed81940f81cca805a3e2aaef1d125d1ff78476f679a225fabd6d056f8ea5e1a.
- [x] Serial pack/install/import/declaration/private-dispatch validation: 43 entries.
- [x] Pack SRI: sha512-KYo76D79vabGEZK5n/J5nSh15RtP01SRLTjgRK7/UrNMEhUhrQRkxryjzeJBKeQLuPyUztuf8o/kj/ZMubYbaA==.
- [x] Production archive scans: no source, tests, lifecycle hooks, test capabilities, native provider, secrets or private standalone runtime files.
- [x] git diff --check and clean worktree.
Full/root repository tests and pnpm test:root were intentionally not run.
## Independent review
The same independent reviewer audited each repaired range. Findings covering identity, lease/CAS behavior, payload retention, environment/path authority, public declarations, live coordinator composition, package importability, native-provider provenance, canonical roots, stream cancellation and duplicated probe contracts were repaired or explicitly rejected where they would invent authority outside this slice.
Final pre-rebase verdict: PASS on package tree 41f4be7f15c32f7132278dc4807fdde8833f6d4c.
After seven unrelated commits advanced main, the branch rebased cleanly. No upstream commit touched packages/add-aerie-skill; the subtree remained byte-identical. The same reviewer resumed and returned exact-head PASS.
Mercy then identified concrete repair classes covering terminal metadata reclamation, truthful settlement, stale-settlement, and deferred-release accounting, exact pre-RNG capacity projection, credential-authority, final-read, overlap-state, and foreground drain reporting, foreground/detached platform-root identity, recoverable per-account vault sequencing, and private-dispatch failure exits. The same author repaired them and the same reviewer returned exact-head PASS at 89fe7e570419be5c0524c59f5dd2504f8c2c4d7e after byte-identical package rebases onto current main. The non-blocking self-hash note remains documented as best-effort substitution detection, not external integrity authority.
## Risks and monitoring
- Detached wake is best effort. Process launch, machine shutdown or missing credential authority may leave work queued until another admission or bounded foreground drain.
- Authentication errors retain the stable record rather than deleting credentials from a detached process. A foreground command must reauthenticate before a later successful retry.
- Current native-provider absence is deliberate. Adding an unauthenticated local module would be worse than deferred delivery.
- The queue is best-effort telemetry: hard capacity, attempt and age bounds drop proof-bearing payload while retaining bounded terminal evidence.
## Rollback
Before publication, revert this PR to remove automatic wake and private uploader composition. If preserving state compatibility is required, revert the wake/dispatch and transport surfaces while retaining the queue schema and manual bounded drain. No package has been published, no host is registered, and no production state, deployment or network operation was performed by this rollout slice.