instar 1.3.706 → 1.3.708

package/upgrades/1.3.708.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The last hardcoded-model callsites from the LLM Routing Registry audit ("Risk
+items" #3/#5/#6/#7) are now overridable configuration with behavior-preserving
+inline defaults — with nothing set, every callsite behaves byte-for-byte as
+before, and nothing is written to any config file (absence IS the default; no
+migration needed).
+
+- `DispatchExecutor.runAgentic`'s spawned dispatch session model:
+  `intelligence.pinnedModels.dispatchAgentic` (default 'haiku', unchanged).
+- The anthropic-headless credential-probe validation ping:
+  `intelligence.pinnedModels.anthropicCredentialProbe` (default now sourced
+  from `ANTHROPIC_MODELS.haiku` in the central tier map instead of a
+  free-floating `'claude-haiku-4-5'` literal, so a future model bump cannot
+  silently miss it).
+- The setup wizard's narrative models (codex + gemini drivers): env-var
+  overrides `INSTAR_WIZARD_CODEX_MODEL` / `INSTAR_WIZARD_GEMINI_MODEL` — env
+  not config, because the wizard runs before `.instar/config.json` exists.
+  `setup.ts`'s duplicate `WIZARD_CODEX_MODEL` const collapsed into a single
+  source of truth in `setup-wizard/model-constants.ts` (re-exported, canary
+  contract preserved).
+- Honest audit correction: risk item #4 (mentor loop → 'opus') needed no code
+  change — it was already config-driven via `mentor.autonomousFix.model`; a
+  canary test now pins that fact.
+
+15 new unit tests cover both sides of every boundary (absent ⇒ shipped
+default, present ⇒ override wins, whitespace ⇒ absent) plus wiring canaries
+asserting `server.ts` threads both config keys. This is step one of the
+INSTAR-Bench v2 program (operator-approved 2026-07-02): before benchmark
+results can drive model routing, every model choice must be reachable by
+configuration rather than buried in code.
+
+## What to Tell Your User
+
+Nothing proactively — this changes no behavior on its own. If your operator
+asks: a handful of my internal helpers (the background dispatch runner, my
+setup wizard's text generator, and the tiny "does this credential work?"
+check) had their AI model choice typed directly into my code; those choices
+are now ordinary settings, with the old models still used unless someone
+deliberately changes them.
+
+## Summary of New Capabilities
+
+- New config block `intelligence.pinnedModels` (`dispatchAgentic`,
+  `anthropicCredentialProbe`) — inline-defaulted, absent means today's
+  behavior exactly.
+- New env overrides `INSTAR_WIZARD_CODEX_MODEL` / `INSTAR_WIZARD_GEMINI_MODEL`
+  for the pre-config setup wizard.
+- New adapter config field `credentialProbeModel` on anthropic-headless.

package/upgrades/config-driven-pinned-models.eli16.md

@@ -0,0 +1,18 @@
+# The last few "model choices burned into the code" are now settings
+
+Instar makes hundreds of small AI calls a day — checking messages, validating credentials, running its setup wizard, executing background dispatch steps. For almost all of them, WHICH model gets used is a setting an operator can change. But an audit this week found a handful of stragglers where the model name was typed directly into the code: the background dispatch runner always spawned "haiku", the setup wizard always asked "gpt-5.3-codex" (or "gemini-2.5-flash") to write its intro text, and the credential checker always pinged Anthropic with a hard-typed "claude-haiku-4-5". If benchmarking ever showed a better/cheaper model for one of these jobs, changing it meant editing source code and shipping a release — for what should be a one-line setting.
+
+This change makes those last callsites configurable, with one iron rule: **if you change nothing, nothing changes.** Every one of them keeps exactly its old model as the built-in default. The new settings don't even get written into config files — absence IS the default, so no existing agent's config is touched on update, and there is nothing to migrate.
+
+The specifics, in plain terms:
+
+- The background dispatch runner's model can now be set in config (`intelligence.pinnedModels.dispatchAgentic`). Unset, it's "haiku" like always.
+- The credential checker's tiny "does this key work?" ping model is configurable too (`intelligence.pinnedModels.anthropicCredentialProbe`) — and its default now comes from the central model list instead of a lone typed-out string, so a future Claude model bump can't silently miss it.
+- The setup wizard is special: it runs BEFORE the config file exists (creating that file is its whole job), so a config setting could never reach it. Its override is an environment variable instead (`INSTAR_WIZARD_CODEX_MODEL` / `INSTAR_WIZARD_GEMINI_MODEL`), which is the only kind of setting that CAN reach it.
+- One honest discovery: the mentor loop — listed in the audit as hardcoded to "opus" — turned out to already be configurable (`mentor.autonomousFix.model`); the audit row was wrong. A test now pins that so the record stays honest.
+
+Also cleaned up: the wizard's codex model name was typed in TWO places that could drift apart; now there's one source of truth that the other re-exports.
+
+Safety story: this adds no new decision-making, no gating, no blocking — it only lets an operator choose the model for five existing, unchanged jobs. Fifteen new tests prove both directions on every surface: leave it unset and you get byte-for-byte the old behavior; set it and your value wins; set it to whitespace and it's treated as unset. The existing wizard canary tests (which pin the "-m model" discipline on every codex spawn) pass unmodified. Rollback is deleting a config line.
+
+Why now: this is step one of the INSTAR-Bench v2 program (operator-approved 2026-07-02) — before benchmark results can drive model routing, every model choice has to be reachable by configuration rather than buried in code.

package/upgrades/side-effects/config-driven-pinned-models.md

@@ -0,0 +1,63 @@
+# Side-Effects Review — Config-driven pinned-model callsites (routing-registry risk items #3/#5/#6/#7)
+
+**Version / slug:** `config-driven-pinned-models`
+**Date:** `2026-07-02`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `not required` (no gate/sentinel/lifecycle surface — pure config plumbing with behavior-preserving defaults)
+
+## Summary of the change
+
+Migrates the hardcoded-model callsites catalogued as "Risk items" #3, #5, #6, #7 in the LLM Routing Registry audit (2026-07-01, operator-directed) to overridable configuration with **behavior-preserving inline defaults** — with no config/env set, every callsite behaves byte-for-byte as before. Files touched: `src/core/types.ts` (new `intelligence.pinnedModels` block, inline-defaulted per the documented codexExecJson/swapAttemptTimeoutMs precedent), `src/core/DispatchExecutor.ts` (optional `agenticModel` ctor option, default 'haiku'), `src/commands/server.ts` (threads `pinnedModels.dispatchAgentic` + `pinnedModels.anthropicCredentialProbe` into the two construction sites), `src/commands/setup-wizard/model-constants.ts` (env-overridable resolvers `INSTAR_WIZARD_CODEX_MODEL` / `INSTAR_WIZARD_GEMINI_MODEL` — env not config because the wizard runs before `.instar/config.json` exists), `src/commands/setup.ts` (duplicate const replaced with import/re-export from model-constants — single source of truth), `src/providers/adapters/anthropic-headless/config.ts` + `control/authCredentialInjection.ts` (new `credentialProbeModel` field; default now sourced from `ANTHROPIC_MODELS.haiku` in `src/core/models.ts` instead of a free-floating string literal), and `tests/unit/pinned-model-callsites.test.ts` (15 new tests).
+
+**Honest scope note:** risk item #4 (mentor loop → opus) required NO code change — it was already config-driven via `mentor.autonomousFix.model` (default 'opus'); the registry row was imprecise. A canary test now pins that fact.
+
+## Decision-point inventory
+
+No decision point is added, modified, or removed. Model *selection inputs* to five existing callsites become configurable; the callsites' logic, gating, and control flow are untouched. All five are pass-through surfaces:
+
+- `DispatchExecutor.runAgentic` — pass-through — spawned-session model tier now `options.agenticModel ?? 'haiku'`.
+- `setup-wizard codex narrative spawn` — pass-through — model const now env-resolvable, default unchanged.
+- `setup-wizard gemini narrative spawn` — pass-through — same.
+- `anthropic-headless credential probe` — pass-through — ping model now `config.credentialProbeModel ?? ANTHROPIC_MODELS.haiku`.
+- `server.ts boot wiring` — pass-through — threads the two config keys when present; spreads nothing when absent.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. (No input is ever rejected by this change; a nonsense model value in config flows to the underlying spawn/API call, which fails with that layer's existing error surface — same as a nonsense value in any other model config key like `subscriptionPath.model`.)
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. One adjacent honest note: this change does NOT validate configured model ids against a known-models list. That is deliberate and consistent with every existing model config key (`sessions.frameworkDefaultModels`, `subscriptionPath.model`, `mentor.autonomousFix.model` — none validate); inventing validation only here would be a new inconsistent behavior surface.
+
+## 3. Level-of-abstraction fit
+
+Right layer. The change follows the established three-layer pattern already used by every other model-selection surface: config type (`types.ts`) → boot threading (`server.ts`) → inline default at the consumption site. The wizard deviation (env var instead of config key) is a deliberate fit-to-layer choice: the wizard runs pre-config by definition, so a config key would be unreadable at its runtime — an env var is the only honest override surface there, and the config docblock documents the split. The credential-probe default moving to `ANTHROPIC_MODELS.haiku` removes a string literal that could silently drift from the tier map (registry risk item #8's concern).
+
+## 4. Signal vs authority compliance
+
+Compliant — trivially. No signal is produced, no authority is held, no brittle check is added anywhere. (Reference: docs/signal-vs-authority.md.)
+
+## 5. Interactions
+
+- **Tier maps / escalation:** `dispatchAgentic` feeds `SessionManager.spawnSession({model})` exactly as the literal did; tier escalation and topic-profile resolution operate on spawned *conversation* sessions, not this job-slugged dispatch session — no new interaction.
+- **componentFrameworks routing:** untouched — these callsites were router-bypasses before and remain framework-pinned; only the *model value* became configurable. (Making them router-routed was considered and rejected for this change: dispatch/wizard/probe are structurally tied to their frameworks. The v2 bench routing pass may revisit.)
+- **Canary tests:** `setup-codex-model-canary.test.ts` still passes unmodified — the const-shape contract (`-m WIZARD_CODEX_MODEL` on every codex spawn; pinned to a subscription-supported model) is preserved by computing the const through the resolver at module load.
+- **No double-fire / shadow / race surface:** nothing fires.
+
+## 6. External surfaces
+
+None. No user-visible output changes, no API shape changes, no cross-agent surface. The probe ping still sends 4 max_tokens to the same endpoint with the same default model id.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** `intelligence.pinnedModels` lives in `.instar/config.json`, which deliberately does not sync across machines (same posture as every other `intelligence.*` key — each machine's operator tunes its own routing). The wizard env vars are process-local by nature. No durable state, no user-facing notices, no generated URLs.
+
+## 8. Rollback cost
+
+Trivial. Remove the config key / env var → shipped defaults apply immediately (next boot for config, next wizard run for env). Reverting the commit restores literals with zero data migration — no persisted state depends on the new keys (inline-defaulted precisely so absence is the default state; nothing was added to ConfigDefaults/migrateConfig, so no migration parity work is owed).
+
+## Test evidence
+
+`tests/unit/pinned-model-callsites.test.ts` — 15 tests: both sides of every boundary (absent ⇒ shipped default, present ⇒ override wins, whitespace ⇒ absent) for all three migrated surfaces, wiring canaries asserting server.ts actually threads both config keys, and the mentor already-config-driven canary. Plus `setup-codex-model-canary.test.ts` (5 tests) unmodified and green. `npx tsc --noEmit` clean.

package/upgrades/side-effects/llm-routing-register-uncategorized-components.md

@@ -0,0 +1,100 @@
+# Side-Effects Review — Register 13 uncategorized LLM components
+
+**Version / slug:** `llm-routing-register-uncategorized-components`
+**Date:** `2026-07-01`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds 13 previously-unregistered LLM call-site component names to `COMPONENT_CATEGORY`
+in `src/core/componentCategories.ts`, each tagged `sentinel` / `gate` / `reflector`
+by function, so the framework router resolves them to a real category instead of
+`other` (which falls back to the agent default framework, Claude). Correspondingly
+removes those 13 names from the `WIRING_EXCLUSIONS` pinned backlog in
+`tests/unit/llm-attribution-ratchet.test.ts`, leaving only the 5 components that
+route via an explicit `attribution.category` (so they correctly stay map-unregistered).
+Files touched: `src/core/componentCategories.ts`, `tests/unit/llm-attribution-ratchet.test.ts`.
+The change interacts with one decision point — the router's category resolution
+(`categoryForComponent`) — but only feeds it more data; it adds no branching logic.
+
+## Decision-point inventory
+
+- `categoryForComponent` (src/core/componentCategories.ts) — **pass-through** — unchanged
+  function; this change only adds rows to the map it reads. No control-flow edit.
+- `IntelligenceRouter.resolveFramework` (per-component framework routing) — **pass-through** —
+  consumes the category; unchanged. The 13 components now resolve to their category's
+  configured framework instead of the default, which is the intended effect.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. This is a routing-map data change,
+not a gate. It changes WHICH provider runs a call, never WHETHER the call is allowed.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable. The change cannot make any gate
+more permissive; gate *authority* is untouched. (The one `gate`-category addition,
+ResumeValidator, keeps its existing behavior; only its provider changes.)
+
+---
+
+## 3. Wrong-provider / routing correctness
+
+**Could a component now route to a provider that can't serve it correctly?**
+
+Low risk. All 13 join categories (`sentinel`/`gate`/`reflector`) that the
+Provider-Fallback Default Policy already routes off-Claude for dozens of live
+components — the target providers (codex-cli → pi-cli → gemini-cli, Claude last)
+are production-exercised. A rate-limited or missing framework degrades via the
+existing per-framework circuit breaker + fallback chain (unchanged). No component
+routes to a provider class not already in use for its category.
+
+The one behavioral nuance: components that make *nuanced/critical* judgments
+(e.g. LLMConflictResolver resolving divergent multi-machine state) now run on a
+non-Claude reasoning-capable model (gpt-5.5 via codex) rather than Claude. This is
+aligned with the operator directive to prefer subsidized non-Claude subscriptions,
+and gpt-5.5 is reasoning-capable. A later nature-based routing pass (operator-reviewed)
+will refine per-task model tiers; this change does not lock that in.
+
+---
+
+## 4. Reversibility / rollback
+
+Fully reversible: remove the 13 rows from `COMPONENT_CATEGORY` (and restore them to
+`WIRING_EXCLUSIONS`) and routing returns to the prior state. No migration, no state
+schema change, no persisted data. An operator can also override any single component
+per-agent via `sessions.componentFrameworks.overrides` without touching this map.
+
+---
+
+## 5. Blast radius
+
+Fleet-wide once shipped (it's a core map), but strictly additive and category-consistent.
+No new code paths execute; the router simply finds a category where it previously found
+none. Existing tests cover it: the wiring ratchet (`llm-attribution-ratchet.test.ts`)
+proves every live `.evaluate()` component now resolves, `intelligence-router.test.ts` and
+the integration/e2e routing suites remain green. Signal-vs-authority: N/A — no detector
+and no authority is added or modified; this is a data-map completion.
+
+---
+
+## 6. Test coverage
+
+- `tests/unit/llm-attribution-ratchet.test.ts` — the drift guard; asserts every literal
+  `attribution.component` in `src/` resolves to a registered category or a pinned
+  (explicit-category) exception, AND that every pinned exception still resolves to `other`.
+  Both sides green after the change.
+- `tests/unit/intelligence-router.test.ts`, `tests/unit/standards-coverage-component-category.test.ts`,
+  `tests/integration/intelligence-routing-routes.test.ts`,
+  `tests/integration/provider-fallback-default-routing.test.ts` — all green.
+- No NEW test added: the existing ratchet already IS the structural guard for this
+  invariant (adding a duplicate would be noise).