quotacap 0.0.56 → 0.0.57

package/dist/advisory/engine.js

@@ -1,4 +1,4 @@
-import { MIN_PACE_SPAN_DAYS, BLEND_K, RISK_MARGIN, GATE_TOL } from "./types.js";
+import { MIN_PACE_SPAN_DAYS, BLEND_K, RISK_MARGIN, GATE_TOL, paceTube } from "./types.js";
 const DAY_MS = 86400000;
 /**
  * Pace from a single reading.
@@ -113,6 +113,7 @@ export function computeAdvisory(q, recent, baseline, now = new Date(), exhausted
             recentRate: null,
             baselineRate: null,
             aheadOfElapsed: null,
+            closeToReset: false,
             avgPace,
             burnMeasured: false,
             paceSource: "unknown",
@@ -136,6 +137,7 @@ export function computeAdvisory(q, recent, baseline, now = new Date(), exhausted
             recentRate: null,
             baselineRate: null,
             aheadOfElapsed: null,
+            closeToReset: false,
             avgPace,
             burnMeasured,
             paceSource,
@@ -151,6 +153,9 @@ export function computeAdvisory(q, recent, baseline, now = new Date(), exhausted
     }
     // Red needs a deadband margin and a cumulatively-ahead position on a
     // verified clock; a missing or estimated clock caps at Watch.
+    // The on-track tube widens with time left: a near-full finish reads on
+    // track while the reset is days away, and the shell out to RISK_MARGIN
+    // stays Watch so a small miss still warns near the reset.
     const elapsed = elapsedPctOf(q, now);
     const estimated = q.resetsAtEstimated === true;
     const gate = elapsed !== null && !estimated && q.weeklyPct >= elapsed * (1 - GATE_TOL);
@@ -158,14 +163,17 @@ export function computeAdvisory(q, recent, baseline, now = new Date(), exhausted
     const wastePct = Math.max(0, remaining - burnRate * daysLeft);
     const daysToExhaust = burnRate > 0 ? remaining / burnRate : Infinity;
     const over = daysToExhaust < daysLeft * (1 - RISK_MARGIN);
-    const marginal = !over && daysToExhaust < daysLeft * (1 + RISK_MARGIN);
+    const missFrac = Number.isFinite(daysToExhaust) ? Math.abs(daysToExhaust - daysLeft) / daysLeft : Infinity;
+    const insideTube = missFrac <= paceTube(daysLeft);
+    const inShell = !over && !insideTube && daysToExhaust < daysLeft * (1 + RISK_MARGIN);
     let status;
     if (over && gate)
         status = "at risk";
-    else if (over || marginal)
+    else if (over || inShell || (insideTube && estimated))
         status = "watch";
     else
         status = "on track";
+    const closeToReset = status === "on track" && insideTube;
     let urgency = "on track";
     if (wastePct > 30 && daysLeft < 3)
         urgency = "burn now";
@@ -177,7 +185,7 @@ export function computeAdvisory(q, recent, baseline, now = new Date(), exhausted
         urgency = "save";
     if (estimated && urgency === "burn now")
         urgency = "use soon";
-    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, recentRate: recent, baselineRate: baseline, aheadOfElapsed, avgPace, burnMeasured, paceSource, daysToExhaust, status, wastePct, urgency, bindingWindow, bindingRemaining, bindingDaysLeft, exhaustedAt };
+    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, recentRate: recent, baselineRate: baseline, aheadOfElapsed, closeToReset, avgPace, burnMeasured, paceSource, daysToExhaust, status, wastePct, urgency, bindingWindow, bindingRemaining, bindingDaysLeft, exhaustedAt };
 }
 /**
  * Known-waste sort key. `wastePct` is a flow (budget forecast to go unspent
@@ -250,10 +258,12 @@ export function recommend(quotas, _task, paceByProvider = new Map(), now = new D
             advisories,
         };
     }
-    // 3. No meaningful candidate (e.g. all quotas at risk, watch, or exhausted).
+    // 3. No meaningful candidate. A hot board names the amber and red tiers.
+    // An on-track board with nothing spare (a finish inside the tube) does not.
+    const hot = advisories.some(a => a.status === "at risk" || a.status === "watch");
     return {
         use: "none",
-        reason: "all quotas at risk, watch, or exhausted",
+        reason: hot ? "all quotas at risk, watch, or exhausted" : "no avoidable waste",
         wastePct: 0,
         idealRate: 0,
         recommendationBasis: "none",

package/dist/advisory/snapshot.js

@@ -17,6 +17,7 @@ function normalizeAdvisory(adv) {
         recentRate: adv.recentRate != null && Number.isFinite(adv.recentRate) ? adv.recentRate : null,
         baselineRate: adv.baselineRate != null && Number.isFinite(adv.baselineRate) ? adv.baselineRate : null,
         aheadOfElapsed: typeof adv.aheadOfElapsed === "boolean" ? adv.aheadOfElapsed : null,
+        closeToReset: adv.closeToReset === true,
         avgPace: adv.avgPace !== null && Number.isFinite(adv.avgPace) ? adv.avgPace : null,
         daysToExhaust: adv.daysToExhaust !== null && Number.isFinite(adv.daysToExhaust) ? adv.daysToExhaust : null,
         wastePct: adv.wastePct !== null && Number.isFinite(adv.wastePct) ? adv.wastePct : null,

package/dist/advisory/types.d.ts

@@ -11,6 +11,23 @@ export declare const MIN_PACE_SPAN_DAYS: number;
 export declare const BLEND_K = 0.5;
 export declare const RISK_MARGIN = 0.15;
 export declare const GATE_TOL = 0.1;
+/** Weekly quota window. "Far from reset" in the on-track tube is this long. */
+export declare const PACE_WINDOW_DAYS = 7;
+/**
+ * Narrowest on-track tube, as a fraction of the time still left. At the
+ * reset, a finish within 5% of it still reads on track.
+ */
+export declare const TUBE_FLOOR = 0.05;
+/**
+ * Half-width of the on-track tube, as a fraction of `daysLeft`.
+ *
+ * The tube grows from `TUBE_FLOOR` at the reset to `margin` once about 4.7
+ * days remain, and never wider than `margin`. A forecast inside it is close
+ * enough to a full finish to read on track. The shell between the tube and
+ * `margin` stays Watch, so a small miss still warns near the reset. Cap risk
+ * stays outside `margin` on the early side.
+ */
+export declare function paceTube(daysLeft: number, margin?: number): number;
 export type Urgency = "burn now" | "use soon" | "slow down" | "save" | "on track";
 export type BurnStatus = "at risk" | "watch" | "on track" | "unknown";
 export type PaceSource = "recent" | "window-average" | "unknown";
@@ -27,6 +44,13 @@ export interface Advisory {
     recentRate?: number | null;
     baselineRate?: number | null;
     aheadOfElapsed?: boolean | null;
+    /**
+     * True when the forecast finish sits inside the horizon tube around the
+     * reset and the verdict is on track. The badge stays On track even if
+     * usage is slightly ahead of elapsed time. False for a clear leftover,
+     * a Watch shell, and an estimated clock.
+     */
+    closeToReset: boolean;
     /**
      * Window-average pace (used % ÷ days elapsed), always computed when the
      * window start is known — independent of `burnRate`, which is the forecast

package/dist/advisory/types.js

@@ -8,3 +8,25 @@ export const MIN_PACE_SPAN_DAYS = 6 / 24;
 export const BLEND_K = 0.5;
 export const RISK_MARGIN = 0.15;
 export const GATE_TOL = 0.10;
+/** Weekly quota window. "Far from reset" in the on-track tube is this long. */
+export const PACE_WINDOW_DAYS = 7;
+/**
+ * Narrowest on-track tube, as a fraction of the time still left. At the
+ * reset, a finish within 5% of it still reads on track.
+ */
+export const TUBE_FLOOR = 0.05;
+/**
+ * Half-width of the on-track tube, as a fraction of `daysLeft`.
+ *
+ * The tube grows from `TUBE_FLOOR` at the reset to `margin` once about 4.7
+ * days remain, and never wider than `margin`. A forecast inside it is close
+ * enough to a full finish to read on track. The shell between the tube and
+ * `margin` stays Watch, so a small miss still warns near the reset. Cap risk
+ * stays outside `margin` on the early side.
+ */
+export function paceTube(daysLeft, margin = RISK_MARGIN) {
+    if (!(daysLeft > 0) || !(margin > 0))
+        return TUBE_FLOOR;
+    const grown = TUBE_FLOOR + margin * (daysLeft / PACE_WINDOW_DAYS);
+    return Math.min(margin, grown);
+}

package/dist/format/rows.js

@@ -159,7 +159,8 @@ export function railCells(ps, now) {
 }
 // Shared STATE vocabulary (locked badge mapping): any exclusion reads
 // Not reporting; at-risk status beats urgency, then watch, then unknown;
-// on-track rows ahead of cumulative elapsed time revive Ahead of pace;
+// on-track rows ahead of cumulative elapsed time revive Ahead of pace,
+// except a finish inside the horizon tube, which stays On track;
 // urgency maps to the remaining pace words.
 export function stateWord(ps) {
     if (ps.exclusionReason !== null)
@@ -183,6 +184,8 @@ export function stateWord(ps) {
         return "Watch";
     if (adv.status === "unknown")
         return "Measuring";
+    if (adv.status === "on track" && adv.closeToReset === true)
+        return "On track";
     if (adv.aheadOfElapsed === true)
         return "Ahead of pace";
     switch (adv.urgency) {

package/dist/version.js

@@ -1,2 +1,2 @@
 // generated by scripts/build-embed.mjs — do not edit
-export const VERSION = "0.0.56";
+export const VERSION = "0.0.57";

package/dist/web/src/components/PaceBar.d.ts

@@ -4,7 +4,8 @@ export type PaceBadge = "Not reporting" | "Cap risk" | "Watch" | "Behind pace" |
 /**
  * Pace-state badge from the mapping table. Exclusion always wins; a blocked
  * month next; otherwise status "at risk" wins, then "watch", then "unknown";
- * on-track rows ahead of cumulative elapsed time read Ahead of pace;
+ * on-track rows ahead of cumulative elapsed time read Ahead of pace,
+ * except a finish inside the horizon tube, which stays On track;
  * otherwise urgency decides. No client thresholds.
  */
 export declare function paceBadge(provider: ProviderView): PaceBadge;

package/dist/web/src/components/PaceBar.js

@@ -3,7 +3,8 @@ import { ageDuration } from "../state.js";
 /**
  * Pace-state badge from the mapping table. Exclusion always wins; a blocked
  * month next; otherwise status "at risk" wins, then "watch", then "unknown";
- * on-track rows ahead of cumulative elapsed time read Ahead of pace;
+ * on-track rows ahead of cumulative elapsed time read Ahead of pace,
+ * except a finish inside the horizon tube, which stays On track;
  * otherwise urgency decides. No client thresholds.
  */
 export function paceBadge(provider) {
@@ -26,6 +27,8 @@ export function paceBadge(provider) {
         return "Watch";
     if (advisory.status === "unknown")
         return "Measuring";
+    if (advisory.status === "on track" && advisory.closeToReset === true)
+        return "On track";
     if (advisory.aheadOfElapsed === true)
         return "Ahead of pace";
     switch (advisory.urgency) {

package/dist/web/src/state.d.ts

@@ -15,6 +15,11 @@ export interface AdvisoryView {
     baselineRate?: number | null;
     /** Cumulative position versus elapsed time; null on excluded/unknown branches. */
     aheadOfElapsed?: boolean | null;
+    /**
+     * Forecast finish sits inside the horizon tube and the verdict is on track.
+     * Absent on advisories from a daemon older than the tube.
+     */
+    closeToReset?: boolean;
     /** Window-average pace (used % ÷ days elapsed); null before the window start is known. */
     avgPace: number | null;
     burnMeasured: boolean;