Neon branch-per-attempt disposable DB fork for APR execution (implements #7649)

[JSONbored]

Problem

#7649 ratified Neon branch-per-attempt as the disposable data-fork mechanism for APR execution — a per-attempt copy-on-write database branch, mirroring worktree-pool.ts's per-attempt code checkout. No implementation exists yet.

Area

packages/loopover-engine/src/miner/ (wherever worktree-pool.ts's attempt lifecycle is orchestrated), control-plane/ (Hyperdrive connection routing).

Proposal

At the start of an AMS attempt against an APR repo, create a Neon branch off that tenant's database (via Neon's branching API), route that attempt's DB connection through Hyperdrive at the branch instead of the tenant's primary database, and discard the branch when the attempt concludes (merged or abandoned) — never auto-merging branch data back into the primary. Mirror worktree-pool.ts's create/discard lifecycle hooks so this activates and tears down at the same points in an attempt's lifecycle as the code-side fork already does.

Deliverables

• Branch creation at attempt start, keyed to the attempt (not the tenant globally — concurrent attempts against the same APR repo get independent branches).
• The attempt's DB connection routed at the branch via Hyperdrive.
• Branch discarded on attempt conclusion (merged or abandoned), never auto-merged into primary.
• Tests: two concurrent attempts don't see each other's writes; a destructive query inside one attempt's branch never reaches the tenant's primary database.

Resources

• Disposable per-attempt data/DB fork for APR execution (data-side equivalent of worktree-pool.ts) #7649 (the ratified decision this implements)
• Real Postgres/Hyperdrive driver for control-plane's provisionDatabase/deprovisionDatabase #7653 (the Neon/Hyperdrive driver this builds on)
• packages/loopover-engine/src/miner/worktree-pool.ts (the code-side precedent this mirrors)

Boundaries

APR data-fork only — BYOR's target database (customer-owned) is explicitly out of scope, per #7649's own boundaries.

maintainer-only — data-safety mechanism handling real tenant data, not a first-pass contributor task.

[linear-code]

JSO-5496

[JSONbored]

Investigated before implementing. Found a real gap between this issue's proposal and what exists today — flagging rather than guessing at an interpretation.

No Cloudflare Hyperdrive binding exists anywhere in the deployable config. control-plane/wrangler.jsonc is real, deployable infrastructure (KV namespace, Durable Object containers for OrbTenantContainer/AmsTenantContainer, cron triggers) — but declares no hyperdrive binding. The only Hyperdrive references in control-plane/src are doc-comments in neon-database-driver.ts/tenant-provisioning-driver.ts stating routing through Hyperdrive is deferred to "#7654's job once control-plane has a deployable service to attach one to." That comment is now stale in one respect (control-plane does have a deployable service — #7654 closed) but accurate in the conclusion: no Hyperdrive binding was actually added, and I found no issue currently tracking adding one.

Separately, "Hyperdrive" may not be the right mechanism for where this issue's own cited precedent actually runs. This issue names worktree-pool.ts (packages/loopover-engine/src/miner/) as the code-side pattern to mirror — that's the AMS miner's attempt-scheduling code, which runs as a bare Node.js process in a container (self-host today; the same packages/loopover-miner/Dockerfile image is what AmsTenantContainer provisions for the hosted path too — confirmed via control-plane/src/worker.ts's container image reference). Cloudflare Hyperdrive bindings (env.HYPERDRIVE.connectionString) are a Workers-runtime construct; I did not find evidence they're accessible to a bare containerized Node process the way this issue's proposal describes ("route that attempt's DB connection through Hyperdrive"). I also found no code anywhere in control-plane/src invoking the miner's iterate-loop/attempt-execution logic — AmsTenantContainer today is container lifecycle (start/stop/provisioning) only, not attempt dispatch — so it's not yet demonstrated that hosted AMS attempt execution exists for this to plug into.

The underlying Neon branch-creation mechanics this issue needs do already exist and are well-tested (neon-database-driver.ts's provisionDatabase/dropDatabase, real Neon branching API calls) — that part is a solid foundation to build attempt-level branch-off-a-branch forking on top of. The open question is specifically how the forked branch's connection reaches the attempt process (direct Postgres connection string vs. some Hyperdrive-adjacent path), and whether that's meant for self-host, hosted, or both given they currently share the same miner codebase but different runtimes/orchestration.

Recommend clarifying scope (self-host vs. hosted vs. both) and the actual connection-routing mechanism before implementation — leaving this open rather than building against an assumption.

[JSONbored]

Progress: the core Neon-forking module has shipped as its own PR — #8205 (`createAttemptDbFork`/`discardAttemptDbFork`, self-host scope, no Hyperdrive needed — see that PR's description for why). It's standalone and inert until wired into `attempt-cli.ts`'s live `runAttempt` pipeline, which I'm deliberately treating as a separate, small follow-up given how production-critical that ~700-line function already is (it's the real, live coding-agent execution path).

Remaining for this issue:

• Wire `createAttemptDbFork`/`discardAttemptDbFork` into `runAttempt`'s acquire/finally lifecycle (mirroring `allocator.acquire`/`allocator.release`'s existing shape), config-gated so it's a no-op for any operator who hasn't configured Neon credentials
• The hosted-execution portion is separately blocked by Deliver secrets/env vars into a running hosted tenant container (OrbTenantContainer/AmsTenantContainer) #8202 (no mechanism exists yet to deliver any secret into a running hosted container) — will split into its own issue once Deliver secrets/env vars into a running hosted tenant container (OrbTenantContainer/AmsTenantContainer) #8202 is resolved, rather than leaving this one meaning two different things over time

Keeping this open until the self-host wiring lands.