instar 1.3.1244 → 1.3.1245

package/dashboard/index.html

@@ -3744,6 +3744,11 @@
       .sub-quota-pct { opacity:.65; }
       .sub-quota-track { height:8px; border-radius:4px; background:var(--border,#2a2a2a); overflow:hidden; }
       .sub-quota-fill { height:100%; background:linear-gradient(90deg,#4caf80,#3a9); }
+      /* Severity bands (dashboard/subscriptions.js quotaSeverity): <75% ok, 75-89% warn, >=90% critical.
+         Colour is redundant with the always-present "N% used" text, never the only signal. */
+      .sub-quota-fill.sub-quota-ok { background:linear-gradient(90deg,#4caf80,#3a9); }
+      .sub-quota-fill.sub-quota-warn { background:linear-gradient(90deg,#f59e0b,#e0900a); }
+      .sub-quota-fill.sub-quota-critical { background:linear-gradient(90deg,#f87171,#ef4444); }
       .sub-pending { border:1px solid var(--border,#2a2a2a); border-radius:10px; padding:12px 16px; margin-bottom:10px; }
       .sub-pending-head { display:flex; justify-content:space-between; align-items:baseline; gap:12px; }
       .sub-pending-label { font-weight:600; }

package/dashboard/subscriptions.js

@@ -202,18 +202,45 @@ function el(doc, tag, cls, text) {
   return node;
 }
 
+// Quota-bar severity thresholds. A single green bar made a 92%-consumed account
+// read the same as a 4%-consumed one at a glance, so the bar communicated width
+// only. These bands give it colour as well: comfortable / getting tight / about
+// to wall. PRESENTATION ONLY — nothing routes, sheds, or swaps on this class;
+// placement and load-shedding keep reading the numeric quota they always read.
+export const QUOTA_WARN_PCT = 75;
+export const QUOTA_CRITICAL_PCT = 90;
+
+/** Severity band for an already-clamped 0–100 integer. */
+export function quotaSeverity(usedPct) {
+  const used = clampPct(usedPct);
+  if (used >= QUOTA_CRITICAL_PCT) return 'critical';
+  if (used >= QUOTA_WARN_PCT) return 'warn';
+  return 'ok';
+}
+
+// Severity → STATIC class literal. The map is the reason the class attribute stays
+// a fixed literal (the file's safety contract): the severity is chosen from a
+// closed set of three, never interpolated from data.
+const QUOTA_FILL_CLASS = Object.freeze({
+  ok: 'sub-quota-fill sub-quota-ok',
+  warn: 'sub-quota-fill sub-quota-warn',
+  critical: 'sub-quota-fill sub-quota-critical',
+});
+
 /** A labelled quota bar. `pct` is clamped to a 0–100 NUMBER before it reaches the
- *  only dynamic attribute (style width); the percent text is also from that number. */
+ *  only dynamic attribute (style width); the percent text is also from that number.
+ *  The fill also carries a severity class derived from that same clamped number. */
 export function quotaBar(doc, label, pct, resetIso, now = Date.now()) {
   const wrap = el(doc, 'div', 'sub-quota');
   const used = clampPct(pct);
+  const severity = quotaSeverity(used);
   const head = el(doc, 'div', 'sub-quota-head');
   head.appendChild(el(doc, 'span', 'sub-quota-label', sanitizeForDisplay(label, 'label')));
   const resetTxt = resetIso ? countdown(resetIso, now, { expiredWord: 'resetting' }) : '';
   head.appendChild(el(doc, 'span', 'sub-quota-pct', `${used}% used${resetTxt ? ` · resets in ${resetTxt}` : ''}`));
   wrap.appendChild(head);
   const track = el(doc, 'div', 'sub-quota-track');
-  const fill = el(doc, 'div', 'sub-quota-fill');
+  const fill = el(doc, 'div', QUOTA_FILL_CLASS[severity]); // static literal from a closed set
   fill.style.width = `${used}%`; // safe: `used` is a clamped integer
   track.appendChild(fill);
   wrap.appendChild(track);

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "890eec3dcf80e4388c396f43001a0bd3fabc80c88f79aa9525885d6402a6dfdf",
-  "packageVersion": "1.3.1244",
+  "packageVersion": "1.3.1245",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "31fa6f41d59fa409722165554609c10263f47aed73da9f99261c689342b001af",
+  "sha256": "7957af2c8bb2014be0ed964adc5be0a94c9be477962f55fd3869f8915640c1bd",
   "registrySha256": "890eec3dcf80e4388c396f43001a0bd3fabc80c88f79aa9525885d6402a6dfdf",
-  "packageVersion": "1.3.1244"
+  "packageVersion": "1.3.1245"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "890eec3dcf80e4388c396f43001a0bd3fabc80c88f79aa9525885d6402a6dfdf",
   "articleCount": 91,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1244"
+  "packageVersion": "1.3.1245"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1244",
+  "version": "1.3.1245",
   "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-09-17T01:21:28.866Z",
-  "instarVersion": "1.3.1244",
+  "generatedAt": "2026-09-19T01:17:14.478Z",
+  "instarVersion": "1.3.1245",
   "entryCount": 203,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "890eec3dcf80e4388c396f43001a0bd3fabc80c88f79aa9525885d6402a6dfdf",
-  "packageVersion": "1.3.1244",
+  "packageVersion": "1.3.1245",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "31fa6f41d59fa409722165554609c10263f47aed73da9f99261c689342b001af",
+  "sha256": "7957af2c8bb2014be0ed964adc5be0a94c9be477962f55fd3869f8915640c1bd",
   "registrySha256": "890eec3dcf80e4388c396f43001a0bd3fabc80c88f79aa9525885d6402a6dfdf",
-  "packageVersion": "1.3.1244"
+  "packageVersion": "1.3.1245"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "890eec3dcf80e4388c396f43001a0bd3fabc80c88f79aa9525885d6402a6dfdf",
   "articleCount": 91,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1244"
+  "packageVersion": "1.3.1245"
 }

package/upgrades/1.3.1245.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Subscriptions dashboard's quota bars are now colour-coded by how much of each account's limit is used. Every bar previously rendered in the same green regardless of utilization, so the only difference between an account at 4% and one at 92% was the bar's length — a distinction that is hard to read at a glance across a stacked list of accounts, which is exactly where the list is read.
+
+Each bar's fill now carries one of three severity classes derived from the same clamped 0–100 integer that already sets its width: green below 75% used, amber from 75% through 89%, red at 90% and above. The percent text that has always sat beside the bar is unchanged, so the colour is redundant with information already on screen rather than the only way to read the value.
+
+This is presentation only. No routing, placement, load-shedding, proactive-swap or alerting decision reads the new class — those keep consuming the numeric quota they already consumed, on their own thresholds, unchanged.
+
+## What to Tell Your User
+
+Your Subscriptions dashboard now shows each account's quota bar in green, amber or red depending on how much of the limit is used, instead of always green. An account that is comfortable stays green, one that is getting tight turns amber at 75%, and one that is at or near its wall turns red at 90%. Nothing about how work is routed between your accounts changed — this only makes the page easier to scan. The percentage is still written next to every bar.
+
+## Summary of New Capabilities
+
+- Subscriptions quota bars are colour-coded: green (<75% used), amber (75–89%), red (≥90%).
+- The colour is derived from the already-clamped percent, so a bad reading cannot produce a misleading colour — it clamps to 0% / green or 100% / red.
+- Colour is never the only signal: the "N% used" text is unchanged and always present.
+- No routing, shedding or alerting behaviour reads the new class.
+
+## Evidence
+
+- Visual: the shipped module and the shipped CSS rendered together against the account mix from the operator's reference screenshot — 0/22/68% green, 83/89% amber, 100% red.
+- Unit (`tests/unit/subscriptions-render.test.ts`, 92 passing): both sides of both band boundaries (74/75 and 89/90), severity derived from the clamped number (1000 → critical, −50 → ok, non-numeric → ok, 74.6 → warn by rounding), the fill's class attribute, and a hostile percent proving the class stays a closed-set literal.
+- Mutation-checked: flipping `>=` to `>` on the warn boundary fails the 75% case, so the boundary assertions are load-bearing rather than decorative.

package/upgrades/side-effects/quota-bar-severity-colors.md

@@ -0,0 +1,139 @@
+# Side-Effects Review — quota-bar severity colours
+
+**Change:** `dashboard/subscriptions.js` `quotaBar()` now derives a severity band
+(`ok` / `warn` / `critical`) from the already-clamped 0–100 percent and puts it on the
+fill's class; `dashboard/index.html` gives each band a colour. Thresholds: ok <75,
+warn 75–89, critical ≥90.
+
+**Tier:** 1 — presentation-only, 3 files, no `src/` runtime surface, no new capability,
+no migration, no irreversibility. (Note: `dashboard/` is outside
+`scripts/instar-dev-precommit.js`'s `inScope()` filter, so the gate does not demand a
+trace here. The artifact is produced anyway — see §9.)
+
+## Phase 1 — Principle check (signal vs authority)
+
+**Does this change involve a decision point — something that gates information flow,
+blocks actions, filters messages, or constrains agent behaviour?**
+
+No. `quotaSeverity()` is a pure function from a number the renderer already holds to one
+of three CSS class literals. It has no consumer other than the DOM. It does not gate,
+block, filter, route, shed, alert or gate-keep anything, and nothing reads it back.
+
+The valid-reason category is "presentation of data already computed and already
+displayed." The numeric quota that placement, proactive-swap, load-shedding and the
+quota brake consume is untouched, and those subsystems keep their own thresholds — this
+change deliberately does not unify them (see §5).
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+Nothing is rejected; there is no accept/reject decision. The nearest analogue is a
+misleading colour. The band is computed from `clampPct()`'s output, so the reachable
+inputs are exactly the integers 0–100 and the three bands partition that range with no
+gap and no overlap. A non-finite or missing reading clamps to 0 and renders green — the
+same "empty bar" a missing reading already rendered, so this does not invent a
+reassuring colour for absent data. An account with no quota reading at all still takes
+the separate `sub-account-noquota` path and draws no bar.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **A stale reading still looks authoritative.** A bar polled ten minutes ago renders
+  the same as one polled ten seconds ago; colour does not encode freshness. This is
+  pre-existing (the bar itself had the same property) and out of this change's reach.
+- **0% green is ambiguous** between "genuinely unused" and "clamped from an unusable
+  reading." Also pre-existing — the width was already 0 in both cases — and the row's
+  status text is what distinguishes them.
+- **Colour does not distinguish 90% from 100%.** Deliberate: both mean "do not plan
+  work here", and a fourth band buys resolution the operator does not act on differently.
+- **The 5-hour and weekly bars are banded independently.** An account green on 5-hour and
+  red on weekly shows both, which is correct — they are different limits — but there is
+  no single per-account "worst band" summary. Not attempted here.
+
+## 3. Level-of-abstraction fit
+
+Right layer. The severity is a property of *this view* of the number, not of the number,
+so it belongs in the renderer that owns the bar. Pushing it server-side would mean the
+API asserting an operational verdict ("this account is critical") that routing does not
+share, which would be a stronger claim than the data supports and would invite consumers
+to treat a presentation band as authority.
+
+A smarter gate does exist for the operational question — `QuotaTracker`, the proactive
+swap's measured threshold, and the placement quota gate — and this change deliberately
+does **not** feed them or read from them. It is a sibling view, not a parallel authority.
+
+## 4. Signal vs authority compliance
+
+Compliant, in the strongest available form: this produces neither. It holds no blocking
+authority, and it is not even a signal (nothing consumes it programmatically). The
+brittle-check-with-authority failure mode this question exists to catch is structurally
+unreachable — the only consumer is CSS.
+
+The constants are exported (`QUOTA_WARN_PCT`, `QUOTA_CRITICAL_PCT`) so the tests assert
+against the same numbers the code uses. That export is a hazard worth naming: a future
+change that imports them into a routing decision would silently convert a presentation
+band into an authority. The file comment states the boundary; if that ever happens it
+should be a reviewed change, not an import.
+
+## 5. Interactions
+
+- **Does it shadow another check?** No. It does not participate in any check.
+- **Is it shadowed?** The `.sub-quota-fill` base rule still carries the green gradient
+  and the three band rules follow it with equal-or-higher specificity
+  (`.sub-quota-fill.sub-quota-warn` is one class more specific), so the band always wins
+  and the base rule remains a correct fallback if a future caller builds a fill without
+  a band class. No `!important` anywhere in the chain.
+- **Does it double-fire or race?** No timers, no state, no async. `quotaBar()` is called
+  synchronously during render and is idempotent.
+- **Threshold divergence is real and intentional.** The proactive swap's measured
+  threshold (default 80%) sits *between* this change's warn (75) and critical (90)
+  boundaries, so an operator can see an amber bar on an account the swap has not yet
+  moved off. That is honest — amber means "getting tight", not "the swap fired" — but it
+  is the most likely question this change generates, and it is why the two numbers are
+  not wired to each other.
+
+## 6. External surfaces
+
+- **Visible to the operator:** yes — that is the point. The change is additive to the
+  existing view; no element is removed, renamed or reordered, and the percent text,
+  reset countdown, labels and layout are byte-identical.
+- **Visible to other agents / systems:** no. No API response, no state file, no message,
+  no log line changes. The class is never serialized off the page.
+- **Accessibility:** colour is redundant with the always-present "N% used" text, so no
+  information is conveyed by colour alone. The three fills stay well above the track
+  background in luminance on the dark theme (the dashboard has no light theme and no
+  `prefers-color-scheme` block, so there is no second palette to maintain). Amber
+  `#f59e0b` and red `#f87171` are both already in the dashboard's existing palette, so
+  this introduces no new colours to the page.
+- **Timing / runtime conditions:** none depended on.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local by design, with no coherence surface.** The dashboard is served as static
+assets by whichever machine the operator has open, and the banding is computed in that
+browser from whatever account rows that page already fetched. There is no state to
+replicate, nothing to proxy on read, and no durable record that could strand on a topic
+transfer.
+
+The pool-scope account view (`GET /subscription-pool?scope=pool`) is unchanged, and rows
+merged from a peer machine render through the same `quotaBar()` as local rows — so a
+mixed-machine list is banded consistently rather than one machine's rows being coloured
+and another's not. Because the asset ships inside the instar package, a machine still on
+an older version simply renders the old all-green bars until it updates; the two versions
+do not disagree about any value, only about colour. No user-facing notice is emitted, so
+there is no one-voice gating question. No URL is generated.
+
+## 8. Rollback cost
+
+Near-zero and immediate. Reverting the commit restores the previous rendering exactly —
+there is no persisted state, no migration, no agent state to repair, and no consumer to
+un-wire. A hot-fix release is not required for correctness: even left in place, a wrong
+threshold only mis-colours a bar whose number is still printed next to it. An operator
+who dislikes the bands before a release can neutralise them by removing three CSS rules.
+
+## 9. Follow-up raised, not deferred
+
+`inScope()` in `scripts/instar-dev-precommit.js` does not cover `dashboard/`, although
+the dashboard ships to every install and is the operator's primary read surface. That is
+a genuine gap in the gate — a dashboard change can land with no artifact and no trace.
+This artifact was produced regardless, and the gap is filed as its own item rather than
+widened into this PR (changing the gate's scope is a gate change, with its own blast
+radius, and belongs in a change that can be reviewed on those terms).