feat(code-editing): Step 4 — save→redeploy orchestration (flag-gated, inert)

[WayforthOfficial]

The integration step, per the signed-off design. Wires building + versioning + activation onto the dispatch path — flag-gated and inert (AGENT_VERSIONED_DISPATCH_ENABLED, default OFF). No merge — for review.

The flow

create version → validate (PARAMS extraction + requirements vs allowlist) → build image (injectable build_fn) → forward-only atomic activate. Fail-closed: any failure before activation leaves the prior active version serving.

The two tests you said you'd review hardest — proven against real Postgres

scripts/agent_redeploy_proof.py runs the real orchestrator + dispatch resolver against a live DB with an injected fake build_fn (no E2B/mirror needed):

A. build failure leaves prior active version serving
  PASS  redeploy raises RedeployError(build)
  PASS  active pointer still v1 (agent not broken)
  PASS  failed build recorded as a 'failed' version
B. in-flight isolation (run before edit stays on old version)
  PASS  edit activated v2
  PASS  run R1 (pre-edit) still bound to v1      ← version_id binding
  PASS  run R2 (post-edit) bound to v2
  PASS  the two runs resolved DIFFERENT versions
C. forward-only activate
  PASS  older build (v8) did NOT clobber newer active (v9)
ALL PROPERTIES PROVEN ✓ (8/8)

• (1) Build failure → pointer unmoved: redeploy raises RedeployError(build), the new version is marked failed, and active_version_id is still v1 — a bad edit can't take an agent down.
• (2) In-flight isolation: a run dispatched before the edit is bound (agent_runs.version_id) to v1; a run dispatched after gets v2. The binding is set once at dispatch and never re-read, so the activate can't touch a running run.

One refinement over the signed-off design (flagging it)

The design said UNIQUE + advisory lock for the double-save race. I implemented UNIQUE + forward-only activate instead — activation only advances version_no, so a slow older build can't clobber a newer already-active version (proof C). This gives the same last-submitted-wins without holding a DB transaction/lock across the multi-second E2B build (which the advisory-lock approach would have required). Same guarantee, no long-held connection.

Flag-gating + backward-compat

• OFF (default) → save + dispatch are the legacy single-file .code paths, byte-identical. Proven by the unchanged suite + explicit _resolve_dispatch flag-off unit test.
• ON → save redeploys (create→build→activate); dispatch resolves the active version, boots its image, writes its files. A version with image_ref IS NULL (backfilled v1) falls back to the .code path but still binds version_id for audit — gradual cutover, agents move to the image path only as rebuilt.

Migration 070 (agent_runs.version_id)

Additive/nullable; idempotent check_db mirror; ephemeral-pg proof: additive, idempotent, reversible (existing runs intact with version_id NULL, down-migration clean).

Mirror — option (B), as agreed

build_fn is injectable (real build_agent_image in prod, fake in tests — same pattern as Step 1's sandbox_factory). The prod build_fn reads AGENT_MIRROR_URL (empty until the mirror stands up). The mirror is a flip-on gate, not a merge gate — Step 4b proves the real end-to-end build before the flag ever flips.

Tests

9 new unit tests (fail-closed validation, build-never-activates, flag-off dispatch identical, NULL-image fallback, versioned path). Full suite 616 passed.

Not in this PR (next)

• Step 4b: stand up the minimal real mirror + prove the real egress-locked build E2E, then the flip.
• Step 5: multi-file save endpoint (the orchestrator already takes a files map) + frontend.

🤖 Generated with Claude Code