feat(#576): durable per-scope sandbox — P3 scope durability + RO-layer content hash + reaper

[Weegy]

Summary

Issue #576, Phase 3 of 3 (interface+Docker = #776, execute tool+policy
gate = #777). Stacks on #777 — base branch is
feat/576-sandbox-p2-execute-tool, not main. Once #776/#777 merge this
PR's diff against main will shrink to just the P3 commit.

Adds durability bookkeeping, an idle-sandbox reaper, and RO-layer
content-hash materialization to @omadia/sandbox.

Migration 0044_sandbox_registry.sql

One table, sandbox_registry (scope_key PK, backend, sandbox_ref,
profile JSONB, ro_layer_hash, created_at, last_used_at + an index
on last_used_at for the reaper's sweep). Chosen with margin: at
authoring time 0040-0043 were occupied by concurrent credential-work
PRs, including an observed three-way collision at 0040 across two of
them — that has since resolved itself upstream (one of the 0040 files
was deleted and replaced by 0043_credential_asks.sql in a later merge of
origin/main into this branch). Noted in the migration's own header;
nothing here touches the credentials/ namespace.

Verified by applying the migration file verbatim via psql against a
real postgres:16-alpine container (not just eyeballing the SQL) — schema
matches what postgresSandboxRegistry.pg.test.ts expects.

SandboxRegistry — the durable bookkeeping Docker doesn't give for free

SandboxRegistry interface (get/upsert/touch/delete/listAll):

• InMemorySandboxRegistry — for tests and any deployment that hasn't
  wired a durable store.
• PostgresSandboxRegistry — migration 0044's table.

DockerSandboxBackend gained an optional registry constructor
option:

• Omitted (the default): byte-identical to what feat(#576): durable per-scope sandbox — P1 interface + Docker backend #776/feat(#576): durable per-scope sandbox — P2 execute tool + command-policy gate #777 shipped —
  deterministic container naming, zero registry calls. Regression-tested
  directly — dockerSandboxRegistry.test.ts's first suite asserts the
  no-registry path is unchanged.
• Provided: provision() records (scopeKey, containerName, profile, lastUsedAt) and re-attaches via the registry's stored sandboxRef
  rather than recomputing the deterministic name — the seam a future
  non-deterministic backend (Fly/Firecracker/a Epic: Satellites — outbound-only edge nodes (Raspberry Pi class) that pair with a device code, run selected agents, and bridge internal-only systems securely into the main omadia #746 Satellite, where the
  platform assigns the id) needs, exercised now even though this backend's
  own name is always independently recomputable. A process-local cache hit
  also touches the registry, so the reaper never sees an actively-reused
  scope as idle just because Docker itself wasn't consulted that call.

Reaper — orphaned (idle, non-persistent) sandbox cleanup

reapOrphanedSandboxes takes now as a required, externally supplied
parameter — never new Date() computed inside the function, never derived
from the registry entries. This is the #709/#710 clock-race lesson
applied here: an idle-timeout check must anchor to a clock independent of
the row being checked, or a self-referential comparison becomes racy.
reaper.test.ts has a dedicated regression test for exactly this
(the anchor is the CALLER-supplied now, not anything derived from the entries).

• profile.persistent === true entries are never reaped, regardless
  of idle time.
• A teardown failure leaves the registry row intact (for retry on the next
  sweep) and is reported in failedScopeKeys rather than silently
  dropped, and does not abort the sweep for the remaining entries.

Not wired to a scheduler in this PR. The function is a complete,
directly callable, fully tested capability — the same shape as
DockerSandbox.teardown() itself, which also isn't auto-invoked by
anything in this codebase. Hooking it to a cron/routine is a
scheduling-system integration (Pulse/routines already exist for that);
#576's scope is the sandbox substrate, not a new scheduler.

RO-layer content-hash materialization

computeContentHash (deterministic, order-independent — sorted keys,
NUL-separated path/content encoding so a shifted-boundary input like
{ab:'c'} vs {a:'bc'} can't collide, asserted directly) +
syncReadOnlyLayer, which calls Sandbox.write only when the
computed hash differs from a caller-supplied previousHash.

#576 is deliberately the mechanism here, not the consumer: the issue's
own text frames "skills materialization" as a concept that builds on
this sandbox, not part of it — inventing an org-files/skills content
source in this PR would be scope creep into a separate, undecided concept.
contentHash.test.ts proves the skip-when-unchanged behavior directly
against a stub Sandbox's write-call count, so the primitive itself is
fully exercised even with no real consumer yet.

Tests

• contentHash.test.ts (8), reaper.test.ts (6),
  dockerSandboxRegistry.test.ts (4) — stub/pure, no Docker or Postgres
  needed, always run in npm test.
• postgresSandboxRegistry.pg.test.ts (5) — gated on
  GRAPH_PG_TEST_URL/MEMORY_PG_TEST_URL/DATABASE_URL, same
  probePgTest convention as postgresCredentialStore.pg.test.ts.
  Verified locally against a real postgres:16-alpine container
  (docker run, migration applied via psql, all 5 green) — not just
  trusted to pass under CI's pg service; not touching ci.yml since the
  existing test:pg step's recursive glob already picks up
  test/sandbox/*.pg.test.ts.

Mutation-check evidence (dist rebuild between runs)

Removed the persistent-skip guard
(if (entry.profile.persistent) continue;) in reaper.ts, rebuilt
@omadia/sandbox: the "never reaps a persistent sandbox" test failed as
expected (a persistent scope got reaped). Reverted, rebuilt again,
confirmed green. (P1's egress/traversal mutations and P2's deny-bypass
mutation were separately verified in their own PRs; this round targets
the one new security/data-loss-relevant branch P3 adds — the persistent
flag is the only thing standing between the reaper and tearing down a
sandbox a deployment explicitly asked to keep.)

Blast radius

• New: contentHash.ts, sandboxRegistry.ts, postgresSandboxRegistry.ts,
  reaper.ts (all in @omadia/sandbox), migration 0044, 4 new test
  files.
• Modified: dockerSandbox.ts (additive registry option — see the
  regression-tested no-op path above), index.ts (barrel exports),
  package.json (added pg peerDependency).
• No orchestrator, src/index.ts, agentBuilder.ts, credential, or skill
  namespace changes.
• No new consumer of the reaper or the RO-layer sync wired into a live
  path in this PR — both are complete, tested, standalone capabilities;
  see the sections above for why that's the right cut rather than scope
  creep.

Verification run locally (this branch, after merging origin/main —

currently at 6c9081fd, includes #578 P3 keychain-asks)

• npm run build (full workspace): green
• npm run typecheck (full workspace incl. golden/adversarial): green
• npm run lint: clean
• npm run test: 7223 tests, 7211 pass, 0 fail, 12 skipped
  (pre-existing), 0 cancelled
• postgresSandboxRegistry.pg.test.ts run separately against a real
  local Postgres: 5/5 green (see above)

Base / stacking

Branched from feat/576-sandbox-p2-execute-tool (#777). Do not merge
before #776 and #777.

What's NOT in this PR (P4)

Admin view (web-ui) for the sandbox registry — explicitly optional per the
phase-4b plan ("nur wenn Zeit UND Konfidenz... Sonst sauber dokumentiert
weglassen"). Not attempted: web-ui work needs its own design pass (what
does an operator actually need to see/do — list live sandboxes, force-reap
one, inspect RO-layer sync state?) that I don't want to guess at without
that input, and it would be a fourth stacked PR on top of three already
awaiting review. Documenting it as deliberately deferred rather than
half-building a page nobody asked for the shape of yet.

Open questions for Marcel

• The reaper's idle threshold and sweep cadence are entirely caller-owned
  (idleThresholdMs is a parameter, there's no default and no scheduler).
  Worth a follow-up issue once there's a real operator surface to configure
  it from, rather than me guessing a number now.
• PostgresSandboxRegistry.upsert's ON CONFLICT clause uses
  COALESCE(EXCLUDED.ro_layer_hash, sandbox_registry.ro_layer_hash) so a
  re-provision that doesn't pass a hash doesn't clobber a previously
  synced one — worth a second pair of eyes on that semantic, since it's
  the one place this migration's upsert behavior isn't a straight
  "last write wins."

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}