@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/bin/token-budget.js

@@ -1,10 +1,22 @@
 #!/usr/bin/env node
 
 /**
- * GSD-T Token Budget — Session-level token tracking and graduated degradation
+ * GSD-T Token Budget — Session-level token tracking (three-band model)
  *
- * Reads .gsd-t/token-log.md for historical averages, tracks session usage,
- * and returns model override recommendations at degradation thresholds.
+ * Reads .gsd-t/.context-meter-state.json (M34) for real context-window
+ * readings, tracks session usage, and returns a three-band status signal
+ * (normal / warn / stop) that callers use to decide whether to proceed,
+ * log a warning, or halt cleanly.
+ *
+ * v3.0.0 (M35 — clean break from v2.0.0):
+ *   - The `downgrade` and `conserve` bands were REMOVED. Silent model
+ *     degradation and silent phase-skipping are anti-features — they
+ *     violate GSD-T's "quality is non-negotiable" principle.
+ *   - `getDegradationActions()` now returns `{band, pct, message}` instead
+ *     of `{threshold, actions, modelOverrides}`. No `modelOverride`, no
+ *     `skipPhases`, no `checkpoint` side-channel.
+ *   - `warn` threshold tightened from 60% → 70%. `stop` tightened from
+ *     95% → 85% — keeps us clear of the runtime's native ~95% compact.
  *
  * Zero external dependencies (Node.js built-ins only).
  */
@@ -28,11 +40,16 @@ const BASE_ESTIMATES = {
   default: 6000,
 };
 
+// v3.0.0 three-band thresholds. Lower-bound inclusive.
+//   pct <  70 → normal
+//   70 ≤ pct <  85 → warn (informational — log, proceed)
+//   pct ≥ 85 → stop  (halt cleanly, hand off to runway estimator)
+const WARN_THRESHOLD_PCT = 70;
+const STOP_THRESHOLD_PCT = 85;
+
 const THRESHOLDS = {
-  warn: 60,
-  downgrade: 70,
-  conserve: 85,
-  stop: 95,
+  warn: WARN_THRESHOLD_PCT,
+  stop: STOP_THRESHOLD_PCT,
 };
 
 // ── Exports ──────────────────────────────────────────────────────────────────
@@ -74,50 +91,57 @@ function estimateCost(model, taskType, options) {
 
 // ── getSessionStatus ─────────────────────────────────────────────────────────
 
+const STATE_FILE_REL = path.join(".gsd-t", ".context-meter-state.json");
+const STATE_STALE_MS = 5 * 60 * 1000;
+
 /**
  * @param {string} [projectDir]
  * @returns {{ consumed: number, estimated_remaining: number, pct: number, threshold: string }}
  *
- * v2.74.12: previously this read process.env.CLAUDE_CONTEXT_TOKENS_USED /
- * CLAUDE_CONTEXT_TOKENS_MAX, which Claude Code does not export — so consumed
- * was always 0 and threshold was always 'normal'. The graduated-degradation
- * machinery downstream was inert. Now we synthesise a percent from the real
- * task counter at .gsd-t/.task-counter, mapping 0..limit linearly to
- * 0..100%. This keeps the API stable so commands that ask for thresholds
- * (downgrade/conserve/stop) get a real signal.
+ * v2.0.0 (M34): reads `.gsd-t/.context-meter-state.json` produced by the
+ * Context Meter PostToolUse hook. When that file is fresh (timestamp within
+ * the last 5 minutes), real `input_tokens` drive the response. Otherwise we
+ * fall back to a historical heuristic from `.gsd-t/token-log.md`, preserving
+ * graceful degradation for projects without the hook installed.
  */
 function getSessionStatus(projectDir) {
   const dir = projectDir || process.cwd();
-  const counter = readTaskCounter(dir);
-  const limit = counter.limit > 0 ? counter.limit : 5;
-  const consumed = counter.count;
-  const pct = Math.min(100, Math.round((consumed / limit) * 100 * 10) / 10);
-  const threshold = resolveThreshold(pct);
-  const estimated_remaining = Math.max(0, limit - consumed);
-  return { consumed, estimated_remaining, pct, threshold };
+  const real = readContextMeterState(dir);
+  if (real) {
+    const consumed = real.inputTokens;
+    const window = real.modelWindowSize > 0 ? real.modelWindowSize : 200000;
+    const estimated_remaining = Math.max(0, window - consumed);
+    const pct = Math.round(real.pct * 10) / 10;
+    const threshold = resolveThreshold(pct);
+    return { consumed, estimated_remaining, pct, threshold };
+  }
+  return getSessionStatusHeuristic(dir);
 }
 
-function readTaskCounter(dir) {
+function readContextMeterState(dir) {
   try {
-    const fp = path.join(dir, ".gsd-t", ".task-counter");
+    const fp = path.join(dir, STATE_FILE_REL);
     const raw = fs.readFileSync(fp, "utf8");
     const s = JSON.parse(raw);
-    let limit = 5;
-    try {
-      const cfgRaw = fs.readFileSync(path.join(dir, ".gsd-t", "task-counter-config.json"), "utf8");
-      const cfg = JSON.parse(cfgRaw);
-      if (cfg && typeof cfg.limit === "number" && cfg.limit > 0) limit = cfg.limit;
-    } catch (_) {}
-    if (process.env.GSD_T_TASK_LIMIT) {
-      const n = parseInt(process.env.GSD_T_TASK_LIMIT, 10);
-      if (!isNaN(n) && n > 0) limit = n;
-    }
-    return { count: typeof s.count === "number" ? s.count : 0, limit };
+    if (!s || typeof s.inputTokens !== "number" || typeof s.pct !== "number") return null;
+    if (!s.timestamp) return null;
+    const age = Date.now() - Date.parse(s.timestamp);
+    if (isNaN(age) || age > STATE_STALE_MS || age < 0) return null;
+    return s;
   } catch (_) {
-    return { count: 0, limit: 5 };
+    return null;
   }
 }
 
+function getSessionStatusHeuristic(dir) {
+  const window = 200000;
+  const consumed = readSessionConsumed(dir);
+  const estimated_remaining = Math.max(0, window - consumed);
+  const pct = window > 0 ? Math.round((consumed / window) * 100 * 10) / 10 : 0;
+  const threshold = resolveThreshold(pct);
+  return { consumed, estimated_remaining, pct, threshold };
+}
+
 // ── recordUsage ──────────────────────────────────────────────────────────────
 
 /**
@@ -136,15 +160,20 @@ function recordUsage(usage) {
   fs.appendFileSync(fp, line);
 }
 
-// ── getDegradationActions ─────────────────────────────────────────────────────
+// ── getDegradationActions (v3.0.0 — three-band) ─────────────────────────────
 
 /**
+ * v3.0.0 three-band response. The name is preserved for caller-identification
+ * convenience; the return shape is a CLEAN BREAK from v2.0.0 — no
+ * `modelOverrides`, no `actions` list, no `skipPhases`, no `checkpoint`
+ * side-channel. Callers that relied on those fields MUST be updated.
+ *
  * @param {string} [projectDir]
- * @returns {{ threshold: string, actions: string[], modelOverrides: object }}
+ * @returns {{ band: 'normal'|'warn'|'stop', pct: number, message: string }}
  */
 function getDegradationActions(projectDir) {
-  const { threshold } = getSessionStatus(projectDir);
-  return buildDegradationResponse(threshold);
+  const { threshold, pct } = getSessionStatus(projectDir);
+  return buildBandResponse(threshold, pct);
 }
 
 // ── estimateMilestoneCost ─────────────────────────────────────────────────────
@@ -156,69 +185,47 @@ function getDegradationActions(projectDir) {
  */
 function estimateMilestoneCost(remainingTasks, projectDir) {
   const status = getSessionStatus(projectDir);
-  const limit = status.consumed + status.estimated_remaining || 5;
+  const window = status.consumed + status.estimated_remaining || 200000;
   const estimatedTokens = remainingTasks.reduce((sum, t) => {
     return sum + estimateCost(t.model, t.taskType, { complexity: t.complexity, projectDir });
   }, 0);
-  // Estimate task-equivalents needed for the remaining work: cost-weighted
-  // approximation against historical avg, capped at the configured task limit.
-  const taskEquivalents = remainingTasks.length;
-  const estimatedPct = limit > 0 ? Math.min(100, Math.round((taskEquivalents / limit) * 100 * 10) / 10) : 0;
-  const feasible = taskEquivalents <= status.estimated_remaining;
+  const estimatedPct = window > 0 ? Math.min(100, Math.round((estimatedTokens / window) * 100 * 10) / 10) : 0;
+  const feasible = estimatedTokens <= status.estimated_remaining;
   return { estimatedTokens, estimatedPct, feasible };
 }
 
-// ── Internal: threshold resolution ───────────────────────────────────────────
+// ── Internal: threshold resolution (v3.0.0 — three-band) ─────────────────────
 
 function resolveThreshold(pct) {
+  if (!Number.isFinite(pct)) return "normal";
   if (pct >= THRESHOLDS.stop) return "stop";
-  if (pct >= THRESHOLDS.conserve) return "conserve";
-  if (pct >= THRESHOLDS.downgrade) return "downgrade";
   if (pct >= THRESHOLDS.warn) return "warn";
   return "normal";
 }
 
-function buildDegradationResponse(threshold) {
-  const responses = {
-    normal: {
-      threshold: "normal",
-      actions: [],
-      modelOverrides: {},
-    },
-    warn: {
-      threshold: "warn",
-      actions: ["Display budget alert", "Reduce iteration budgets to minimum (2)"],
-      modelOverrides: {},
-    },
-    downgrade: {
-      threshold: "downgrade",
-      actions: ["Downgrade non-critical Sonnet to Haiku", "Skip exploratory testing", "Disable shadow-mode audit"],
-      modelOverrides: {
-        "sonnet:qa": "sonnet",
-        "sonnet:execute": "haiku",
-        "sonnet:doc-ripple": "skip",
-        "opus:red-team": "sonnet",
-        "haiku:*": "haiku",
-      },
-    },
-    conserve: {
-      threshold: "conserve",
-      actions: ["Pause doc-ripple", "Pause design brief generation", "Checkpoint all progress"],
-      modelOverrides: {
-        "sonnet:qa": "sonnet",
-        "sonnet:execute": "haiku",
-        "sonnet:doc-ripple": "skip",
-        "opus:red-team": "sonnet",
-        "haiku:*": "haiku",
-      },
-    },
-    stop: {
-      threshold: "stop",
-      actions: ["Hard stop", "Save all progress", "Display resume instruction"],
-      modelOverrides: {},
-    },
-  };
-  return responses[threshold] || responses.normal;
+function buildBandResponse(band, pct) {
+  const safePct = Number.isFinite(pct) ? pct : 0;
+  switch (band) {
+    case "warn":
+      return {
+        band: "warn",
+        pct: safePct,
+        message: `Context ${safePct.toFixed(1)}% — warn band (≥${WARN_THRESHOLD_PCT}%). Informational only; proceed.`,
+      };
+    case "stop":
+      return {
+        band: "stop",
+        pct: safePct,
+        message: `Context ${safePct.toFixed(1)}% — stop band (≥${STOP_THRESHOLD_PCT}%). Halt cleanly; hand off to runway estimator / headless auto-spawn.`,
+      };
+    case "normal":
+    default:
+      return {
+        band: "normal",
+        pct: safePct,
+        message: `Context ${safePct.toFixed(1)}% — normal band. Proceed.`,
+      };
+  }
 }
 
 // ── Internal: token-log parsing ───────────────────────────────────────────────