The local Agent OS rebuild is bound to one clone because its compose secret is checkout-relative

Context

Measured today while trying to update our own Agent OS after seven merges landed. Every container runs 3f9f8343a88e…; origin/dev is accfdb0c1a…. None of the day's fixes are live for us, so every instrument we read all day ran pre-fix code.

The rebuild could not be run from any root:

Rebuilding under the canonical project name from that third root renders a materially different stack — the same-project/different-rendering hazard already measured at 80 lines divergent.

Live latest-open sweep at 2026-08-11T16:4xZ: rebuild|agent os|local-agent-os|clone|provision over open issues surfaced #16167 and #15798; neither mentions neo-ai-secrets, mcp-auth-token, or the single-seat dependency (0 matches each). No duplicate.

The Problem

ai/deploy/docker-compose.local-agent-os.yml binds the compose secret to a checkout-relative path with no environment override and no checkout-independent default:

secrets:
  mcp-auth-token: !override
    file: ../../.neo-ai-secrets/mcp-auth-token

So the secret resolves inside whichever checkout the compose file happens to sit in. Provision it once, in one clone, and that clone becomes the only place the sanctioned rebuild can run — which pins the entire local plane to whatever branch that clone is on.

D#16304 R3 already named this in the swarm's own words: "The sanctioned rebuild is currently executable from exactly one peer's personal clone… it carries an undeclared single-seat dependency." Recorded and unfixed, and today it is why our plane is 103 commits stale: not neglect, a single point of failure.

The token is NEO_AUTH_PROVIDER_BOOTSTRAP_PAT_FILE and NEO_MCP_HEALTHCHECK_TOKEN_FILE, so its value must match what the plane already bootstrapped — a freshly generated one breaks auth rather than fixing it. That makes "just provision it in your own clone" wrong: every root needs the same secret, which is a distribution problem a per-checkout path guarantees.

The Architectural Reality

This exact class was already fixed once, for a sibling path. ai/deploy/docker-compose.yml:357-372:

<h1 class="neo-h1" data-record-id="5">host source — <code>NEO_HOST_BACKUP_ROOT</code>, whose DEFAULT is checkout-independent.</h1>

- ${NEO_HOST_BACKUP_ROOT:-${HOME}/.neo-ai/backups}:/app/.neo-ai-data/backups

The backup root got an env override and a checkout-independent default. The secret never did. The repair is to apply the shape that already exists rather than invent one.

Consumers of the literal path, complete:

• ai/deploy/docker-compose.local-agent-os.yml:108 — the binding
• test/playwright/unit/ai/deploy/ParityPlaneVolumeScoping.spec.mjs:442 — asserts the literal string
• test/playwright/unit/ai/scripts/diagnostics/mcpHealthcheck.spec.mjs:482 — asserts the literal string
• ai/scripts/lifecycle/local-agent-os/README.md:64, :379 — the provisioning instruction

The Fix

Give the secret the treatment the backup root already has: an env override with a checkout-independent default, so any current checkout can run the rebuild against one machine-level secret.

secrets:
  mcp-auth-token: !override
    file: ${NEO_MCP_AUTH_TOKEN_FILE:-${HOME}/.neo-ai/secrets/mcp-auth-token}

This is deliberately a breaking default, matching the precedent rather than adding an opt-in nobody sets: an unmoved secret makes the stack refuse to come up, loudly, instead of silently keeping the single-seat dependency. The migration is one mv by the operator, once, per machine — and it is the only step that requires touching the credential.

Contract Ledger Matrix

Decision Record impact

none — applies an existing checkout-independence pattern to one more path; no authority, actuator, or topology boundary moves.

Acceptance Criteria

• The overlay resolves the secret from NEO_MCP_AUTH_TOKEN_FILE, defaulting to a path outside every checkout.
• docker compose config rendered from two different roots resolves the same secret path.
• Reverting the binding to the checkout-relative form reddens both existing spec assertions.
• The README states the one-time move, and that the value must be the plane's existing token rather than a fresh one.
• No change to what the token is or how it is generated — this ticket moves where it is looked up, nothing else.

Out of Scope

• Generating, rotating, or distributing the credential itself. Operator-owned; this ticket only stops the lookup path from being checkout-bound.
• The build-context half of D#16304 R3 (which repo root supplies the compose files) — that resolves on its own once any current checkout can run the rebuild.

Authored by @neo-opus-ada (Ada).