instar 1.3.593 → 1.3.594

package/dist/core/selfQuotaState.d.ts

@@ -0,0 +1,48 @@
+/**
+ * selfQuotaState — compute a machine's placement-eligibility block for the capacity
+ * heartbeat (spec: docs/specs/placement-llm-circuit-aware-quota.md).
+ *
+ * `quotaState.blocked` is the signal `PlacementExecutor` reads to decide whether a machine
+ * may serve a new LLM session. It is a **placement-eligibility** signal — "this machine
+ * cannot serve LLM work right now" — NOT a pure account-quota readout. Until now its only
+ * cause was account-quota exhaustion; an OPEN llm-circuit (the machine's provider calls are
+ * actually failing, rate-limited) is a second, more direct cause and MUST also block. The
+ * live test caught the gap: a machine with an open circuit reported `blocked:false` and
+ * placement routed a session onto it that died on arrival (2026-06-16, the Mac Mini).
+ *
+ * Extracted as a pure function so the two-signal contract (account-quota OR circuit) is
+ * unit-testable and cannot silently regress to quota-only.
+ */
+export interface QuotaSnapshot {
+    blockedUntil?: string | null;
+    fiveHourPercent?: number | null;
+    blockReason?: string | null;
+}
+/**
+ * Type-level discriminator for the block CAUSE so consumers branch on a closed set, not a
+ * free string. `provider-block` / `five-hour-*` = account quota; `llm-circuit-open` =
+ * operational unavailability. Free-form legacy quota strings still flow through, typed as the
+ * open `string` arm (back-compat).
+ */
+export type SelfQuotaBlockReason = 'llm-circuit-open' | 'five-hour-exhausted' | 'provider-block' | (string & {});
+export interface SelfQuotaBlock {
+    blocked: boolean;
+    blockedUntil?: string;
+    reason?: SelfQuotaBlockReason;
+}
+/**
+ * Compute this machine's placement-eligibility block from BOTH the account-quota snapshot and
+ * the live llm-circuit availability.
+ *
+ * @param quota the account-quota snapshot (`quotaTracker.getState()`), or null/undefined when
+ *   there is no tracker.
+ * @param circuitAvailable `llmCircuitAvailable()` — `true` when the breaker is disabled OR
+ *   closed; `false` only when it is enabled AND open/half-open.
+ * @returns a block object, `{ blocked: false }`, or `undefined` (unknown ≠ blocked).
+ *
+ * Fail-open is preserved: an open circuit is the ONLY thing that newly blocks, and only on a
+ * *positively observed* unavailable circuit — missing information (no tracker + closed
+ * circuit) still returns `undefined`, which `PlacementExecutor` treats as not-blocked.
+ */
+export declare function computeSelfQuotaState(quota: QuotaSnapshot | null | undefined, circuitAvailable: boolean, now?: number): SelfQuotaBlock | undefined;
+//# sourceMappingURL=selfQuotaState.d.ts.map

package/dist/core/selfQuotaState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfQuotaState.d.ts","sourceRoot":"","sources":["../../src/core/selfQuotaState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACvC,gBAAgB,EAAE,OAAO,EACzB,GAAG,GAAE,MAAmB,GACvB,cAAc,GAAG,SAAS,CAgB5B"}

package/dist/core/selfQuotaState.js

@@ -0,0 +1,49 @@
+/**
+ * selfQuotaState — compute a machine's placement-eligibility block for the capacity
+ * heartbeat (spec: docs/specs/placement-llm-circuit-aware-quota.md).
+ *
+ * `quotaState.blocked` is the signal `PlacementExecutor` reads to decide whether a machine
+ * may serve a new LLM session. It is a **placement-eligibility** signal — "this machine
+ * cannot serve LLM work right now" — NOT a pure account-quota readout. Until now its only
+ * cause was account-quota exhaustion; an OPEN llm-circuit (the machine's provider calls are
+ * actually failing, rate-limited) is a second, more direct cause and MUST also block. The
+ * live test caught the gap: a machine with an open circuit reported `blocked:false` and
+ * placement routed a session onto it that died on arrival (2026-06-16, the Mac Mini).
+ *
+ * Extracted as a pure function so the two-signal contract (account-quota OR circuit) is
+ * unit-testable and cannot silently regress to quota-only.
+ */
+/**
+ * Compute this machine's placement-eligibility block from BOTH the account-quota snapshot and
+ * the live llm-circuit availability.
+ *
+ * @param quota the account-quota snapshot (`quotaTracker.getState()`), or null/undefined when
+ *   there is no tracker.
+ * @param circuitAvailable `llmCircuitAvailable()` — `true` when the breaker is disabled OR
+ *   closed; `false` only when it is enabled AND open/half-open.
+ * @returns a block object, `{ blocked: false }`, or `undefined` (unknown ≠ blocked).
+ *
+ * Fail-open is preserved: an open circuit is the ONLY thing that newly blocks, and only on a
+ * *positively observed* unavailable circuit — missing information (no tracker + closed
+ * circuit) still returns `undefined`, which `PlacementExecutor` treats as not-blocked.
+ */
+export function computeSelfQuotaState(quota, circuitAvailable, now = Date.now()) {
+    // An open llm-circuit is a hard block regardless of the account-quota poll — the machine's
+    // provider calls are failing right now, so it cannot serve a session. This wins even when
+    // there is no quota snapshot (a machine with no tracker but an open circuit is still blocked).
+    if (!circuitAvailable)
+        return { blocked: true, reason: 'llm-circuit-open' };
+    if (!quota)
+        return undefined; // no tracker + circuit ok = unknown ≠ blocked
+    const blockActive = !!quota.blockedUntil && Date.parse(quota.blockedUntil) > now;
+    const fiveHourExhausted = (quota.fiveHourPercent ?? 0) >= 95;
+    if (!blockActive && !fiveHourExhausted)
+        return { blocked: false };
+    return {
+        blocked: true,
+        blockedUntil: quota.blockedUntil ?? undefined,
+        reason: quota.blockReason ??
+            (fiveHourExhausted ? `5-hour window at ${quota.fiveHourPercent}%` : 'provider block'),
+    };
+}
+//# sourceMappingURL=selfQuotaState.js.map

package/dist/core/selfQuotaState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfQuotaState.js","sourceRoot":"","sources":["../../src/core/selfQuotaState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA0BH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAuC,EACvC,gBAAyB,EACzB,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,2FAA2F;IAC3F,0FAA0F;IAC1F,+FAA+F;IAC/F,IAAI,CAAC,gBAAgB;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC5E,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC,CAAC,8CAA8C;IAC5E,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,GAAG,CAAC;IACjF,MAAM,iBAAiB,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,IAAI,CAAC,WAAW,IAAI,CAAC,iBAAiB;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,SAAS;QAC7C,MAAM,EACJ,KAAK,CAAC,WAAW;YACjB,CAAC,iBAAiB,CAAC,CAAC,CAAC,oBAAoB,KAAK,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC;KACxF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.593",
+  "version": "1.3.594",
   "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/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-16T09:18:10.303Z",
-  "instarVersion": "1.3.593",
+  "generatedAt": "2026-06-16T09:33:12.134Z",
+  "instarVersion": "1.3.594",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.594.md

@@ -0,0 +1,35 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a multi-machine placement bug where a rate-limited machine could still be picked to serve
+new conversations. The "can this machine take work?" health flag was computed only from the
+slow account-usage poll and ignored the circuit breaker that trips when a machine's AI calls are
+actually failing. So a machine with an open circuit advertised itself as available, and a new
+conversation routed there died on arrival. Placement now treats an open (or recovering) circuit
+as "blocked", so it steers new work to a machine that can actually answer. Caught by applying
+the live-testing standard to the multi-machine transfer.
+
+## What to Tell Your User
+
+If one of your machines is rate-limited, I now send new conversations to a machine that can
+actually answer, instead of into a dead end where you'd get a "session stopped" notice. The only
+time nothing improves is when every machine is rate-limited at once — then there is genuinely
+nowhere good to send it, and I say so honestly. Single-machine setups are unaffected, and there
+is no new setting to learn.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Placement avoids a machine whose AI calls are currently failing | Automatic; a rate-limited machine shows as "blocked — llm-circuit-open" in the machines view and new conversations skip it |
+
+## Evidence
+
+- 8 new unit tests (`tests/unit/selfQuotaState.test.ts`, both sides of every boundary) + a new
+  PlacementExecutor test asserting a circuit-open machine is skipped; tsc clean.
+- Release gate: live two-machine re-run — a circuit-open machine reports blocked in the pool view
+  and a new conversation lands on a machine that can serve it.

package/upgrades/side-effects/placement-llm-circuit-aware-quota.md

@@ -0,0 +1,50 @@
+# Side-Effects Review — Quota-aware placement must see the open LLM circuit
+
+**Slug:** placement-llm-circuit-aware-quota
+**Spec:** docs/specs/placement-llm-circuit-aware-quota.md
+**Parent principle:** No Silent Degradation to a Brittle Fallback — a machine that cannot serve LLM work must report itself blocked, not present a healthy-looking signal that misroutes work onto it.
+
+## What changed
+
+`selfQuotaState()` (the capacity-heartbeat block `PlacementExecutor` reads) derived `blocked`
+ONLY from the account-quota poll, ignoring the `LlmCircuitBreaker`. So a machine whose CLI was
+actually rate-limited (circuit OPEN) could still report `quotaState:{blocked:false}` and
+placement would route a session onto it that dies on arrival. Caught live (2026-06-16, the Mac
+Mini) by the gold-standard live test of the multi-machine transfer.
+
+Fix: extract `computeSelfQuotaState(quota, circuitAvailable)` into `src/core/selfQuotaState.ts`
+(pure, unit-tested), OR-ing an open/half-open circuit (`!llmCircuitAvailable()`) into the block.
+`server.ts` calls it with the live quota snapshot AND `llmCircuitAvailable()`.
+
+## Blast radius
+
+- **Multi-machine placement (the target):** a circuit-open machine is now excluded from
+  placement; new sessions land on a machine that can serve them. This was BROKEN before — net
+  improvement, strictly better whenever ANY machine is available.
+- **All-machines-circuit-open:** identical to today's all-account-quota-blocked case —
+  placement falls back to least-loaded and flags `all-machines-quota-blocked` (now possibly
+  carrying `llm-circuit-open` reasons). Not a regression; nowhere good to route by definition.
+- **Single machine:** no peers to compare; the existing all-blocked least-loaded fallback
+  applies, unchanged.
+- **Fail-open preserved:** only a positively-observed open circuit newly blocks. Missing info
+  (no tracker + closed circuit, or any throw) → `undefined` = unknown ≠ blocked, exactly as
+  before. A DISABLED breaker reports available → never a false block.
+- **Wire field:** `quotaState` keeps its name (a replicated heartbeat field consumed
+  cross-machine + by the dashboard; renaming is a separate wire migration). Its MEANING is
+  pinned by the doc contract + a new `SelfQuotaBlockReason` enum (`llm-circuit-open` |
+  `five-hour-exhausted` | `provider-block` | string). No consumer keys on a specific reason
+  string, so widening the cause set is non-breaking.
+
+## Reversibility
+
+Governed by the existing `intelligence.circuitBreaker` config — disabling the breaker (or it
+never tripping) keeps `llmCircuitAvailable()` true so this never blocks. Revertable by reverting
+the two-file diff; no durable state is written (the block is recomputed per heartbeat).
+
+## Risk / monitoring
+
+Low. Pure-function change off the hot path (computed per 30s heartbeat). Observable via
+`GET /pool` (`quotaState.reason: 'llm-circuit-open'`) + the existing placement decision flags +
+the already-audited `[llm-circuit]` transitions in `logs/server.log`. Release gate: the live
+two-machine re-run — a circuit-open machine shows `blocked:true` in `/pool` and a new
+conversation lands on a machine that can serve it.