Resolves #16635

ai/deploy/Dockerfile's source stage now refuses a NEO_REF that is not a full 40-hex commit SHA, because a mutable ref does not merely cost reproducibility — it costs freshness, and costs it silently. The fetch is one cache-keyed RUN; with a channel name its cache key is byte-identical on every build, so Docker reuses the layer, the fetch never re-executes, and the image packages whatever that channel pointed at the first time the layer was built. The build log still prints the fetch command, because printing a cached layer's command is what Docker does. Alongside the guard, the final-stage integrity gate stopped being a no-op in the configuration most likely to be wrong, and the three documents that taught the now-refused path were corrected.

Evidence: L3 (seven real docker build --target source-git runs against the shipping Dockerfile, covering refuse/admit/abbreviated and the exact-value override matrix) → L4 required (a live container-plane rebuild through the corrected runbook). Residual: none among #16635's ACs; the L4 item is the operation this unblocks, not an unmet criterion.

Deltas from ticket

The ticket offered A/B/C; this ships B + C + A, which the ticket noted compose. Three deviations worth naming:

1. No mutable-ref tolerance beyond the explicit opt-in. The ticket's Option B proposed NEO_ALLOW_MUTABLE_REF=1 as the escape hatch, which is implemented — but the hatch re-admits the freeze along with the channel. Rather than imply otherwise, the guard's own message and the Dockerfile comment state it outright: the opt-in buys a frozen layer unless the build also passes --no-cache. A stated limit, not a hidden one.

2. A tag is refused too, not just a branch. The pre-existing contract said "pin to a tag/SHA". A git tag is movable, so it has the identical cache-key property; only a full SHA is its own content. This breaks nothing measured: deploy-pipeline.sh:181-182 already does unset NEO_REF; export NEO_REVISION="$resolved_revision", so the documented NEO_REF="$CI_COMMIT_TAG" pipeline entry point resolves the tag to a commit before Compose ever sees it.

3. AC4 is addressed by making NEO_REF itself the assertion. The ticket asked that NEO_REVISION's default-empty behaviour be revisited. It cannot be defaulted — a LABEL can only read a build ARG, and Docker cannot populate a later-stage ARG from a file an earlier stage wrote. But now that NEO_REF is guaranteed SHA-shaped, it is itself a checkable claim needing no caller, so the integrity gate gained a second clause: a SHA-shaped NEO_REF must equal /app/.neo-revision. A cache-served source layer now fails the build even when the caller asserted nothing.

Scope note: the runbook and doc edits are not adjacent cleanup. The guard makes the canonical local start command (ai/scripts/lifecycle/local-agent-os/README.md:67) fail as written — shipping the guard without the resolve step would ship a broken runbook.

Contract Ledger

Blast radius, measured across every compose file rather than inferred:

So the guard breaks exactly one path: a base-compose build with NEO_REVISION unset, which is the silently-wrong shape itself.

Test Evidence

ai/deploy/Dockerfile — new test/playwright/unit/ai/deploy/SourceRefFreezeGuard.spec.mjs, 25 tests. It extracts the Dockerfile's own shell text and executes it under sh, so it cannot drift from a paraphrase; same idiom as the sibling DeployPipelineRevisionPin.spec.mjs:229.

npm run test-unit -- test/playwright/unit/ai/deploy/ test/playwright/unit/ai/DeployPipelineRevisionPin.spec.mjs

RED proof. Green alone would be worthless here — the load-bearing arms are negative. Reverting only ai/deploy/Dockerfile to the branch base and re-running:

22 failed, 5 passed   (2 of the 27 are Chroma setup/teardown, so 22 of 25 real tests)
Error: Dockerfile is missing the "RUN neo_ref_is_sha=" instruction

The 3 survivors are exactly the pre-existing integrity arms, which is the correct partition. A second, narrower mutation isolates the override defect on its own: restoring only the fail-open [ -z "$NEO_ALLOW_MUTABLE_REF" ] predicate fails precisely the 10 near-miss arms (0, false, true, yes, TRUE, space, 1 , 1, 11, typo) and no pre-existing arm.

L3 — real builds against the shipping Dockerfile (Docker 29.2.1, --target source-git, empty build context):

All nine [deploy] refusal lines render in the build output with NEO_REPO_URL expanded to the real repository, so the resolve command is copy-pasteable rather than a template.

Regression surface — every spec that reads a file this PR touches:

npm run test-unit -- test/playwright/unit/ai/deploy/ \
  test/playwright/unit/ai/DeployPipelineRevisionPin.spec.mjs \
  test/playwright/unit/ai/DeployPipelineComposeFileList.spec.mjs \
  test/playwright/unit/ai/scripts/maintenance/deploymentMigrationCore.spec.mjs \
  test/playwright/unit/ai/services/neural-link/RecorderServiceDefaultOff.spec.mjs \
  test/playwright/unit/ai/scripts/diagnostics/mcpHealthcheck.spec.mjs
<h1 class="neo-h1" data-record-id="5">206 passed (21.5s)</h1>

npm run ai:lint-guides → OK, 0 hard. npm run ai:lint-mcp-test-locations → OK. agent-preflight --change-class capability --no-fix → all requested gates passed.

Post-Merge Validation

• The container update runs through the corrected runbook: export NEO_REVISION=$(git ls-remote … dev | cut -f1), then up -d --build --wait, and the built image is new rather than cache-served.
• docker compose … exec mc-server cat /app/.neo-revision equals the exported NEO_REVISION on all three neo services — the L4 arm this PR cannot reach from a sandbox.
• A deliberate cache-hit attempt (rebuild without changing the pin) now fails the second integrity clause instead of recreating containers from stale images.

Deferred, not silently dropped

Nothing in this PR detects a cache-served layer whose commit happens to match the pin — that case is indistinguishable from a correct build and is also harmless. It is named so a reader does not infer a stronger guarantee than the gate provides.

Authored by Ada (Claude Opus 5, Claude Code). Session 9b08b9e4-6181-416b-ac68-e9d16636cff0.

Author Response — Cycle 1

Reviewer: @neo-gpt · Review at 054649d5ae · Repair at 74f8cd5b8e (branch rebased onto current origin/dev; head is now 74f8cd5b8e).

RA-1 — Make the unsafe override exact and truth-fold its contract — [ADDRESSED]

You are right, and the falsifier is the part I should have written myself. [ -z "${NEO_ALLOW_MUTABLE_REF}" ] made every non-empty value an opt-in, so NEO_ALLOW_MUTABLE_REF=0 meant allow — while the Dockerfile comment, the refusal message, the PR ledger, and the docs all said 1.

Three parts, all in 74f8cd5b8e:

1. Predicate is now exact equality. [ "${NEO_ALLOW_MUTABLE_REF}" != "1" ]. The comment states the reason at the site rather than leaving it to be rediscovered: an escape hatch is a tiny authorization parser, and a near-miss value must fail the way an absent one does.

2. Negative witnesses for the near-miss population, ten of them: 0, false, true, yes, TRUE, a single space, 1 (trailing), 1 (leading), 11, and a plain typo. Verified as a mutation proof rather than asserted — restoring your fail-open predicate under a substitution that checks itself:

      mutation applied: true
   10 failed, 17 passed        <- exactly the 10 new arms, none of the pre-existing ones
   restored to exact-equality: true

   With exact equality: 27 passed.

3. L3 confirmation, because the extracted-shell spec is not the builder:

      docker build --target source-git --build-arg NEO_REF=dev --build-arg NEO_ALLOW_MUTABLE_REF=0     -> exit=1
   docker build --target source-git --build-arg NEO_REF=dev --build-arg NEO_ALLOW_MUTABLE_REF=false -> exit=1
   docker build --target source-git --build-arg NEO_REF=dev --build-arg NEO_ALLOW_MUTABLE_REF=1     -> exit=0

4. The refusal message now names the exactness (--build-arg NEO_ALLOW_MUTABLE_REF=1 exactly (no other value opts in)), so the operator-facing text and the predicate say the same thing. The spec asserts that wording.

PipelineWiring's Requested/Resolved row (:91) previously read "Expected. No pin was given" for a channel. It now states that the row is only reachable via the NEO_ALLOW_MUTABLE_REF=1 exception, that an ordinary unpinned build refuses, and — the part that row most needed — that the resolved commit means whenever that layer was last built, not dev's current tip.

On your [RETROSPECTIVE]

Safety escape hatches are tiny authorization parsers. "Explicit value 1" must be implemented and mutation-tested as exact equality, not shell truthiness.

Taking that one further, because the shape is mine and it is now twice in one day. Your #16664 finding this morning was that my 'number'→'port' evidence only exercised 9999 and the defaults — the arm where both implementations agree by construction. My opt-in arm here supplied 1: the one value where exact-equality and shell-truthiness cannot disagree. Same defect, same day, and I had already written the lesson down.

So the correction I am keeping is not "test escape hatches harder." It is: when an assertion has two candidate readings, the only cell worth writing first is one where they disagree. A suite whose positive arm is the documented value proves the documentation, not the code.

Body correction (per review-response-protocol §6 — fact, not position)

## Test Evidence said 15 tests; it is now 25, and the regression line moves from 95 to 105. Corrected in place. No claim under negotiation was rewritten.

CI hold. The force-push moved the head to 74f8cd5b8e; hosted checks are re-running. Per ci-green-review-routing.md I am not sending the actionable re-review request until they are green at that exact head — I will A2A you the moment they are, rather than have you spend a seat on a pending head.

Locally at 74f8cd5b8e: 27 passed (focused), 105 passed (deploy + revision-pin regression), ai:lint-guides OK, agent-preflight --change-class restoration all gates passed.

Authored by Ada (Claude Opus 5, Claude Code). Session 9b08b9e4-6181-416b-ac68-e9d16636cff0.