@tekyzinc/gsd-t 2.74.13 → 2.76.10

package/bin/gsd-t.js

@@ -18,6 +18,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const readline = require("readline");
 const { execFileSync, spawn: cpSpawn } = require("child_process");
 const debugLedger = require(path.join(__dirname, "debug-ledger.js"));
 
@@ -376,6 +377,311 @@ function addHeartbeatHook(hooks, event, cmd) {
   return true;
 }
 
+// ─── Context Meter ──────────────────────────────────────────────────────────
+
+const CONTEXT_METER_SCRIPT = "gsd-t-context-meter.js";
+const CONTEXT_METER_DEPS_DIR = "context-meter";
+const CONTEXT_METER_CONFIG_TEMPLATE = "context-meter-config.json";
+const CONTEXT_METER_CONFIG_DEST = path.join(".gsd-t", "context-meter-config.json");
+const CONTEXT_METER_GITIGNORE_ENTRIES = [
+  ".gsd-t/.context-meter-state.json",
+  ".gsd-t/context-meter.log",
+];
+const CONTEXT_METER_HOOK_MARKER = "gsd-t-context-meter";
+const CONTEXT_METER_HOOK_COMMAND =
+  'node "$CLAUDE_PROJECT_DIR/scripts/gsd-t-context-meter.js"';
+
+// Append entries to {projectDir}/.gitignore. Each entry added only if absent.
+// Idempotent. Returns true if any entries were added, false otherwise.
+function ensureGitignoreEntries(projectDir, entries) {
+  const gitignorePath = path.join(projectDir, ".gitignore");
+  if (isSymlink(gitignorePath)) {
+    warn("Skipping .gitignore — target is a symlink");
+    return false;
+  }
+  let content = "";
+  try {
+    if (fs.existsSync(gitignorePath)) {
+      content = fs.readFileSync(gitignorePath, "utf8");
+    }
+  } catch (e) {
+    warn(`Failed to read .gitignore: ${e.message}`);
+    return false;
+  }
+  const existingLines = new Set(
+    content.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+  );
+  const toAdd = entries.filter((e) => !existingLines.has(e));
+  if (toAdd.length === 0) return false;
+  try {
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, toAdd.join("\n") + "\n");
+    } else {
+      const prefix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+      const block =
+        "\n# GSD-T context meter (session state — do not commit)\n" +
+        toAdd.join("\n") +
+        "\n";
+      fs.appendFileSync(gitignorePath, prefix + block);
+    }
+    return true;
+  } catch (e) {
+    warn(`Failed to append to .gitignore: ${e.message}`);
+    return false;
+  }
+}
+
+// Install the Context Meter into a project directory.
+// Copies scripts/gsd-t-context-meter.js, scripts/context-meter/*.js (runtime
+// only — skips .test.js and test-injector.js), and the config template (if
+// missing). Also appends entries to .gitignore.
+function installContextMeter(projectDir) {
+  try {
+    // 1. Copy gsd-t-context-meter.js → {projectDir}/scripts/
+    const projectScriptsDir = path.join(projectDir, "scripts");
+    if (!fs.existsSync(projectScriptsDir)) {
+      try {
+        fs.mkdirSync(projectScriptsDir, { recursive: true });
+      } catch (e) {
+        warn(`Failed to create scripts/: ${e.message}`);
+        return false;
+      }
+    }
+    const scriptSrc = path.join(PKG_SCRIPTS, CONTEXT_METER_SCRIPT);
+    const scriptDest = path.join(projectScriptsDir, CONTEXT_METER_SCRIPT);
+    if (!fs.existsSync(scriptSrc)) {
+      warn(`${CONTEXT_METER_SCRIPT} not found in package — skipping context meter`);
+      return false;
+    }
+    if (!isSymlink(scriptDest)) {
+      const srcContent = fs.readFileSync(scriptSrc, "utf8");
+      const destContent = fs.existsSync(scriptDest)
+        ? fs.readFileSync(scriptDest, "utf8")
+        : "";
+      if (normalizeEol(srcContent) !== normalizeEol(destContent)) {
+        fs.copyFileSync(scriptSrc, scriptDest);
+        try {
+          fs.chmodSync(scriptDest, 0o755);
+        } catch {}
+      }
+    }
+
+    // 2. Copy scripts/context-meter/*.js (runtime files only)
+    const depsSrcDir = path.join(PKG_SCRIPTS, CONTEXT_METER_DEPS_DIR);
+    const depsDestDir = path.join(projectScriptsDir, CONTEXT_METER_DEPS_DIR);
+    if (fs.existsSync(depsSrcDir)) {
+      if (!fs.existsSync(depsDestDir)) {
+        try {
+          fs.mkdirSync(depsDestDir, { recursive: true });
+        } catch (e) {
+          warn(`Failed to create scripts/${CONTEXT_METER_DEPS_DIR}/: ${e.message}`);
+          return false;
+        }
+      }
+      let depFiles = [];
+      try {
+        depFiles = fs.readdirSync(depsSrcDir);
+      } catch (e) {
+        warn(`Failed to read ${CONTEXT_METER_DEPS_DIR}/: ${e.message}`);
+        return false;
+      }
+      for (const fname of depFiles) {
+        // Skip test files and test-only infrastructure
+        if (fname.includes(".test.")) continue;
+        if (fname === "test-injector.js") continue;
+        const fsrc = path.join(depsSrcDir, fname);
+        const fdest = path.join(depsDestDir, fname);
+        try {
+          const stat = fs.statSync(fsrc);
+          if (!stat.isFile()) continue;
+        } catch {
+          continue;
+        }
+        if (isSymlink(fdest)) continue;
+        try {
+          const srcContent = fs.readFileSync(fsrc, "utf8");
+          const destContent = fs.existsSync(fdest)
+            ? fs.readFileSync(fdest, "utf8")
+            : "";
+          if (normalizeEol(srcContent) !== normalizeEol(destContent)) {
+            fs.copyFileSync(fsrc, fdest);
+          }
+        } catch (e) {
+          warn(`Failed to copy ${CONTEXT_METER_DEPS_DIR}/${fname}: ${e.message}`);
+        }
+      }
+    }
+
+    // 3. Copy config template → {projectDir}/.gsd-t/context-meter-config.json
+    //    ONLY if the destination does not already exist (never overwrite user config).
+    const configSrc = path.join(PKG_TEMPLATES, CONTEXT_METER_CONFIG_TEMPLATE);
+    const configDest = path.join(projectDir, CONTEXT_METER_CONFIG_DEST);
+    const gsdtDir = path.dirname(configDest);
+    if (!fs.existsSync(gsdtDir)) {
+      try {
+        fs.mkdirSync(gsdtDir, { recursive: true });
+      } catch (e) {
+        warn(`Failed to create .gsd-t/: ${e.message}`);
+      }
+    }
+    if (fs.existsSync(configSrc) && !fs.existsSync(configDest)) {
+      if (!isSymlink(configDest)) {
+        try {
+          fs.copyFileSync(configSrc, configDest);
+        } catch (e) {
+          warn(`Failed to copy context-meter-config.json: ${e.message}`);
+        }
+      }
+    }
+
+    // 4. Append .gitignore entries
+    ensureGitignoreEntries(projectDir, CONTEXT_METER_GITIGNORE_ENTRIES);
+
+    return true;
+  } catch (e) {
+    warn(`installContextMeter failed: ${e.message}`);
+    return false;
+  }
+}
+
+// Register the Context Meter PostToolUse hook in ~/.claude/settings.json.
+// Idempotent — if an existing hook references CONTEXT_METER_HOOK_MARKER the
+// command string is refreshed in-place. All other settings/hooks preserved.
+// Returns { installed: bool, action: "added"|"updated"|"noop" }.
+function configureContextMeterHooks(settingsPath) {
+  const targetPath = settingsPath || SETTINGS_JSON;
+  let settings = {};
+  const fileExists = fs.existsSync(targetPath);
+  if (fileExists) {
+    try {
+      settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+      if (!settings || typeof settings !== "object") settings = {};
+    } catch {
+      warn("settings.json has invalid JSON — cannot configure context meter hook");
+      return { installed: false, action: "noop" };
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+
+  const cmd = CONTEXT_METER_HOOK_COMMAND;
+  let action = "noop";
+  let found = false;
+
+  for (const entry of settings.hooks.PostToolUse) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (h && typeof h.command === "string" && h.command.includes(CONTEXT_METER_HOOK_MARKER)) {
+        found = true;
+        if (h.command !== cmd) {
+          h.command = cmd;
+          action = "updated";
+        } else if (action === "noop") {
+          action = "noop";
+        }
+      }
+    }
+  }
+
+  if (!found) {
+    settings.hooks.PostToolUse.push({
+      matcher: "*",
+      hooks: [{ type: "command", command: cmd }],
+    });
+    action = "added";
+  }
+
+  if (action === "noop") {
+    return { installed: true, action: "noop" };
+  }
+
+  if (isSymlink(targetPath)) {
+    warn("Skipping settings.json write — target is a symlink");
+    return { installed: false, action: "noop" };
+  }
+  try {
+    fs.writeFileSync(targetPath, JSON.stringify(settings, null, 2));
+  } catch (e) {
+    warn(`Failed to write settings.json: ${e.message}`);
+    return { installed: false, action: "noop" };
+  }
+  return { installed: true, action };
+}
+
+// Interactive prompt for the Anthropic API key env var.
+// Skips if not a TTY or if the env var is already set.
+// Never writes the key anywhere — just prints the export command for the user
+// to paste into their shell profile themselves. Always non-blocking.
+async function promptForApiKeyIfMissing(envVarName) {
+  const varName = envVarName || "ANTHROPIC_API_KEY";
+  if (!process.stdout.isTTY || !process.stdin.isTTY) return "";
+  if (process.env[varName]) return process.env[varName];
+
+  heading("Context Meter — Anthropic API Key");
+  log("");
+  log(`  ${YELLOW}⚠${RESET}  Context Meter: ${varName} is not set.`);
+  log(`     The hook uses Anthropic's count_tokens API (free, not billed) to measure`);
+  log(`     real context window usage. Without it, the meter falls back to heuristics.`);
+  log(`     Get a key: https://console.anthropic.com/settings/keys`);
+  log("");
+
+  let rl;
+  try {
+    rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  } catch (e) {
+    warn(`Could not open API key prompt: ${e.message}`);
+    return "";
+  }
+
+  return new Promise((resolve) => {
+    try {
+      rl.question("  Paste key now, or press Enter to skip: ", (answer) => {
+        try {
+          const key = (answer || "").trim();
+          if (key.length === 0) {
+            log("");
+            info(`Skipped. Set ${varName} later or run 'gsd-t doctor' to re-check.`);
+            log("");
+          } else {
+            log("");
+            success("Got it. Add this line to your shell profile (~/.zshrc or ~/.bashrc):");
+            log("");
+            log(`    ${DIM}export ${varName}="${key}"${RESET}`);
+            log("");
+            log("  Re-open your shell or run the export command to activate.");
+            log("");
+          }
+          resolve(key);
+        } finally {
+          try { rl.close(); } catch {}
+        }
+      });
+    } catch (e) {
+      warn(`API key prompt failed: ${e.message}`);
+      try { rl.close(); } catch {}
+      resolve("");
+    }
+  });
+}
+
+// Resolve the apiKeyEnvVar from the project's context-meter-config.json
+// Falls back to "ANTHROPIC_API_KEY" if loader unavailable or config absent.
+function resolveApiKeyEnvVar(projectDir) {
+  try {
+    const loader = require(path.join(PKG_ROOT, "bin", "context-meter-config.cjs"));
+    if (loader && typeof loader.loadConfig === "function") {
+      const cfg = loader.loadConfig(projectDir || process.cwd());
+      if (cfg && typeof cfg.apiKeyEnvVar === "string" && cfg.apiKeyEnvVar.length > 0) {
+        return cfg.apiKeyEnvVar;
+      }
+    }
+  } catch {
+    // Fall through to default
+  }
+  return "ANTHROPIC_API_KEY";
+}
+
 // ─── Update Check Hook ──────────────────────────────────────────────────────
 
 const UPDATE_CHECK_SCRIPT = "gsd-t-update-check.js";
@@ -884,7 +1190,7 @@ function appendGsdtToClaudeMd(template) {
   info("Your existing content was preserved.");
 }
 
-function doInstall(opts = {}) {
+async function doInstall(opts = {}) {
   const isUpdate = opts.update || false;
   heading(`${isUpdate ? "Updating" : "Installing"} GSD-T ${versionLink()}`);
   log("");
@@ -912,12 +1218,23 @@ function doInstall(opts = {}) {
   heading("Utility Scripts");
   installUtilityScripts();
 
+  heading("Context Meter (PostToolUse)");
+  const cmHook = configureContextMeterHooks(SETTINGS_JSON);
+  if (cmHook.installed) {
+    if (cmHook.action === "added") success("Context meter PostToolUse hook added");
+    else if (cmHook.action === "updated") success("Context meter hook command refreshed");
+    else info("Context meter hook already configured");
+  }
+
   heading("Graph Engine (CGC)");
   installCgc();
 
   saveInstalledVersion();
 
   showInstallSummary(gsdtCommands.length, utilityCommands.length);
+
+  // Interactive prompt (skipped silently in non-TTY shells)
+  await promptForApiKeyIfMissing(resolveApiKeyEnvVar(process.cwd()));
 }
 
 function showInstallSummary(gsdtCount, utilCount) {
@@ -942,7 +1259,7 @@ function showInstallSummary(gsdtCount, utilCount) {
   log("");
 }
 
-function doUpdate() {
+async function doUpdate() {
   const installedVersion = getInstalledVersion();
 
   if (installedVersion === PKG_VERSION) {
@@ -959,7 +1276,7 @@ function doUpdate() {
     heading(`Updating GSD-T: ${versionLink(installedVersion)} → ${versionLink()}`);
   }
 
-  doInstall({ update: true });
+  await doInstall({ update: true });
 }
 
 function initClaudeMd(projectDir, projectName, today) {
@@ -1092,7 +1409,7 @@ function writeTemplateFile(templateName, destPath, label, projectName, today) {
   }
 }
 
-function doInit(projectName) {
+async function doInit(projectName) {
   if (!projectName) projectName = path.basename(process.cwd());
 
   if (!validateProjectName(projectName)) {
@@ -1112,9 +1429,24 @@ function doInit(projectName) {
   initGsdtDir(projectDir, projectName, today);
   copyBinToolsToProject(projectDir, projectName);
 
+  // Context Meter: copy script + deps + config template, append .gitignore,
+  // register the global PostToolUse hook.
+  if (installContextMeter(projectDir)) {
+    success("Context meter installed (scripts/, config template, .gitignore)");
+  }
+  const cmHook = configureContextMeterHooks(SETTINGS_JSON);
+  if (cmHook.installed) {
+    if (cmHook.action === "added") success("Context meter PostToolUse hook added");
+    else if (cmHook.action === "updated") success("Context meter hook command refreshed");
+    else info("Context meter hook already configured");
+  }
+
   if (registerProject(projectDir)) success("Registered in ~/.claude/.gsd-t-projects");
 
   showInitTree(projectDir);
+
+  // Interactive prompt (skipped silently in non-TTY shells)
+  await promptForApiKeyIfMissing(resolveApiKeyEnvVar(projectDir));
 }
 
 function showInitTree(projectDir) {
@@ -1149,10 +1481,83 @@ function doStatus() {
   showStatusCommands();
   showStatusConfig();
   showStatusTeams();
+  showStatusContextMeter();
   showStatusProject();
   log("");
 }
 
+function formatRelativeTime(timestampIso) {
+  const then = Date.parse(timestampIso);
+  if (!Number.isFinite(then)) return "unknown";
+  const deltaSec = Math.max(0, Math.floor((Date.now() - then) / 1000));
+  if (deltaSec < 60) return `${deltaSec}s ago`;
+  if (deltaSec < 3600) return `${Math.floor(deltaSec / 60)}m ago`;
+  if (deltaSec < 86400) return `${Math.floor(deltaSec / 3600)}h ago`;
+  return `${Math.floor(deltaSec / 86400)} days ago`;
+}
+
+function showStatusContextMeter() {
+  heading("Context Meter");
+  const cwd = process.cwd();
+  const statePath = path.join(cwd, ".gsd-t", ".context-meter-state.json");
+
+  let state = null;
+  try {
+    if (fs.existsSync(statePath)) {
+      state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    }
+  } catch {
+    state = null;
+  }
+
+  if (!state || typeof state !== "object") {
+    log(`  ${DIM}Context: N/A (meter hook not run this session)${RESET}`);
+    return;
+  }
+
+  // Error case: inputTokens === 0 AND lastError set
+  if (state.lastError && state.inputTokens === 0) {
+    const code = (state.lastError && state.lastError.code) || "unknown";
+    const rel = state.timestamp ? formatRelativeTime(state.timestamp) : "unknown";
+    log(`  ${DIM}Context: N/A (meter error: ${code}) — last check ${rel}${RESET}`);
+    return;
+  }
+
+  // Require minimum viable fields for a fresh reading
+  if (
+    typeof state.pct !== "number" ||
+    typeof state.modelWindowSize !== "number" ||
+    typeof state.threshold !== "string" ||
+    typeof state.timestamp !== "string"
+  ) {
+    log(`  ${DIM}Context: N/A (meter hook not run this session)${RESET}`);
+    return;
+  }
+
+  const pctStr = state.pct.toFixed(1);
+  const rel = formatRelativeTime(state.timestamp);
+  const ageMs = Date.now() - Date.parse(state.timestamp);
+  const stale = !Number.isFinite(ageMs) || ageMs > 5 * 60 * 1000;
+  const staleSuffix = stale ? " (stale)" : "";
+
+  // v3.0.0 three-band: normal (green) / warn (yellow) / stop (bold red).
+  let color = DIM;
+  switch (state.threshold) {
+    case "normal":
+      color = GREEN;
+      break;
+    case "warn":
+      color = YELLOW;
+      break;
+    case "stop":
+      color = BOLD + RED;
+      break;
+  }
+
+  const line = `Context: ${pctStr}% of ${state.modelWindowSize} tokens (${state.threshold} band) — last check ${rel}${staleSuffix}`;
+  log(`  ${color}${line}${RESET}`);
+}
+
 function showStatusVersion() {
   const installedVersion = getInstalledVersion();
   if (installedVersion) {
@@ -1486,8 +1891,8 @@ function exportUniversalRulesForNpm() {
   }
 }
 
-function doUpdateAll() {
-  updateGlobalCommands();
+async function doUpdateAll() {
+  await updateGlobalCommands();
   heading("Updating registered projects...");
   log("");
 
@@ -1511,9 +1916,9 @@ function doUpdateAll() {
   showUpdateAllSummary(projects.length, counts, playwrightMissing, swaggerMissing, syncCount);
 }
 
-function updateGlobalCommands() {
+async function updateGlobalCommands() {
   if (getInstalledVersion() !== PKG_VERSION) {
-    doInstall({ update: true });
+    await doInstall({ update: true });
   } else {
     heading(`GSD-T ${versionLink()}`);
     success("Global commands already up to date");
@@ -1549,7 +1954,8 @@ function updateSingleProject(projectDir, counts) {
   const changelogCreated = createProjectChangelog(projectDir, projectName);
   const binToolsCopied = copyBinToolsToProject(projectDir, projectName);
   const archiveRan = runProgressArchiveMigration(projectDir, projectName);
-  if (guardAdded || changelogCreated || binToolsCopied || archiveRan) {
+  const taskCounterRetired = runTaskCounterRetirementMigration(projectDir, projectName);
+  if (guardAdded || changelogCreated || binToolsCopied || archiveRan || taskCounterRetired) {
     counts.updated++;
   } else {
     info(`${projectName} — already up to date`);
@@ -1560,7 +1966,7 @@ function updateSingleProject(projectDir, counts) {
 // Bin tools that should ship with every registered project. Listed here so adding
 // a new tool only requires appending to this array. Use .cjs extension so they
 // always run as CommonJS regardless of the project's package.json "type" field.
-const PROJECT_BIN_TOOLS = ["archive-progress.cjs", "log-tail.cjs", "context-budget-audit.cjs", "task-counter.cjs"];
+const PROJECT_BIN_TOOLS = ["archive-progress.cjs", "log-tail.cjs", "context-budget-audit.cjs", "context-meter-config.cjs"];
 
 function copyBinToolsToProject(projectDir, projectName) {
   const projectBinDir = path.join(projectDir, "bin");
@@ -1634,6 +2040,55 @@ function runProgressArchiveMigration(projectDir, projectName) {
   }
 }
 
+// One-shot migration: retire the v2.74.12 task-counter proxy. Removes the stale
+// bin/task-counter.cjs and any leftover .task-counter* state/config files from
+// downstream projects, then writes a marker so subsequent runs are no-ops. The
+// context meter hook (M34) is the authoritative context-burn signal now.
+function runTaskCounterRetirementMigration(projectDir, projectName) {
+  const gsdtDir = path.join(projectDir, ".gsd-t");
+  if (!fs.existsSync(gsdtDir)) return false;
+
+  const markerPath = path.join(gsdtDir, ".task-counter-retired-v1");
+  if (fs.existsSync(markerPath)) return false;
+
+  const targets = [
+    path.join(projectDir, "bin", "task-counter.cjs"),
+    path.join(gsdtDir, "task-counter-config.json"),
+    path.join(gsdtDir, ".task-counter-state.json"),
+    path.join(gsdtDir, ".task-counter"),
+  ];
+
+  let removed = 0;
+  for (const target of targets) {
+    try {
+      if (fs.existsSync(target)) {
+        try { if (fs.lstatSync(target).isSymbolicLink()) continue; } catch {}
+        fs.unlinkSync(target);
+        removed++;
+      }
+    } catch (e) {
+      warn(`${projectName} — failed to remove ${path.basename(target)}: ${e.message}`);
+    }
+  }
+
+  try {
+    fs.writeFileSync(
+      markerPath,
+      `# task-counter-retired-v1\nApplied: ${new Date().toISOString()}\nReplaced-by: scripts/gsd-t-context-meter.js (M34)\n`
+    );
+  } catch (e) {
+    warn(`${projectName} — failed to write retirement marker: ${e.message}`);
+    return false;
+  }
+
+  if (removed > 0) {
+    info(`${projectName} — retired task-counter (removed ${removed} file(s))`);
+  } else {
+    info(`${projectName} — retired task-counter (no legacy files found)`);
+  }
+  return true;
+}
+
 function showUpdateAllSummary(total, counts, playwrightMissing, swaggerMissing, syncCount) {
   log("");
   heading("Update All Complete");
@@ -1787,7 +2242,120 @@ function checkDoctorCgc() {
   return issues;
 }
 
-function doDoctor() {
+// Verify context meter wiring: API key env var, hook registration,
+// hook script presence, config validity, and a live count_tokens dry-run.
+// Returns number of issues (RED results). Mirrors checkDoctorCgc shape.
+async function checkDoctorContextMeter(projectDir) {
+  let issues = 0;
+  heading("Context Meter");
+
+  const cwd = projectDir || process.cwd();
+
+  // Load config (used by checks 1, 4, and 5). Missing file → defaults; invalid
+  // JSON or schema-mismatch → throws (handled in Check 4).
+  let cfg = null;
+  let cfgLoadErr = null;
+  try {
+    const { loadConfig } = require("./context-meter-config.cjs");
+    cfg = loadConfig(cwd);
+  } catch (e) {
+    cfgLoadErr = e;
+  }
+  const apiKeyEnvVar = (cfg && cfg.apiKeyEnvVar) || "ANTHROPIC_API_KEY";
+
+  // Check 1: API key env var present
+  const apiKeyValue = process.env[apiKeyEnvVar];
+  const apiKeyPresent = typeof apiKeyValue === "string" && apiKeyValue.length > 0;
+  if (apiKeyPresent) {
+    success(`API key present ($${apiKeyEnvVar})`);
+  } else {
+    error(`Missing API key: set $${apiKeyEnvVar} — https://console.anthropic.com/settings/keys`);
+    issues++;
+  }
+
+  // Check 2: Hook registered in ~/.claude/settings.json
+  let hookRegistered = false;
+  try {
+    if (fs.existsSync(SETTINGS_JSON)) {
+      const raw = fs.readFileSync(SETTINGS_JSON, "utf8");
+      const settings = JSON.parse(raw);
+      const postHooks = (settings && settings.hooks && settings.hooks.PostToolUse) || [];
+      for (const entry of postHooks) {
+        if (!entry || !Array.isArray(entry.hooks)) continue;
+        for (const h of entry.hooks) {
+          if (h && typeof h.command === "string" && h.command.includes(CONTEXT_METER_HOOK_MARKER)) {
+            hookRegistered = true;
+            break;
+          }
+        }
+        if (hookRegistered) break;
+      }
+    }
+  } catch {
+    // Fall through — treat as not registered
+  }
+  if (hookRegistered) {
+    success("Context meter hook registered in settings.json");
+  } else {
+    error("Context meter hook not installed — run gsd-t install");
+    issues++;
+  }
+
+  // Check 3: Hook script file exists in project
+  const scriptPath = path.join(cwd, "scripts", CONTEXT_METER_SCRIPT);
+  if (fs.existsSync(scriptPath)) {
+    success("Hook script present");
+  } else {
+    error(`Hook script missing at scripts/${CONTEXT_METER_SCRIPT} — run gsd-t update`);
+    issues++;
+  }
+
+  // Check 4: Config file parses via loader
+  const configPath = path.join(cwd, CONTEXT_METER_CONFIG_DEST);
+  if (cfgLoadErr) {
+    error(`Config file invalid: ${cfgLoadErr.message} — fix ${CONTEXT_METER_CONFIG_DEST}`);
+    issues++;
+  } else if (fs.existsSync(configPath)) {
+    success(`Config valid (threshold ${cfg.thresholdPct}%, check every ${cfg.checkFrequency} calls)`);
+  } else {
+    warn("Using default config — run gsd-t install to copy template");
+  }
+
+  // Check 5: Dry-run count_tokens API call (skip if no API key)
+  if (!apiKeyPresent) {
+    log(`  ${DIM}Skipped count_tokens dry-run (no API key)${RESET}`);
+  } else {
+    const clientPath = path.join(cwd, "scripts", "context-meter", "count-tokens-client.js");
+    if (!fs.existsSync(clientPath)) {
+      error("count_tokens client missing at scripts/context-meter/count-tokens-client.js — run gsd-t update");
+      issues++;
+    } else {
+      try {
+        const { countTokens } = require(clientPath);
+        const result = await countTokens({
+          apiKey: apiKeyValue,
+          model: "claude-opus-4-6",
+          system: "",
+          messages: [{ role: "user", content: [{ type: "text", text: "ping" }] }],
+          timeoutMs: 5000,
+        });
+        if (result && typeof result.inputTokens === "number") {
+          success(`count_tokens dry-run OK (${result.inputTokens} tokens)`);
+        } else {
+          error("count_tokens API call failed — check API key and network");
+          issues++;
+        }
+      } catch (e) {
+        error(`count_tokens dry-run threw: ${e.message}`);
+        issues++;
+      }
+    }
+  }
+
+  return issues;
+}
+
+async function doDoctor() {
   heading("GSD-T Doctor");
   log("");
   let issues = 0;
@@ -1795,6 +2363,7 @@ function doDoctor() {
   issues += checkDoctorInstallation();
   issues += checkDoctorProject();
   issues += checkDoctorCgc();
+  issues += await checkDoctorContextMeter(process.cwd());
   log("");
   if (issues === 0) {
     log(`${GREEN}${BOLD}  All checks passed!${RESET}`);
@@ -1802,6 +2371,7 @@ function doDoctor() {
     log(`${YELLOW}${BOLD}  ${issues} issue${issues > 1 ? "s" : ""} found${RESET}`);
   }
   log("");
+  if (issues > 0) process.exit(1);
 }
 
 function doRegister() {
@@ -2627,6 +3197,119 @@ function showHeadlessHelp() {
   log(`  ${DIM}$${RESET} gsd-t headless query domains\n`);
 }
 
+// ─── Metrics (M35 token telemetry CLI) ────────────────────────────────────────
+
+function parseMetricsByFlag(args) {
+  const byArg = args.find(a => a.startsWith("--by="));
+  if (!byArg) return [];
+  const raw = byArg.slice(5).trim();
+  if (!raw) return [];
+  return raw.split(",").map(s => s.trim()).filter(Boolean);
+}
+
+function formatPct(v) {
+  if (v === null || v === undefined || Number.isNaN(v)) return "—";
+  return `${Number(v).toFixed(1)}%`;
+}
+
+function formatInt(v) {
+  if (v === null || v === undefined || Number.isNaN(v)) return "—";
+  return String(Math.round(Number(v)));
+}
+
+function doMetrics(args) {
+  const projectDir = process.cwd();
+  let tt;
+  try {
+    tt = require(path.join(projectDir, "bin", "token-telemetry.js"));
+  } catch (e) {
+    error(`bin/token-telemetry.js not found in ${projectDir} — run gsd-t install first.`);
+    process.exit(1);
+  }
+
+  const records = tt.readAll(projectDir);
+  if (records.length === 0) {
+    log(`${DIM}No telemetry records yet — .gsd-t/token-metrics.jsonl is empty or missing.${RESET}`);
+    return;
+  }
+
+  const isTokens = args.includes("--tokens");
+  const isHalts = args.includes("--halts");
+  const isContextWindow = args.includes("--context-window");
+
+  if (!isTokens && !isHalts && !isContextWindow) {
+    log(`${YELLOW}Specify at least one of: --tokens, --halts, --context-window${RESET}`);
+    return;
+  }
+
+  if (isHalts) {
+    const halts = records.filter(r => r.halt_type);
+    log(`\n${BOLD}Halts — ${halts.length} record(s)${RESET}`);
+    if (halts.length === 0) {
+      log(`${DIM}  (no halts recorded — all spawns completed normally)${RESET}\n`);
+    } else {
+      const byType = {};
+      for (const r of halts) {
+        const key = String(r.halt_type);
+        byType[key] = (byType[key] || 0) + 1;
+      }
+      for (const [type, count] of Object.entries(byType).sort()) {
+        log(`  ${CYAN}${type.padEnd(24)}${RESET} ${count}`);
+      }
+      log("");
+    }
+  }
+
+  if (isTokens) {
+    const by = parseMetricsByFlag(args);
+    if (by.length === 0) {
+      const totalConsumed = records.reduce((a, r) => a + (Number(r.tokens_consumed) || 0), 0);
+      const totalDuration = records.reduce((a, r) => a + (Number(r.duration_s) || 0), 0);
+      log(`\n${BOLD}Tokens — ${records.length} spawn(s)${RESET}`);
+      log(`  total tokens consumed:  ${formatInt(totalConsumed)}`);
+      log(`  total duration (s):     ${formatInt(totalDuration)}`);
+      if (records.length > 0) {
+        log(`  mean tokens/spawn:      ${formatInt(totalConsumed / records.length)}`);
+      }
+      log("");
+    } else {
+      const groups = tt.aggregate(records, { by });
+      log(`\n${BOLD}Tokens by ${by.join(",")} — ${groups.length} group(s)${RESET}`);
+      const keyHeader = by.join("/");
+      log(`  ${keyHeader.padEnd(36)}  ${"count".padStart(7)}  ${"total".padStart(12)}  ${"mean".padStart(10)}  ${"median".padStart(10)}  ${"p95".padStart(10)}`);
+      log(`  ${"-".repeat(36)}  ${"-".repeat(7)}  ${"-".repeat(12)}  ${"-".repeat(10)}  ${"-".repeat(10)}  ${"-".repeat(10)}`);
+      for (const g of groups) {
+        const label = by.map(k => g.key[k] == null ? "—" : String(g.key[k])).join("/");
+        log(`  ${label.padEnd(36)}  ${formatInt(g.count).padStart(7)}  ${formatInt(g.total_tokens).padStart(12)}  ${formatInt(g.mean).padStart(10)}  ${formatInt(g.median).padStart(10)}  ${formatInt(g.p95).padStart(10)}`);
+      }
+      log("");
+    }
+  }
+
+  if (isContextWindow) {
+    log(`\n${BOLD}Context window trend — ${records.length} record(s)${RESET}`);
+    const withPct = records.filter(r => r.context_window_pct_after != null && !Number.isNaN(Number(r.context_window_pct_after)));
+    if (withPct.length === 0) {
+      log(`${DIM}  (no context-window measurements in records)${RESET}\n`);
+    } else {
+      const sorted = [...withPct].map(r => Number(r.context_window_pct_after)).sort((a, b) => a - b);
+      const min = sorted[0];
+      const max = sorted[sorted.length - 1];
+      const mean = sorted.reduce((a, b) => a + b, 0) / sorted.length;
+      const p95 = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))];
+      log(`  min:   ${formatPct(min)}`);
+      log(`  mean:  ${formatPct(mean)}`);
+      log(`  p95:   ${formatPct(p95)}`);
+      log(`  max:   ${formatPct(max)}`);
+      const atWarn = withPct.filter(r => Number(r.context_window_pct_after) >= 70).length;
+      const atStop = withPct.filter(r => Number(r.context_window_pct_after) >= 85).length;
+      log(`  spawns at warn band (≥70%):  ${atWarn}`);
+      log(`  spawns at stop band (≥85%):  ${atStop}`);
+      log("");
+    }
+  }
+}
+
 function showHelp() {
   log(`\n${BOLD}GSD-T${RESET} — Contract-Driven Development for Claude Code\n`);
   log(`${BOLD}Usage:${RESET}  npx @tekyzinc/gsd-t ${CYAN}<command>${RESET} [options]\n`);
@@ -2735,6 +3418,13 @@ module.exports = {
   syncGlobalRulesToProject,
   syncGlobalRules,
   exportUniversalRulesForNpm,
+  // M34: Context Meter installer integration
+  ensureGitignoreEntries,
+  installContextMeter,
+  configureContextMeterHooks,
+  promptForApiKeyIfMissing,
+  resolveApiKeyEnvVar,
+  runTaskCounterRetirementMigration,
 };
 
 // ─── Main ────────────────────────────────────────────────────────────────────
@@ -2745,16 +3435,16 @@ if (require.main === module) {
 
   switch (command) {
     case "install":
-      doInstall();
+      doInstall().catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
     case "update":
-      doUpdate();
+      doUpdate().catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
     case "update-all":
-      doUpdateAll();
+      doUpdateAll().catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
     case "init":
-      doInit(args[1]);
+      doInit(args[1]).catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
     case "register":
       doRegister();
@@ -2766,7 +3456,7 @@ if (require.main === module) {
       doUninstall();
       break;
     case "doctor":
-      doDoctor();
+      doDoctor().catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
     case "changelog":
       doChangelog();
@@ -2777,6 +3467,9 @@ if (require.main === module) {
     case "headless":
       doHeadless(args.slice(1));
       break;
+    case "metrics":
+      doMetrics(args.slice(1));
+      break;
     case "design-build": {
       const orchestrator = require("./design-orchestrator.js");
       orchestrator.run(args.slice(1)).catch(e => { console.error(e); process.exit(1); });