@kal-elsam/kairo-runtime 0.16.0 → 0.17.0

package/src/global/intelligence/subscription-pressure-source.js

@@ -0,0 +1,41 @@
+// Real subscription quota pressure — how much headroom is actually left
+// on each provider's account right now (from the same usage probes
+// service.js already fetches for /usage). This is a PROVIDER-level
+// signal, not a per-model efficiency measurement: quota is account-wide,
+// so it is modeled here as its own ProviderCapacity map, keyed by
+// adapterId — never copied into the per-model capability registry as if
+// it were evidence about an individual model. Two models from the same
+// provider share the exact same real capacity entry; there is no way to
+// represent "this model is more quota-efficient than that one" here,
+// because that isn't a real, measurable thing — only the provider's
+// account has quota.
+//
+// EFFICIENT TEAM (model-intelligence.js) resolves this separately from
+// its per-model EFFICIENCY_DIMENSIONS, and deliberately checks it LAST —
+// only when no real per-model signal (consumption, cost, duration, price,
+// throughput) distinguishes otherwise-adequate candidates. A provider's
+// spare quota must never, by itself, decide who wins a role over a model
+// with genuinely better per-task economics.
+
+/**
+ * @typedef {object} ProviderCapacity
+ * @property {string} adapterId
+ * @property {number} [quotaRemainingPercent]
+ */
+
+/**
+ * Builds a real ProviderCapacity map from the same remaining-percent
+ * figures already computed for /usage — one entry per adapter that
+ * reported a real number, never a fabricated one for an adapter with no
+ * data.
+ * @param {Record<string, number|null|undefined>} remainingPercentByAdapter
+ * @returns {Record<string, ProviderCapacity>}
+ */
+export function buildProviderCapacity(remainingPercentByAdapter) {
+  const capacity = {};
+  for (const [adapterId, remainingPercent] of Object.entries(remainingPercentByAdapter ?? {})) {
+    if (remainingPercent == null) continue;
+    capacity[adapterId] = { adapterId, quotaRemainingPercent: remainingPercent };
+  }
+  return capacity;
+}

package/src/global/mcp/kairo-mcp.js

@@ -18,16 +18,35 @@ import {
   workSnapshotPublishSchema
 } from "./work-snapshot-tool.js";
 import { resolveMcpWorkspaceCwd } from "./resolve-mcp-workspace.js";
+import {
+  WORKSPACE_BINDING_CODES,
+  resolveWorkspaceWriteBinding
+} from "./workspace-binding.js";
 
-/** Sole MCP write tool for companion snapshots. */
+/** Sole MCP write tool for companion snapshots. Bound servers only. */
 export const KAIRO_MCP_WRITE_TOOLS = Object.freeze(["kairo_publish_work_snapshot"]);
 
-export const KAIRO_MCP_TOOLS = Object.freeze([
+export const KAIRO_MCP_READ_TOOLS = Object.freeze([
   "kairo_status", "kairo_runs", "kairo_alerts", "kairo_gentle_status",
-  "kairo_graph_query", "kairo_graph_path", "kairo_context_summary", "kairo_fleet",
+  "kairo_graph_query", "kairo_graph_path", "kairo_context_summary", "kairo_fleet"
+]);
+
+export const KAIRO_MCP_TOOLS = Object.freeze([
+  ...KAIRO_MCP_READ_TOOLS,
   ...KAIRO_MCP_WRITE_TOOLS
 ]);
 
+export function mcpWorkspaceBinding(deps = {}) {
+  return resolveWorkspaceWriteBinding({
+    workspaceBound: deps.workspaceBound === true,
+    cwdExplicit: deps.cwdExplicit === true,
+    cwd: deps.cwd,
+    processCwd: deps.processCwd ?? process.cwd(),
+    userHome: deps.userHome,
+    env: deps.env ?? process.env
+  });
+}
+
 const empty = z.object({});
 export const mcpSchemas = Object.freeze({
   empty,
@@ -105,11 +124,14 @@ function graphEnvelope(result) {
 
 export function createToolHandlers(deps = {}) {
   const homeDir = deps.homeDir ?? resolveHomeDir();
-  // Cursor may spawn MCP under $HOME; prefer VSCODE_CWD / WORKSPACE_FOLDER_PATHS.
-  const cwd = resolveMcpWorkspaceCwd({
-    cwd: deps.cwd,
-    env: deps.env ?? process.env
-  });
+  const env = deps.env ?? process.env;
+  const binding = mcpWorkspaceBinding({ ...deps, env });
+  const cwd = binding.writable
+    ? binding.cwd
+    : resolveMcpWorkspaceCwd({
+      cwd: deps.cwdExplicit === true ? deps.cwd : (binding.bound ? undefined : deps.cwd),
+      env: binding.bound ? {} : env
+    });
   const listRuns = deps.listRuns ?? ((o) => listRunRecords(homeDir, o));
   const listAlertRows = deps.listAlerts ?? ((o) => listAlerts({ homeDir, ...o }));
   const listReviews = deps.listReviews ?? (() => listReviewReceipts({ homeDir, limit: 20 }));
@@ -238,20 +260,26 @@ export function createToolHandlers(deps = {}) {
         });
       }
     },
-    kairo_publish_work_snapshot: createPublishWorkSnapshotHandler({
-      homeDir,
-      cwd,
-      now: deps.now,
-      writeAtomic: deps.writeAtomic,
-      publishWorkSnapshot: deps.publishWorkSnapshot,
-      mcpResult
-    })
+    kairo_publish_work_snapshot: async (args = {}) => {
+      if (!binding.writable) {
+        const code = binding.code ?? WORKSPACE_BINDING_CODES.UNBOUND;
+        return mcpResult({ ok: false, code, data: null, diagnostics: [code], isError: true });
+      }
+      return createPublishWorkSnapshotHandler({
+        homeDir,
+        cwd: binding.cwd,
+        now: deps.now,
+        writeAtomic: deps.writeAtomic,
+        publishWorkSnapshot: deps.publishWorkSnapshot,
+        mcpResult
+      })(args);
+    }
   };
 }
 
 export function registerKairoMcpTools(registerTool, deps = {}) {
   const h = createToolHandlers(deps);
-  for (const [name, description, inputSchema] of [
+  const catalog = [
     ["kairo_status", "Read-only control-plane + companion summary", empty],
     ["kairo_runs", "Read-only run list", mcpSchemas.runs],
     ["kairo_alerts", "Read-only alert list", mcpSchemas.alerts],
@@ -265,7 +293,12 @@ export function registerKairoMcpTools(registerTool, deps = {}) {
       "Publish kairo.work-snapshot/v1 for the runtime workspace (enrolls conversation)",
       mcpSchemas.workSnapshotPublish
     ]
-  ]) registerTool(name, { description, inputSchema }, h[name]);
+  ];
+  const bound = deps.workspaceBound === true;
+  for (const [name, description, inputSchema] of catalog) {
+    if (bound ? !KAIRO_MCP_WRITE_TOOLS.includes(name) : KAIRO_MCP_WRITE_TOOLS.includes(name)) continue;
+    registerTool(name, { description, inputSchema }, h[name]);
+  }
   return h;
 }
 

package/src/global/mcp/work-snapshot-rule.js

@@ -18,13 +18,15 @@ export function resolveWorkSnapshotRulePath(homeDir = homedir()) {
 
 export const WORK_SNAPSHOT_RULE_BODY = `# Kairo work snapshot
 
-After each significant turn, publish the true work state with MCP \`kairo_publish_work_snapshot\`:
+After each significant turn, publish the true work state with MCP \`kairo_publish_work_snapshot\` **only on \`kairo-workspace\`** (\`kairo mcp --workspace-bound --cwd <absolute-folder>\`; unique \`WORKSPACE_FOLDER_PATHS\` may bind):
 
 - Required: \`conversationId\`, \`provider\` (\`cursor\`), \`goal\`, \`now\`, \`next\`
 - Optional: \`progress\` (≤3), \`blockers\`, \`delegations\` (only real ones)
-- Workspace identity is derived by Kairo from the runtime — never send \`projectKey\`, paths, or \`cwd\`
+- Workspace identity is derived by Kairo from the bound process — never send \`projectKey\`, paths, or \`cwd\`
 - Never invent work. Never send prompts, transcripts, or tool dumps
 - Reuse the same \`conversationId\` for later turns in this chat
+- If the publish tool is missing, stop. The global \`kairo\` MCP does not register it. Do not retry with paths.
+- On the bound server, \`workspace_ambiguous\` or \`workspace_mismatch\` also means stop. Never retry with paths.
 `;
 
 export function buildWorkSnapshotRuleFile() {

package/src/global/mcp/workspace-binding.js

@@ -0,0 +1,88 @@
+/**
+ * Explicit workspace binding for MCP writes.
+ * Agents never supply paths. VSCODE_CWD never authorizes writes.
+ * Canonical `--cwd` may match process.cwd() or the unique
+ * WORKSPACE_FOLDER_PATHS entry (Cursor stdio has no cwd field).
+ */
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { statSync } from "node:fs";
+import { canonicalizeProjectPath, projectKeyForPath } from "../next/project-key.js";
+import { parseWorkspaceFolderPaths } from "./resolve-mcp-workspace.js";
+
+export const WORKSPACE_BINDING_CODES = Object.freeze({
+  UNBOUND: "workspace_unbound",
+  AMBIGUOUS: "workspace_ambiguous",
+  MISMATCH: "workspace_mismatch"
+});
+
+function fail(code, bound = false) {
+  return { writable: false, bound, cwd: null, projectKey: null, code };
+}
+
+function isForbiddenWriteRoot(canonical, userHome) {
+  const root = canonicalizeProjectPath("/");
+  if (canonical === root || canonical === "/") return true;
+  return canonical === canonicalizeProjectPath(userHome);
+}
+
+function tryCanonical(pathValue) {
+  try {
+    return canonicalizeProjectPath(pathValue);
+  } catch {
+    return null;
+  }
+}
+
+function uniqueFolderCanonical(env) {
+  const folders = parseWorkspaceFolderPaths(env.WORKSPACE_FOLDER_PATHS);
+  if (folders.length > 1) return { code: WORKSPACE_BINDING_CODES.AMBIGUOUS, canonical: null };
+  if (folders.length === 0) return { code: null, canonical: null };
+  const canonical = tryCanonical(folders[0]);
+  return { code: canonical ? null : WORKSPACE_BINDING_CODES.UNBOUND, canonical };
+}
+
+export function resolveWorkspaceWriteBinding({
+  workspaceBound = false,
+  cwdExplicit = false,
+  cwd,
+  processCwd = process.cwd(),
+  userHome = homedir(),
+  env = process.env
+} = {}) {
+  if (!workspaceBound) return fail(WORKSPACE_BINDING_CODES.UNBOUND);
+  if (!cwdExplicit || typeof cwd !== "string" || !cwd.trim()) {
+    return fail(WORKSPACE_BINDING_CODES.UNBOUND, true);
+  }
+
+  const canonical = tryCanonical(resolve(processCwd, cwd));
+  if (!canonical) return fail(WORKSPACE_BINDING_CODES.UNBOUND, true);
+  try {
+    if (!statSync(canonical).isDirectory()) {
+      return fail(WORKSPACE_BINDING_CODES.UNBOUND, true);
+    }
+  } catch {
+    return fail(WORKSPACE_BINDING_CODES.UNBOUND, true);
+  }
+  if (isForbiddenWriteRoot(canonical, userHome)) {
+    return fail(WORKSPACE_BINDING_CODES.MISMATCH, true);
+  }
+
+  const folder = uniqueFolderCanonical(env);
+  if (folder.code) return fail(folder.code, true);
+
+  const processCanonical = tryCanonical(processCwd);
+  const matchesProcess = processCanonical != null && canonical === processCanonical;
+  const matchesFolder = folder.canonical != null && canonical === folder.canonical;
+  if (!matchesProcess && !matchesFolder) {
+    return fail(WORKSPACE_BINDING_CODES.MISMATCH, true);
+  }
+
+  return {
+    writable: true,
+    bound: true,
+    cwd: canonical,
+    projectKey: projectKeyForPath(canonical),
+    code: null
+  };
+}

package/src/global/mcp/workspace-mcp-entry.js

@@ -0,0 +1,74 @@
+/**
+ * VSIX write MCP: publish only. Global/unbound reads stay on `kairo mcp`.
+ */
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import {
+  createPublishWorkSnapshotHandler,
+  workSnapshotPublishSchema
+} from "./work-snapshot-tool.js";
+import {
+  WORKSPACE_BINDING_CODES,
+  resolveWorkspaceWriteBinding
+} from "./workspace-binding.js";
+
+export function parseWorkspaceMcpArgv(argv = []) {
+  const args = [...argv];
+  if (args[0] === "mcp") args.shift();
+  let workspaceBound = false;
+  let cwd;
+  let cwdExplicit = false;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--workspace-bound") workspaceBound = true;
+    else if (args[i] === "--cwd") {
+      cwd = args[++i];
+      cwdExplicit = true;
+    }
+  }
+  return { workspaceBound, cwd, cwdExplicit };
+}
+
+function mcpResult({ ok, code, data = null, diagnostics = [], isError = false }) {
+  const structuredContent = { ok, code, data, diagnostics };
+  return {
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    structuredContent, ...(isError ? { isError: true } : {})
+  };
+}
+
+export function startWorkspaceMcp(argv = process.argv.slice(2), deps = {}) {
+  const parsed = parseWorkspaceMcpArgv(argv);
+  const merged = { ...deps, ...parsed };
+  const binding = resolveWorkspaceWriteBinding({
+    workspaceBound: merged.workspaceBound === true,
+    cwdExplicit: merged.cwdExplicit === true,
+    cwd: merged.cwd,
+    processCwd: merged.processCwd ?? process.cwd(),
+    userHome: merged.userHome,
+    env: merged.env ?? process.env
+  });
+  const publish = createPublishWorkSnapshotHandler({
+    homeDir: merged.homeDir, cwd: binding.cwd, now: merged.now,
+    writeAtomic: merged.writeAtomic, publishWorkSnapshot: merged.publishWorkSnapshot,
+    mcpResult
+  });
+  const serve = deps.serveStdio ?? serveStdio;
+  return serve(() => {
+    const server = new (deps.McpServer ?? McpServer)({ name: "kairo-workspace", version: "0.8.0" });
+    const register = deps.registerTool ?? ((name, config, handler) => server.registerTool(name, config, handler));
+    register("kairo_publish_work_snapshot", {
+      description: "Publish kairo.work-snapshot/v1 for the runtime workspace (enrolls conversation)",
+      inputSchema: workSnapshotPublishSchema
+    }, async (args = {}) => {
+      if (!binding.writable) {
+        const code = binding.code ?? WORKSPACE_BINDING_CODES.UNBOUND;
+        return mcpResult({ ok: false, code, data: null, diagnostics: [code], isError: true });
+      }
+      return publish(args);
+    });
+    return server;
+  });
+}
+
+const invoked = process.argv[1] ?? "";
+if (/(?:kairo-workspace\.cjs|workspace-mcp-entry\.js)$/.test(invoked)) void startWorkspaceMcp();

package/src/global/mcp-install.js

@@ -227,7 +227,14 @@ export async function runMcpCli(options = {}) {
   if (action === "serve" || action == null) {
     const { runKairoMcp } = await import("./mcp/kairo-mcp.js");
     return runKairoMcp({
-      cwd: resolveMcpServeCwd(options),
+      cwd: resolveMcpServeCwd(options) ?? options.cwd,
+      cwdExplicit: options.cwdExplicit === true,
+      workspaceBound: options.workspaceBound === true,
+      processCwd: options.processCwd ?? process.cwd(),
+      homeDir: options.homeDir,
+      env: options.env,
+      registerTool: options.registerTool,
+      serveStdio: options.serveStdio,
       packageRoot: options.packageRoot,
       packageName: options.packageName,
       version: options.version

package/src/global/observability/artificial-analysis-models.js

@@ -0,0 +1,118 @@
+// Real per-model benchmark scores from Artificial Analysis's official Data
+// API (verified live against https://artificialanalysis.ai/api/v2/data/llms/models
+// — not scraped from their leaderboard website, which has no stable JSON
+// endpoint). Fails closed like every other observability probe: no API key
+// or a failed fetch never fabricates a score, it falls back to the last
+// successfully cached snapshot (marked "cached", with its real age) or
+// "unknown" if there's no cache either.
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+
+export const SOURCE = "artificial-analysis api v2 (data/llms/models)";
+const API_URL = "https://artificialanalysis.ai/api/v2/data/llms/models";
+const DEFAULT_TIMEOUT_MS = 8000;
+
+function normalizeModel(entry) {
+  const evaluations = entry.evaluations ?? {};
+  return {
+    slug: entry.slug,
+    name: entry.name,
+    creator: entry.model_creator?.slug ?? null,
+    intelligenceIndex: evaluations.artificial_analysis_intelligence_index ?? null,
+    codingIndex: evaluations.artificial_analysis_coding_index ?? null,
+    mathIndex: evaluations.artificial_analysis_math_index ?? null,
+    // Real per-benchmark scores the free API already returns alongside the
+    // composite indices above — verified live (not documented anywhere as
+    // a free-tier feature, an earlier assumption here was wrong). These
+    // matter because the composite intelligenceIndex can blur a real,
+    // benchmark-specific near-tie: e.g. two models 18% apart on the
+    // composite can be 0.2 points apart on GPQA specifically. Real,
+    // 0-1 scale values as AA reports them — never rescaled or blended.
+    gpqa: evaluations.gpqa ?? null,
+    hle: evaluations.hle ?? null,
+    sciCode: evaluations.scicode ?? null,
+    mmluPro: evaluations.mmlu_pro ?? null,
+    liveCodeBench: evaluations.livecodebench ?? null,
+    ifBench: evaluations.ifbench ?? null,
+    terminalBenchHard: evaluations.terminalbench_hard ?? null,
+    terminalBenchV2: evaluations.terminalbench_v2_1 ?? null,
+    tau2: evaluations.tau2 ?? null,
+    tauBanking: evaluations.tau_banking ?? null,
+    // Real reported numbers, not derived scores — used to flag the
+    // cheapest/fastest real option among what you actually have access to,
+    // never blended into a single invented composite.
+    priceInputPerMTok: entry.pricing?.price_1m_input_tokens ?? null,
+    priceOutputPerMTok: entry.pricing?.price_1m_output_tokens ?? null,
+    outputTokensPerSecond: entry.median_output_tokens_per_second ?? null
+  };
+}
+
+function ageLabel(fetchedAtIso) {
+  const fetchedAt = new Date(fetchedAtIso ?? "").getTime();
+  if (!Number.isFinite(fetchedAt)) return null;
+  const hours = (Date.now() - fetchedAt) / 3_600_000;
+  if (hours < 1) return "<1h";
+  if (hours < 48) return `${Math.round(hours)}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+async function readCache(homeDir, deps) {
+  const read = deps.readFile ?? readFile;
+  try {
+    const raw = await read(harnessHomePaths(homeDir).modelIntelligencePath, "utf8");
+    const doc = JSON.parse(raw);
+    if (!Array.isArray(doc?.models) || typeof doc.fetchedAt !== "string") return null;
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(homeDir, doc, deps) {
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const path = harnessHomePaths(homeDir).modelIntelligencePath;
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, doc);
+}
+
+function fromCache(cache, error) {
+  if (!cache) return { status: "unknown", source: SOURCE, fetchedAt: null, age: null, models: [], error };
+  return { status: "cached", source: SOURCE, fetchedAt: cache.fetchedAt, age: ageLabel(cache.fetchedAt), models: cache.models, error };
+}
+
+/**
+ * @param {object} [options]
+ * @param {string|null} [options.apiKey] - defaults to ARTIFICIAL_ANALYSIS_API_KEY; never hardcode a key
+ * @param {string} options.homeDir - required; the cache lives under this harness home
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {number} [options.timeoutMs]
+ */
+export async function readArtificialAnalysisModels({
+  apiKey = process.env.ARTIFICIAL_ANALYSIS_API_KEY ?? null,
+  homeDir,
+  fetchImpl = fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  ...deps
+} = {}) {
+  if (!apiKey) return fromCache(await readCache(homeDir, deps), "no API key configured");
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(API_URL, { headers: { "x-api-key": apiKey }, signal: controller.signal });
+    if (!response.ok) throw new Error(`artificial analysis api returned ${response.status}`);
+    const payload = await response.json();
+    const models = Array.isArray(payload?.data) ? payload.data.map(normalizeModel) : [];
+    const fetchedAt = new Date().toISOString();
+    await writeCache(homeDir, { fetchedAt, models }, deps).catch(() => {});
+    return { status: "live", source: SOURCE, fetchedAt, age: "<1h", models, error: null };
+  } catch (error) {
+    return fromCache(await readCache(homeDir, deps), error?.message ?? String(error));
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/global/observability/claude-models.js

@@ -0,0 +1,31 @@
+// Claude Code's CLI has no model-discovery command (`claude --help` exposes
+// no `models` subcommand, unlike Codex's `model/list` RPC or OpenCode's
+// `models` command) — verified by inspecting its full --help output, not
+// assumed. So there is no live, per-account catalog to read.
+//
+// This is the documented model catalog only — current as of this file's
+// last update — NOT a live entitlement check. It intentionally carries
+// `status: "documented"` (never "measured") so callers can't mistake it for
+// verified data the way Codex/OpenCode/Cursor's catalogs are.
+const SOURCE = "documented catalog (no live discovery command exists for claude)";
+
+const DOCUMENTED_MODELS = [
+  { id: "claude-opus-5", displayName: "Claude Opus 5" },
+  { id: "claude-sonnet-5", displayName: "Claude Sonnet 5" },
+  { id: "claude-haiku-4-5", displayName: "Claude Haiku 4.5" },
+  { id: "claude-fable-5-1", displayName: "Claude Fable 5.1" },
+  { id: "claude-fable-5", displayName: "Claude Fable 5" },
+  { id: "claude-opus-4-8", displayName: "Claude Opus 4.8" },
+  { id: "claude-opus-4-7", displayName: "Claude Opus 4.7" },
+  { id: "claude-opus-4-6", displayName: "Claude Opus 4.6" },
+  { id: "claude-sonnet-4-6", displayName: "Claude Sonnet 4.6" }
+];
+
+/**
+ * Returns the documented Claude model catalog. Always synchronous and
+ * always `status: "documented"` — there is nothing to fail closed on since
+ * no live read is attempted.
+ */
+export function readClaudeModels() {
+  return { status: "documented", source: SOURCE, models: DOCUMENTED_MODELS.slice(), error: null };
+}

package/src/global/observability/claude-usage.js

@@ -0,0 +1,112 @@
+import { spawn as defaultSpawn } from "node:child_process";
+
+// Claude Code's `/usage` is a local_command — intercepted client-side before
+// it reaches the model, so `claude -p "/usage" --output-format json` returns
+// real session/weekly percentages at zero cost (total_cost_usd: 0, all token
+// counts 0). This mirrors codex-usage.js's app-server approach: a real,
+// zero-cost, local read, never a fabricated quota.
+const SOURCE = 'claude -p "/usage" (local_command, zero-cost)';
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+function unknown(error = null) {
+  return {
+    status: "unknown",
+    source: SOURCE,
+    windows: [],
+    primary: null,
+    secondary: null,
+    raw: null,
+    error: error ? String(error) : null
+  };
+}
+
+/**
+ * Parses lines like:
+ *   "Current session: 0% used · resets Sep 11 at 7:09pm (America/Mexico_City)"
+ *   "Current week (all models): 7% used · resets Sep 13 at 7:59am (America/Mexico_City)"
+ * into normalized usage windows. Unrecognized lines are skipped, not guessed.
+ */
+export function parseClaudeUsageText(text) {
+  const windows = [];
+  for (const line of String(text ?? "").split("\n")) {
+    const match = line.match(/^(.+?):\s*(\d+)%\s*used(?:\s*·\s*resets\s*(.+))?\s*$/);
+    if (!match) continue;
+    const usedPercent = Number(match[2]);
+    if (!Number.isFinite(usedPercent)) continue;
+    windows.push({
+      label: match[1].trim(),
+      usedPercent,
+      remainingPercent: 100 - usedPercent,
+      resetsAt: match[3] ? match[3].trim() : null
+    });
+  }
+  return windows;
+}
+
+/**
+ * Reads Claude Code's own real session/weekly usage percentages via its
+ * `/usage` local_command, without starting a model turn. Fail-closed: any
+ * spawn error, timeout, malformed JSON, or unparseable response yields
+ * `unknown`, never a fabricated percentage.
+ */
+export async function readClaudeUsage({
+  spawn = defaultSpawn,
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  let child;
+  try {
+    child = spawn("claude", ["-p", "/usage", "--output-format", "json"], {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (error) {
+    return unknown(error?.message ?? error);
+  }
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let finished = false;
+    const timer = setTimeout(() => finish(unknown("claude -p \"/usage\" timed out")), timeoutMs);
+
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.on("error", (error) => finish(unknown(error?.message ?? error)));
+    child.on("close", () => {
+      let parsed;
+      try {
+        parsed = JSON.parse(stdout);
+      } catch {
+        finish(unknown("malformed JSON from claude -p \"/usage\""));
+        return;
+      }
+      if (parsed?.local_command !== "usage" || typeof parsed?.result !== "string") {
+        finish(unknown("unexpected response shape from claude -p \"/usage\""));
+        return;
+      }
+      const windows = parseClaudeUsageText(parsed.result);
+      if (windows.length === 0) {
+        finish(unknown("no usage windows parsed from claude -p \"/usage\""));
+        return;
+      }
+      finish({
+        status: "measured",
+        source: SOURCE,
+        windows,
+        primary: windows[0] ?? null,
+        secondary: windows[1] ?? null,
+        raw: parsed.result,
+        error: null
+      });
+    });
+  });
+}