instar 1.3.251 → 1.3.253

package/dist/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.d.ts

@@ -44,11 +44,21 @@ export interface GeminiCapacityGate {
 export declare function isGeminiCapacityError(message: string | null | undefined): boolean;
 export declare function parseGeminiRetryAfterMs(message: string | null | undefined): number | undefined;
 export declare function resolveKnownGeminiFallback(requestedModel: string, config: GeminiCapacityPolicyConfig | undefined): string;
+/**
+ * Pick a known Gemini model to switch to when `exhaustedModel` hit its capacity
+ * limit. A candidate qualifies when it is (a) a known Gemini model, (b) not the
+ * just-exhausted model, and (c) not itself inside a recorded exhaustion window
+ * at `now`. Prefers an operator-configured fallback when it qualifies, otherwise
+ * the first known model with headroom. Returns undefined when every known model
+ * is exhausted — the genuine account-wide block case.
+ */
+export declare function pickGeminiFallbackModel(exhaustedModel: string, config: GeminiCapacityPolicyConfig | undefined, now: number): string | undefined;
 export declare function decideGeminiCapacityPolicy(params: {
     errorMessage: string;
     attempt: number;
     model: string;
     config?: GeminiCapacityPolicyConfig;
+    now?: number;
 }): GeminiCapacityDecision;
 export declare function getGeminiCapacityGate(now?: number): GeminiCapacityGate;
 export declare function recordGeminiCapacityDeferral(params: {

package/dist/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geminiCapacityPolicy.d.ts","sourceRoot":"","sources":["../../../../../src/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAWD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAajF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAoB9F;AAOD,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,0BAA0B,GAAG,SAAS,GAC7C,MAAM,CAIR;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,0BAA0B,CAAC;CACrC,GAAG,sBAAsB,CA8BzB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,SAAa,GAAG,kBAAkB,CAU1E;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,kBAAkB,CAsBrB;AAoCD,wBAAgB,iCAAiC,IAAI,IAAI,CAGxD"}
+{"version":3,"file":"geminiCapacityPolicy.d.ts","sourceRoot":"","sources":["../../../../../src/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAsBD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAajF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAoB9F;AAOD,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,0BAA0B,GAAG,SAAS,GAC7C,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,0BAA0B,GAAG,SAAS,EAC9C,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAWpB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,sBAAsB,CAgDzB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,SAAa,GAAG,kBAAkB,CAU1E;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,kBAAkB,CAsBrB;AA0CD,wBAAgB,iCAAiC,IAAI,IAAI,CAIxD"}

package/dist/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.js

@@ -11,17 +11,27 @@
  * - later calls are refused locally while deferred, avoiding doomed subprocesses;
  * - fallback models must be in the verified Gemini model set.
  */
-import { GEMINI_DEFAULT_MODEL, isKnownGeminiModel } from '../models.js';
+import { GEMINI_DEFAULT_MODEL, isKnownGeminiModel, KNOWN_GEMINI_MODELS } from '../models.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { SafeFsExecutor } from '../../../../core/SafeFsExecutor.js';
 const DEFAULT_IMMEDIATE_RETRIES = 1;
 const DEFAULT_IMMEDIATE_RETRY_MAX_MS = 30_000;
 const DEFAULT_BACKOFF_MS = 5_000;
+// Switching to a DIFFERENT model (separate quota) needs no real backoff — the
+// wait the exhausted model wanted does not apply to the fresh one. Use a tiny
+// delay only to avoid a tight loop in pathological cases.
+const DEFAULT_MODEL_SWITCH_BACKOFF_MS = 250;
 const DEFAULT_UNKNOWN_RESET_MS = 15 * 60_000;
 const RESET_GRACE_MS = 5_000;
 let deferredUntil = 0;
 let deferredReason = null;
+// Per-model exhaustion windows (model id → epoch ms its quota is expected to
+// reset). The known Gemini models draw on SEPARATE quotas, so a single model
+// exhausting is NOT an account-wide block: we record the exhausted model here
+// and switch to a model with headroom before globally deferring. Time-based, so
+// entries self-clear once a model's reported reset window has passed.
+const modelExhaustedUntil = new Map();
 export function isGeminiCapacityError(message) {
     if (!message)
         return false;
@@ -64,6 +74,27 @@ export function resolveKnownGeminiFallback(requestedModel, config) {
         return requestedModel;
     return fallback;
 }
+/**
+ * Pick a known Gemini model to switch to when `exhaustedModel` hit its capacity
+ * limit. A candidate qualifies when it is (a) a known Gemini model, (b) not the
+ * just-exhausted model, and (c) not itself inside a recorded exhaustion window
+ * at `now`. Prefers an operator-configured fallback when it qualifies, otherwise
+ * the first known model with headroom. Returns undefined when every known model
+ * is exhausted — the genuine account-wide block case.
+ */
+export function pickGeminiFallbackModel(exhaustedModel, config, now) {
+    const hasHeadroom = (m) => !!m &&
+        isKnownGeminiModel(m) &&
+        m !== exhaustedModel &&
+        (modelExhaustedUntil.get(m) ?? 0) <= now;
+    if (hasHeadroom(config?.fallbackModel))
+        return config?.fallbackModel;
+    for (const m of KNOWN_GEMINI_MODELS) {
+        if (hasHeadroom(m))
+            return m;
+    }
+    return undefined;
+}
 export function decideGeminiCapacityPolicy(params) {
     const { errorMessage, attempt, model, config } = params;
     if (config?.enabled === false || !isGeminiCapacityError(errorMessage)) {
@@ -83,11 +114,29 @@ export function decideGeminiCapacityPolicy(params) {
         };
     }
     const deferMs = retryAfterMs ?? DEFAULT_UNKNOWN_RESET_MS;
+    const now = params.now ?? Date.now();
+    // Per-model exhaustion is NOT an account-wide block — the known Gemini models
+    // (flash, pro) draw on SEPARATE quotas. Record this model's window, then switch
+    // to a model with headroom before globally deferring. The switch also means we
+    // do NOT write the global stop-state for a single-model exhaustion (the caller
+    // only records a deferral on action:'defer'), which is what made instar report
+    // a fully-available account as "blocked". Mirrors the codex auto-swap policy.
+    modelExhaustedUntil.set(model, now + deferMs);
+    const fallback = pickGeminiFallbackModel(model, config, now);
+    if (fallback) {
+        return {
+            action: 'retry',
+            retryAfterMs: DEFAULT_MODEL_SWITCH_BACKOFF_MS,
+            model: fallback,
+            reason: `gemini model ${model} exhausted; switching to ${fallback} (separate quota may have headroom)`,
+        };
+    }
+    // Every known model is exhausted — a genuine account-wide block.
     return {
         action: 'defer',
         retryAfterMs: deferMs,
         model,
-        reason: `gemini capacity exhausted; deferring calls for ${deferMs}ms`,
+        reason: `gemini capacity exhausted on all known models; deferring calls for ${deferMs}ms`,
     };
 }
 export function getGeminiCapacityGate(now = Date.now()) {
@@ -126,6 +175,12 @@ function writeGeminiQuotaState(params) {
         usagePercent: 0,
         fiveHourPercent: 100,
         source: 'gemini-cli-capacity',
+        // 'account': this stop-state is only written once EVERY known model is
+        // exhausted (the genuine account-wide block). A single model exhausting no
+        // longer reaches here — the policy switches to a model with headroom first —
+        // so a reader can trust `recommendation:'stop'` here means the agent really
+        // is out of capacity, not just one model.
+        scope: 'account',
         model: params.model,
         blockedUntil: new Date(params.blockedUntil).toISOString(),
         blockReason: params.reason,
@@ -152,5 +207,6 @@ function writeGeminiQuotaState(params) {
 export function resetGeminiCapacityPolicyForTests() {
     deferredUntil = 0;
     deferredReason = null;
+    modelExhaustedUntil.clear();
 }
 //# sourceMappingURL=geminiCapacityPolicy.js.map

package/dist/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"geminiCapacityPolicy.js","sourceRoot":"","sources":["../../../../../src/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"geminiCapacityPolicy.js","sourceRoot":"","sources":["../../../../../src/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.251",
+  "version": "1.3.253",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/assemble-next-md.mjs

@@ -83,6 +83,22 @@ export function parseBumpType(content) {
   return match ? match[1].toLowerCase() : null;
 }
 
+/**
+ * Does this fragment opt into the internal-only ship lane via an
+ * `<!-- internal-only -->` marker? Such a fragment has no user-facing surface,
+ * so it may omit the "What to Tell Your User" / "Summary of New Capabilities"
+ * sections — the assembler auto-fills them ONLY when EVERY contributing fragment
+ * is internal-only (see assembleNextMd). The pre-push gate independently verifies
+ * the marker against the staged diff (an internal-only fragment whose PR touches
+ * runtime `src/` is rejected), so the marker cannot be misused.
+ */
+export function hasInternalOnlyMarker(content) {
+  return /<!--\s*internal-only\s*-->/i.test(String(content));
+}
+
+/** Canonical text auto-filled into the user-facing sections of an all-internal release. */
+export const INTERNAL_ONLY_FILL = 'None — internal change (no user-facing surface).';
+
 /**
  * Split a fragment body into H2 sections: [{ title, body }] in source order.
  * `body` excludes the heading line itself and is right-trimmed.
@@ -140,9 +156,15 @@ export function assembleNextMd(fragments) {
   const extraOrder = [];
   let maxBumpRank = 0;
   let sawAnyBump = false;
+  // The internal-only lane auto-fills the user-facing sections ONLY when every
+  // contributing fragment opts in. Starts true for a non-empty input set and is
+  // cleared by the first fragment WITHOUT an <!-- internal-only --> marker, so a
+  // single user-facing fragment keeps the full user-section requirement.
+  let allInternal = effective.length > 0;
 
   for (const frag of effective) {
     const content = frag.content ?? '';
+    if (!hasInternalOnlyMarker(content)) allInternal = false;
     const bump = parseBumpType(content);
     if (bump) {
       sawAnyBump = true;
@@ -183,6 +205,20 @@ export function assembleNextMd(fragments) {
     );
   }
 
+  // Internal-only lane: when EVERY contributing fragment is marked
+  // <!-- internal-only -->, the change has no user-facing surface, so the two
+  // user-facing sections are auto-filled rather than hand-written. This keeps the
+  // shared validator (pre-push AND publish) satisfied without forcing
+  // "None — internal" boilerplate by hand. We auto-fill ONLY missing sections, so
+  // an internal fragment that DOES say something user-facing is preserved as-is;
+  // and because `allInternal` is false whenever any fragment lacks the marker, a
+  // genuinely user-facing change that omits these sections still fails validation.
+  if (allInternal) {
+    for (const title of ['What to Tell Your User', 'Summary of New Capabilities']) {
+      if (!merged.has(title)) merged.set(title, [INTERNAL_ONLY_FILL]);
+    }
+  }
+
   // Emit canonical sections first (only when present), then extras in
   // first-seen order.
   const titleOrder = [

package/scripts/pre-push-gate.js

@@ -14,7 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validateGuideContent } from './upgrade-guide-validator.mjs';
-import { assembleNextMd, gatherFragmentInputs } from './assemble-next-md.mjs';
+import { assembleNextMd, gatherFragmentInputs, hasInternalOnlyMarker } from './assemble-next-md.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -186,6 +186,29 @@ try {
     );
   }
 
+  // ── 3c. Internal-only lane verification (objective gate) ──────────────
+  // A release fragment marked <!-- internal-only --> may omit the user-facing
+  // sections — the assembler auto-fills "None — internal" for an all-internal
+  // release. That is ONLY valid for changes with no shipped runtime surface.
+  // Verify against the diff: if any staged internal-only fragment accompanies a
+  // runtime src/ change, REJECT — a user-facing change must not skip
+  // "What to Tell Your User" / "Summary of New Capabilities". This is the
+  // objective gate that keeps the marker from being misused (the agent sets it,
+  // the diff verifies it). tests/docs/scripts-only changes are fine.
+  const internalOnlyFragments = fragmentChanges.filter(f => {
+    try { return hasInternalOnlyMarker(fs.readFileSync(path.join(ROOT, f), 'utf-8')); }
+    catch { return false; }
+  });
+  if (internalOnlyFragments.length > 0 && srcChanges.length > 0) {
+    errors.push(
+      `Internal-only release fragment(s) accompany ${srcChanges.length} runtime src/ change(s):\n` +
+      internalOnlyFragments.slice(0, 5).map(f => `      • ${f} (marked <!-- internal-only -->)`).join('\n') + '\n' +
+      `      The internal-only lane (which auto-fills the user-facing release sections) is ONLY for changes ` +
+      `with no shipped runtime surface (tests / docs / scripts). Either remove the marker and write the ` +
+      `"What to Tell Your User" + "Summary of New Capabilities" sections, or split the src/ change into its own PR.`
+    );
+  }
+
   // ── 4. Adapter contract test gate ─────────────────────────────────────
   // If messaging adapter source files changed, require contract test evidence.
   // This prevents shipping integration code verified only by mocked unit tests.

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-04T22:14:41.846Z",
-  "instarVersion": "1.3.251",
+  "generatedAt": "2026-06-04T23:12:21.750Z",
+  "instarVersion": "1.3.253",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.252.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When a Gemini call hit a per-model capacity limit (e.g. "You have exhausted your
+capacity on this model. Quota resets after 46m"), instar's Gemini capacity policy
+globally deferred on that model and wrote a `quota-state.json` snapshot with
+`recommendation: 'stop'` / `fiveHourPercent: 100`. But the known Gemini models
+(`gemini-2.5-flash`, `gemini-2.5-pro`) draw on SEPARATE quotas, so one model
+exhausting was mis-recorded as a full account-wide block — and every reader of that
+file (the agent, the mentor, the escalation monitor) concluded the whole Gemini
+agent was down, even when the account had headroom on the other model. This produced
+repeated false "agent is blocked" reports.
+
+The policy now switches to a known model with headroom and retries before deferring
+(mirroring the codex auto-swap-on-limit policy). Only when EVERY known model is
+exhausted does it globally defer and write the stop-state — now tagged
+`scope: 'account'`. The per-model exhaustion windows are tracked time-based and
+self-clear, so there is no switch loop and no stale state. The model switch uses a
+short 250ms backoff (a different model needs no wait).
+
+## What to Tell Your User
+
+If you run a Gemini-backed agent: when one Gemini model hits its limit, the agent now
+quietly switches to the other model and keeps working, instead of going dark for the
+length of that model's reset window. It only reports itself as out of capacity when
+every model is genuinely exhausted. Nothing to do — it just stops the false "blocked"
+reports and keeps the agent productive.
+
+## Summary of New Capabilities
+
+Gemini agents auto-fall-back across models on a per-model capacity limit (parity with
+the codex auto-swap), and the durable quota-state now distinguishes a single-model
+deferral from a genuine account-wide block (`scope: 'account'`).
+
+## Evidence
+
+- **Reproduction (live this session):** a Gemini agent's `gemini -p` probe returned
+  "You have exhausted your capacity on this model. Your quota will reset after 46m11s"
+  while the account `/stats` showed 20% remaining on the Auto model — i.e. one model
+  exhausted, account fine. The old policy wrote `recommendation: 'stop'` for this,
+  which read as a full block.
+- **Before:** single-model exhaustion → global defer + `recommendation:'stop'` /
+  `fiveHourPercent:100`; the agent appeared fully blocked for the whole reset window.
+- **After:** single-model exhaustion → switch to the model with headroom and keep
+  working; global stop-state (now `scope:'account'`) is written ONLY when every known
+  model is exhausted.
+- **Tests:** 21 across three tiers — `tests/unit/geminiCapacityPolicy.test.ts`
+  (switch-then-defer, single-model-no-global-stop, `pickGeminiFallbackModel`,
+  self-clearing windows), `tests/integration/gemini-capacity-policy-integration.test.ts`,
+  and `tests/e2e/gemini-capacity-policy-lifecycle.test.ts` (both updated to assert the
+  two-model attempt + account scope), plus the escalation-monitor suite. `tsc --noEmit`
+  clean.

package/upgrades/1.3.253.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added an internal-only release-note lane to the instar-dev ship gate. A release-note
+fragment that has no user-facing surface (test-only, docs-only, or build/CI scripts
+with no `src/` runtime change) can now carry an `<!-- internal-only -->` marker and
+OMIT the two user-facing sections ("What to Tell Your User", "Summary of New
+Capabilities"). The shared assembler (`scripts/assemble-next-md.mjs`) auto-fills those
+sections with "None — internal change (no user-facing surface)." — but ONLY when every
+fragment in the release is internal-only, so a real user-facing change can never skip
+telling the user.
+
+The marker is verified objectively: `scripts/pre-push-gate.js` rejects an
+`<!-- internal-only -->` fragment whose diff touches a runtime `src/` file. The
+side-effects review and decision-trace are unchanged — only the user-facing release
+boilerplate is lifted, and only for changes that provably have no user-facing surface.
+
+This very fragment uses the new lane (this PR is scripts + tests only), dogfooding it.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- 45 tests green across `tests/unit/assemble-next-md.test.ts` (auto-fill on all-internal,
+  validator passes the auto-filled guide, real content preserved when any fragment is
+  user-facing, marker detection, self-... ) and `tests/unit/pre-push-gate.test.ts` (the
+  objective §3c marker-vs-diff gate). `node --check scripts/pre-push-gate.js` clean.
+- The auto-fill lives in the assembler shared by BOTH the pre-push gate and the publish
+  gate (`check-upgrade-guide.js`), so the two can never disagree about a release note.

package/upgrades/side-effects/gemini-model-fallback-on-exhaustion.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Gemini per-model exhaustion switches model before deferring
+
+**Version / slug:** `gemini-model-fallback-on-exhaustion`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `required (LLM-routing behavior change)`
+
+## Summary of the change
+
+When a Gemini call hit a capacity limit, `decideGeminiCapacityPolicy` (after its
+short-window immediate-retry path) went straight to a GLOBAL `defer` on the SAME
+model, and `recordGeminiCapacityDeferral` wrote a `quota-state.json` snapshot with
+`fiveHourPercent: 100` / `recommendation: 'stop'`. But the known Gemini models —
+`gemini-2.5-flash` and `gemini-2.5-pro` — draw on **separate** quotas. So one model
+exhausting (e.g. "You have exhausted your capacity on this model. Quota resets after
+46m") was recorded as a full account-wide block, and any reader of `quota-state.json`
+(including the agent itself, the mentor, the escalation monitor) saw `recommendation:
+'stop'` and concluded the whole Gemini agent was down — even when the account had
+headroom on the other model. This caused repeated false "Gemi is blocked" reports
+(confirmed live this session: a `gemini -p` probe returned that exact error while
+`/stats` showed the account at 20% remaining on Auto).
+
+The fix (mirrors the existing codex auto-swap-on-limit policy, #31): on per-model
+exhaustion, record the exhausted model's reset window, then switch to a known model
+with headroom and retry. Only when **every** known model is exhausted do we globally
+defer and write the stop-state — now tagged `scope: 'account'`. Because the caller
+records a deferral only on `action: 'defer'`, switching models also means a single-
+model exhaustion no longer writes a global stop at all.
+
+## Decision-point inventory
+
+1. **`decideGeminiCapacityPolicy` (long-reset branch):** record `model` as exhausted
+   (time-based, `now + deferMs`); pick a fallback via `pickGeminiFallbackModel`; if
+   one exists → `retry` with that model; else → `defer`.
+2. **`pickGeminiFallbackModel`:** a candidate qualifies when known, ≠ the exhausted
+   model, and not itself inside a recorded exhaustion window at `now`. Prefers an
+   operator-configured `fallbackModel`, else the first known model with headroom.
+
+## 1. Over-block (what still defers / blocks)
+
+- When ALL known models are in an exhaustion window → `defer` + the global stop-state
+  (now `scope: 'account'`). That is the genuine account-wide block and still gates
+  scheduler spawns exactly as before. (tests: "defers once ALL models exhausted",
+  integration "defers after a long quota reset", e2e lifecycle.)
+- The short-window immediate-retry path (attempt < maxImmediateRetries, small reset)
+  is unchanged.
+- Non-capacity errors are unchanged — `decide` returns `none` and the error surfaces.
+
+## 2. Under-block (what it now allows that it didn't)
+
+- A single model exhausting now triggers ONE extra Gemini spawn on the other model
+  (the switch) before any deferral. Worst-case cost when BOTH models are exhausted:
+  two spawns instead of one (flash then pro) before the global defer — bounded at 2
+  (one per known model; each is recorded exhausted so it is never retried within its
+  window). The model-switch retry uses a 250ms backoff (not the 5s same-model
+  backoff) since a different model needs no wait.
+- Loop-safety: `modelExhaustedUntil` is time-based and self-clears once a window
+  passes, so there is no permanent state and no A→B→A switch loop (each model is
+  recorded before fallback selection; once both are recorded, `pickGeminiFallbackModel`
+  returns undefined → defer). (tests: "returns undefined once both exhausted",
+  "windows self-clear once the reset passes".)
+
+## 3. Blast radius
+
+- One file of logic: `src/providers/adapters/gemini-cli/observability/geminiCapacityPolicy.ts`
+  (new module state `modelExhaustedUntil`, new export `pickGeminiFallbackModel`, a
+  `now?` param on `decide`, the switch-before-defer branch, `scope` on the stop-state,
+  reset clears the map).
+- NO consumer signature changes: both callers (`transport/oneShotCompletion.ts`,
+  `core/GeminiCliIntelligenceProvider.ts`) already switch to `decision.model` on
+  `action:'retry'` and record a deferral only on `action:'defer'`.
+- Affects only Gemini-CLI agents. Claude / codex paths untouched. The added
+  `scope` field is additive (readers that don't know it are unaffected).
+
+## 4. Reversibility
+
+Fully reversible: revert the one policy file + the test updates. Module state is
+in-process and time-based (no persistence); the `quota-state.json` shape only gains
+an additive `scope` field. Verified: `tsc --noEmit` clean; 21 tests green across
+unit + integration + e2e + escalation tiers (both the switch path and the genuine
+all-models-defer path).

package/upgrades/side-effects/internal-only-ship-lane.md

@@ -0,0 +1,77 @@
+# Side-Effects Review — internal-only release-note lane (mechanism)
+
+**Version / slug:** `internal-only-ship-lane`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `required (release-critical CI machinery)`
+
+## Summary of the change
+
+Every release-note fragment currently must carry all four sections — including the
+two user-facing ones (**What to Tell Your User**, **Summary of New Capabilities**).
+For a change with NO user-facing surface (test-only, docs-only, build/CI scripts with
+no `src/` runtime change) that copy is pure boilerplate ("None — internal"), which is
+disproportionate ceremony (the codex-#25 friction; the #758 telegraph test-flake fix
+had to hand-write two "None — internal" sections).
+
+This adds an **internal-only lane** (operator-approved). A fragment opts in with an
+`<!-- internal-only -->` marker and may OMIT the two user-facing sections. The
+assembler auto-fills them with a canonical "None — internal change…" ONLY when
+*every* contributing fragment is internal-only. The objective gate: the pre-push gate
+verifies the marker against the diff — an internal-only fragment whose change touches
+runtime `src/` is REJECTED. Side-effects review + decision-trace are unchanged — safety
+and auditability never get a lighter lane.
+
+This PR is the **mechanism** (assembler + pre-push verification + tests). The
+deployed-skill documentation (`skills/instar-dev/SKILL.md` + a PostUpdateMigrator
+migration to redeploy it) is a tracked follow-up.
+
+## Decision-point inventory
+
+1. **assembler auto-fill** (`assembleNextMd`): when `allInternal` (every fragment
+   marked) and a user-facing canonical section is missing from the merged map, inject
+   `INTERNAL_ONLY_FILL`. Never auto-fills when any fragment is non-internal.
+2. **pre-push verification** (`pre-push-gate.js` §3c): an internal-only fragment +
+   any `src/*.ts` change in the diff → error.
+
+## 1. Over-block (what still fails / is required)
+
+- A genuinely user-facing change that OMITS the user sections still fails: it is not
+  `allInternal` (it has no marker, or the gate rejects the marker on a `src/` diff), so
+  the assembler does NOT auto-fill, and `validateGuideContent` reports the missing
+  sections. (test: "does NOT auto-fill when any fragment is user-facing".)
+- `What Changed` + `Evidence` are still required; the Evidence-bar (fix-claim →
+  Evidence) is untouched.
+- All existing fragment validations (inline-code / camelCase / fenced-block leakage,
+  malformed fragment, bump tier) are unchanged — 25 pre-existing assembler tests +
+  the full pre-push suite stay green.
+
+## 2. Under-block (what it now allows)
+
+- An all-internal release may omit the two user-facing sections; the assembler fills
+  them. This is gated objectively: the marker is verified against the diff at pre-push,
+  so it cannot be set on a runtime `src/` change to hide user-facing impact. The agent
+  sets the marker; the diff verifies it. (test: source-presence of the §3c gate +
+  `hasInternalOnlyMarker`.)
+- Worst case of a wrong marker on a non-src change (e.g. a scripts change that DOES have
+  user impact): the publish notes say "None — internal" for that release. Bounded and
+  low-harm — scripts/docs/test changes have no agent-user runtime surface by
+  construction.
+
+## 3. Blast radius
+
+- `scripts/assemble-next-md.mjs` — pure function; new `hasInternalOnlyMarker` +
+  `INTERNAL_ONLY_FILL` exports + the auto-fill branch.
+- `scripts/pre-push-gate.js` — one new §3c check (reuses existing `srcChanges` /
+  `fragmentChanges`).
+- Tests only otherwise. NO `src/` change, no runtime/agent surface. The assembler is
+  shared by BOTH the pre-push gate and the publish gate (`check-upgrade-guide.js`), so
+  the auto-fill keeps both consistent — the change was deliberately placed in the shared
+  assembler so the two gates can never disagree.
+
+## 4. Reversibility
+
+Fully reversible: revert the two scripts + test edits. No state, no persisted format
+(the `<!-- internal-only -->` marker is just a fragment comment — a fragment without it
+behaves exactly as before). Verified: 45 tests green (assemble-next-md + pre-push-gate
+suites), `node --check` clean on the gate.