instar 1.3.539 → 1.3.541

package/upgrades/1.3.540.md

@@ -0,0 +1,70 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Retired the catch-all `deliberate-fleet-default` category from the dev-feature
+dark-gate classification and added a concrete `action-bearing` category. Every
+"off even on a development agent" feature must now name a real reason it would be
+unsafe or non-runnable there — it kills/deletes, spends money, takes an external
+action, or needs per-deployment config — and the vague "off by policy" bucket is
+gone. The CI lint (`scripts/lint-dev-agent-dark-gate.js`) rejects the retired
+category and now fails loud if an exclusion entry escapes category validation (the
+backtick-reason silent-skip hole), via a count-match guard in
+`scripts/lib/dark-gate-attribution.js`.
+
+Reclassified the 11 features that were in the retired bucket. Each candidate for
+going live on a development agent was re-grounded against its actual code (D4): 4
+verified safe and moved to `DEV_GATED_FEATURES` (`parallelWorkSentinel`,
+`failureLearning`, `releaseReadiness`, `bootHealthBeacon`) — their `enabled` flag
+is now omitted from `ConfigDefaults` so the developmentAgent gate resolves them
+live-on-dev / dark-on-fleet, and their construction sites route through
+`resolveDevAgentGate`. The other 3 candidates were held back as honest exclusions
+because their code contradicted "observe-only": `correctionLearning` (cost-bearing
+— per-message LLM spend), `apprenticeshipCycleSla` and `geminiCapacityEscalation`
+(action-bearing — auto-post Telegram alerts). `greenPrAutoMerge` + `a2aCheckIn` are
+recategorized action-bearing; `mentor` + `mentee` optional-integration.
+
+Added a one-shot, dev-agent-only `PostUpdateMigrator.migrateDevGateTeethStrip` that
+strips a stale persisted `enabled: false` for the 4 newly-dev-gated flags so an
+existing development agent actually picks up the change (without it the add-missing
+config merge would leave the stale value and the features would stay dark — the
+cartographer trap).
+
+## What to Tell Your User
+
+Nothing changes for you on a normal install — every one of these features stays off
+until you turn it on, exactly as before. On a development agent (the dogfooding
+machine), four watch-only helpers now switch on automatically after the update: a
+parallel-work overlap watcher, a failure-learning recorder, a release-readiness
+watcher, and a boot health responder. They only observe and record — none of them
+sends you a message, spends money, or changes anything. Three other helpers that
+were candidates to turn on were deliberately kept off because they would have spent
+money or sent you alerts; you can still switch any of those on yourself if you want
+them.
+
+## Summary of New Capabilities
+
+- A development agent now runs four verified watch-only observers live (parallel-work
+  overlap, failure-learning, release-readiness, boot health) so they get dogfooded
+  before the fleet ever sees them.
+- The dark-feature classification now requires a concrete, honest reason for any
+  feature parked "off even on dev" — enforced in CI — so a safe feature can no longer
+  be hidden behind a vague "off by policy" label.
+
+## Evidence
+
+- Spec + 6-round convergence report with a real cross-model (GPT-tier) external pass:
+  `docs/specs/DEV-AGENT-DARK-GATE-TEETH-SPEC.md`,
+  `docs/specs/reports/dev-agent-dark-gate-teeth-convergence.md`.
+- Tests (all green): `tests/unit/lint-dev-agent-dark-gate.test.ts` (retired category
+  rejected, `action-bearing` accepted, count-match guard, hand-verified drift canary),
+  `tests/unit/devGatedFeatures-wiring.test.ts` (the 4 new entries resolve live-on-dev /
+  dark-on-fleet through the real `ConfigDefaults`),
+  `tests/unit/PostUpdateMigrator-devGateTeethStrip.test.ts` (migration both sides +
+  idempotency + the 3 held untouched), `tests/integration/dev-gate-teeth-rollout.test.ts`
+  (full migration → defaults → resolver pipeline + the two-switch drift guard).
+- D4 code-grounding evidence (file:line per feature) is recorded in the spec's
+  "D4 grounding result" section.

package/upgrades/1.3.541.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Enforces the spec's applicability precondition: live credential re-pointing only works for sessions that read their credential from the per-config-home store. A session launched with an env token bypasses that store and is invisible to the mechanism — so this step records, at spawn, WHERE each session's Anthropic credential comes from, and refuses to run the feature whenever an env-token session is present.
+
+- **Durable per-session provenance flag** — a new `credentialSource: 'store' | 'env'` field on the session record, set at every claude-code spawn lane. It is derived from the IDENTICAL expression that selects the session's Anthropic env block — `(config.anthropicApiKey ?? '') !== '' ? 'env' : 'store'`, computed at the spawn site — so the flag can never drift from what actually launched the session (single source of truth; an independent recomputation would re-create the staleness class this spec exists to kill).
+- **The env-token gate** — a new `CredentialEnvTokenGate` (src/core/CredentialEnvTokenGate.ts), a pure evaluator. It REFUSES the feature, with a NAMED category reason, when either the config field `anthropicApiKey` is any non-empty value (an OAuth token OR a direct API key — both bypass the store) OR any running claude-code session's provenance flag is `env`. Checking the LIVE fleet — not just the config field — closes the mid-life-flip hole: an operator setting an env token mid-run would otherwise leave already-running store sessions steerable while new env spawns are silently un-steered.
+- **Named reason on the status route** — `GET /credentials/rebalancer`, when the feature flag is ON, now surfaces the gate verdict (refused, the reason category, and the count of env sessions), scrubbed through the existing secret-scrub chokepoint. Dark (flag off) it stays a strict 503 no-op.
+- **Attribution-suppression** — on a gate refusal the location gate behaves as dark, so the quota poller stops routing reads/attribution through moved slots: an env session's usage is never mis-attributed to a slot tenant.
+- **Dark** — gated by the existing `subscriptionPool.credentialRepointing` flag. With the feature off (the fleet + dev default) the gate is never consulted and the only delta is the additive provenance field on new session records (free metadata, never read) — byte-for-byte today's behavior.
+
+## What to Tell Your User
+
+This is internal plumbing that ships turned off, so nothing changes for you day to day. What it builds toward, with a safety guarantee baked in: the under-the-hood feature that moves a credential between your subscription accounts only works for sessions that read their login from the on-disk store I manage. If a session was instead launched with a login token handed straight to it in its environment, that session ignores the store entirely and the moving trick would be a no-op for it. So this step teaches me to record, the moment each session starts, which of those two kinds it is — and to refuse to run the whole moving feature at all whenever any running session is the kind I cannot steer. That refusal is deliberate and visible, with a plain reason, rather than the feature quietly mis-handling a session it does not actually control. It is off by default and does nothing until the feature is turned on after a review window.
+
+## Summary of New Capabilities
+
+One new exported class — `CredentialEnvTokenGate` (the env-token applicability gate: refuses on the config field OR a live env-token session in the fleet, with a named reason) — plus a new additive optional `Session.credentialSource` provenance field set at every claude-code spawn lane, and the `GET /credentials/rebalancer` route surfacing the gate verdict. All gated by the existing `subscriptionPool.credentialRepointing` flag. No new gate flag, no new unfunneled credential write path.
+
+## Evidence
+
+- `tests/unit/credential-env-token-gate.test.ts` (18) — config predicate (permits empty/undefined; refuses on sk-ant-oat, on a direct sk-ant-api03 key, and on any non-empty value); live-fleet path (refuses on one running env session with config empty, counts multiple, ignores a non-running env session and a non-claude env session, treats undefined as store, config-field refusal short-circuits before the fleet scan); attribution-suppression (`shouldAttributeSlotTenant` false for env, true for store/undefined); and the single-source-of-truth blocker proven by a static grep-assert against the real SessionManager source (exactly 3 env-block predicates + 3 identical provenance derivations + 4 record writes).
+- `tests/integration/credential-routes.test.ts` (+3) — the rebalancer route surfaces the config-field refusal (scrubbed, no token leak), the live-fleet refusal (mid-life flip, config empty), and permits when config empty + all-store fleet.
+- `tests/e2e/credential-repointing-routes-alive.test.ts` (+3) — feature-alive on the real AgentServer factory: rebalancer DARK is a strict 503 no-op, ENABLED + clean config + all-store fleet permits, ENABLED + a live env-token session refuses with the named reason.
+- tsc clean; full `npm run lint` clean (dark-gate 16/16 unchanged — no ConfigDefaults touched); no-silent-fallbacks + no-empty-catch-blocks + feature-delivery-completeness + docs-coverage green.

package/upgrades/side-effects/dev-agent-dark-gate-teeth.md

@@ -0,0 +1,201 @@
+# Side-Effects Review — Dev-Agent Dark-Gate Teeth (CMT-1438)
+
+**Version / slug:** `dev-agent-dark-gate-teeth`
+**Date:** `2026-06-13`
+**Author:** `echo`
+**Second-pass reviewer:** `required (touches gate/sentinel/migration) — see below`
+
+## Summary of the change
+
+Retires the catch-all `deliberate-fleet-default` category from the `DarkGateCategory`
+enum and adds a concrete `action-bearing` category, so every "off even on dev"
+classification must name a real reason dev-live is wrong (unsafe: destructive /
+cost-bearing / action-bearing; or not-runnable: optional-integration /
+structural-stub). Tightens the CI lint (`scripts/lint-dev-agent-dark-gate.js` +
+`scripts/lib/dark-gate-attribution.js`) to reject the retired category and adds a
+count-match guard that fails loud when an exclusion entry escapes category validation
+(the backtick-reason silent-skip hole). Reclassifies the 11 occupants: after per-feature
+D4 code-grounding, 4 move to `DEV_GATED_FEATURES` (parallelWorkSentinel, failureLearning,
+releaseReadiness, bootHealthBeacon) — their construction sites now route through
+`resolveDevAgentGate` and their `enabled: false` literal is removed from ConfigDefaults;
+7 stay exclusions with concrete categories (correctionLearning=cost-bearing,
+apprenticeshipCycleSla/geminiCapacityEscalation/greenPrAutoMerge/a2aCheckIn=action-bearing,
+mentor/mentee=optional-integration). Adds `PostUpdateMigrator.migrateDevGateTeethStrip` —
+a one-shot, dev-agent-only strip of stale persisted `enabled: false` for the 4 paths so
+the move actually lands on existing dev agents.
+Files: `src/core/devGatedFeatures.ts`, `scripts/lib/dark-gate-attribution.js`,
+`scripts/lint-dev-agent-dark-gate.js`, `src/config/ConfigDefaults.ts`,
+`src/server/AgentServer.ts` (parallelWorkSentinel + failureLearning gates),
+`src/commands/server.ts` (releaseReadiness + bootHealthBeacon gates),
+`src/server/CapabilityIndex.ts` (failureLearning capability report),
+`src/core/PostUpdateMigrator.ts` (D5 migration) + 3 test files.
+
+## Decision-point inventory
+
+- `DarkGateCategory` enum (classification taxonomy) — **modify** — drop the catch-all, add `action-bearing`; closes the willpower escape hatch.
+- `lint-dev-agent-dark-gate.js` Assertion C (CI gate) — **modify** — the closed-enum membership check tightens (one fewer valid category) + a count-match guard added.
+- `resolveDevAgentGate` at 4 construction sites — **modify (pass-through to the funnel)** — the 4 features' enable check now goes through the existing dev-gate funnel instead of a hand-rolled `=== true`. No new decision logic; it reuses the established resolver.
+- `migrateDevGateTeethStrip` — **add** — a config-mutation migration (deletes a stale `enabled: false`), dev-agent-only, run-once. Not an information-flow gate.
+
+---
+
+## 1. Over-block
+
+No outbound/inbound message block surface. The only "block"-shaped surface is the CI
+lint, which now *rejects* (a) an exclusion using the retired `deliberate-fleet-default`
+category and (b) an exclusion entry that doesn't fully parse (count-mismatch). The
+count-match guard can *over-trip* on a legitimate-but-unparseable entry — specifically
+an exclusion `reason` written with embedded quotes or a backtick/template literal. This
+is intentional fail-safe behavior (it forces a parseable, single-line, quote-delimited
+reason); it never lets a bad entry through. It surfaced exactly once during this build
+(my own reasons contained embedded `"`), was loud, and was fixed by rewording — proving
+the guard works. Authoring constraint, not a runtime over-block.
+
+---
+
+## 2. Under-block
+
+The lint still matches the literal `enabled: false` spelling only (a pre-existing,
+documented limitation — a non-literal `enabled: someFlag ?? false` evades attribution).
+The count-match guard closes the parsed-path-without-a-parsed-entry class (backtick
+reasons, reordered fields) but the registry parser remains regex-based, so other
+source-shape shifts (object spread, imported constants, `as const`) are still a
+theoretical blind spot — disclosed in the spec and tracked as a follow-up (AST /
+pure-data registry). The category honesty itself is never machine-checked (the lint
+validates spelling + reason length, not truthfulness); D4 code-grounding + the
+GrowthMilestoneAnalyst R6 runtime cross-check are the backstops, also disclosed.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Right layer. The change does NOT add a new detector or authority — it (a) edits a
+classification enum + its CI lint (build-time signal), and (b) routes 4 features through
+the EXISTING `resolveDevAgentGate` funnel rather than re-implementing the gate inline
+(it removes 4 hand-rolled `=== true` checks). The migration reuses the EXISTING
+`migrateCartographerDevGate` pattern (same `_instar_migrations` marker machinery, same
+dev-agent guard). Nothing is re-implemented; everything feeds or reuses an existing
+primitive.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change produces a signal consumed by an existing smart gate / has no
+  runtime block-allow surface.
+
+The CI lint is a deterministic build-time *signal-emitter* (it fails CI on an invalid
+classification); it is not a runtime authority over agent behavior. The spec is explicit
+that the lint closes only the *unclassified/invalid-category* hole — it does NOT
+adjudicate category *honesty* (that is D4 + R6). `resolveDevAgentGate` is the established
+funnel, not a new brittle authority. No brittle blocking authority is added.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** the 4 construction-site gate calls replace `=== true` with
+  `resolveDevAgentGate(...)`. For 3 of the 4, routes/consumers already gate on the
+  *constructed instance* (null → 503), so they follow the gate result with no shadowing.
+  For `failureLearning`, `CapabilityIndex` also reads the flag — updated to the SAME
+  funnel so the capability report matches the construction gate (no skew).
+- **Double-fire:** `migrateDevGateTeethStrip` shares the `_instar_migrations` ledger
+  with `migrateCartographerDevGate`; the new marker key (`dev-gate-teeth-strip`) is
+  distinct (not a prefix of, nor prefixed by, `cartographer-dev-gate-strip`), so the two
+  run independently and each exactly once. Verified by the round-2 integration review.
+- **Races:** the migration runs in the single-threaded PostUpdateMigrator pass at update
+  time; no concurrent writer to config.json during it.
+- **Feedback loops:** none. The lint is one-way (CI fails or passes).
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the machine:** none — the change is per-agent config + a CI lint.
+- **Install base:** fleet behavior is byte-for-byte unchanged (every reclassified flag
+  still resolves `false` on a non-development agent; the migration is dev-agent-only).
+  Only development agents gain the 4 live observers.
+- **External systems (Telegram/GitHub/etc.):** the 4 features moved live are
+  D4-verified to make NO automatic outbound send on enable (parallelWorkSentinel: local
+  event/JSONL; failureLearning: append-only ledger, send path unimplemented;
+  releaseReadiness: read surface only, sends gated behind the separate dark job;
+  bootHealthBeacon: localhost-only inbound socket). The 3 features that DO auto-send
+  (correctionLearning spend; apprenticeshipCycleSla/geminiCapacityEscalation Telegram)
+  were deliberately HELD as exclusions precisely to avoid that surface on dev.
+- **Persistent state:** the migration deletes a stale `enabled: false` key from the dev
+  agent's own `config.json` (and records a run-once marker). Reported in the migration
+  result summary so a non-Echo operator sees which flags were freed.
+- **Operator surface (Mobile-Complete):** no operator-facing actions added — no route, no
+  form, no PIN-gated action. Not applicable.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — this change touches no dashboard renderer/markup, approval page, or
+grant/revoke/secret-drop form. Not applicable.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** The dev-feature classification is a code-shipped TypeScript
+enum + `ConfigDefaults` + each agent's per-machine `.instar/config.json`; `developmentAgent`
+is intrinsically a per-machine identity. None of the `multiMachine.stateSync.*` replicated
+kinds cover config flags or dev-gate state, and nothing here should follow the agent across
+machines — a machine either is or isn't a development agent. The D5 migration is
+dev-agent-only and mutates only the local config.json. No user-facing notice is emitted by
+this change (the 4 live features that COULD notify are either send-inert on enable or held
+as exclusions). No durable cross-machine state, no generated URLs. Confirmed by the
+round-1 integration reviewer (no journal kind needed).
+
+---
+
+## 8. Rollback cost
+
+Pure code + config-default change. Back-out = revert the commit (re-adds the
+`deliberate-fleet-default` enum member, the 4 `enabled: false` literals, the 4
+construction-site `=== true` checks, and removes the migration) and ship a patch. The D5
+migration is idempotent and run-once; a rolled-back agent that already ran it keeps its
+stripped config (the 4 flags then resolve via the reverted hardcoded `false` again — back
+to dark — with no error). No data migration, no agent state repair, no user-visible
+regression during the rollback window (fleet was never changed). An operator who wants a
+freed flag off again simply re-adds `enabled: false` (the run-once marker preserves it).
+
+---
+
+## Conclusion
+
+This review (plus the 6-round spec convergence that preceded it) reshaped the change in
+three material ways: (1) the migration was added after convergence found the 4 flags
+would otherwise stay dark on Echo (the cartographer trap); (2) D4 code-grounding held 3
+of 7 candidates back as honest exclusions when their code contradicted "observe-only";
+(3) the count-match lint guard was added after the adversarial reviewer found the
+backtick-reason silent-skip. The change adds no runtime blocking authority, makes no
+automatic external send on the dev agent (the senders are held off), leaves the fleet
+byte-for-byte unchanged, and is cleanly reversible. Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent reviewer subagent
+**Independent read of the artifact: concur**
+
+Concur with the review. The reviewer grounded every claim against the actual diff and confirmed: (1) all 4 construction sites route through `resolveDevAgentGate` with no hand-rolled `?? !!developmentAgent` (AgentServer.ts:858/1238, server.ts:3041/13258, CapabilityIndex.ts:794); (2) the migration allowlist is EXACTLY the 4 dev-gated paths, dev-agent-guarded, with a run-once marker distinct from cartographer's; (3) the signal-vs-authority answer holds (build-time signal + reused funnel + fail-safe count-match guard, no new blocking authority); (4) the highest-risk check — a missed read site — was investigated: the 4 flags also feed `src/monitoring/guardManifest.ts` → the `/guards` posture endpoint, but `guardPosture.ts:resolveGuardConfigSnapshot` already iterates `DEV_GATED_FEATURES` and injects the gate-resolved value, so moving the 4 into the registry makes `/guards` resolve them live on a dev agent automatically — NO "live-but-reported-disabled" skew, and the now-absent default raises no spurious boot tripwire. The reviewer's one non-blocking nit (stale "ships dark" prose in 4 `guardManifest.ts` descriptions) was fixed in this commit (descriptions now say "(dev-gated)"). Clear to ship.
+
+---
+
+## Evidence pointers
+
+- Spec + convergence report: `docs/specs/DEV-AGENT-DARK-GATE-TEETH-SPEC.md`,
+  `docs/specs/reports/dev-agent-dark-gate-teeth-convergence.md` (6 rounds, real
+  cross-model pass codex-cli:gpt-5.5).
+- Tests: `tests/unit/lint-dev-agent-dark-gate.test.ts` (enum/category/count-match +
+  drift canary), `tests/unit/devGatedFeatures-wiring.test.ts` (42 tests — 4 new entries
+  resolve live-on-dev/dark-on-fleet), `tests/unit/PostUpdateMigrator-devGateTeethStrip.test.ts`
+  (7 tests — migration both sides + idempotency + the 3 held), `tests/integration/dev-gate-teeth-rollout.test.ts`
+  (5 tests — full migration→defaults→resolver pipeline + two-switch drift guard).
+- D4 grounding evidence (file:line) is in the spec's "D4 grounding result" section.

package/upgrades/side-effects/ws52-step8-provenance-gate.md

@@ -0,0 +1,78 @@
+# Side-effects review — WS5.2 Step 8 (credential provenance flag + env-token gate)
+
+**Spec:** `docs/specs/live-credential-repointing-rebalancer.md` (approved:true, converged) §2.10/§0.b/§2.4, build-plan §8.
+**Tier:** 2 (src code + a read-time gate + a session-record metadata field; ships DARK behind the EXISTING `subscriptionPool.credentialRepointing` flag — NO new gate flag).
+**Parent principle:** Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions.
+**Second-pass reviewer:** independent reviewer subagent (this change touches a "gate" → Phase 5 required).
+
+## What changed
+
+- **NEW `src/core/CredentialEnvTokenGate.ts`** — the §2.10 env-token gate (the §0.b applicability precondition, enforced). Pure evaluator (no IO): `evaluate()` REFUSES the feature, with a NAMED CATEGORY reason, when (a) `config.anthropicApiKey` is ANY non-empty value (OAuth OR API key — round-3) OR (b) any RUNNING claude-code session's durable `credentialSource` flag is `'env'` (the live-fleet path that closes the mid-life flip). The static helper `shouldAttributeSlotTenant(session)` is `false` for an env session (its usage is never mis-attributed to a slot tenant — §2.10 requirement 3).
+- **`src/core/types.ts`** — adds `Session.credentialSource?: 'store' | 'env'` (additive optional metadata field; no `enabled:` literal → dark-gate UNCHANGED).
+- **`src/core/SessionManager.ts`** — sets `credentialSource` on the session record at all four claude-code spawn record-writes. At the three env-block lanes (headless `~:1846`, rerouted-interactive `~:2127`, interactive `~:3248`) it is derived from the **IDENTICAL** expression that selects the Anthropic env block — `(this.config.anthropicApiKey ?? '') !== '' ? 'env' : 'store'`, computed at the spawn site, NEVER a recomputation. The triage lane hardcodes `'store'` (it always empties `ANTHROPIC_API_KEY=`, so it deterministically reads the store).
+- **`src/commands/server.ts`** — constructs the `CredentialEnvTokenGate` (reading `config.sessions.anthropicApiKey` — the SAME source `sessionManagerConfig` spreads into SessionManager — and `state.listSessions()`); AND-s its refusal into the `CredentialLocationGate.isEnabled` (so a §2.10 refusal suppresses ALL re-pointing attribution: requirement 3 enforced structurally through the one gate the QuotaPoller already consults); adds the gate to the `credentialRepointing` bundle.
+- **`src/server/routes.ts`** — adds `envTokenGate` to the `credentialRepointing` RouteContext type; `GET /credentials/rebalancer` now surfaces the gate verdict (refused + named reason + envSessionCount) when the flag is ON, scrubbed via `audit.response`. DARK → strict 503 no-op (unchanged).
+- **Tests:** NEW `tests/unit/credential-env-token-gate.test.ts` (18); extended `tests/integration/credential-routes.test.ts` (+3 rebalancer cases) and `tests/e2e/credential-repointing-routes-alive.test.ts` (+3 cases, incl. live env-token fleet); widened the look-back window in `tests/unit/codex-model-swap-wiring.test.ts` (the §2.10 derivation sits between `effectiveAccountId` and `buildInteractiveLaunch` — the WS5.3 source-string-ratchet lesson).
+
+## Decision-point inventory
+
+- `CredentialEnvTokenGate.evaluate()` — **add** — the §2.10 refusal decision (config field OR live fleet). It is a SIGNAL feeding the rebalancer status surface + the location-gate enablement; it never blocks a session spawn, a message, or a swap directly.
+- `CredentialLocationGate.isEnabled` AND-in — **modify** — a §2.10 refusal makes the location gate behave as dark (attribution off) so the QuotaPoller stops re-routing reads/attribution through moved slots for an env fleet.
+- `Session.credentialSource` derivation — **add** — additive provenance metadata, not a decision (it is the durable INPUT the gate's fleet scan reads).
+
+## State files / migrations
+
+- **No new state file.** `credentialSource` rides the existing session record (`state/sessions/*.json`); additive optional field, absent on legacy records (treated as `'store'` — the safe, non-refusing direction).
+- **No migration in Step 8.** The CLAUDE.md awareness template + `migrateConfig`/`migrateClaudeMd` + CapabilityIndex are explicitly scoped to **build-plan §9 (Step 9 — Migration parity)** — tracked there, not deferred silently. No new config flag means nothing to migrate for the gate itself.
+
+## Blast radius / reversibility
+
+- **Ships DARK.** The gate is only consulted behind `subscriptionPool.credentialRepointing.enabled` (the location-gate AND-in short-circuits on the flag BEFORE evaluating the gate, and the rebalancer route 503s while dark). With the flag off (always, fleet-wide) the only runtime delta is the additive `credentialSource` field on new session records — free metadata, never read. E2E proves the dark surface is a byte-for-byte 503 no-op.
+- Reversibility: revert the commit. The `credentialSource` field is inert metadata; no credential write, no schema migration, no durable state to repair. A swap is still the reversible oracle-verified permutation from Step 5.
+
+## Per-Phase-C (multi-machine posture)
+
+- **Machine-local BY DESIGN.** The gate is per-machine: each machine evaluates ITS OWN `config.sessions.anthropicApiKey` + ITS OWN `state.listSessions()`. An N-machine pool is N independent gates; a machine running an env-token fleet refuses LOCALLY without reading or affecting a peer's store-reading fleet. No cross-machine credential read, no LAN/broadcast assumption. The `credentialSource` flag is per-session-per-machine durable metadata and never crosses machines (it would be meaningless on another machine, whose config/fleet differ). This is the correct posture: env-vs-store is a function of the LOCAL config field + the LOCAL fleet, so a remote read would be both unnecessary and a coherence hazard.
+
+## Adversarial review (4 lenses, folded as named tests)
+
+1. **Single-source-of-truth provenance (THE blocker)** — the flag is the IDENTICAL `(this.config.anthropicApiKey ?? '')` expression as the env-block selection at each of the three lanes, computed at the spawn site. Proven by a static grep-assert against the real SessionManager source (exactly 3 env-block predicates + 3 identical provenance derivations + 4 record writes) — an independent recomputation would fail it. A divergence test guards the staleness class this whole spec exists to kill.
+2. **Mid-life-flip / live-fleet** — the gate refuses on a running `env` session even when the config field is empty (named unit + integration + e2e tests). A config-only gate would miss it; the fleet scan reads the durable flag.
+3. **Attribution-suppression** — `shouldAttributeSlotTenant` is false for an env session (named test); structurally, the location-gate AND-in suppresses re-pointing attribution wholesale on refusal so the QuotaPoller never mis-attributes an env session's usage to a slot tenant.
+4. **Dark-ship inertness** — flag OFF → rebalancer 503 strict no-op; record-write shape unchanged except the additive field (e2e "feature is alive" — the single most important test).
+
+## Silent-fallback tags
+
+`CredentialEnvTokenGate` is pure logic with NO catch blocks. The route/server edits add no new catch. no-silent-fallbacks (5/5) + no-empty-catch-blocks (4/4) pass with NO baseline bump.
+
+## Second-pass review (Phase 5 — independent reviewer subagent)
+
+**Concur with the review.** All seven load-bearing invariants verified against the actual code:
+1. Single-source-of-truth — the `credentialSource` derivation is the IDENTICAL `(this.config.anthropicApiKey ?? '') !== ''` expression adjacent to each lane's `.startsWith('sk-ant-oat')` env-block predicate over the SAME `this.config.anthropicApiKey` field (SessionManager lanes 1/2/3); triage hardcodes `'store'` and demonstrably empties `ANTHROPIC_API_KEY=`. Not a recomputation.
+2. Config predicate is "any non-empty value" (`key !== ''`), correctly broader than the launch's sk-ant-oat branch (both branches set a store-bypassing env var).
+3. Gate ANDs the live-fleet scan (running + claude-code + `credentialSource === 'env'`, undefined→store safe default) onto the config check, closing the mid-life-flip hole.
+4. The location-gate `isEnabled` AND-in is sound: `&&` short-circuits on the dark flag BEFORE `evaluate()` is ever called (true no-op while dark); on refusal it suppresses re-pointing attribution wholesale (the conservatively-correct direction); `shouldAttributeSlotTenant` false for env.
+5. Gate-level single-source-of-truth holds — `config.sessions?.anthropicApiKey` is the same value `sessionManagerConfig = { ...config.sessions }` feeds SessionManager (anthropicApiKey not overridden).
+6. Dark surface is a strict 503 no-op through the scrub chokepoint; the only record-shape delta is the additive optional field.
+7. Signal-vs-authority: advisory except the attribution-suppression AND-in, which is appropriate and non-brittle (a boolean over a durable flag with a safe default).
+
+No concern raised.
+
+## Gate-ratchet results (run locally before push)
+
+- `tsc --noEmit` clean; full `npm run lint` clean (includes dark-gate 16/16 — **UNCHANGED**, no ConfigDefaults touch).
+- no-silent-fallbacks 5/5, no-empty-catch-blocks 4/4, feature-delivery-completeness 97/97, docs-coverage --check pass (floor-based; internal-plumbing symbol, no floor breach).
+- credential-env-token-gate 18/18; credential-routes (integration) all pass incl. 3 new rebalancer cases; credential-repointing-routes-alive (e2e) 6/6 incl. live env-token fleet; codex-model-swap-wiring 7/7 (window widened); all SessionManager wiring/activation tests green.
+
+## Second-pass review verdict (Phase 5 — required: change touches a "gate")
+
+Independent reviewer subagent audited the gate + the 4 spawn-site provenance derivations + the dark-ship short-circuit against the real code (not the artifact's claims), and against `docs/signal-vs-authority.md`. All six verification points held:
+
+1. **Single-source-of-truth** — all 3 env-block lanes (`SessionManager.ts:1844/2126/3246`) derive `credentialSource` from the identical `(this.config.anthropicApiKey ?? '') !== ''` predicate adjacent to their own env-block write; the triage lane hardcodes `'store'` and provably empties `ANTHROPIC_API_KEY=`. The gate reads `config.sessions?.anthropicApiKey` (`server.ts:9213`), which is the SAME value `sessionManagerConfig = {...config.sessions}` feeds SessionManager (not overridden). Not a recompute.
+2. **Fail-safe direction** — `credentialSource==='env'` is the only fleet-path refusal; `undefined`→`'store'` (non-refusing). A refusal disables the FEATURE (re-pointing attribution), never messaging/sessions/swaps.
+3. **Dark-ship inertness** — `enabled === true && !gate.evaluate().refused` short-circuits on the flag BEFORE `evaluate()`; the route 503s before evaluating. Byte-for-byte prior behavior when dark.
+4. **Config predicate** — refuses on ANY non-empty `anthropicApiKey` (OAuth `sk-ant-oat` OR api key), matching both SessionManager launch branches.
+5. **Signal-vs-authority** — a deterministic policy evaluator over a structured durable flag, not a brittle detector; the only authority it holds is suppressing the feature itself (the conservatively-correct fail-safe), which the principle doc explicitly permits for a domain this constrained.
+6. **Over/under-refuse** — the mixed-fleet whole-feature refusal is conservatively-correct (refuse rather than mis-steer); machine-local posture is correct. No hole found.
+
+**Verdict: CONCUR.** The side-effects artifact's claims all hold against the actual code.