instar 1.3.744 → 1.3.745

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.744",
+  "version": "1.3.745",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,9 +28,11 @@
     "test:contract": "node scripts/run-contract-tests.js",
     "test:contract:raw": "vitest run --config vitest.contract.config.ts",
     "test:all": "vitest run && vitest run --config vitest.integration.config.ts && vitest run --config vitest.e2e.config.ts",
-    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unbounded-llm-spawn.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-store-retention-declared.js && node scripts/lint-no-wholefile-sync-read.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-sync-subprocess-chokepoint.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js && node scripts/lint-routing-registry-freshness.js && node scripts/lint-no-opus-claude-cli-gating.js",
+    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unbounded-llm-spawn.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-store-retention-declared.js && node scripts/lint-no-wholefile-sync-read.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-sync-subprocess-chokepoint.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js && node scripts/lint-routing-registry-freshness.js && node scripts/lint-no-opus-claude-cli-gating.js && node scripts/lint-model-registry-freshness.mjs",
     "lint:routing-registry": "node scripts/lint-routing-registry-freshness.js",
     "lint:no-opus-claude-cli-gating": "node scripts/lint-no-opus-claude-cli-gating.js",
+    "lint:model-freshness": "node scripts/lint-model-registry-freshness.mjs",
+    "lint:model-freshness:strict": "INSTAR_MODEL_FRESHNESS_STRICT=1 node scripts/lint-model-registry-freshness.mjs",
     "lint:no-unbounded-llm-spawn": "node scripts/lint-no-unbounded-llm-spawn.js",
     "lint:no-unbounded-llm-spawn:staged": "node scripts/lint-no-unbounded-llm-spawn.js --staged",
     "lint:destructive": "node scripts/lint-no-direct-destructive.js",

package/scripts/lint-model-registry-freshness.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * lint-model-registry-freshness.mjs — the model-registry FRESHNESS ratchet.
+ *
+ * THE PROBLEM (2026-07-03, operator directive): Instar's per-provider "capable/
+ * latest/frontier" model pins rot SILENTLY. Nothing forces anyone to re-check
+ * that (e.g.) the gemini `capable` tier still points at a current model — so
+ * `gemini-2.5-pro` kept routing spec-review/converge work long after
+ * Gemini 3-class shipped. A stale pin is invisible until it degrades output.
+ *
+ * THE GUARD (model-id-AGNOSTIC by construction): a deterministic check with
+ * TWO teeth, both driven by scripts/model-registry-freshness.manifest.json —
+ * the single human-edit surface:
+ *
+ *   TOOTH 1 — STALENESS. `lastReviewedAt` must be within `stalenessWindowDays`
+ *     of today. An un-reviewed list ages out and fails LOUDLY, forcing a
+ *     periodic "is each pin still frontier?" review + a date bump. This is the
+ *     anti-rot mechanism: it fails even if no id ever changes.
+ *
+ *   TOOTH 2 — DRIFT. Every pinned capable/latest model id (extracted live from
+ *     the real source files via each pin's regex) must be a member of that
+ *     door's `frontierAllowlist` (the CURRENT_FRONTIER_MODELS set). A pin that
+ *     names a model not in the maintained allowlist fails — either the pin is
+ *     stale, or the allowlist wasn't updated. To go green a human must reconcile
+ *     the two, which IS the review.
+ *
+ * Plus: `flaggedStale[]` entries (known-stale-pending-operator-confirmation) are
+ * always printed as WARN lines and, under strict enforcement, count as findings.
+ *
+ * The guard NEVER hard-codes what the "right" model id is — it only asserts the
+ * pins and the allowlist agree and that the review is fresh. Swapping to a new
+ * frontier id is a manifest edit (allowlist + date), never a code change here.
+ *
+ * ENFORCEMENT (dark/reversible): manifest `enforcement` field —
+ *   "report" (default) — prints findings, ALWAYS exits 0 (non-gating). Safe to
+ *     wire into CI today while the current list is known-stale: it stays VISIBLE
+ *     in the lint log without breaking the build.
+ *   "strict" — exits 1 on any finding (staleness, drift, or a flaggedStale row).
+ *     Flip here once the flagged door swaps are operator-confirmed + applied.
+ *   Env INSTAR_MODEL_FRESHNESS_STRICT=1 forces strict for a one-off run.
+ *
+ * Exit codes:
+ *   0 — no findings, OR findings under "report" enforcement (non-gating).
+ *   1 — findings under "strict" enforcement, or a manifest/parse error.
+ *
+ * Usage:
+ *   node scripts/lint-model-registry-freshness.mjs            # honor manifest enforcement
+ *   INSTAR_MODEL_FRESHNESS_STRICT=1 node scripts/lint-model-registry-freshness.mjs
+ *
+ * Test overrides:
+ *   INSTAR_MODEL_FRESHNESS_MANIFEST=<path>   # point at a fixture manifest
+ *   INSTAR_MODEL_FRESHNESS_ROOT=<path>       # resolve pin files under this root
+ *   INSTAR_MODEL_FRESHNESS_NOW=<ISO date>    # inject the clock (staleness tests)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = process.env.INSTAR_MODEL_FRESHNESS_ROOT
+  ? path.resolve(process.env.INSTAR_MODEL_FRESHNESS_ROOT)
+  : path.resolve(__dirname, '..');
+const MANIFEST_PATH = process.env.INSTAR_MODEL_FRESHNESS_MANIFEST
+  ? path.resolve(process.env.INSTAR_MODEL_FRESHNESS_MANIFEST)
+  : path.join(__dirname, 'model-registry-freshness.manifest.json');
+
+/**
+ * Run the freshness check. Pure over its inputs (manifest + files under root +
+ * the injected clock), so the unit test drives it directly with fixtures.
+ * @returns {{ findings: string[], warnings: string[], info: string[], strict: boolean, error: string|null }}
+ */
+export function checkModelRegistryFreshness({
+  manifestPath = MANIFEST_PATH,
+  repoRoot = REPO_ROOT,
+  now = process.env.INSTAR_MODEL_FRESHNESS_NOW
+    ? new Date(process.env.INSTAR_MODEL_FRESHNESS_NOW)
+    : new Date(),
+  forceStrict = process.env.INSTAR_MODEL_FRESHNESS_STRICT === '1',
+} = {}) {
+  const findings = [];
+  const warnings = [];
+  const info = [];
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    return { findings: [], warnings: [], info: [], strict: true, error: `cannot read/parse manifest ${manifestPath}: ${e.message}` };
+  }
+
+  const strict = forceStrict || manifest.enforcement === 'strict';
+
+  // --- TOOTH 1: staleness ---
+  const reviewedRaw = manifest.lastReviewedAt;
+  const reviewed = reviewedRaw ? new Date(reviewedRaw) : null;
+  const windowDays = Number(manifest.stalenessWindowDays);
+  if (!reviewed || Number.isNaN(reviewed.getTime())) {
+    findings.push(`STALENESS: manifest.lastReviewedAt is missing or unparseable (got ${JSON.stringify(reviewedRaw)}).`);
+  } else if (!Number.isFinite(windowDays) || windowDays <= 0) {
+    findings.push(`STALENESS: manifest.stalenessWindowDays is missing or invalid (got ${JSON.stringify(manifest.stalenessWindowDays)}).`);
+  } else {
+    const ageDays = Math.floor((now.getTime() - reviewed.getTime()) / 86_400_000);
+    if (ageDays > windowDays) {
+      findings.push(
+        `STALENESS: model registry last reviewed ${reviewedRaw} (${ageDays}d ago) exceeds the ${windowDays}d window. ` +
+        `Re-review each capable/latest pin against current frontier, update frontierAllowlist if a model has moved, then bump lastReviewedAt.`
+      );
+    } else {
+      info.push(`Staleness OK: reviewed ${reviewedRaw} (${ageDays}d ago, window ${windowDays}d).`);
+    }
+  }
+
+  // --- TOOTH 2: drift (pin id must be in its door's frontier allowlist) ---
+  const allowlist = manifest.frontierAllowlist || {};
+  for (const pin of manifest.pins || []) {
+    const abs = path.join(repoRoot, pin.file);
+    let src;
+    try {
+      src = fs.readFileSync(abs, 'utf8');
+    } catch {
+      findings.push(`DRIFT: pin '${pin.id}' references ${pin.file} which is missing under ${repoRoot} (a pin site moved or was deleted — re-anchor it).`);
+      continue;
+    }
+    let re;
+    try {
+      re = new RegExp(pin.regex);
+    } catch (e) {
+      findings.push(`DRIFT: pin '${pin.id}' has an invalid regex (${e.message}).`);
+      continue;
+    }
+    const m = src.match(re);
+    if (!m) {
+      findings.push(`DRIFT: pin '${pin.id}' pattern did not match in ${pin.file} (the pinned site changed shape — re-anchor the regex).`);
+      continue;
+    }
+    // All capture groups are candidate model ids (e.g. default + escalated).
+    const ids = m.slice(1).filter(Boolean);
+    const doorAllow = allowlist[pin.door] || [];
+    for (const id of ids) {
+      if (!doorAllow.includes(id)) {
+        findings.push(
+          `DRIFT: pin '${pin.id}' (${pin.door}) pins '${id}' in ${pin.file}, which is NOT in frontierAllowlist['${pin.door}'] = [${doorAllow.join(', ')}]. ` +
+          `Either the pin is stale or the allowlist wasn't updated — reconcile the two (operator-confirm the frontier id).`
+        );
+      } else {
+        info.push(`Drift OK: ${pin.door} '${pin.id}' -> '${id}' (in allowlist).`);
+      }
+    }
+  }
+
+  // --- flaggedStale (known-stale-pending-confirmation): always WARN; strict counts them ---
+  for (const f of manifest.flaggedStale || []) {
+    const line =
+      `FLAGGED-STALE: ${f.door} pin '${f.pin}' currently '${f.currentId}' -> suspected frontier '${f.suspectedFrontier}'. ` +
+      `${f.evidence || ''} ${f.note || ''}`.trim();
+    warnings.push(line);
+    if (strict) findings.push(line);
+  }
+
+  return { findings, warnings, info, strict, error: null };
+}
+
+// --- CLI entry ---
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const res = checkModelRegistryFreshness();
+  const B = '\x1b[1m', R = '\x1b[0m', Y = '\x1b[33m', RED = '\x1b[31m', G = '\x1b[32m';
+  console.log(`${B}[lint-model-registry-freshness]${R} enforcement=${res.strict ? 'strict' : 'report'}`);
+
+  if (res.error) {
+    console.error(`${RED}ERROR:${R} ${res.error}`);
+    process.exit(1);
+  }
+  for (const i of res.info) console.log(`  ${G}ok${R}   ${i}`);
+  for (const w of res.warnings) console.log(`  ${Y}warn${R} ${w}`);
+  for (const f of res.findings) console.log(`  ${RED}FIND${R} ${f}`);
+
+  if (res.findings.length === 0) {
+    console.log(`${G}PASS${R} — model registry pins fresh and in-allowlist.`);
+    process.exit(0);
+  }
+  if (res.strict) {
+    console.error(`${RED}FAIL${R} — ${res.findings.length} finding(s) under strict enforcement.`);
+    process.exit(1);
+  }
+  console.log(
+    `${Y}REPORT-ONLY${R} — ${res.findings.length} finding(s) surfaced but NOT gating (manifest enforcement="report"). ` +
+    `Resolve them, then flip enforcement to "strict".`
+  );
+  process.exit(0);
+}

package/scripts/model-registry-freshness.manifest.json

@@ -0,0 +1,104 @@
+{
+  "$comment": "Frontier-model allowlist + staleness gate for Instar's per-provider 'capable/latest' model pins. This file is the SINGLE human-edit surface that keeps the model registry from silently rotting. See docs/LLM-ROUTING-REGISTRY.md and scripts/lint-model-registry-freshness.mjs. Two teeth: (1) STALENESS — lastReviewedAt must be within stalenessWindowDays; (2) DRIFT — every pinned capable model id must be a member of frontierAllowlist[door]. To pass the check a human must confirm each capable pin is genuinely current frontier AND bump lastReviewedAt. An un-reviewed list fails loudly.",
+  "lastReviewedAt": "2026-07-03",
+  "stalenessWindowDays": 45,
+  "enforcement": "report",
+  "$enforcementNote": "'report' = non-gating (prints findings, always exits 0) — the dark/reversible default while the current list is known-stale. Flip to 'strict' (exits 1 on any finding) ONLY after the flaggedStale door swaps below are operator-confirmed and applied. Env INSTAR_MODEL_FRESHNESS_STRICT=1 forces strict for a one-off run.",
+  "doors": {
+    "claude-code": {
+      "accessMethod": "Claude Code CLI (subscription/OAuth)",
+      "status": "alive",
+      "note": "Primary door. Tier aliases opus/sonnet/haiku auto-resolve to latest and do NOT rot; only concrete claude-*-N ids below are pinned."
+    },
+    "anthropic-headless": {
+      "accessMethod": "claude -p one-shot (Agent SDK credit pot)",
+      "status": "alive",
+      "note": "Background/internal calls. Billing shifts to interactive pool after 2026-06-15 per subscriptionPath."
+    },
+    "codex-cli": {
+      "accessMethod": "codex exec (ChatGPT account)",
+      "status": "referenced-not-installed",
+      "note": "codex CLI is NOT installed on this machine (which codex -> not found), yet componentFrameworks routes job/Usher/TopicIntentExtractor to it -> those fall back at runtime. Door-liveness gap flagged to operator."
+    },
+    "gemini-cli": {
+      "accessMethod": "gemini -m <model> (Homebrew formula, OAuth)",
+      "status": "alive-but-deprecated-formula",
+      "note": "Homebrew gemini-cli formula DEPRECATED (upstream-unsupported, disabled 2026-12-18). CLI v0.25.2 still runs. Default model still gemini-2.5-pro; CLI already knows gemini-3-pro-preview / gemini-3-flash-preview. Migrate off the deprecated formula (npm @google/gemini-cli, or an OpenRouter/pi door)."
+    },
+    "pi-cli": {
+      "accessMethod": "pi --model <provider>/<id> (multi-provider: openai-codex, openrouter, ...)",
+      "status": "alive",
+      "note": "Multi-provider consolidation door. Can reach OpenRouter (one door to many frontier models; vault key metered_openrouter_bench present). pi policy DENIES anthropic/claude via openrouter passthrough by default to protect subscription billing."
+    }
+  },
+  "frontierAllowlist": {
+    "$comment": "CURRENT_FRONTIER_MODELS — the set of model ids considered acceptable-current for each door. A pinned capable model NOT in its door's list fails the DRIFT tooth. Add a new frontier id here (operator-confirmed) at the same time you update the pin.",
+    "claude-code": [
+      "claude-opus-4-8",
+      "claude-fable-5"
+    ],
+    "anthropic-headless": [
+      "claude-opus-4-6",
+      "claude-sonnet-4-6",
+      "claude-haiku-4-5"
+    ],
+    "codex-cli": [
+      "gpt-5.5"
+    ],
+    "gemini-cli": [
+      "gemini-2.5-pro"
+    ]
+  },
+  "pins": [
+    {
+      "id": "gemini-capable-tier",
+      "door": "gemini-cli",
+      "tier": "capable",
+      "file": "src/providers/adapters/gemini-cli/models.ts",
+      "regex": "capable:\\s*'((?:claude|gpt|gemini)-[^']+)'",
+      "note": "TIER_TO_MODEL.capable in the gemini adapter."
+    },
+    {
+      "id": "codex-capable-tier",
+      "door": "codex-cli",
+      "tier": "capable",
+      "file": "src/providers/adapters/openai-codex/models.ts",
+      "regex": "capable:\\s*'((?:claude|gpt|gemini)-[^']+)'",
+      "note": "TIER_TO_MODEL.capable in the codex adapter."
+    },
+    {
+      "id": "anthropic-headless-capable-tier",
+      "door": "anthropic-headless",
+      "tier": "capable",
+      "file": "src/providers/adapters/anthropic-headless/models.ts",
+      "regex": "capable:\\s*'((?:claude|gpt|gemini)-[^']+)'",
+      "note": "TIER_TO_MODEL.capable in the anthropic-headless adapter."
+    },
+    {
+      "id": "claude-tier-escalation-default-escalated",
+      "door": "claude-code",
+      "tier": "capable",
+      "file": "src/core/ModelTierEscalation.ts",
+      "regex": "'claude-code':\\s*\\{\\s*default:\\s*'([^']+)',\\s*escalated:\\s*'([^']+)'",
+      "note": "DEFAULT_TIER_ESCALATION.frameworks['claude-code'] default + escalated ids."
+    }
+  ],
+  "flaggedStale": [
+    {
+      "door": "gemini-cli",
+      "pin": "gemini-capable-tier",
+      "currentId": "gemini-2.5-pro",
+      "suspectedFrontier": "gemini-3-pro-preview",
+      "evidence": "gemini CLI v0.25.2 accepts gemini-3-pro-preview / gemini-3-flash-preview (in gemini-cli-core known-models); operator referenced 'Gemini 3-class'. Homebrew formula also deprecated (disabled 2026-12-18).",
+      "note": "OPERATOR TO CONFIRM exact frontier id before the pin+allowlist are updated. Also present at src/core/frameworkSessionLaunch.ts, src/commands/route.ts (KNOWN_MODELS), src/server/routes.ts."
+    },
+    {
+      "door": "codex-cli",
+      "pin": "codex-capable-tier",
+      "currentId": "gpt-5.5",
+      "suspectedFrontier": "gpt-5.6 (Sol) — UNVERIFIED",
+      "evidence": "codex CLI NOT installed on this machine, so newer accepted ids could NOT be probed. Operator referenced 'GPT-5.6 Sol'.",
+      "note": "OPERATOR TO CONFIRM. Cannot verify from a live probe (codex door not installed)."
+    }
+  ]
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-04T00:06:57.116Z",
-  "instarVersion": "1.3.744",
+  "generatedAt": "2026-07-04T00:24:28.139Z",
+  "instarVersion": "1.3.745",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.745.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Repo-internal CI tooling only — a deterministic lint + manifest + unit test that
+flags when per-provider `capable/latest/frontier` model pins go stale. Ships in
+report mode (non-gating); changes no model id and no runtime path. No user-facing
+or agent-facing behavior change.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).

package/upgrades/side-effects/model-registry-freshness-guard.md

@@ -0,0 +1,53 @@
+# Side-effects — Model-registry freshness guard
+
+**Change:** add a deterministic, model-id-AGNOSTIC lint that flags when Instar's
+per-provider "capable/latest/frontier" model pins have gone stale, plus its
+manifest (the human-edit frontier allowlist + `lastReviewedAt`) and a unit test.
+Ships **non-gating** (`enforcement: "report"`), dark/reversible.
+
+## Files touched
+- `scripts/lint-model-registry-freshness.mjs` (new) — the checker. Two teeth:
+  staleness window + per-door allowlist-membership drift. Exports a pure
+  `checkModelRegistryFreshness()` for the test; CLI honors `enforcement`.
+- `scripts/model-registry-freshness.manifest.json` (new) — the single edit
+  surface: `frontierAllowlist`, `pins` (file+regex), `lastReviewedAt`,
+  `stalenessWindowDays`, `enforcement`, `doors` (door-status map), `flaggedStale`.
+- `tests/unit/model-registry-freshness.test.ts` (new) — 11 tests, both sides of
+  both teeth + gating + the shipped manifest's self-consistency.
+- `package.json` — appended the lint to the `lint` chain (runs in report mode,
+  exits 0, VISIBLE in CI logs) + `lint:model-freshness[:strict]` aliases.
+- `docs/LLM-ROUTING-REGISTRY.md` — a freshness-guard pointer note.
+
+## Blast radius
+- **CI:** the lint is added to `npm run lint`. In `report` mode it ALWAYS exits
+  0, so it cannot break the build while the current list is known-stale. It only
+  prints findings/warnings. Flipping `enforcement: "strict"` (a future,
+  operator-gated one-line manifest edit) is what makes it gate.
+- **Runtime:** NONE. This is build/CI tooling only — it never runs in the server,
+  never touches a session, never changes model routing. It reads source files
+  and a JSON manifest; it writes nothing.
+- **Model IDs:** UNCHANGED. This change deliberately does NOT swap any pinned
+  model id — those swaps wait on operator confirmation of exact frontier ids.
+  The manifest's allowlist is seeded with the CURRENTLY-pinned ids so drift is
+  green today; the known-stale pins are carried in `flaggedStale` as warnings.
+
+## Reversibility
+- Delete the two new scripts + test + revert the `package.json`/doc edits.
+- Or set `enforcement` stays `report` forever (inert-but-visible).
+- No migration, no config default, no state file, no template change.
+
+## Rollback lever
+- Remove `&& node scripts/lint-model-registry-freshness.mjs` from the `lint`
+  script, or set the manifest `enforcement` to any value other than `strict`.
+
+## Migration parity
+- N/A — this is repo-internal CI tooling, not an agent-installed file. No hook,
+  config default, CLAUDE.md template section, or built-in skill is changed, so
+  `PostUpdateMigrator` needs no entry.
+
+## Follow-ups (operator-gated, NOT in this change)
+1. Confirm exact frontier ids (`gemini-3-pro-preview`?, `gpt-5.6 Sol`?) and swap
+   the pins + update `frontierAllowlist` + bump `lastReviewedAt` in one change.
+2. Then flip `enforcement: "strict"` so the guard gates.
+3. Door-liveness gaps surfaced by the audit: codex CLI not installed but routed
+   to; Homebrew gemini-cli formula deprecated (disabled 2026-12-18).