Resolves #16568

Both healthchecks now report the packaged source revision, so a plane can answer which commit it is running instead of leaving skew to be discovered during an incident.

Evidence: L3 (unit specs + mutation against the silent-omission shape) → L4 required (the field observed on a live deployment's MCP surface). Residual: AC3's skew subtraction has the data it needs and no reporter consuming it [#16568].

The change

Reads .neo-revision, not the NEO_REVISION build arg.

The arg records what was requested and is empty by default; the file is written by the image's source stage from git rev-parse HEAD after the checkout, so it records what was packaged. The case worth detecting is precisely where those disagree — and there is one: with a mutable NEO_REF, the source layer is cache-stable and the image can package a commit nobody asked for (#16635). An implementation reading the arg would report the request and call it identity.

The file is also always populated — the local-source stage writes an explicit local-build marker rather than leaving it absent — so absence means "not built by the image pipeline" rather than "no answer".

Emitted as a value, never an omission. {revision: null, source: 'unknown'} when no build wrote one. A consumer computing skew subtracts the reported revision from a named ref, and a missing field reads as current to every naive reader — which is the failure this ticket exists to remove, so the absent case had to be a stated answer rather than a gap.

Deliberately not a config leaf. This is measured artifact truth; a deployment that could override it could lie about its own identity. Config carries what an operator chooses. No ADR-0019 surface is touched.

Deltas from ticket

AC1 says "or an explicit unknown when the build arg was not supplied". Implemented against the file rather than the arg, which is strictly stronger: an image built without NEO_REVISION still reports its real packaged commit rather than unknown, and unknown is reserved for a runtime no image built. Same guarantee at the consumer, more information.

Test Evidence

test/playwright/unit/ai/services/shared/deployedRevision.spec.mjs — new.

npm run test-unit -- test/playwright/unit/ai/services/shared/deployedRevision.spec.mjs
  7 passed (2.8s)

npm run test-unit -- test/playwright/unit/ai/services/
  3825 passed

Cases: a packaged SHA reported verbatim · an absent file reporting unknown with both keys present · an empty file as unknown rather than an empty-string revision · local-build surviving as a real answer rather than being coerced · the memo holding, with a reset proving the memo was what held it.

Mutation-tested. Returning {} on a missing file — the exact silent-omission shape the ticket names — turns the spec red on the key-presence assertions. Every absence assertion checks the key exists before checking what it holds; an assertion on a missing key would pass for the wrong reason.

The memo test carries its own non-vacuity control: without one, "the second read returns the first value" would pass simply because the intervening write never landed. Proving the reset changes the answer proves the memo was what held it.

Surfaces touched: KB and MC healthcheck payloads — existing non-CI coverage green in the 3825 above. One failure in that directory run is a pre-existing teardown race, reproduced on clean origin/dev (2 failures there vs 1 here) and passing in isolation.

Post-Merge Validation

• The field observed on a live deployment's MCP surface, reporting a real SHA rather than unknown.
• Skew computed end-to-end: reported revision vs origin/dev, from the MCP surface alone with no shell access on the target.

Scope

AC3 asks that skew be computable from the MCP surface. The data is now there and a caller can subtract; no reporter tool ships here. Flagging rather than claiming it closed.

AC4's documentation lives at both emission sites, stating what version and runtimeFreshness each answer and why neither sees a plane hundreds of commits behind.

Pairs with #16635: that one is why an image can be frozen at an old commit, this one is how anybody finds out. Neither is much use alone.

Authored by @neo-opus-grace (Claude Opus 5). Origin Session ID: 9ced67a1-8f21-4da2-a1bf-a2a968c47ed2

Author response — cycle-2 blockers discharged @ db2121b919

1. Top-level requiredness. Both HealthCheckResponse schemas now carry required: [deployedRevision]. You were right that required: [revision, source] constrains the object only once it exists — my own description claimed "always present" while the contract permitted omission, which is the ambiguity this field exists to remove.

Kept deliberately narrow, with the reasoning in-file: its siblings are emitted in practice but not contractually guaranteed, and widening that list is a per-field decision rather than a convention this PR starts. Say so if you read that differently — it is the one judgement call here.

2. The permanent witness, which is the finding that mattered. I verified the first repair with a one-off probe and shipped no guard. That is this ticket's own defect, for the third time in one PR — a fact established once and not held. First at the payload, then at the contract, then at the verification.

test/playwright/unit/ai/services/shared/deployedRevision.spec.mjs now asserts, per service:

• the field is declared
• its enum and nested required set are correct
• the response requires it — a separate assertion from the nested shape, because they fail independently
• the emitted object satisfies the declared contract, including the unknown case

With a control (runtimeFreshness declared) so a mistyped schema path cannot fail every assertion for the wrong reason and read as a regression.

Mutation-verified per service: dropping required: [deployedRevision] from knowledge-base reddens that service's assertion and leaves memory-core green.

this spec        10/10
parity lint      0 consumed-but-undeclared
unit/ai/services 1 pre-existing failure — reproduced IDENTICALLY with these changes stashed
                 (MemoryService.Lifecycle timer count; not this diff)

On your [TOOLING_GAP] — the parity lint compares the two service schemas against each other, so two services that both omit a field are perfectly consistent and both wrong. It can never be asked whether a payload key exists in the schema. Left unfiled deliberately: it is your finding, and I hold two unclaimed tickets already in a deep queue. Happy to carry it if you would rather.

Worth recording about the review rather than the fix. Your patch-blind snapshot predicted "declare the same shape in both MCP output schemas so a remote client can discover and consume it" before reading the diff — and that prediction is exactly where both gaps were. Predict-then-compare found in two cycles what two green suites, a parity lint and a positive-control spec did not.

Authored by @neo-opus-grace (Claude Opus 5).