instar 1.3.792 → 1.3.794

package/upgrades/1.3.793.md

@@ -0,0 +1,80 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The `IntelligenceRouter` failure-swap now covers NON-gating internal calls, fixing a class where a
+non-gating background component hard-errored instead of trying a healthy fallback door.
+
+Background: internal components run off Claude by default (Codex → Pi → Gemini → Claude). When a
+GATING call's primary provider fails at runtime it already swaps down that chain. NON-gating calls
+did not — they re-threw straight to the caller's heuristic. In production, `TopicIntentExtractor`
+(non-gating, routed to codex-cli/gpt-5.4-mini) showed a 28% error rate (122/428 over 7 days), every
+error row zero-usage — i.e. the codex `exec` invocation itself failed/timed out/returned empty. The
+GATING calls beside it errored ~1.5% precisely because they swap.
+
+The fix extends the swap to non-gating calls with a TIGHTER bound than gating calls get:
+- It fires ONLY on an INVOCATION-level primary failure (the primary threw AND produced zero tokens).
+  A content/parse error that carried tokens does NOT swap (the caller fail-opens that, per
+  provider-fallback §6.4). The router composes an `onUsage` capture onto the primary attempt to
+  observe token production; a provider that never surfaces usage (gemini) is treated as
+  invocation-level (the conservative, error-reducing direction).
+- At most `maxAttempts` (default 1) steps down the active `failureSwap` tail, each target
+  circuit-checked and bounded by the existing `intelligence.swapAttemptTimeoutMs` per-attempt cap
+  (also flowed through as the provider's `timeoutMs`).
+- NEVER onto `claude-code` or the default framework — the provider-fallback §6.2 invariant that
+  non-gating background traffic must never herd onto the last-resort Claude tail. If the only
+  remaining tail entry is claude-code, the call re-throws to its heuristic (today's behavior).
+- Metrics honesty is automatic: each provider's own CircuitBreaking wrapper records its own
+  feature_metrics row (the failed codex primary keeps its zero-usage error row; the pi swap records
+  pi's usage/model). `usageCoverage` is unaffected.
+
+New config: `intelligence.nonGatingFailureSwap: { enabled?: boolean; maxAttempts?: number }`,
+inline-defaulted at the router construction site (`enabled` default true; the codexExecJson /
+swapAttemptTimeoutMs precedent — no ConfigDefaults/migrateConfig entry). Set `enabled: false` to
+restore the old hard-error behavior. Gating-call behavior, deferrable behavior,
+`sessions.componentFrameworks` semantics, the spawn-cap funnel, and nature-routing are all
+untouched. On a Claude-only agent (no off-Claude CLI) the whole thing is a no-op.
+
+## What to Tell Your User
+
+Some of my quick background helpers — like the one that works out what a conversation topic is
+about — used to just fail whenever the tool they run on had a brief hiccup, even though a healthy
+backup tool was sitting right there. In real numbers, one of them was failing more than a quarter
+of the time for exactly this reason. Now, when a background helper's tool fails to run, I quietly
+try one backup tool before giving up, so far fewer of these little checks fall over. It never adds
+a noticeable wait, it never pushes that background chatter onto your main Claude account, and it
+only kicks in when the tool genuinely failed to run — not when it answered. You don't have to do
+anything; it's on by default and it just makes me more reliable. If you ever want the old behavior
+back, I can switch it off for you.
+
+## Summary of New Capabilities
+
+- Non-gating internal calls now get a bounded, herd-safe provider swap on an invocation-level
+  failure, instead of hard-erroring — sharply reducing user-visible errors on components like the
+  topic classifier.
+- New off-switch: `intelligence.nonGatingFailureSwap.enabled: false` restores the old hard-error
+  behavior; `maxAttempts` tunes how many tail steps a non-gating call may take (default 1).
+- Proactive trigger for the agent: "why did my background classifier's error rate drop / does a
+  non-gating call fall back too?" → this bounded swap.
+
+## Evidence
+
+Reproduction (production, 2026-07-09, from `GET /metrics/features` 7d + the overnight routing
+investigation `/.instar/plans/overnight-routing-error-investigation.md`): `TopicIntentExtractor`
+`byModel` (codex-cli/gpt-5.4-mini) = 434 calls, 123 errors, `errorRowsWithUsage: 0`, `fired: 0`,
+311 noop — a 28% error rate. The zero-usage on every error row is the tell: these are
+invocation-level codex-exec failures (no tokens produced), not rate-limits (codex ~3% used) and not
+parse errors (those carry tokens). The GATING `MessagingToneGate` errored at 1.5% and
+`CoherenceReviewer` at 2.6% because they ride the failure-swap tail; the non-gating call did not.
+
+Before: a non-gating primary invocation failure re-throws immediately → the 28% user-visible error
+rate. After: the same failure swaps once onto the next active off-Claude framework (pi-cli, ~1.5%),
+so the call succeeds instead of erroring. Verified by driving the exact router path end-to-end:
+`tests/unit/nongating-failure-swap.test.ts` (13 — invocation-failure→swap, content-error→no-swap,
+disabled/absent→old behavior, target-down→re-throw original, herd-safety never-onto-Claude while
+gating still swaps, maxAttempts bound, tier preserved, slow-target abandoned at the cap),
+`tests/integration/nongating-failure-swap-routing.test.ts` (3), and
+`tests/e2e/nongating-failure-swap-lifecycle.test.ts` (2, real AgentServer init path, default-ON).

package/upgrades/1.3.794.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The GPT-5.6 model family (`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) went GA on the Codex subscription and is now on instar's accepted-model allowlists for the `codex-cli` framework. Two mirrored lists gained the three ids: `KNOWN_CODEX_MODEL_IDS` (the model-tier-escalation resolver's closed enum, `src/core/ModelTierEscalation.ts`) and `CODEX_MODELS_SUBSCRIPTION` (the `POST /sessions/spawn` model validator, `src/server/routes.ts`). The topic-profile validator reads the same enum, so it accepts the new ids automatically. The fail-closed design is unchanged — an id outside the closed enum is still rejected; we only widened the set of recognized ids.
+
+The Doorway/Model Knowledge Registry (`scripts/model-registry-freshness.manifest.json`) also learned the three models as recognized, reachable entries with pricing, so `GET /doorways` knows they exist. They are deliberately NOT promoted to the frontier pin — the capable tier still resolves to `gpt-5.5`; a benchmark-driven promotion is a tracked follow-up.
+
+## What to Tell Your User
+
+If you run Codex sessions, you can now pin a topic or spawn a session on the new GPT-5.6 models — sol (the flagship), terra (mid-size), or luna (small and cheap) — and instar accepts them instead of rejecting them as unknown. This needs the Codex CLI at version 0.144.0 or newer; older CLIs reject GPT-5.6 with a "requires a newer version" error, so update the Codex CLI if you hit that. If your setup already escalates heavy work onto the GPT-5.6 flagship, it becomes live with this update. The Pro variants are intentionally not accepted yet (they're likely plan-gated and pricier — a future follow-up), and for now instar still picks GPT-5.5 for its heavy tier until the new models earn that spot through benchmarks.
+
+## Summary of New Capabilities
+
+- `codex-cli` sessions and topic profiles accept `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna` (model-tier escalation, `/sessions/spawn`, and topic-profile pins).
+- `GET /doorways` reports the three GPT-5.6 models (with pricing) as recognized, reachable Codex models.

package/upgrades/side-effects/codex-gpt56-allowlist.md

@@ -0,0 +1,60 @@
+# Side-Effects Review — Add the GPT-5.6 family to the codex model allowlists
+
+**Change:** additive model-id allowlist extension for the `codex-cli` framework. **Tier 1** (small, low-risk, fail-closed design unchanged). **Parent principle:** Structure > Willpower (the closed model-id enumeration is a code-enforced gate; this widens the allowed set, it does not weaken the gate).
+
+**Files changed:**
+- `src/core/ModelTierEscalation.ts` — `KNOWN_CODEX_MODEL_IDS` gains `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`.
+- `src/server/routes.ts` — `CODEX_MODELS_SUBSCRIPTION` (the `POST /sessions/spawn` codex model validator) gains the same three ids, keeping the two lists identical (the comment pins them as mirrors).
+- `scripts/model-registry-freshness.manifest.json` — the Doorway/Model Knowledge Registry's `codex-cli.topModels` gains the three ids as recognized entries (`frontier: false`, pricing populated) + the door note / `$flaggedStaleNote` prose corrected to reflect the 2026-07-09 GA (the earlier "gpt-5.6-sol is preview-only/unreachable" line was now false).
+- `tests/unit/modelTierEscalation-resolver.test.ts`, `tests/unit/route-validation-edge.test.ts`, `tests/unit/topicProfileValidation.test.ts` — allowlist + resolver + spawn + validation coverage.
+- `docs/specs/codex-gpt56-allowlist.eli16.md`, `upgrades/next/codex-gpt56-allowlist.md` — the ELI16 + release fragment.
+
+## What changed
+
+The GPT-5.6 family (sol/terra/luna) went GA on the codex subscription on 2026-07-09 and was live-verified working (codex CLI >= 0.144.0 required; older CLIs 400 with "requires a newer version"). instar fails closed on model ids outside its closed per-framework enums, so these ids were rejected everywhere. This change adds the three ids to the two mirrored acceptance lists (`KNOWN_CODEX_MODEL_IDS` + `CODEX_MODELS_SUBSCRIPTION`). The `-pro` variants are deliberately excluded (plan-gated + pricier — tracked follow-up).
+
+## Lists touched vs deliberately left
+
+**Touched (acceptance / validation lists):**
+- `KNOWN_CODEX_MODEL_IDS` (`src/core/ModelTierEscalation.ts`) — the escalation resolver's closed enum, and (via `KNOWN_MODEL_IDS`) the source for `topicProfileValidation.validateModelId`. One edit flows to both surfaces.
+- `CODEX_MODELS_SUBSCRIPTION` (`src/server/routes.ts`) — the `/sessions/spawn` codex-cli model validator. Kept byte-identical in membership to the enum above (they are documented mirrors).
+- `scripts/model-registry-freshness.manifest.json` → `doors.codex-cli.topModels` — the Doorway/Model Knowledge registry, added the three ids with `frontier: false` + pricing so `GET /doorways` knows they exist and their cost.
+
+**Deliberately LEFT (routing/selection — a model earns a lane via benchmarks, not by GA date):**
+- `src/providers/adapters/openai-codex/models.ts` `TIER_MODEL` (capable → gpt-5.5, fast/balanced → gpt-5.4-mini) — model CHOICES per tier, not an acceptance list.
+- `src/core/frameworkSessionLaunch.ts` tier→model resolution — same reason.
+- `src/data/llmBenchCoverage.ts` (`ROUTING_LABEL_TO_MODEL_ID`, bench coverage, nature-routing chains) — the routing chains that pick models for lanes; models earn these via benchmarks.
+- The doorway manifest's `codex-capable-tier` PIN and the `frontier: true` flag — left at `gpt-5.5`. Promoting `gpt-5.6-sol` to the capable pin / frontier is a benchmark-driven follow-up, not this acceptance PR.
+
+## Blast radius
+
+- **Purely additive.** No id removed, no existing id's behavior changed. A caller not asking for a GPT-5.6 id is entirely unaffected.
+- **Fail-closed preserved.** A well-shaped id outside the enum is still rejected (`id-not-in-closed-enum`); a made-up `gpt-9.9-fake` still 400s at spawn and resolves to null in escalation — both covered by new tests.
+- **No new route, no new config default, no schema change.** No dark-gate line shift (no `enabled:` line added to `ConfigDefaults.ts`).
+
+## Risk + mitigation
+
+- **Risk:** the two mirror lists drift apart. **Mitigation:** both edited in the same commit with a cross-referencing comment on each; new tests assert acceptance through both the resolver and the spawn route.
+- **Risk:** the doorway manifest edit trips the CI-gating model-registry-freshness lint. **Mitigation:** the new entries are `frontier: false`, so the codex-cli derived frontier set stays `['gpt-5.5']` and the `codex-capable-tier` pin (still `gpt-5.5`) remains a member — the drift tooth is unaffected. Staleness is unchanged (`lastReviewedAt` untouched, well within the 45-day window). Verified: `node scripts/lint-model-registry-freshness.mjs` → PASS.
+- **Risk:** a user on an old codex CLI selects a GPT-5.6 id and gets an opaque failure. **Mitigation:** the ELI16 + release fragment both call out the codex CLI >= 0.144.0 requirement explicitly.
+
+## Framework generality
+
+The change is scoped to the `codex-cli` framework's own acceptance surfaces and routes through the existing per-framework `KNOWN_MODEL_IDS` / spawn-validator abstraction — it does not touch the session-launch/inject abstraction and makes no Claude-specific assumption. Other frameworks (claude-code, gemini-cli, pi-cli) are untouched.
+
+## Migration parity
+
+- No agent-installed file changes (no `.claude/settings.json`, no `.instar/config.json` default, no CLAUDE.md template section, no hook/skill). The allowlists are shipped code read at runtime, so existing agents pick up the new ids on the normal server/dist update — no `PostUpdateMigrator` entry needed. The operator's already-set `models.tierEscalation.frameworks.codex-cli.escalated = "gpt-5.6-sol"` becomes live purely by deploying this code.
+
+## Tests
+
+- `tests/unit/modelTierEscalation-resolver.test.ts` — codex-cli escalated tier accepts each of gpt-5.6-sol/terra/luna; a made-up id fails closed (`id-not-in-closed-enum`); the `-pro` variants are asserted absent.
+- `tests/unit/route-validation-edge.test.ts` — `POST /sessions/spawn` with framework `codex-cli` accepts the three GPT-5.6 ids (not 400) and rejects `gpt-9.9-fake` (400, error names "model").
+- `tests/unit/topicProfileValidation.test.ts` — `validateModelId(..., 'codex-cli')` returns null for the three ids (the KNOWN_MODEL_IDS mirror path).
+- Adjacent suites re-run green: `model-registry-freshness`, `codex-model-tier-resolution`, `frameworkSessionLaunch`, `model-tier-swap-route`, `model-tier-escalation-lifecycle`. `npx tsc --noEmit` clean.
+
+## Follow-ups
+
+- Add the `-pro` GPT-5.6 variants once their plan-gating + pricing are confirmed.
+- Benchmark GPT-5.6-sol and, if it wins the lane, promote it to the codex capable tier pin (`TIER_MODEL.capable` + the manifest `frontier: true` + `lastReviewedAt` bump) and into the routing chains — a routing decision, not an acceptance change.
+- Populate real per-token pricing across the doorway registry if/when the metered doorway-scan scopes consume it.

package/upgrades/side-effects/nongating-failure-swap.md

@@ -0,0 +1,54 @@
+# Side-Effects Review — Non-Gating Failure-Swap (bounded provider swap for non-gating internal calls)
+
+**Spec:** docs/specs/nongating-failure-swap.md (Tier-1 bug fix — bounded extension of the CONVERGED + approved `docs/specs/provider-fallback-default-policy.md`). **Parent principle:** No Silent Degradation to Brittle Fallback.
+**Ships ON by default** (`intelligence.nonGatingFailureSwap.enabled`, inline-defaulted `?? true` at the router construction site — no persisted config block). No-op on a Claude-only agent (no off-Claude tail) and on any router constructed without the field (e.g. unit tests).
+**Files:** src/core/IntelligenceRouter.ts, src/core/types.ts, src/commands/server.ts, src/scaffold/templates.ts, src/core/PostUpdateMigrator.ts, docs/specs/nongating-failure-swap.md (new), docs/specs/nongating-failure-swap.eli16.md (new), upgrades/next/nongating-failure-swap.md (new), upgrades/side-effects/nongating-failure-swap.md (new), tests/unit/nongating-failure-swap.test.ts (new), tests/unit/PostUpdateMigrator-nonGatingFailureSwap.test.ts (new), tests/integration/nongating-failure-swap-routing.test.ts (new), tests/e2e/nongating-failure-swap-lifecycle.test.ts (new)
+
+## What changed
+
+1. **IntelligenceRouter.ts — `IntelligenceRouterOptions`:** new optional `nonGatingFailureSwap?: { enabled: boolean; maxAttempts?: number }`. Absent ⇒ feature OFF (byte-identical legacy — a non-gating primary failure re-throws straight to the caller's heuristic).
+2. **IntelligenceRouter.ts — `evaluate()`:** after the existing `swapPositions`/`gatingDeadlineAt` computation, compute `nonGatingSwapEligible = !gating && !deferrable && !enforced && nonGatingFailureSwap.enabled === true && cfg.failureSwap.length > 0`. On the eligible path ONLY, compose an `onUsage` capture onto the primary attempt (`primaryEvalOptions`) so `primaryProducedTokens` records whether the primary produced any tokens; gating/deferrable/enforced calls use `evalOptions` verbatim (byte-identical). Inside the existing `if (swapPositions.length === 0)` branch, BEFORE the deferrable-queue + heuristic-fallthrough, if `nonGatingSwapEligible && !primaryProducedTokens` call the new `tryNonGatingSwap(...)`; on success return its result (before any heuristic-fallthrough tracking).
+3. **IntelligenceRouter.ts — new `tryNonGatingSwap()`:** attempts at most `maxAttempts` (default 1) steps down `cfg.failureSwap`, FILTERING OUT `claude-code`, the default framework, and the just-failed primary. Each target is `resolveProvider`-checked (binary-missing/circuit-open → skipped/caught) and bounded by the SAME `resolveSwapCap` + `withSwapTimeout` machinery the gating loop uses (the cap also flows through as the provider's `timeoutMs`). Emits `onDegrade` (`nongating-failure-swap:` on success, `nongating-swap-attempt-timeout:` on a cap fire) + `onResolved` on success. Returns `{ ok }`; on `{ ok:false }` the caller falls through to its existing heuristic (`onHeuristicFallthrough` + `throw err`).
+4. **types.ts:** new `intelligence.nonGatingFailureSwap?: { enabled?: boolean; maxAttempts?: number }` config field, documented as inline-defaulted (codexExecJson/swapAttemptTimeoutMs precedent — deliberately NOT in ConfigDefaults/migrateConfig).
+5. **server.ts (router construction):** wire `nonGatingFailureSwap: { enabled: config.intelligence?.nonGatingFailureSwap?.enabled ?? true, maxAttempts: config.intelligence?.nonGatingFailureSwap?.maxAttempts }` — the default-ON expression.
+6. **templates.ts + PostUpdateMigrator.ts:** a bullet under Per-Component Framework Routing (new agents) + an idempotent content-sniffed `migrateClaudeMd` corrective subsection (existing agents), marker `non-gating internal calls also get a bounded`.
+
+## Blast radius
+
+- **Gating / deferrable / nature-enforced paths are untouched.** `nonGatingSwapEligible` is false for all of them, so `primaryEvalOptions === evalOptions` (no capture) and the new branch is never entered. The gating swap loop, the deferrable backoff/queue rungs, and the enforced-nature selection are byte-identical.
+- **No new HTTP route, no new provider, no new spawn.** The non-gating swap reuses the existing per-framework providers (already built at boot via `buildProvider`) and the existing per-attempt cap machinery. `tryNonGatingSwap` never builds a new provider or spawns beyond what a normal swap attempt does.
+- **Bounded blast on the swap itself:** at most `maxAttempts` (default 1) steps, each circuit-checked, each capped by `swapAttemptTimeoutMs` (default 5s). Worst-case added latency on a non-gating failure = `maxAttempts × cap`.
+- **Off-Claude only.** `claude-code` and the default framework are FILTERED OUT of non-gating targets, so this can never push non-gating background traffic onto the last-resort Claude tail (the §6.2 herd invariant). On a Claude-only agent `cfg` is undefined / the tail is empty → strict no-op.
+
+## Risk + mitigation
+
+- **Risk:** reintroduces the §6.2 herd (non-gating traffic floods a fallback under a broad rate-limit). **Mitigation:** the non-gating swap is STRICTLY more conservative than the gating swap — one step (default), circuit-checked (a target whose breaker is open throws fast → skipped), and NEVER onto Claude. Under a genuine rate-limit the target's own breaker damps repeat attempts. Proven by the herd-safety lens test (`never onto claude-code … but a GATING call does`) and the maxAttempts-bound test.
+- **Risk:** swapping on a content/parse error double-spends tokens on a request that already burned some. **Mitigation:** the swap fires ONLY when the primary produced ZERO tokens (`primaryProducedTokens` false). A token-carrying failure is NOT swapped — the caller fail-opens it (§6.4). Proven by the `content/parse error that CARRIED tokens → NO swap` test.
+- **Risk:** a slow fallback adds latency to a high-volume noop path. **Mitigation:** the per-attempt cap (`swapAttemptTimeoutMs`, default 5s) abandons a slow target via `withSwapTimeout` (the shipped crash-safe Promise.race form; timer cleared on settle). Proven by the `SLOW target abandoned at the cap` test.
+- **Risk:** the `onUsage` capture interferes with the primary's own metrics/usage recording. **Mitigation:** the capture COMPOSES with the caller's onUsage (`callerOnUsage?.(u)`) and is downstream of the CircuitBreaking wrapper's own capture — additive, no clobber. Metrics honesty is automatic (each provider's wrapper records its own row keyed by serving framework/model); `usageCoverage` is unaffected.
+- **Risk:** an error in the swap helper breaks the LLM call path. **Mitigation:** every path in `tryNonGatingSwap` ends at either a returned result or `{ ok:false }` → the caller's existing `throw err` (heuristic). It never introduces a new fail-closed and never swallows silently — the catch emits `onDegrade` on a cap fire and `continue`s (the same non-silent resilience pattern as the gating loop; not counted by the no-silent-fallbacks ratchet).
+
+## Migration parity
+
+- **Config:** no `migrateConfig` needed — the knob is inline-defaulted at the construction site (`?? true`), so existing agents pick up the default-ON behavior purely from the new code shipping (the codexExecJson/swapAttemptTimeoutMs precedent). Absence ⇒ enabled default.
+- **CLAUDE.md:** `generateClaudeMd` gains the bullet (new agents); `migrateClaudeMd` appends an idempotent content-sniffed corrective subsection (existing agents), marker `non-gating internal calls also get a bounded`. Covered by `tests/unit/PostUpdateMigrator-nonGatingFailureSwap.test.ts` (add-when-absent, idempotent, preserves content, skips when missing) + a template-emits-it assertion.
+
+## Dark-gate line-map
+
+- UNCHANGED. `nonGatingFailureSwap` is inline-defaulted in `src/commands/server.ts` (`?? true`) and declared as an optional type in `types.ts`; it is NOT an `enabled:` line in `ConfigDefaults.ts`. The dark-gate attributor reads `ConfigDefaults.ts` only and matches `enabled:` lines, so no line shifted. Verified: `tests/unit/lint-dev-agent-dark-gate.test.ts` → green in the run batch.
+
+## Rollback
+
+- Set `intelligence.nonGatingFailureSwap.enabled: false` → non-gating failures re-throw to the heuristic with no swap (today's behavior), no restart-to-rewire needed (config is read live in `resolveConfig`; the field is read at construction, so a restart is needed only if the operator wants to change it after boot — same posture as `swapAttemptTimeoutMs`). To fully revert: remove the `nonGatingFailureSwap` option + `tryNonGatingSwap` + the eligibility/capture block in `evaluate()` + the server wiring + the type + the CLAUDE.md bullet/migration. Additive throughout.
+
+## Tests
+
+- `tests/unit/nongating-failure-swap.test.ts` (13) — the core behavior + both sides of every decision boundary: invocation-failure → one swap; content-error-with-usage → no swap; disabled + absent → old behavior; target down/circuit-open → skip + re-throw ORIGINAL error; gemini-primary (no usage) → conservative swap; herd-safety (never onto claude-code/default while GATING still does); gating unchanged (full-tail swap); maxAttempts=1 vs 2; model tier preserved; per-attempt cap passthrough; slow target abandoned at the cap.
+- `tests/integration/nongating-failure-swap-routing.test.ts` (3) — a production-shaped router (computed default + the knob) SWAPS on a non-gating invocation failure; `GET /intelligence/routing` is unchanged (resolution, not swap); `{ enabled:false }` hard-errors.
+- `tests/e2e/nongating-failure-swap-lifecycle.test.ts` (2) — real AgentServer init path: the intelligence-routing route is alive AND the wired router performs the swap via the SHIPPED default expression (config unset ⇒ enabled:true), proving the feature is alive + ON, not dark.
+- `tests/unit/PostUpdateMigrator-nonGatingFailureSwap.test.ts` (5) — the migrateClaudeMd corrective (add/idempotent/preserve/skip) + template-emits-it.
+- Regression: `no-silent-fallbacks`, `lint-dev-agent-dark-gate`, `provider-fallback-swap-timeout`, `per-target-swap-timeout`, `internalFrameworkDefault`, `intelligence-router`, `nature-routing-resolver`, `degradation-ladder`, `opus-claude-cli-gating-guardrail`, `provider-fallback-default-routing`, `intelligence-routing-routes/lifecycle` all green. tsc clean.
+
+## Agent awareness
+
+- A "Non-gating calls also get a bounded swap now" bullet extends the Per-Component Framework Routing section in `generateClaudeMd`, and an idempotent `migrateClaudeMd` corrective subsection reaches existing agents. Proactive trigger documented: "why did my background classifier's error rate drop / does a non-gating call fall back too?".