@tekyzinc/gsd-t 3.16.12 → 3.18.12

package/bin/gsd-t.js

@@ -976,7 +976,7 @@ function configureFigmaMcp() {
 
 // ─── Utility Scripts ─────────────────────────────────────────────────────────
 
-const UTILITY_SCRIPTS = ["gsd-t-tools.js", "gsd-t-statusline.js", "gsd-t-event-writer.js", "gsd-t-dashboard-server.js", "gsd-t-dashboard.html"];
+const UTILITY_SCRIPTS = ["gsd-t-tools.js", "gsd-t-statusline.js", "gsd-t-event-writer.js", "gsd-t-dashboard-server.js", "gsd-t-dashboard.html", "gsd-t-transcript.html"];
 
 function installUtilityScripts() {
   ensureDir(SCRIPTS_DIR);
@@ -2854,17 +2854,86 @@ function doGraphQuery(args) {
 }
 
 function doGraph(args) {
+  // M44 D1-T4: `gsd-t graph --output json|table` prints the task-graph DAG
+  // (parsed from .gsd-t/domains/*/tasks.md) for debugging. The pre-existing
+  // `index|status|query` subcommands are the codebase entity graph (graph-
+  // indexer) and remain unchanged.
+  const outIdx = args.indexOf("--output");
+  if (outIdx !== -1) {
+    const fmt = args[outIdx + 1] || "json";
+    return doGraphTaskOutput(fmt);
+  }
   const sub = args[0] || "status";
   switch (sub) {
     case "index":  doGraphIndex(); break;
     case "status": doGraphStatus(); break;
     case "query":  doGraphQuery(args.slice(1)); break;
+    case "tasks":  doGraphTaskOutput(args[1] || "table"); break;
     default:
       error(`Unknown graph subcommand: ${sub}`);
-      info("Usage: gsd-t graph [index|status|query]");
+      info("Usage: gsd-t graph [index|status|query|tasks]");
+      info("       gsd-t graph --output json|table   (task DAG)");
   }
 }
 
+// M44 D1-T4: print the task DAG built by bin/gsd-t-task-graph.cjs.
+function doGraphTaskOutput(format) {
+  const tg = require("./gsd-t-task-graph.cjs");
+  let graph;
+  try {
+    graph = tg.buildTaskGraph({ projectDir: process.cwd() });
+  } catch (e) {
+    if (e && e.name === "TaskGraphCycleError") {
+      error(`Task graph cycle: ${(e.cycle || []).join(" → ")}`);
+      process.exit(2);
+    }
+    error(e && e.message ? e.message : String(e));
+    process.exit(2);
+  }
+  const fmt = String(format || "table").toLowerCase();
+  if (fmt === "json") {
+    process.stdout.write(JSON.stringify(graph, null, 2) + "\n");
+    return;
+  }
+  if (fmt === "table") {
+    if (!graph.nodes.length) {
+      info("No tasks found in .gsd-t/domains/*/tasks.md");
+      if (graph.warnings.length) graph.warnings.forEach((w) => warn(w));
+      return;
+    }
+    // header
+    const rows = graph.nodes.map((n) => ({
+      id: n.id,
+      domain: n.domain,
+      wave: String(n.wave),
+      status: n.status,
+      ready: graph.ready.indexOf(n.id) !== -1 ? "yes" : "no",
+      deps: n.deps.join(", ") || "-",
+    }));
+    const cols = ["id", "domain", "wave", "status", "ready", "deps"];
+    const widths = {};
+    for (const c of cols) {
+      widths[c] = c.length;
+      for (const r of rows) widths[c] = Math.max(widths[c], String(r[c]).length);
+    }
+    const fmtRow = (r) =>
+      cols.map((c) => String(r[c]).padEnd(widths[c])).join("  ");
+    log(fmtRow(Object.fromEntries(cols.map((c) => [c, c.toUpperCase()]))));
+    log(cols.map((c) => "-".repeat(widths[c])).join("  "));
+    for (const r of rows) log(fmtRow(r));
+    log("");
+    info(`${graph.nodes.length} tasks · ${graph.edges.length} edges · ${graph.ready.length} ready`);
+    if (graph.warnings.length) {
+      log("");
+      warn(`${graph.warnings.length} warning(s):`);
+      graph.warnings.forEach((w) => log(`  ${w}`));
+    }
+    return;
+  }
+  error(`Unknown --output format: ${format} (expected: json|table)`);
+  process.exit(2);
+}
+
 // ─── Token-Log Writer (Fix 1, v3.12.12) ─────────────────────────────────────
 
 const _TL_HEADER =
@@ -3716,6 +3785,8 @@ function showHelp() {
   log(`  ${CYAN}benchmark-orchestrator${RESET} M40 speed gate — compares orchestrator vs in-session wall-clock`);
   log(`  ${CYAN}stream-feed${RESET}    Localhost stream-json watcher (start|status|stop) — M40 D4`);
   log(`  ${CYAN}design-build${RESET}   Deterministic design→code pipeline (elements → widgets → pages)`);
+  log(`  ${CYAN}tool-cost${RESET}      Per-tool token/cost attribution (M43 D2) — group-by tool|command|domain`);
+  log(`  ${CYAN}report tokens${RESET}  Generate token-usage optimization report (Run → Iter → CW → Turn → Tool)`);
   log(`  ${CYAN}help${RESET}           Show this help\n`);
   log(`${BOLD}Examples:${RESET}`);
   log(`  ${DIM}$${RESET} npx @tekyzinc/gsd-t install`);
@@ -3887,6 +3958,13 @@ if (require.main === module) {
       });
       process.exit(res.status == null ? 1 : res.status);
     }
+    case "parallel": {
+      // M44 D2 — `gsd-t parallel` wraps M40 orchestrator with task-level
+      // parallelism + mode-aware gating math. Extends, does not replace.
+      const { runCli: runParallelCli } = require(path.join(__dirname, "gsd-t-parallel.cjs"));
+      const code = runParallelCli(args.slice(1), process.env);
+      process.exit(code);
+    }
     case "benchmark-orchestrator": {
       const { spawnSync } = require("child_process");
       const js = path.join(__dirname, "gsd-t-benchmark-orchestrator.js");
@@ -3967,7 +4045,7 @@ if (require.main === module) {
       break;
     }
     case "tokens": {
-      const tkOpts = { projectDir: process.cwd(), since: null, milestone: null, format: 'table', regenerateLog: false };
+      const tkOpts = { projectDir: process.cwd(), since: null, milestone: null, format: 'table', regenerateLog: false, showToolCosts: false };
       for (let i = 1; i < args.length; i++) {
         const a = args[i];
         if (a === '--since' && args[i+1]) { tkOpts.since = args[++i]; }
@@ -3979,8 +4057,9 @@ if (require.main === module) {
         else if (a === '--project-dir' && args[i+1]) { tkOpts.projectDir = args[++i]; }
         else if (a.startsWith('--project-dir=')) { tkOpts.projectDir = a.slice(14); }
         else if (a === '--regenerate-log') { tkOpts.regenerateLog = true; }
+        else if (a === '--show-tool-costs') { tkOpts.showToolCosts = true; }
         else if (a === '--help' || a === '-h') {
-          log('Usage: gsd-t tokens [--since YYYY-MM-DD] [--milestone Mxx] [--format table|json]');
+          log('Usage: gsd-t tokens [--since YYYY-MM-DD] [--milestone Mxx] [--format table|json] [--show-tool-costs]');
           log('       gsd-t tokens --regenerate-log   (rewrite .gsd-t/token-log.md from token-usage.jsonl)');
           process.exit(0);
         }
@@ -4008,7 +4087,22 @@ if (require.main === module) {
       const dashboard = require(path.join(__dirname, 'gsd-t-token-dashboard.cjs'));
       dashboard.aggregate(tkOpts)
         .then((agg) => {
-          log(tkOpts.format === 'json' ? dashboard.renderJson(agg) : dashboard.renderTable(agg));
+          const baseOut = tkOpts.format === 'json' ? dashboard.renderJson(agg) : dashboard.renderTable(agg);
+          let out = baseOut;
+          if (tkOpts.showToolCosts) {
+            try {
+              out = out + '\n' + dashboard.renderToolCostsSection({
+                projectDir: tkOpts.projectDir,
+                since: tkOpts.since,
+                milestone: tkOpts.milestone,
+                format: tkOpts.format,
+              });
+            } catch (e) {
+              // Non-fatal: tool-cost section failure doesn't break primary output.
+              out = out + '\n── Top 10 tools by cost ──\n  (tool-cost section unavailable: ' + (e.message || String(e)) + ')';
+            }
+          }
+          log(out);
           process.exit(0);
         })
         .catch((e) => { error(e.message || String(e)); process.exit(3); });
@@ -4019,6 +4113,62 @@ if (require.main === module) {
       orchestrator.run(args.slice(1)).catch(e => { console.error(e); process.exit(1); });
       break;
     }
+    case "tool-cost": {
+      const toolCost = require(path.join(__dirname, 'gsd-t-tool-cost.cjs'));
+      process.exit(toolCost.run(args.slice(1)));
+      break;
+    }
+    case "report": {
+      // Nested dispatch: `gsd-t report tokens [--date YYYY-MM-DD] [--out PATH]`
+      const sub = args[1];
+      if (!sub || sub === '--help' || sub === '-h') {
+        log('Usage: gsd-t report tokens [--date YYYY-MM-DD] [--out PATH]');
+        log('');
+        log('Subcommands:');
+        log('  tokens   Generate token-usage optimization report (Run → Iter → CW → Turn → Tool).');
+        process.exit(sub ? 0 : 2);
+        break;
+      }
+      if (sub !== 'tokens') {
+        error(`report: unknown subcommand: ${sub}`);
+        log('Usage: gsd-t report tokens [--date YYYY-MM-DD] [--out PATH]');
+        process.exit(2);
+        break;
+      }
+      const rOpts = { projectDir: process.cwd(), date: null, outPath: null };
+      for (let i = 2; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--date' && args[i+1]) { rOpts.date = args[++i]; }
+        else if (a.startsWith('--date=')) { rOpts.date = a.slice(7); }
+        else if (a === '--out' && args[i+1]) { rOpts.outPath = args[++i]; }
+        else if (a.startsWith('--out=')) { rOpts.outPath = a.slice(6); }
+        else if (a === '--project-dir' && args[i+1]) { rOpts.projectDir = args[++i]; }
+        else if (a.startsWith('--project-dir=')) { rOpts.projectDir = a.slice(14); }
+        else if (a === '--help' || a === '-h') {
+          log('Usage: gsd-t report tokens [--date YYYY-MM-DD] [--out PATH]');
+          log('  --date YYYY-MM-DD  Date stamp in output filename (default: today UTC)');
+          log('  --out PATH         Output path (default: .gsd-t/reports/token-usage-{DATE}.md)');
+          process.exit(0);
+        }
+        else {
+          error(`report tokens: unknown arg: ${a}`);
+          process.exit(2);
+        }
+      }
+      try {
+        const rep = require(path.join(__dirname, 'gsd-t-report-tokens.cjs'));
+        const res = rep.generateReport(rOpts);
+        log(`Wrote ${res.path}`);
+        const s = res.summary;
+        log(`  ${s.cws} CW(s) · ${s.turns} turn rows · ${s.compactions} compactions · ${s.sessions} session(s)`);
+        log(`  ${s.compactionEndedCWs}/${s.cws} CW${s.cws === 1 ? '' : 's'} ended by compaction · top tool: ${s.topTool || '—'}`);
+        process.exit(0);
+      } catch (e) {
+        error(e.message || String(e));
+        process.exit(3);
+      }
+      break;
+    }
     case "scan": {
       const exportFlag = args.find(a => a.startsWith('--export='));
       const exportFormat = exportFlag ? exportFlag.split('=')[1] : null;

package/bin/headless-auto-spawn.cjs

@@ -3,19 +3,26 @@
 /**
  * GSD-T Headless Auto-Spawn — Detached headless continuation
  *
- * When the runway estimator refuses a run (projected context ≥ stop band),
- * the caller invokes `autoSpawnHeadless()` to hand off to a detached child
- * process running `gsd-t headless {command} --log`. The interactive session
- * never blocks on the child (`child.unref()`), so the user retains their
- * terminal and can work on unrelated tasks. On child completion, a macOS
- * notification fires (T2). The interactive session surfaces the result via
- * a read-back banner on the next `gsd-t-resume` or `gsd-t-status` call (T4).
+ * Every GSD-T command spawn routes through `autoSpawnHeadless()` to a
+ * detached child process running `gsd-t headless {command} --log`. The
+ * interactive session never blocks on the child (`child.unref()`), so the
+ * user retains their terminal and can work on unrelated tasks. On child
+ * completion, a macOS notification fires (T2). The interactive session
+ * surfaces the result via a read-back banner on the next `gsd-t-resume`
+ * or `gsd-t-status` call (T4).
  *
  * Zero external dependencies (Node.js built-ins only).
  *
- * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
- * Consumers: commands/gsd-t-execute|wave|integrate|quick|debug.md (via runway
- *            estimator handoff), bin/runway-estimator.js (conceptual target).
+ * Contract: .gsd-t/contracts/headless-default-contract.md v2.0.0
+ *   - v2.0.0 (M43 D4): channel-separation invariant. Every command spawns.
+ *     No opt-out flag, no context-meter threshold gating, no `--in-session`
+ *     escape hatch. `shouldSpawnHeadless` is a constant `() => true`. The
+ *     `watch` parameter is accepted for caller backward-compat for one
+ *     version but ignored (deprecation warning emitted once per process).
+ * Consumers: every command file that spawns subagents (execute, wave, quick,
+ *            integrate, debug, scan, verify, complete-milestone, test-sync,
+ *            scan, gap-analysis, populate, feature, project, partition);
+ *            the `/gsd` router (Step 2 action-turn handoff).
  */
 
 const fs = require("fs");
@@ -43,8 +50,17 @@ module.exports = {
   writeSessionFile,
   writeContinueHereFile,
   markSessionCompleted,
+  // M43 D4 — channel-separation invariant. The helper is retained for
+  // backward-compat with any caller that imported it from a v1.x consumer;
+  // it now unconditionally returns true. See headless-default-contract
+  // v2.0.0 §Invariants.
+  shouldSpawnHeadless: () => true,
 };
 
+// M43 D4 — one-shot deprecation banner when a caller still passes `watch`
+// (or the never-shipped `inSession`). Module-level flag avoids log spam.
+let _deprecatedWatchWarned = false;
+
 // ── autoSpawnHeadless ────────────────────────────────────────────────────────
 
 /**
@@ -67,7 +83,23 @@ function autoSpawnHeadless(opts) {
   const continue_from = opts.continue_from || ".";
   const projectDir = opts.projectDir || process.cwd();
   const context = opts.context || opts.sessionContext || null;
-  const watch = opts.watch === true;
+  // M43 D4 — `watch` is accepted for caller backward-compat but IGNORED.
+  // `inSession` was never shipped; accept+ignore for the same reason.
+  // Under headless-default-contract v2.0.0 every spawn goes headless; the
+  // only in-session surface is the `/gsd` router dialog channel, which is
+  // upstream of this function. One-shot deprecation warning on stderr.
+  const legacyWatch = opts.watch === true;
+  const legacyInSession = opts.inSession === true;
+  if ((legacyWatch || legacyInSession) && !_deprecatedWatchWarned) {
+    _deprecatedWatchWarned = true;
+    try {
+      process.stderr.write(
+        "[headless-default] `watch`/`inSession` flag is deprecated under headless-default-contract v2.0.0 — every spawn is headless; caller hint ignored.\n",
+      );
+    } catch (_) {
+      /* best-effort */
+    }
+  }
   const spawnType = opts.spawnType || "primary";
 
   if (!command || typeof command !== "string") {
@@ -79,44 +111,6 @@ function autoSpawnHeadless(opts) {
     );
   }
 
-  // Propagation rules (headless-default-contract §2):
-  //   watch=true + primary    → signal in-context fallback (caller uses Task)
-  //   watch=true + validation → warn on stderr; proceed headless
-  //   watch=false             → headless (default behavior)
-  if (watch && spawnType === "primary") {
-    // M39 D2 — append watch-progress tree below banner (best-effort).
-    // Banner here is the in-context-fallback signal printed by the caller;
-    // we don't own it, so we only render the tree to stdout. Never throws.
-    try {
-      const wp = require("./watch-progress.js");
-      const stateDir = path.join(projectDir, ".gsd-t", ".watch-state");
-      const tree = wp.buildTree(stateDir);
-      const rendered = wp.renderTree(tree, { currentAgent: null });
-      if (rendered) {
-        // eslint-disable-next-line no-console
-        console.log(rendered);
-      }
-    } catch (_) {
-      /* watch-progress is best-effort; never crash the watch */
-    }
-    return {
-      id: null,
-      pid: null,
-      logPath: null,
-      timestamp: new Date().toISOString(),
-      mode: "in-context",
-    };
-  }
-  if (watch && spawnType === "validation") {
-    try {
-      process.stderr.write(
-        `[headless-default] --watch ignored for validation spawn type: ${spawnType}\n`,
-      );
-    } catch (_) {
-      /* best effort */
-    }
-  }
-
   const timestamp = new Date().toISOString();
   const id = makeSessionId(command, new Date());
   const logPath = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
@@ -124,6 +118,32 @@ function autoSpawnHeadless(opts) {
   ensureDir(path.join(projectDir, LOG_DIR_REL));
   ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
 
+  // M43 D6-T4 — Ensure dashboard is running (idempotent; no-op if already up).
+  // Must happen BEFORE the URL banner print (D6-T3) so the link is live.
+  // Never throws — autostart is best-effort.
+  let autostartInfo = null;
+  try {
+    const { ensureDashboardRunning } = require("../scripts/gsd-t-dashboard-autostart.cjs");
+    autostartInfo = ensureDashboardRunning({ projectDir });
+  } catch (_) {
+    /* best-effort; fall through without banner port info */
+  }
+
+  // M43 D6-T3 — Live transcript URL banner. Printed for every spawn so the
+  // viewer at :PORT is "the" primary watching surface. Never throws.
+  // Text is coordinated with D4 — exact line shape is part of
+  // dashboard-server-contract.md §Banner Format.
+  try {
+    let port = autostartInfo && autostartInfo.port;
+    if (!port) {
+      const { projectScopedDefaultPort } = require("../scripts/gsd-t-dashboard-server.js");
+      port = projectScopedDefaultPort(projectDir);
+    }
+    process.stdout.write(`▶ Live transcript: http://127.0.0.1:${port}/transcript/${id}\n`);
+  } catch (_) {
+    /* best-effort — never crash the spawn on banner failure */
+  }
+
   // Handoff-lock gate (m36 gap-fix T2). Only engaged when the caller
   // supplies a `sessionId` — existing callers that do not pass one keep
   // the pre-m36 behavior unchanged. When engaged, the lock is held

package/bin/headless-auto-spawn.js

@@ -43,8 +43,13 @@ module.exports = {
   writeSessionFile,
   writeContinueHereFile,
   markSessionCompleted,
+  // M43 D4 — channel-separation invariant; see .cjs twin.
+  shouldSpawnHeadless: () => true,
 };
 
+// M43 D4 — one-shot deprecation banner (legacy `.js` copy mirrors `.cjs`).
+let _deprecatedWatchWarned = false;
+
 // ── autoSpawnHeadless ────────────────────────────────────────────────────────
 
 /**
@@ -67,7 +72,19 @@ function autoSpawnHeadless(opts) {
   const continue_from = opts.continue_from || ".";
   const projectDir = opts.projectDir || process.cwd();
   const context = opts.context || opts.sessionContext || null;
-  const watch = opts.watch === true;
+  // M43 D4 — `watch`/`inSession` ignored under v2.0.0 channel-separation.
+  const legacyWatch = opts.watch === true;
+  const legacyInSession = opts.inSession === true;
+  if ((legacyWatch || legacyInSession) && !_deprecatedWatchWarned) {
+    _deprecatedWatchWarned = true;
+    try {
+      process.stderr.write(
+        "[headless-default] `watch`/`inSession` flag is deprecated under headless-default-contract v2.0.0 — every spawn is headless; caller hint ignored.\n",
+      );
+    } catch (_) {
+      /* best-effort */
+    }
+  }
   const spawnType = opts.spawnType || "primary";
 
   if (!command || typeof command !== "string") {
@@ -79,29 +96,6 @@ function autoSpawnHeadless(opts) {
     );
   }
 
-  // Propagation rules (headless-default-contract §2):
-  //   watch=true + primary    → signal in-context fallback (caller uses Task)
-  //   watch=true + validation → warn on stderr; proceed headless
-  //   watch=false             → headless (default behavior)
-  if (watch && spawnType === "primary") {
-    return {
-      id: null,
-      pid: null,
-      logPath: null,
-      timestamp: new Date().toISOString(),
-      mode: "in-context",
-    };
-  }
-  if (watch && spawnType === "validation") {
-    try {
-      process.stderr.write(
-        `[headless-default] --watch ignored for validation spawn type: ${spawnType}\n`,
-      );
-    } catch (_) {
-      /* best effort */
-    }
-  }
-
   const timestamp = new Date().toISOString();
   const id = makeSessionId(command, new Date());
   const logPath = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);

package/bin/runway-estimator.cjs

@@ -0,0 +1,212 @@
+'use strict';
+/**
+ * GSD-T Runway Estimator (M43 D5 — dialog-channel growth meter)
+ *
+ * Under M43's channel-separation model, the only thing that runs in the
+ * in-session channel is the `/gsd` router dialog. Everything else spawns.
+ * This module reads the per-turn usage rows the M43 D1 capture writes to
+ * `.gsd-t/metrics/token-usage.jsonl` (schema v2) and surfaces a one-line
+ * "~N turns to `/compact`" warning to the router.
+ *
+ * Scope (revised 2026-04-21 per M43 partition.md §D5):
+ *   - Read-only. Never refuses, never reroutes. Under always-headless there
+ *     is nothing to reroute *to*.
+ *   - Median-of-deltas growth slope (outlier-resistant; a single spike turn
+ *     does not flip `shouldWarn`).
+ *   - Zero external deps. `.cjs` so it loads in both ESM-default projects
+ *     and CJS projects without transpilation.
+ *
+ * Contracts:
+ *   - .gsd-t/contracts/context-meter-contract.md §Dialog Growth Meter
+ *   - .gsd-t/contracts/metrics-schema-contract.md (schema v2)
+ *
+ * Consumers:
+ *   - commands/gsd.md (router warning footer)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_K = 5;
+const DEFAULT_MODEL_CONTEXT_CAP = 200000;
+// Claude Code starts auto-compacting ~8% before the model window fills, so the
+// effective dialog ceiling is 0.92 × modelContextCap.
+const PRE_COMPACT_HEADROOM = 0.92;
+const DEFAULT_WARN_THRESHOLD_TURNS = 5;
+const MIN_HISTORY = 3;
+
+// ── Row loading ──────────────────────────────────────────────────────
+
+function _safeParse(line) {
+  const s = String(line || '').trim();
+  if (!s || s[0] !== '{') return null;
+  try { return JSON.parse(s); } catch (_) { return null; }
+}
+
+/**
+ * Load in-session rows for the given session from the canonical sink.
+ *
+ * @param {string} projectDir
+ * @param {string} sessionId
+ * @returns {object[]}  schema-v2 rows, unsorted
+ */
+function _loadInSessionRows(projectDir, sessionId) {
+  const p = path.join(projectDir, '.gsd-t', 'metrics', 'token-usage.jsonl');
+  if (!fs.existsSync(p)) return [];
+  let text;
+  try { text = fs.readFileSync(p, 'utf8'); } catch (_) { return []; }
+  const rows = [];
+  for (const line of text.split(/\r?\n/)) {
+    const j = _safeParse(line);
+    if (!j) continue;
+    if (j.sessionType !== 'in-session') continue;
+    if (sessionId != null && j.session_id !== sessionId) continue;
+    rows.push(j);
+  }
+  return rows;
+}
+
+// ── Math helpers ─────────────────────────────────────────────────────
+
+function _median(arr) {
+  if (!arr.length) return 0;
+  const sorted = arr.slice().sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+/**
+ * Deterministic ordering for per-turn rows. Prefers timestamp (`ts`) when
+ * present (monotonic per session), falls back to `turn_id` string compare.
+ */
+function _sortTurns(rows) {
+  return rows.slice().sort((a, b) => {
+    const ta = a.ts || '';
+    const tb = b.ts || '';
+    if (ta !== tb) return ta < tb ? -1 : 1;
+    const ia = String(a.turn_id || '');
+    const ib = String(b.turn_id || '');
+    if (ia !== ib) return ia < ib ? -1 : 1;
+    return 0;
+  });
+}
+
+/**
+ * Compute the dialog-growth signal for one session.
+ *
+ * Reads the last K in-session turns for `sessionId` from
+ * `.gsd-t/metrics/token-usage.jsonl`, computes the median of turn-over-turn
+ * `input_tokens` deltas (robust to single-turn spikes), then predicts how
+ * many turns remain before dialog input crosses the pre-auto-compact ceiling
+ * (`modelContextCap × 0.92`).
+ *
+ * Returns `{ shouldWarn: false, reason: 'insufficient_history' }` when fewer
+ * than `MIN_HISTORY` in-session turns exist for the session.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir
+ * @param {string} opts.sessionId                required
+ * @param {number} [opts.k]                      default 5 (last K turns)
+ * @param {number} [opts.modelContextCap]        default 200000
+ * @param {number} [opts.warnThresholdTurns]     default 5
+ * @returns {{
+ *   shouldWarn: boolean,
+ *   slope: number,
+ *   median_delta: number,
+ *   latest_input_tokens: number,
+ *   predicted_turns_to_compact: number,
+ *   k: number,
+ *   history_len: number,
+ *   reason?: string
+ * }}
+ */
+function estimateDialogGrowth(opts) {
+  const projectDir = (opts && opts.projectDir) || '.';
+  const sessionId = opts && opts.sessionId;
+  const k = (opts && Number.isFinite(opts.k) && opts.k > 0) ? Math.floor(opts.k) : DEFAULT_K;
+  const cap = (opts && Number.isFinite(opts.modelContextCap) && opts.modelContextCap > 0)
+    ? opts.modelContextCap
+    : DEFAULT_MODEL_CONTEXT_CAP;
+  const warnThreshold = (opts && Number.isFinite(opts.warnThresholdTurns) && opts.warnThresholdTurns > 0)
+    ? opts.warnThresholdTurns
+    : DEFAULT_WARN_THRESHOLD_TURNS;
+
+  const empty = {
+    shouldWarn: false,
+    slope: 0,
+    median_delta: 0,
+    latest_input_tokens: 0,
+    predicted_turns_to_compact: Infinity,
+    k,
+    history_len: 0,
+  };
+
+  if (!sessionId) {
+    return { ...empty, reason: 'missing_session_id' };
+  }
+
+  const allRows = _loadInSessionRows(projectDir, sessionId);
+  if (allRows.length === 0) {
+    return { ...empty, reason: 'no_rows' };
+  }
+
+  const sorted = _sortTurns(allRows);
+  const window = sorted.slice(-k);
+
+  if (window.length < MIN_HISTORY) {
+    return { ...empty, history_len: window.length, reason: 'insufficient_history' };
+  }
+
+  // Per-turn input token footprint. Schema v2 writes `inputTokens` (camel)
+  // via the token-capture wrapper; older rows may carry the raw envelope.
+  const inputs = window.map(r => {
+    if (Number.isFinite(r.inputTokens)) return r.inputTokens;
+    if (r.usage && Number.isFinite(r.usage.input_tokens)) return r.usage.input_tokens;
+    return 0;
+  });
+
+  const deltas = [];
+  for (let i = 1; i < inputs.length; i++) {
+    deltas.push(inputs[i] - inputs[i - 1]);
+  }
+
+  const median_delta = _median(deltas);
+  const slope = median_delta;
+  const latest_input_tokens = inputs[inputs.length - 1];
+
+  const ceiling = cap * PRE_COMPACT_HEADROOM;
+  let predicted_turns_to_compact;
+  if (slope > 0) {
+    const headroom = ceiling - latest_input_tokens;
+    predicted_turns_to_compact = headroom <= 0 ? 0 : Math.ceil(headroom / slope);
+  } else {
+    predicted_turns_to_compact = Infinity;
+  }
+
+  const shouldWarn = Number.isFinite(predicted_turns_to_compact) && predicted_turns_to_compact <= warnThreshold;
+
+  return {
+    shouldWarn,
+    slope,
+    median_delta,
+    latest_input_tokens,
+    predicted_turns_to_compact,
+    k,
+    history_len: window.length,
+  };
+}
+
+module.exports = {
+  estimateDialogGrowth,
+  // Exposed for unit tests; not part of the stable contract.
+  _internal: {
+    _median,
+    _sortTurns,
+    _loadInSessionRows,
+    DEFAULT_K,
+    DEFAULT_MODEL_CONTEXT_CAP,
+    PRE_COMPACT_HEADROOM,
+    DEFAULT_WARN_THRESHOLD_TURNS,
+    MIN_HISTORY,
+  },
+};