A lagging deployment has no plan-then-apply migration path: the config delta that prevents boot is never surfaced

Amended 2026-08-03T16:30Z — narrowed from a bundled auto-update-caller + migration ticket to the operator-invoked migration bootstrap only, per @neo-gpt's [NEEDS_NARROWING] intake correction (#16454#issuecomment-5168995671) and my acceptance (#16454#issuecomment-5169058333). Cadence, kill-switch and unattended scheduling moved to #16448/D#15758. No code existed at amendment time.

Amended 2026-08-04T08:xxZ — truth-fold to the delivered contract, operator-authorized. The prescription is the operator's P0: one supervised Neo command repairs a lagging or broken plane with no hand-issued Docker mutation. Two things changed under it since the last amendment, and the ACs below now match the code rather than the plan:

1. #16447 was closed NOT_PLANNED. It had been this ticket's input producer — the census-derivation half. Derivation folded in here instead, so there is one resolver and not two. Anything below that read as "consumes the discover result" is gone.
2. @neo-gpt-emmy's Drop+Supersede was retracted after the operator's correction that the target has no pointed pipeline and no existing update automation. Her three in-place Required Actions replaced it; RA2's outcomes are now prescribed as ACs rather than left as review correspondence. Reviews: PRR_kwDODSospM8AAAABISsOGw and the retraction #16456#pullrequestreview-4849539316.

The compose-identity limb was split out and merged separately as #16458 — a single -f could not address a two-file plane, so no correct invocation existed while that was open. Delivery: PR #16456.

Context

A deployment on an old revision cannot be repaired by a rebuild, and the reason is declared in our own substrate.

ADR-0019 §10.8 (amended by #16229): orchestrator.authorityProfile has no default — "a role is declared, never inherited", requiredness is "armed by the emptiness", and "a refused launch writes no state directory, no PID file, and no log." A deployment crossing that cut without declaring NEO_AI_ORCHESTRATOR_AUTHORITY_PROFILE does not boot. It is one of 13 such required inputs.

So the delta a lagging deployment must cross is not the revision delta. It is the config-contract delta, and nothing surfaces it.

Measured on this plane at 2026-08-03T16:2xZ, not asserted:

mc-server / orchestrator / kb-server   /app/.neo-revision   efe4490dd7
origin/dev                                                  8a5808007a     → 40 commits behind

⚠️ That measurement is historical and must not be re-cited as current. @neo-gpt-emmy brought the plane to d2ddb89180 on 2026-08-03 evening; it is 0 commits behind as of 2026-08-04. The lag is kept above because it is the evidence the problem was real, not a live reading — and because the lagging-plane fixture this ticket needs no longer exists on our own infrastructure, which is why the proof AC calls for a deliberately pinned disposable one.

The Problem

Two capabilities ship and neither is called.

1. ai/examples/cloud-deployment/deploy-pipeline.sh (11.6KB) — resolves one canonical revision before Docker runs, invokes redeployPreflight.mjs, never runs down -v, pins --project-name, gates on up -d --build --wait. git grep deploy-pipeline finds only docs, archives and Discussions. No npm script, no CI job, no caller. D#16304 row A named the falsifier a year ago: "answerable by trying to wire it once."

2. ai/scripts/lint/config-leaf-parity.json → $composeDefaultParity — the executable classified census, per profile. Read today by the parity lint to catch drift; read by nothing to tell a deployment what it is missing.

Wiring (1) alone is the trap: it would rebuild a still-invalid configuration and land on the same unhealthy plane, loudly via the health gate but no closer to running. That is why this ticket is plan-then-apply and not a caller.

And a hard blocker for apply, confirmed against live container labels rather than reasoned:

project      = neo-local-agent-os
config_files = …/docker-compose.yml , …/docker-compose.local-agent-os.yml

The pipeline takes exactly one -f and defaults --project-name to neo-agent-os. Invoked as-is against this plane it drops the overlay and addresses a different project — unattached volumes or a preflight refusal. (@neo-gpt named this on D#16193 on 2026-08-01; it is now measured.)

The Architectural Reality

• $composeDefaultParity.census — requiredDeploymentInputs (13), optionalOverrides (15), baselineUniqueKeys → remainingUniqueKeys = 45 → 30 (the #16039 cut). ADR-0019 §10.8: "when they disagree, the JSON is right and this table is stale." The plan derives from it; it never carries a copy.
• $composeDefaultParity.forbiddenEnv — 22 retired/derived keys, each with a reason string, many naming the owner or replacement (NEO_MESSAGE_WAL_DIR → "derived from NEO_MEMORY_WAL_DIR").
• redeployPreflight.mjs — the survivability gate; the reason a generic updater (Diun/Dockcheck class) is disqualified per #16055, where a deployment lost its Memory Core corpus to a redeploy.
• /app/.neo-revision — the instrument. ai/deploy/Dockerfile: "The label is an assertion, while /app/.neo-revision is measured artifact truth."
• DEPLOYMENT_RUNTIME_LIFECYCLE_OPERATIONS is Object.freeze(['restart']) (DeploymentRuntimeAccessService.mjs:15). rebuild arrives via the external pipeline and never by widening that allowlist (D#15758:62).

The Fix

One operator-invoked command, two modes, mutation strictly behind a clean plan.

1. plan — reads, never mutates. Reports the deployed revision and the exact desired SHA; every missing requiredDeploymentInputs key with its reason; every forbiddenEnv key present with its replacement; config-overlay drift; the discovered compose identity (project + file list); and preflight readiness. Unknown or unreadable conditions fail closed — refuse with a named reason rather than guess.
2. apply — refuses unless the plan is clean. The operator supplies the required values; the command runs the existing overlay migration and the shipped pipeline at the exact pinned revision, preserving target project identity and the discovered compose file list.
3. Multi-file compose support in the pipeline — the minimum capability change apply requires. NEO_DEPLOY_COMPOSE_FILE accepts a delimited list and expands to repeated -f; a single path stays byte-compatible.

Contract Ledger

Decision Record impact

none. This wires shipped capability and does not implement D#15758's out-of-cohort activation authority (still [DIVERGENCE_WINDOW_OPEN]). No ADR is amended; ADR-0019 §10.8 is read as the census authority, not modified.

Acceptance Criteria

Marked against PR #16456 at head 9de58fd3d9. [x] means asserted by a committed spec or a merged change; the two open items are the ones needing a real plane.

• plan surfaces the real delta, derived from $composeDefaultParity — not from a list written into this ticket. Delivered: resolveCensus fails closed on an unknown or mismatched profile, deriveContractDelta names every missing required input with its reason and every forbidden key with the census's verbatim replacement text, so no second copy can drift from the authority it paraphrases.
• Observations stay per service; the census is judged per service. A union is fail-open, not conservative: it only shrinks the delta, so a key set on one container and absent from another reports as satisfied for both. Measured on the canonical profile, four of the thirteen required inputs are declared by one service only and a fifth by two of three, so a union both credits a service with config it does not carry and holds it to keys it never declares. The per-service authority is $composeDefaultParity.profiles[…].services → each service's config template, resolved through the parity lint's own exported buildConfigEnvDefaultsForTemplate, so there is no second mapping.
• Every unestablished input blocks rather than yielding CLEAN. A service observed empty (silence from a stopped container is not absence), an unresolvable declared scope, an unreadable /app/.neo-revision, a required key no service declares (NEO_DEPLOY_HOSTNAME is the live instance — unattributable, never assigned to a defaulted owner), and a required key present but empty, which satisfies a presence check and configures nothing.
• plan carries the repair, not only the diagnosis. --set <service>.<KEY>=<value> turns a missing or empty required input into a declared transition the apply performs. Without it, a plane missing a required input is refused from its own observation and the operator must fix it by another path — the manual intervention this ticket exists to remove. A supplied value that is itself empty blocks rather than replacing one unusable value with another.
• The declared repair reaches the transaction, asserted at the boundary. buildPipelineEnv is pure and exported so the crossing is a value, not a side effect: a test proving only that the pipeline was invoked passed throughout the defect where --set reached the plan and never reached the transaction. The pinning (NEO_REF) and discovered identity must survive alongside a forwarded value, so a desired key cannot overwrite what makes the transaction exact.
• The transport's limit refuses instead of guessing. Desired values travel by Compose interpolation, which is global — one value per key per project — while the carrier is per service, so it can express a transition the transaction cannot perform. Conflicting values across services block at plan time with the reason naming the transport; identical values do not. Whether per-service overrides warrant a generated overlay fragment is not decided here.
• Compose identity is discovered, not assumed — the plane's project and file list are read off com.docker.compose.project.config_files, and an undiscoverable identity blocks rather than defaulting, because the pipeline's own default addresses a different project with the overlay dropped. Addressing a two-file plane merged separately as #16458.
• A failed preflight aborts before touching containers. The assertion is committed in #16458's spec as a positional check — the recorded preflight index precedes the first Docker index, rather than both merely appearing — and this path inherits it by invoking the pipeline rather than reimplementing the sequence. Stated as inheritance because that is what it is; nothing here re-proves it.
• apply refuses a dirty plan. Implemented but unasserted — the guard exists and prints apply refused — … Docker was NOT invoked, and no spec covers it. "Stopped" and "stopped before touching containers" are different guarantees, and only the second one matters here, so this needs the invocation-boundary witness treatment rather than an exit-code check.
• plan never mutates, witnessed on both the clean and dirty paths: no container lifecycle call and no file write to the target. The core's purity makes this structurally true of buildMigrationPlan; it is not yet asserted for plan mode end to end.
• The migration outcome is proven against a deliberately pinned disposable fixture: all three Brain containers healthy at the exact target revision, /app/.neo-revision verified moved per service, durable volumes still attached, KB/MC reachable after the transition, and no hand-issued Docker command in the path. This is @neo-gpt-emmy's RA3 and it is L4 — operator-gated evidence the sandbox cannot reach. test/playwright/integration-parity/ already provisions a disposable Compose plane via fixtures/parityComposeWebServer.mjs, so this is an extension of an existing harness rather than a build. The standing version of this proof is #16455's, not this ticket's.
• PipelineWiring.md documents the bootstrap — delivered 7a69d2417c. Every prior section described the pipeline running FORWARD from a known-good state; nothing said how to point it at a plane that had already drifted. The new section leads with why a rebuild alone cannot repair (the authority leaf carries no default, so a rebuild reproduces the refused launch at a newer revision), then the four properties an operator needs before running it — per-service refusal, the wider derived config cohort, --set travelling as a Compose fragment appended last rather than as pipeline environment, and preservation of interpolated values — plus both honest bounds. Cadence and unattended activation added to Out of scope so the bootstrap cannot read as a resident updater.

Binding-token transition: this ticket's ls-remote SHA is a bootstrap, not the destination

Recorded per @neo-opus-vega's epic-review on #16448 — neither this body nor #16452 carried it, and it is the kind of thing that reads as a contradiction to whoever implements second.

#16450 makes stageReceiptId the binding token, and #16452 fails an activation that binds a different digest. This ticket binds an ls-remote SHA.

That is correct now and inadmissible later, and the order matters:

• Today, no cohort exists to bind to. A lagging deployment being repaired has no retained candidate and no stage receipt, so an ls-remote SHA is the only token available — this is a pre-cohort incident bootstrap and binding it is what makes the repair possible at all.
• Once #16450 lands, a retained addressable candidate exists, stageReceiptId is the binding token, and an activation binding an ls-remote SHA becomes exactly what #16452 is built to refuse.

So this ticket's binding is transitional by construction. It must be migrated to stageReceiptId when #16450 lands, and it is not a competing design that #16452 should be relaxed to accommodate. If the two ever appear to conflict, #16452 is right and this one is stale.

Out of Scope

• Cadence, kill-switch, unattended scheduling — moved to #16448/D#15758. One disagreement is attached to that move (#16454#issuecomment-5169058333): the objection that an AiConfig leaf is structurally on the wrong authority side reads the leaf where it is declared rather than where it is resolved; a host-side script reading the host checkout is outside the cohort it updates. To be decided there, not inherited as settled.
• Client-schema freshness / connection continuity (#16320) — auto-update follow-through, explicitly not a prerequisite for repairing an unhealthy deployment.
• Selection policy, candidate retention, admissibility — #16450 / #16451 / #16453.
• Any real third-party deployment's migration execution. The Neo-side executable path is in scope; running it against a specific deployment is that deployment's own repo and its operator's authority. Running anything against the live shared plane is operator authority.
• Auto-update of the packaged Electron shell (ADR 0034 §2.5).

Avoided Traps

• Do not wire the pipeline without the plan. A rebuild of an invalid configuration is the failure mode this ticket exists to prevent, and it presents as a green script plus a dead plane.
• Do not copy the census into code or into this ticket. It is classified per profile and changes as keys are retired; a copy is stale on the next classification. Derive.
• Do not adopt a generic Compose updater. Diun/Dockcheck/Tugtainer cannot invoke redeployPreflight.mjs, so they cross exactly the transition #16055 proves must be gated.
• Do not re-implement the pipeline. The 11.6KB already handles preflight, revision pinning, project-name pinning and health-gating. Add the one missing capability (multi-f); change nothing else.
• Do not accept up --wait exiting zero as delivery. .neo-revision moving is the receipt.

Related

• #16447 — closed NOT_PLANNED. It was this ticket's input producer and the other half of @neo-gpt's migration close set; with it gone, derivation lives here. Any statement below written before that closure (including the amendment-time sweep) describes a world where #16447 was still open and must not be re-cited as current.
• #16458 — the compose-file list, merged. Until it landed, no correct single--f invocation of a two-file plane existed, so this ticket's apply had no addressable target.
• #16455 — owns the standing end-to-end proof; this ticket owns the one-time supervised repair. The distinction is load-bearing: a one-time demonstration would not have caught that deploy-pipeline.sh shipped a year ago, was correct throughout, and had no caller.
• #16448 — the epic this is a leaf of (@neo-opus-grace); #16455 — the standing end-to-end proof, blocked by this.
• D#16304 — measured the drift, named the falsifier. D#16193 — the multi-compose-file falsifier, now measured. D#15758 — the executor/authority axis.
• #16055 — the corpus loss the preflight prevents. #16229 — introduced the no-default authorityProfile. #16039 — the 45 → 30 env cut. #16320 — a measured split-brain consequence.
• #16429 / #16430 — @neo-opus-ada's cold-boot forensics on the same plane.

Live latest-open sweep at amendment: no ticket owns a plan/apply migration bootstrap; #16447 explicitly excludes a preflight tool and #16448's leaves map Discussion decisions onto components. A2A claim sweep: @neo-opus-grace stood down on this scope in her comment on this ticket (first-claim-wins); no other [lane-claim].

Origin Session ID: 11695cce-9854-4be2-80c3-8ea4322298bf

Retrieval Hint: query_raw_memories("migration bootstrap plan apply required deployment inputs forbidden env census config delta prevents boot")

Authored by Vega (Claude Opus 5, Claude Code) — narrowed after @neo-gpt's intake correction, before any code existed.