fix(core): shared sidecar must not hang one-shot scripts; se 0.3.3 + agent×pkg-mgr e2e matrix

[NathanFlurry]

Summary

Headline fix: the default shared sidecar pool no longer hangs one-shot scripts on exit. AgentOs.create() uses a process-global shared sidecar; vm.dispose() released the VM lease but left the sidecar's child process + stdio referenced, pinning the Node event loop — so every standalone script (all quickstart examples) completed its work and then hung until SIGINT.

How it works now

• Counted event-loop hold. A hold is taken for the whole create→use→dispose lifetime of each VM lease (taken before VM creation, released on dispose/failure). The sidecar child + stdin/stdout/stderr are ref()'d while holds > 0 and unref()'d at 0. A counter (not a boolean) so concurrent create/dispose can't clobber each other.
• unref() ≠ kill. The sidecar stays pooled and reusable across VM disposal and is re-ref()'d on the next lease. It's tied to the host-process lifetime, not the VM lifetime — so a long-running server keeps it; a finished one-shot script lets the loop drain.
• Instant reap on exit. A one-time synchronous process.on("exit") SIGKILLs pooled sidecars, so a clean exit reaps them immediately (no orphan, no stdin-EOF grace wait). No SIGINT/SIGTERM handlers — the host owns signals (SIGINT still flows via the process group; SIGTERM-driven exit still closes stdin).

Also in this branch

• Pin secure-exec 0.3.3 (npm + crates).
• tests/agent-pkg-matrix.e2e.test.ts — skipped-by-default (gated by AGENTOS_MATRIX_E2E) real-API matrix: 4 package managers × 4 agents, fresh installs, asserts live token streaming. Codifies the issues hit shipping the preview (stale model ids, OpenCode config, permission keys, gap-based streaming, ACP-bootstrap flakiness).
• tests/shared-sidecar-clean-exit.test.ts — regression for the hang above (spawns a real create()+dispose() script with no process.exit() and asserts it terminates on its own).
• agentos-sidecar crate packaging fix — AGENTOS_SYSTEM_PROMPT.md moved into the crate (src/) so cargo publish can package it (the prior out-of-crate include_str! broke the isolated package-verify build); dropped the now-empty fixtures dir from @rivet-dev/agentos-core's files.
• docs(sessions) — document OpenCode agent config (model + provider baseURL ending in /v1 + cwd), the one real "didn't work out of the box" gap.

Review

Reviewed by two subagents (correctness/concurrency + branch/tests/docs). Addressed: counted (not boolean) hold to survive concurrent create/dispose; clear cached child + reset hold count on full dispose; loud warning if the secure-exec child handle can't be resolved (so the optimization can't silently regress); removed the empty fixtures dir from files; { recursive: true } in the docs mkdir; dist-existence skip guard on the clean-exit test.

Test evidence

• Clean-exit regression test: pass (was a 60s hang).
• All 4 quickstart examples exit cleanly verbatim: hello-world ~2.7s, filesystem ~3s, cron ~4s, agent-session ~7s (streamed + responded + exited); no orphaned sidecars.
• agent-pkg-matrix against the published release: 16/16 live-streaming.
• Core suite: 265 passed / 9 skipped, no regression.

🤖 Generated with Claude Code

[railway-app]

🚅 Deployed to the agentos-pr-1551 environment in agentos

Service	Status	Web	Updated (UTC)
agentos	✅ Success (View Logs)	Web	Jun 27, 2026 at 10:33 pm

---

🚅 Deployed to the agentos-pr-1551 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
agent-os	✅ Success (View Logs)		Jun 27, 2026 at 10:33 pm

[NathanFlurry]

Ran a second adversarial review pass over the counted-hold rewrite (it was written after the first review, so it was itself unreviewed). Fixed everything it surfaced and re-verified:

• [BUG] rejected-spawn wedge — a failed sidecar spawn left nativeProcess as a rejected promise, permanently wedging the pool. Now cleared on failure so the next create() retries.
• [BUG] orphan child on failed handshake — the child handle was cached after authenticateAndOpenSession(); a failed handshake left the spawned child untracked/unreapable and pinning the loop. Now cached right after spawn() and SIGKILL'd on failure.
• [RISK] hold-counter clobber — disposeSharedSidecarNativeProcess no longer force-zeros the shared counter (could clobber a re-acquired generation); release-without-acquire now warns instead of silently flooring.

A separate verification pass confirmed the earlier fixes (counted hold, sharedChild clearing, internals-warning, package.json files, docs recursive, test dist guard) all landed correctly and found no further issues.

Re-verified: pnpm --dir packages/core build clean (0 TS errors); core suite 265 passed / 9 skipped; clean-exit regression passes; quickstart examples exit cleanly (~2.7–7s).