instar 1.3.222 → 1.3.224

package/src/data/builtin-manifest.json

@@ -1,9 +1,9 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-03T13:08:47.621Z",
-  "instarVersion": "1.3.222",
-  "entryCount": 195,
+  "generatedAt": "2026-06-03T14:11:31.808Z",
+  "instarVersion": "1.3.224",
+  "entryCount": 196,
   "entries": {
     "hook:session-start": {
       "id": "hook:session-start",
@@ -778,7 +778,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -786,7 +786,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -794,7 +794,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -802,7 +802,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -810,7 +810,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -818,7 +818,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -826,7 +826,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -834,7 +834,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -842,7 +842,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -850,7 +850,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -858,7 +858,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -866,7 +866,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -874,7 +874,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -882,7 +882,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -890,7 +890,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -898,7 +898,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -906,7 +906,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -914,7 +914,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -922,7 +922,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -930,7 +930,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -938,7 +938,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -946,7 +946,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -954,7 +954,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -962,7 +962,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -970,7 +970,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -978,7 +978,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -986,7 +986,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -994,7 +994,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -1002,7 +1002,15 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "5c1909925cc2d14b3d8270dd433ec4d6753161553fbe74acc0262608ff368ed4",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
+      "since": "2025-01-01"
+    },
+    "cli:dev-preflight": {
+      "id": "cli:dev-preflight",
+      "type": "cli-command",
+      "domain": "development",
+      "sourcePath": "src/cli.ts",
+      "contentHash": "1b2634f7e1f2a14c409625a87774b5d9fe06cf11b529d38d8b4489a76c6b6f4d",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {

package/src/scaffold/templates.ts

@@ -744,6 +744,8 @@ curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/capabilities
 
 This returns your full capability matrix: scripts, hooks, Telegram status, jobs, git sync status, relationships, and more. **This is the source of truth about what you can do — not the prose descriptions in this file.**
 
+Instar contributors can run \`instar dev:preflight\` before opening PRs to run lint, CapabilityIndex discoverability checks, and an advisory new-route-prefix scan against the diff.
+
 **Critical rule**: If this CLAUDE.md says a feature is "for standalone agents" or "when configured" or uses any qualifier — do NOT conclude you lack the feature. Check \`/capabilities\` instead. Documentation describes features in general; the API tells you what's actually running for YOU right now. When they conflict, the API wins.
 
 ### Registry First, Explore Second

package/upgrades/1.3.223.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Re-points the Codex `fast` model tier off the now-retired `gpt-5.2`.
+
+**The bug (live, fleet-wide).** As of 2026-06-03 OpenAI retired `gpt-5.2` from the
+ChatGPT-account Codex surface — `codex exec --model gpt-5.2` now returns HTTP 400
+*"The 'gpt-5.2' model is not supported when using Codex with a ChatGPT account."*
+Both Codex model-tier maps hardcoded the `fast`/`haiku` tier to `gpt-5.2`:
+
+- `src/providers/adapters/openai-codex/models.ts` (`TIER_TO_MODEL.fast`) — the intel /
+  one-shot path (reviewers, sentinels, CommitmentSentinel, tone-gate, classification).
+- `src/core/frameworkSessionLaunch.ts` (`resolveModelForFramework`, codex-cli) — the
+  session-launch path.
+
+So **every cheap Codex call on every Codex agent was silently failing** — observed live as
+`[CommitmentSentinel] LLM detection failed: … --model gpt-5.2 …` on codey, repeating.
+
+**The fix.** Both maps now resolve `fast`/`haiku` to `gpt-5.4-mini` — the cheapest model
+still accepted on the ChatGPT account (empirically re-probed 2026-06-03: `gpt-5.2` rejected,
+`gpt-5.4`/`gpt-5.4-mini` accepted). `gpt-5.4-mini` is already the `balanced` choice, so the
+`fast` and `balanced` tiers now coincide.
+
+**Trade-off (intentional, documented).** `gpt-5.2` was the only *non-reasoning* model; with it
+retired there is no cheaper option, so cheap Codex calls now run on a reasoning model (higher
+token burn per call). A working model beats a 400-ing one, but this raises cheap-call quota
+pressure on Codex agents until the structural follow-up lands.
+
+**Follow-up (not in this patch).** Drift-resilience: validate the resolved model against a
+known-good set and auto-fall-back on a "not supported" 400, so the *next* model retirement
+self-heals instead of breaking the fleet (the second such break after the 2026-04-14 `-codex`
+retirement). Tracked as a follow-up in `models.ts`.
+
+## What to Tell Your User
+
+Nothing required — this is an internal Codex reliability fix (agent-only). Codex agents'
+cheap internal calls (commitment detection, tone gating, classification) were failing because
+a model name they used got retired; they now use a supported model again.
+
+## Summary of New Capabilities
+
+None — bug fix only. No new routes, config, or surfaces.
+
+## Evidence
+
+- Live failure: codey `logs/server.log` — `[CommitmentSentinel] LLM detection failed: Codex CLI
+  error: … codex exec --model gpt-5.2 …` + the codex 400 `invalid_request_error`.
+- Empirical re-probe (2026-06-03, Justin's ChatGPT subscription): `gpt-5.2` → 400 rejected;
+  `gpt-5.4` and `gpt-5.4-mini` → accepted.
+- Tests: `tests/unit/codex-model-tier-resolution.test.ts` (new — pins both resolvers + a
+  retired-`gpt-5.2` regression guard across all tiers); updated `session-manager-behavioral`
+  and `StallTriageNurse` assertions (haiku/fast → `gpt-5.4-mini`).

package/upgrades/1.3.224.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Adds `instar dev:preflight`, a verify-only contributor preflight for PRs that touch new server
+surfaces.
+
+The command runs lint, runs the CapabilityIndex discoverability unit tests, and scans the diff
+against main for newly added Express route registrations. If the scan sees a new top-level route
+prefix that is not claimed in `CAPABILITY_INDEX`, it prints an advisory warning.
+
+The route scan is intentionally not authority. It is a best-effort regex over added diff lines, not
+an AST parser, and it never edits source. The command exits nonzero only when lint or the explicit
+discoverability/CapabilityIndex test invocation fails.
+
+The safe git funnel now also treats `git diff` as an explicitly allowed source-tree read-tier verb
+when the caller opts into `sourceTreeReadOk`, so this preflight can inspect an Instar checkout
+without bypassing `SafeGitExecutor`.
+
+## What to Tell Your User
+
+- **Instar has a contributor preflight for new surfaces**: "Before a PR, I can run a development
+  preflight that checks lint, capability discoverability, and warns if a newly added route prefix may
+  need a CapabilityIndex classification."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Developer preflight guard | `instar dev:preflight` runs lint, CapabilityIndex discoverability tests, and an advisory diff scan for unclassified new route prefixes. |
+| Route-prefix warning heuristic | Added route registrations in the diff warn when their top-level prefix is absent from `CAPABILITY_INDEX`; warnings do not fail the command. |
+
+## Evidence
+
+Verification:
+
+- Unit: route-detection heuristic covers missing prefix, existing prefix, no routes, and exit-code
+  aggregation.
+- Integration: fixture diff command path verifies the summary, warning output, and real-failure exit
+  behavior.
+- E2E: `dist/cli.js dev:preflight` exits clean on the current tree.
+- Dogfood: `node dist/cli.js dev:preflight` ran lint, discoverability tests, and the route heuristic
+  with exit 0.
+- Docs: docs coverage passed after adding the CLI reference entry.

package/upgrades/codex-fast-model-gpt52-retired.eli16.md

@@ -0,0 +1,26 @@
+# Codex fast-model fix (gpt-5.2 retired) — ELI16
+
+Viewable private artifact:
+https://echo.dawn-tunnel.dev/view/7bc3a2fc-512a-4d1a-b038-725e253145e9?sig=80a2a9cad2adf1d5871bf3611dd6a3b298c07997b7927a730faae64d09193745
+
+Every Codex-powered agent makes lots of small, cheap behind-the-scenes AI calls — spotting a
+promise it made, keeping its tone plain, sorting a message. To keep those cheap, they all ran
+on a lightweight model called **gpt-5.2**.
+
+On June 3, OpenAI quietly **stopped allowing gpt-5.2** on the ChatGPT-subscription kind of
+account these agents use. From that moment every one of those cheap calls started failing with
+a flat error — so, for example, Codey could no longer detect the commitments it makes, all day,
+silently.
+
+The model name was **hardcoded in two places**, so this fix updates both to point at the
+cheapest model that still works on the account: **gpt-5.4-mini**. The agents work again
+immediately.
+
+The one catch, called out honestly: gpt-5.2 was the only *non-thinking* (cheapest) model. The
+replacement is a small *thinking* model, which costs more per call. There was no cheaper option
+left, so this trades a bit more usage for actually working. A follow-up will make this self-heal
+— when a model gets retired, the agent will automatically fall back to a working one instead of
+breaking.
+
+_Patch fix · branch `echo/codex-fast-model-retire` · found by scanning live fleet logs (the
+see-what-breaks loop) and empirically re-probing which models the account still accepts._

package/upgrades/dev-preflight-new-surface-friction-guard.eli16.md

@@ -0,0 +1,18 @@
+# ELI16: Dev Preflight New-Surface Guard
+
+Instar now has a developer-only preflight command for PRs that add or touch new server surfaces. The
+command runs lint, runs the CapabilityIndex discoverability tests, and then scans the diff for newly
+added Express route registrations.
+
+The route scan is only a heuristic. It looks for added `app.get/post/put/delete/patch('/prefix')` or
+`router.get/post/put/delete/patch('/prefix')` lines and warns if the top-level prefix is not in
+`CAPABILITY_INDEX`. It never edits source, never updates `CapabilityIndex`, and never blocks the
+server.
+
+Only two things make the command exit nonzero: lint failing, or the discoverability/CapabilityIndex
+unit tests failing. Route-prefix findings are warnings so the agent can make the deliberate
+classification without hidden automation changing the registry.
+
+Private view proof: https://codey.dawn-tunnel.dev/view/e060533e-cafd-4a37-b251-7d8d4dbeb63b?sig=7d25de0423b88fd4c59ec3f0a1238bfe69e8891d841da33d92308bec7be2f71c
+
+Verified HTTP 200 on 2026-06-03.

package/upgrades/side-effects/codex-fast-model-gpt52-retired.md

@@ -0,0 +1,59 @@
+# Side-Effects Review — Codex `fast` tier off retired `gpt-5.2`
+
+**Version / slug:** `codex-fast-model-gpt52-retired`
+**Date:** `2026-06-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (Tier-1 bug fix — model-string re-point + tests, no decision surface)`
+
+## Summary of the change
+
+Two Codex model-tier maps hardcoded `fast`/`haiku` → `gpt-5.2`. OpenAI retired `gpt-5.2`
+from the ChatGPT-account Codex surface (live 400 as of 2026-06-03), silently breaking every
+cheap Codex call fleet-wide. Both maps now resolve `fast`/`haiku` → `gpt-5.4-mini` (the
+cheapest model still accepted). A new unit test pins both resolvers and guards the retired
+name. No routes, config, schema, or external surface change.
+
+## Decision-point inventory
+
+1. **Which replacement model?** Candidates still accepted (empirically probed 2026-06-03):
+   `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`. Chose `gpt-5.4-mini` — the cheapest (it is already
+   the validated `balanced` tier; "mini" < plain `gpt-5.4`). `gpt-5.2` was the only
+   *non-reasoning* model, so no zero-reasoning option remains; this is the least-cost working
+   choice, not a free one.
+2. **Re-point now vs. build the drift-resilient fallback first?** Chose to ship the re-point
+   immediately (it stops an active fleet-wide failure) and leave the structural fallback
+   (validate-against-known-good + auto-fall-back on a 400) as a follow-up. Rationale: the
+   urgent fix is small and regression-safe; the fallback is a larger, separately-testable
+   surface that shouldn't gate the stop-the-bleeding change.
+
+## 1. Cost / quota
+
+`fast` was the cheap non-reasoning tier (gpt-5.2 ≈ 103 tokens on a trivial prompt vs ~5–7k
+for reasoning models). Moving it to a reasoning model (`gpt-5.4-mini`) raises per-call token
+burn for all cheap Codex calls. This is **unavoidable** (gpt-5.2 is gone) but worth flagging
+against the known self-inflicted cheap-call 429 pressure on the shared ChatGPT account — it
+makes the structural drift-resilient fallback (and any cheap-call-volume reduction) more
+valuable, not less. No way to keep the old cost without the retired model.
+
+## 2. Tier collapse
+
+`fast` now equals `balanced` (`gpt-5.4-mini`). Callers that distinguished the two tiers by
+cost no longer get a cheaper `fast`. Acceptable: there is no cheaper accepted model. Reverts
+automatically if/when a cheaper non-reasoning model is re-added to the map.
+
+## 3. Blast radius / reversibility
+
+Two string literals + comment updates + one new test + two updated assertions. Fully
+reversible (revert the two map entries). Claude and Gemini resolvers are untouched
+(framework-scoped branches). No effect on API-key callers passing raw model names (those
+pass through verbatim — unchanged).
+
+## 4. Tests
+
+- New `tests/unit/codex-model-tier-resolution.test.ts`: both resolvers per tier + a
+  retired-`gpt-5.2` regression guard over `fast/balanced/capable/haiku/sonnet/opus` and the
+  undefined default.
+- Updated `session-manager-behavioral` (codex session spawn: haiku → `gpt-5.4-mini`) and
+  `StallTriageNurse` (legacy haiku alias → `gpt-5.4-mini`).
+- Transcript-fixture tests that contain `model: 'gpt-5.2'` (TokenLedger, CodexRolloutParser)
+  are unchanged — they parse historical rollouts and a past session legitimately used gpt-5.2.

package/upgrades/side-effects/dev-preflight-new-surface-friction-guard.md

@@ -0,0 +1,29 @@
+### dev-preflight-new-surface-friction-guard side effects
+
+Primary risk reviewed: a developer convenience command could become hidden authority over route
+classification.
+
+Decision inventory:
+
+- `instar dev:preflight` is verify-only and has no write path.
+- The command never edits `src/server/CapabilityIndex.ts`.
+- The command never mutates route files or server config.
+- The command exits nonzero only for `pnpm lint` or the explicit
+  capabilities-discoverability/CapabilityIndex test invocation.
+- Diff route-prefix findings are advisory warnings only.
+- Diff lookup failure is a warning, not a failure, because the canonical guard remains the
+  discoverability test.
+- `SafeGitExecutor` now includes `diff` in the explicit `sourceTreeReadOk` read-tier set so this
+  command can inspect the current Instar checkout without bypassing the safe git funnel.
+
+Secondary risk: the heuristic could miss routes or flag false positives because it is regex-based.
+That is acceptable by design. The heuristic is early friction for authors, not the source of truth.
+The source of truth remains the existing CapabilityIndex registry and its unit tests.
+
+Operational risk: running the command can be slow because it runs lint and a targeted Vitest
+invocation. This is deliberate; the command is a contributor preflight, not a server path or
+background job.
+
+CI follow-up: manifest IDs must keep the `type:name` shape, so the built-in manifest registers this
+surface as `cli:dev-preflight` while the actual command remains `instar dev:preflight`. Integration
+assertions strip ANSI color before checking summary text because CI may enable color output.