opencode-usage-coach 0.12.1 → 0.13.1

package/README.md

@@ -33,16 +33,23 @@ See **[docs/architecture.md](docs/architecture.md)** for the full design.
 { "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-usage-coach/tui"] }
 ```
 
-Then wire `codexbar` and drop `agents/usage-coach-harness.md` into `~/.config/opencode/agents/` for agent mode:
+Then run setup:
 
 ```bash
-# provider quota data source
-printf '%s' "$YOUR_PROVIDER_API_KEY" | codexbar config set-api-key --provider <id> --stdin
+usage-coach setup          # auto-generates harness.config.json + copies agent file
+usage-coach setup --json   # machine-readable output (for scripts/CI)
+```
+
+This creates `~/.config/opencode-usage-coach/harness.config.json` (edit `generator`/`grader` or use `/coach-config` at runtime) and copies `agents/usage-coach-harness.md` to `~/.config/opencode/agents/`.
+
+If you use `codexbar` for quota sensing:
 
-# harness role → model mapping (place in your work directory)
-cp harness.config.example.json harness.config.json   # edit generator/grader
+```bash
+printf '%s' "$YOUR_PROVIDER_API_KEY" | codexbar config set-api-key --provider <id> --stdin
 ```
 
+Without codexbar, the plugin runs in GO-only mode (no quota sensing).
+
 For local dev without npm: `bun install && bun run build`, then point both configs at the `dist/` files.
 
 ## Configuration

package/dist/cli.js

@@ -0,0 +1,564 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  copyFileSync
+} from "fs";
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { spawnSync } from "child_process";
+function projectStateDir(dir) {
+  const abs = resolve(dir || ".");
+  const h = createHash("sha1").update(abs).digest("hex").slice(0, 12);
+  return join(homedir(), ".cache", "opencode-usage-coach", "projects", h);
+}
+function resolveStateDir(dir) {
+  return process.env.UC_STATE_DIR ?? projectStateDir(dir ?? process.cwd());
+}
+var CACHE_ROOT = join(homedir(), ".cache", "opencode-usage-coach");
+function readJson(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readLines(path) {
+  try {
+    if (!existsSync(path)) return [];
+    return readFileSync(path, "utf8").split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function readNdjson(path) {
+  return readLines(path).map((l) => {
+    try {
+      return JSON.parse(l);
+    } catch {
+      return null;
+    }
+  }).filter((x) => x !== null);
+}
+function readText(path) {
+  try {
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+function countFileLines(path) {
+  return readLines(path).length;
+}
+function findHarness(stateDir) {
+  let best = null;
+  let entries = [];
+  try {
+    entries = readdirSync(stateDir);
+  } catch {
+  }
+  for (const d of entries) {
+    const sub = join(stateDir, d);
+    let isDir = false;
+    try {
+      isDir = statSync(sub).isDirectory();
+    } catch {
+    }
+    if (!isDir) continue;
+    const f = join(sub, "harness.json");
+    if (!existsSync(f)) continue;
+    let st;
+    try {
+      st = statSync(f);
+    } catch {
+      continue;
+    }
+    let active = false;
+    try {
+      active = !!JSON.parse(readFileSync(f, "utf8")).active;
+    } catch {
+    }
+    if (!best || active && !best.active || active === best.active && st.mtimeMs > best.mtime) {
+      best = { file: f, mtime: st.mtimeMs, active };
+    }
+  }
+  if (best) return readJson(best.file);
+  return readJson(join(stateDir, "harness.json"));
+}
+function readStatus(dir) {
+  const stateDir = resolveStateDir(dir);
+  const s = readJson(join(stateDir, "state.json"));
+  const h = findHarness(stateDir);
+  const rulesCount = parseRules(readText(join(stateDir, "rules.md"))).length;
+  const failuresCount = countFileLines(join(stateDir, "failures.ndjson"));
+  const domainNodes = countFileLines(join(stateDir, "nodes.ndjson"));
+  const domainEdges = countFileLines(join(stateDir, "edges.ndjson"));
+  return {
+    directory: resolve(dir ?? process.cwd()),
+    stateDir,
+    quota: s ? {
+      decision: s.decision,
+      fiveHour: s.fiveHour,
+      weekly: s.weekly,
+      monthly: s.monthly,
+      model: s.model,
+      provider: s.provider,
+      isFree: s.isFree,
+      advice: s.advice
+    } : null,
+    providers: s?.providers ?? null,
+    harness: h ? {
+      active: h.active ?? false,
+      name: h.name,
+      total: h.total,
+      current: h.current,
+      tasks: h.tasks.map((t) => ({
+        id: t.id,
+        title: t.title,
+        status: t.status,
+        score: t.score ?? void 0,
+        model: t.model,
+        steps: t.subStep
+      }))
+    } : null,
+    learning: { rulesCount, failuresCount, domainNodes, domainEdges },
+    updatedAt: s?.updatedAt
+  };
+}
+function readAggregateStatus() {
+  const projectsDir = join(CACHE_ROOT, "projects");
+  let dirs = [];
+  try {
+    dirs = readdirSync(projectsDir).map((d) => join(projectsDir, d));
+  } catch {
+  }
+  const instances = [];
+  const decCount = {};
+  let max5h = 0, maxWk = 0, maxMo = 0, activeHarnesses = 0, totalTasks = 0, totalRules = 0, totalFailures = 0, totalDomainNodes = 0, totalDomainEdges = 0;
+  for (const d of dirs) {
+    let isDir = false;
+    try {
+      isDir = statSync(d).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    const s = readJson(join(d, "state.json"));
+    const decision = s?.decision ?? "unknown";
+    const fiveHour = s?.fiveHour ?? 0;
+    const weekly = s?.weekly ?? 0;
+    instances.push({
+      directory: d,
+      stateDir: d,
+      decision,
+      fiveHour,
+      weekly,
+      model: s?.model
+    });
+    decCount[decision] = (decCount[decision] ?? 0) + 1;
+    max5h = Math.max(max5h, fiveHour);
+    maxWk = Math.max(maxWk, weekly);
+    maxMo = Math.max(maxMo, s?.monthly ?? 0);
+    const h = findHarness(d);
+    if (h?.active) {
+      activeHarnesses++;
+      totalTasks += h.tasks.length;
+    }
+    totalRules += parseRules(readText(join(d, "rules.md"))).length;
+    totalFailures += countFileLines(join(d, "failures.ndjson"));
+    totalDomainNodes += countFileLines(join(d, "nodes.ndjson"));
+    totalDomainEdges += countFileLines(join(d, "edges.ndjson"));
+  }
+  return {
+    instanceCount: instances.length,
+    instances,
+    aggregate: {
+      maxFiveHour: max5h,
+      maxWeekly: maxWk,
+      maxMonthly: maxMo,
+      decisions: decCount,
+      activeHarnesses,
+      totalTasks,
+      totalRules,
+      totalFailures,
+      totalDomainNodes,
+      totalDomainEdges
+    }
+  };
+}
+function readRules(dir) {
+  const stateDir = resolveStateDir(dir);
+  const content = readText(join(stateDir, "rules.md"));
+  const rules = parseRules(content);
+  return { count: rules.length, rules };
+}
+function parseRules(content) {
+  if (!content.trim()) return [];
+  const blocks = content.split(/^## /m).filter((b) => b.startsWith("Rule"));
+  return blocks.map((block) => {
+    const headerMatch = block.match(
+      /^Rule\s+(\d+)\s*\(([^,]+),\s*category:\s*([^)]+)\)/
+    );
+    const number = headerMatch ? parseInt(headerMatch[1], 10) : 0;
+    const date = headerMatch ? headerMatch[2].trim() : "";
+    const category = headerMatch ? headerMatch[3].trim() : "";
+    const body = block.slice(headerMatch?.[0]?.length ?? 0).trim();
+    const originMatch = body.match(/^Origin:\s*(.+)$/m);
+    const text = body.split("\n").filter((l) => !l.startsWith("Origin:")).join(" ").trim();
+    return {
+      number,
+      category,
+      date,
+      text,
+      origin: originMatch ? originMatch[1].trim() : ""
+    };
+  });
+}
+function readDecisions(dir, limit = 20) {
+  const stateDir = resolveStateDir(dir);
+  const lines = readLines(join(stateDir, "coach.log"));
+  const decisions = [];
+  for (let i = lines.length - 1; i >= 0 && decisions.length < limit; i--) {
+    const line = lines[i];
+    const m = line.match(
+      /^(\S+)\s+DECIDE\s+(GO|THROTTLE|STOP)\s+(.*)$/
+    );
+    if (m) {
+      decisions.push({
+        ts: m[1],
+        decision: m[2],
+        detail: m[3]
+      });
+    }
+  }
+  return { count: decisions.length, decisions };
+}
+function readDomainStats(dir) {
+  const stateDir = resolveStateDir(dir);
+  const nodes = readNdjson(join(stateDir, "nodes.ndjson"));
+  const edges = readNdjson(join(stateDir, "edges.ndjson"));
+  const nodeTypes = {};
+  for (const n of nodes) {
+    const t = n.type ?? "unknown";
+    nodeTypes[t] = (nodeTypes[t] ?? 0) + 1;
+  }
+  const edgeTypes = {};
+  for (const e of edges) {
+    const r = e.rel ?? "unknown";
+    edgeTypes[r] = (edgeTypes[r] ?? 0) + 1;
+  }
+  return {
+    nodes: nodes.length,
+    edges: edges.length,
+    nodeTypes,
+    edgeTypes
+  };
+}
+function bar(pct) {
+  const n = pct <= 0 ? 0 : Math.max(1, Math.min(10, Math.round(pct / 10)));
+  return "\u2588".repeat(n) + "\u2591".repeat(10 - n);
+}
+function formatStatus(r) {
+  const lines = [];
+  if (!r.quota) {
+    lines.push("usage-coach: no state (is the plugin running?)");
+    return lines.join("\n");
+  }
+  const q = r.quota;
+  const tag = q.isFree ? "free" : q.decision;
+  const model = q.model ? ` ${q.model.split("/").pop()}` : "";
+  lines.push(`usage-coach [${tag}]${model}`);
+  if (!q.isFree) {
+    if (q.fiveHour >= 0) lines.push(` 5h ${bar(q.fiveHour)} ${q.fiveHour}%`);
+    if (q.weekly >= 0) lines.push(` 1w ${bar(q.weekly)} ${q.weekly}%`);
+  }
+  if (q.advice) lines.push(` ${q.advice}`);
+  if (r.harness?.active) {
+    lines.push("");
+    lines.push(`harness: ${r.harness.name} ${r.harness.current}/${r.harness.total}`);
+    for (const t of r.harness.tasks) {
+      const score = t.score ? ` [${t.score}]` : "";
+      lines.push(`  ${t.id} [${t.status}]${score} ${t.title}`);
+    }
+  }
+  if (r.learning.rulesCount > 0) {
+    lines.push("");
+    lines.push(
+      `learning: ${r.learning.rulesCount} rules, ${r.learning.failuresCount} failures, ${r.learning.domainNodes} domain nodes`
+    );
+  }
+  return lines.join("\n");
+}
+function formatAggregate(r) {
+  const lines = [];
+  const a = r.aggregate;
+  lines.push(`usage-coach aggregate \u2014 ${r.instanceCount} instances`);
+  lines.push(` max 5h ${bar(a.maxFiveHour)} ${a.maxFiveHour}%`);
+  lines.push(` max 1w ${bar(a.maxWeekly)} ${a.maxWeekly}%`);
+  const decs = Object.entries(a.decisions).map(([k, v]) => `${k}:${v}`).join(" ");
+  lines.push(` decisions: ${decs}`);
+  lines.push(
+    ` harnesses: ${a.activeHarnesses} active, ${a.totalTasks} tasks`
+  );
+  lines.push(
+    ` learning: ${a.totalRules} rules, ${a.totalFailures} failures, ${a.totalDomainNodes} domain nodes`
+  );
+  return lines.join("\n");
+}
+function formatRules(r) {
+  if (r.count === 0) return "No rules accumulated yet.";
+  const lines = [`${r.count} rules:`];
+  for (const rule of r.rules) {
+    lines.push(
+      `  #${rule.number} (${rule.date}, ${rule.category}): ${rule.text.slice(0, 80)}${rule.text.length > 80 ? "..." : ""}`
+    );
+  }
+  return lines.join("\n");
+}
+function formatDecisions(r) {
+  if (r.count === 0) return "No decisions logged.";
+  const lines = [`${r.count} recent decisions:`];
+  for (const d of r.decisions) {
+    lines.push(`  ${d.ts} ${d.decision} ${d.detail}`);
+  }
+  return lines.join("\n");
+}
+function formatDomain(r) {
+  if (r.nodes === 0 && r.edges === 0) return "No domain knowledge stored.";
+  const nt = Object.entries(r.nodeTypes).map(([k, v]) => `${k}:${v}`).join(" ");
+  const et = Object.entries(r.edgeTypes).map(([k, v]) => `${k}:${v}`).join(" ");
+  return [
+    `domain: ${r.nodes} nodes, ${r.edges} edges`,
+    ` node types: ${nt}`,
+    ` edge types: ${et}`
+  ].join("\n");
+}
+var GLOBAL_CONFIG_DIR = join(homedir(), ".config", "opencode-usage-coach");
+var OPENCODE_AGENTS_DIR = join(homedir(), ".config", "opencode", "agents");
+var DEFAULT_HARNESS_CONFIG = {
+  generator: "opencode/deepseek-v4-flash-free",
+  grader: "opencode/mimo-v2.5-free",
+  provider: "",
+  lighterModel: ""
+};
+function resolveAgentSourceFile() {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  return join(scriptDir, "..", "agents", "usage-coach-harness.md");
+}
+function detectCodexbar() {
+  try {
+    const r = spawnSync("codexbar", ["--version"], { timeout: 5e3 });
+    if (r.status === 0 || r.stdout && r.stdout.toString().trim().length > 0) {
+      return { found: true, version: (r.stdout?.toString().trim() ?? "") || "unknown" };
+    }
+    return { found: false, version: "" };
+  } catch {
+    return { found: false, version: "" };
+  }
+}
+function doSetup(opts = {}) {
+  const configDir = opts.configDir ?? GLOBAL_CONFIG_DIR;
+  const agentsDir = opts.agentsDir ?? OPENCODE_AGENTS_DIR;
+  const agentSource = opts.agentSourceFile ?? resolveAgentSourceFile();
+  const configPath = join(configDir, "harness.config.json");
+  let configAction;
+  if (existsSync(configPath)) {
+    configAction = "exists";
+  } else {
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(
+      configPath,
+      JSON.stringify(DEFAULT_HARNESS_CONFIG, null, 2) + "\n"
+    );
+    configAction = "created";
+  }
+  const codexbar = detectCodexbar();
+  const agentDestPath = join(agentsDir, "usage-coach-harness.md");
+  let agentAction;
+  if (!existsSync(agentSource)) {
+    agentAction = "source-not-found";
+  } else if (existsSync(agentDestPath)) {
+    agentAction = "exists";
+  } else {
+    mkdirSync(agentsDir, { recursive: true });
+    copyFileSync(agentSource, agentDestPath);
+    agentAction = "copied";
+  }
+  return {
+    harnessConfig: { action: configAction, path: configPath },
+    codexbar,
+    agentFile: { action: agentAction, path: agentDestPath }
+  };
+}
+function formatSetup(r) {
+  const lines = ["usage-coach setup", ""];
+  const configCheck = r.harnessConfig.action === "created" ? "\u2705" : "\u2705";
+  lines.push(
+    `  ${configCheck} harness.config.json ${r.harnessConfig.action === "created" ? "created" : "already exists"}`
+  );
+  lines.push(`     ${r.harnessConfig.path}`);
+  if (r.harnessConfig.action === "created") {
+    lines.push(
+      `     generator: ${DEFAULT_HARNESS_CONFIG.generator} (edit or use /coach-config)`
+    );
+  }
+  if (r.codexbar.found) {
+    lines.push("");
+    lines.push(`  \u2705 codexbar found`);
+    lines.push(`     ${r.codexbar.version}`);
+  } else {
+    lines.push("");
+    lines.push(`  \u26A0\uFE0F  codexbar not found`);
+    lines.push(`     Plugin runs in GO-only mode (no quota sensing)`);
+  }
+  lines.push("");
+  if (r.agentFile.action === "copied") {
+    lines.push(`  \u2705 Agent file copied`);
+    lines.push(`     ${r.agentFile.path}`);
+  } else if (r.agentFile.action === "exists") {
+    lines.push(`  \u2705 Agent file already exists`);
+    lines.push(`     ${r.agentFile.path}`);
+  } else {
+    lines.push(`  \u26A0\uFE0F  Agent source not found`);
+    lines.push(`     Expected: ${r.agentFile.path}`);
+  }
+  lines.push("");
+  lines.push("Setup complete. Restart opencode to apply changes.");
+  return lines.join("\n");
+}
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let command = "status";
+  let json = false;
+  let dir;
+  let aggregate = false;
+  let limit = 20;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json" || a === "-j") json = true;
+    else if (a === "--aggregate" || a === "-a") aggregate = true;
+    else if (a === "--dir" || a === "-d") {
+      dir = args[++i];
+    } else if (a === "--limit" || a === "-l") {
+      limit = parseInt(args[++i], 10) || 20;
+    } else if (a === "--help" || a === "-h") {
+      command = "help";
+    } else if (a === "--version" || a === "-v") {
+      command = "version";
+    } else if (!a.startsWith("-")) {
+      command = a;
+    }
+  }
+  return { command, json, dir, aggregate, limit };
+}
+var HELP = `usage-coach \u2014 quota intelligence CLI for opencode
+
+Commands:
+  status          Show quota + harness + learning state (default)
+  rules           List accumulated learning rules
+  decisions       Show recent GO/THROTTLE/STOP decision history
+  domain          Show domain knowledge graph stats
+  setup           Auto-generate harness.config.json, detect codexbar, copy agent file
+
+Flags:
+  --json, -j      Output as JSON (default: human-readable)
+  --dir <path>    Project directory to query (default: cwd)
+  --aggregate, -a Scan all project instances (status only)
+  --limit <n>     Number of decisions to show (default: 20)
+  --help, -h      Show this help
+  --version, -v   Show version
+
+Examples:
+  usage-coach status --json
+  usage-coach status --aggregate --json
+  usage-coach rules --json --dir /path/to/project`;
+function getVersion() {
+  try {
+    const pkgPath = join(
+      dirname(fileURLToPath(import.meta.url)),
+      "..",
+      "package.json"
+    );
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function main() {
+  const args = parseArgs(process.argv);
+  switch (args.command) {
+    case "help": {
+      console.log(HELP);
+      break;
+    }
+    case "version": {
+      console.log(getVersion());
+      break;
+    }
+    case "status": {
+      if (args.aggregate) {
+        const r = readAggregateStatus();
+        console.log(args.json ? JSON.stringify(r, null, 2) : formatAggregate(r));
+      } else {
+        const r = readStatus(args.dir);
+        console.log(args.json ? JSON.stringify(r, null, 2) : formatStatus(r));
+      }
+      break;
+    }
+    case "rules": {
+      const r = readRules(args.dir);
+      console.log(args.json ? JSON.stringify(r, null, 2) : formatRules(r));
+      break;
+    }
+    case "decisions": {
+      const r = readDecisions(args.dir, args.limit);
+      console.log(
+        args.json ? JSON.stringify(r, null, 2) : formatDecisions(r)
+      );
+      break;
+    }
+    case "domain": {
+      const r = readDomainStats(args.dir);
+      console.log(args.json ? JSON.stringify(r, null, 2) : formatDomain(r));
+      break;
+    }
+    case "setup": {
+      const r = doSetup();
+      console.log(args.json ? JSON.stringify(r, null, 2) : formatSetup(r));
+      break;
+    }
+    default: {
+      console.error(`Unknown command: ${args.command}
+
+${HELP}`);
+      process.exit(1);
+    }
+  }
+}
+var isDirectRun = process.argv[1] && (process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("cli.ts") || process.argv[1].endsWith("usage-coach"));
+if (isDirectRun) {
+  main();
+}
+export {
+  doSetup,
+  parseArgs,
+  projectStateDir,
+  readAggregateStatus,
+  readDecisions,
+  readDomainStats,
+  readRules,
+  readStatus,
+  resolveAgentSourceFile,
+  resolveStateDir
+};

package/dist/index.js

@@ -1349,6 +1349,7 @@ async function runModel(client, model, prompt, directory, track, maxSteps = DEFA
     const providerID = slash >= 0 ? model.slice(0, slash) : model;
     const modelID = slash >= 0 ? model.slice(slash + 1) : "";
     const s = await client.session.create({ body: { title: "uc-harness-sub" }, query: { directory } });
+    log(`runModel(${model}): session.create ${Date.now() - t0}ms`);
     const id = s?.data?.info?.id ?? s?.data?.id ?? s?.id;
     if (!id) return `ERROR: session.create returned no id (response: ${JSON.stringify(s?.data ?? s).slice(0, 200)})`;
     subId = id;
@@ -1417,6 +1418,7 @@ async function runModel(client, model, prompt, directory, track, maxSteps = DEFA
     );
     const resp = await Promise.race([promptP, timeoutSignal.then(() => null)]);
     const elapsed = Math.round((Date.now() - t0) / 1e3);
+    log(`runModel(${model}): prompt resolved ${elapsed}s, timedOut=${timedOut}`);
     if (timedOut) {
       try {
         const summary = await client.session.summarize?.({ path: { id } });
@@ -1424,7 +1426,7 @@ async function runModel(client, model, prompt, directory, track, maxSteps = DEFA
       } catch {
       }
       try {
-        await client.session.delete?.({ path: { id } });
+        client.session.delete?.({ path: { id } });
       } catch {
       }
       subId = null;
@@ -1434,17 +1436,19 @@ async function runModel(client, model, prompt, directory, track, maxSteps = DEFA
     }
     const parts = resp?.data?.parts ?? resp?.parts ?? [];
     const text = parts.filter((p) => p?.type === "text").map((p) => p?.text ?? "").join("");
+    const cleanupStart = Date.now();
     try {
-      const summary = await client.session.summarize?.({ path: { id } });
-      log(`runModel(${model}): sub-session summary: ${JSON.stringify(summary?.data ?? summary).slice(0, 300)}`);
+      client.session.summarize?.({ path: { id } }).then((summary) => log(`runModel(${model}): summary ${Date.now() - cleanupStart}ms: ${JSON.stringify(summary?.data ?? summary).slice(0, 300)}`)).catch(() => {
+      });
     } catch {
     }
     try {
-      await client.session.delete?.({ path: { id } });
+      client.session.delete?.({ path: { id } }).catch(() => {
+      });
     } catch {
     }
     subId = null;
-    log(`runModel(${model}): done ${elapsed}s, ${text.length} chars`);
+    log(`runModel(${model}): done ${elapsed}s, ${text.length} chars (cleanup dispatched)`);
     return text.trim() || `ERROR: no assistant text in prompt response after ${elapsed}s (parts: ${parts.length}, types: ${parts.map((p) => p?.type).join(",")})`;
   } catch (e) {
     const elapsed = Math.round((Date.now() - t0) / 1e3);
@@ -1462,7 +1466,8 @@ async function runModel(client, model, prompt, directory, track, maxSteps = DEFA
     }
     if (subId) {
       try {
-        await client.session.delete?.({ path: { id: subId } });
+        client.session.delete?.({ path: { id: subId } }).catch(() => {
+        });
       } catch {
       }
     }
@@ -1510,11 +1515,15 @@ function captureStdout(args) {
     p.stdout?.on("data", (d) => {
       out += d.toString();
     });
-    p.on("error", () => resolve2(""));
+    p.on("error", (err) => {
+      if (err.code === "ENOENT") codexbarMissing = true;
+      resolve2("");
+    });
     p.on("close", () => resolve2(out));
   });
 }
 async function fetchEnabledProviders() {
+  if (codexbarMissing) return [];
   const out = await captureStdout(["config", "providers"]);
   const ids = [];
   for (const line of out.split("\n")) {
@@ -1525,11 +1534,11 @@ async function fetchEnabledProviders() {
 }
 function providerAdvice(h5, wk) {
   const S5H = STOP_5H, SWK = STOP_WK, T5H = THR_5H, TWK = THR_WK;
-  if (h5 >= S5H || wk >= SWK) return "STOP \u2014 finish current only";
-  if (h5 >= T5H && wk >= TWK) return "small tasks only \u2014 big ones will hit both limits";
-  if (h5 >= T5H) return "small tasks only \u2014 5h window nearly full, big tasks after reset";
-  if (wk >= TWK) return "small tasks only \u2014 big ones will strain late-week";
-  if (h5 >= 50 || wk >= 50) return "moderate tasks OK \u2014 save big ones for headroom";
+  if (h5 !== null && h5 >= S5H || wk !== null && wk >= SWK) return "STOP \u2014 finish current only";
+  if (h5 !== null && wk !== null && h5 >= T5H && wk >= TWK) return "small tasks only \u2014 big ones will hit both limits";
+  if (h5 !== null && h5 >= T5H) return "small tasks only \u2014 5h window nearly full, big tasks after reset";
+  if (wk !== null && wk >= TWK) return "small tasks only \u2014 big ones will strain late-week";
+  if (h5 !== null && h5 >= 50 || wk !== null && wk >= 50) return "moderate tasks OK \u2014 save big ones for headroom";
   return "big tasks OK \u2014 short & long limits comfortable";
 }
 async function fetchProvidersCoach() {
@@ -1537,17 +1546,17 @@ async function fetchProvidersCoach() {
   const results = await Promise.all(ids.map(async (id) => {
     try {
       const out = await captureStdout(["usage", "--provider", id, "--json"]);
-      const u = JSON.parse(out)[0]?.usage;
-      if (!u) return null;
-      const h5 = Math.round(u.tertiary?.usedPercent ?? 0);
-      const wk = Math.round(u.primary?.usedPercent ?? 0);
+      const q = parseQuotaResponse(out);
+      if (!q) return null;
+      const h5 = q.fiveHour ? Math.round(q.fiveHour.usedPercent ?? 0) : null;
+      const wk = q.weekly ? Math.round(q.weekly.usedPercent ?? 0) : null;
       return {
         id,
         name: id,
-        fiveHour: h5,
-        weekly: wk,
-        fiveHourReset: humanRemaining(u.tertiary?.resetsAt),
-        weeklyReset: humanRemaining(u.primary?.resetsAt),
+        fiveHour: h5 ?? -1,
+        weekly: wk ?? -1,
+        fiveHourReset: q.fiveHour ? humanRemaining(q.fiveHour.resetsAt) : "",
+        weeklyReset: q.weekly ? humanRemaining(q.weekly.resetsAt) : "",
         advice: providerAdvice(h5, wk)
       };
     } catch {
@@ -1562,11 +1571,36 @@ function parseQuotaResponse(rawText) {
     if (!text || text === "[]") return null;
     const u = JSON.parse(text)[0]?.usage;
     if (!u) return null;
-    return {
-      weekly: u.primary ?? { usedPercent: 0 },
-      monthly: u.secondary ?? { usedPercent: 0 },
-      fiveHour: u.tertiary ?? { usedPercent: 0 }
-    };
+    const result = { weekly: null, monthly: null, fiveHour: null };
+    const entries = [
+      { key: "primary", slot: u.primary },
+      { key: "secondary", slot: u.secondary },
+      { key: "tertiary", slot: u.tertiary }
+    ].filter((e) => e.slot != null);
+    for (const { key, slot } of entries) {
+      const mins = slot.windowMinutes ?? 0;
+      const desc = String(slot.resetDescription ?? "").toLowerCase();
+      if (mins === 300 || desc.includes("5 hour") || desc.includes("5h")) {
+        result.fiveHour = slot;
+      } else if (mins === 10080 || desc.includes("week")) {
+        result.weekly = slot;
+      } else if (desc.includes("month")) {
+        result.monthly = slot;
+      } else if (mins > 0 && mins <= 360) {
+        result.fiveHour = slot;
+      } else if (mins > 360 && mins <= 14400) {
+        result.weekly = slot;
+      } else if (mins > 14400) {
+        result.monthly = slot;
+      } else if (key === "primary") {
+        result.weekly = slot;
+      } else if (key === "secondary") {
+        result.monthly = slot;
+      } else if (key === "tertiary") {
+        result.fiveHour = slot;
+      }
+    }
+    return result;
   } catch {
     return null;
   }
@@ -1586,13 +1620,17 @@ function fetchQuota(provider) {
     p.stdout?.on("data", (d) => {
       out += d.toString();
     });
-    p.on("error", () => resolve2(null));
+    p.on("error", (err) => {
+      if (err.code === "ENOENT") codexbarMissing = true;
+      resolve2(null);
+    });
     p.on("close", () => {
       resolve2(parseQuotaResponse(out));
     });
   });
 }
 async function fetchQuotaWithRetry(provider, maxRetries = 3) {
+  if (codexbarMissing) return null;
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     const q = await fetchQuota(provider);
     if (q) return q;
@@ -1604,23 +1642,44 @@ async function fetchQuotaWithRetry(provider, maxRetries = 3) {
 }
 function coach(q, lighter) {
   if (!q) return { decision: "GO", advice: "quota unavailable \u2014 retrying. proceeding cautiously.", weekly: -2, monthly: -2, fiveHour: -2 };
-  const wk = Math.round(q.weekly?.usedPercent ?? 0), mo = Math.round(q.monthly?.usedPercent ?? 0), h5 = Math.round(q.fiveHour?.usedPercent ?? 0);
-  if (Number.isNaN(wk) || Number.isNaN(mo) || Number.isNaN(h5)) return { decision: "THROTTLE", advice: "invalid quota data \u2014 proceeding with caution. switch to lighter model if available.", weekly: Number.isNaN(wk) ? 0 : wk, monthly: Number.isNaN(mo) ? 0 : mo, fiveHour: Number.isNaN(h5) ? 0 : h5 };
-  const wkR = humanRemaining(q.weekly?.resetsAt), h5R = humanRemaining(q.fiveHour?.resetsAt);
-  const stop = (r) => ({ decision: "STOP", advice: `STOP recommend \u2014 ${r}. window nearly exhausted. stop now or it will be force-blocked.`, weekly: wk, monthly: mo, fiveHour: h5 });
-  const thr = (r) => ({ decision: "THROTTLE", advice: `Throttle recommend \u2014 ${r}. switch to lighter model (${lighter}) or wait for window reset.`, weekly: wk, monthly: mo, fiveHour: h5 });
-  if (h5 >= STOP_5H) return stop(`5h window ${h5}% (${h5R})`);
-  if (wk >= STOP_WK) return stop(`weekly ${wk}% (${wkR})`);
-  if (mo >= STOP_MO) return stop(`monthly ${mo}%`);
-  if (h5 >= THR_5H) return thr(`5h window ${h5}% (${h5R})`);
-  if (wk >= THR_WK) return thr(`weekly ${wk}% (${wkR})`);
-  return { decision: "GO", advice: `Comfortable \u2014 weekly ${wk}% \xB7 5h ${h5}% \xB7 monthly ${mo}%. proceed. 5h window ${h5R}.`, weekly: wk, monthly: mo, fiveHour: h5 };
+  const wk = q.weekly ? Math.round(q.weekly.usedPercent ?? 0) : null;
+  const mo = q.monthly ? Math.round(q.monthly.usedPercent ?? 0) : null;
+  const h5 = q.fiveHour ? Math.round(q.fiveHour.usedPercent ?? 0) : null;
+  if (wk !== null && Number.isNaN(wk) || mo !== null && Number.isNaN(mo) || h5 !== null && Number.isNaN(h5)) {
+    const sWk = wk !== null && !Number.isNaN(wk) ? wk : 0;
+    const sMo = mo !== null && !Number.isNaN(mo) ? mo : 0;
+    const sH5 = h5 !== null && !Number.isNaN(h5) ? h5 : 0;
+    return { decision: "THROTTLE", advice: "invalid quota data \u2014 proceeding with caution. switch to lighter model if available.", weekly: sWk, monthly: sMo, fiveHour: sH5 };
+  }
+  const wkR = q.weekly ? humanRemaining(q.weekly.resetsAt) : "";
+  const h5R = q.fiveHour ? humanRemaining(q.fiveHour.resetsAt) : "";
+  const stop = (r) => ({ decision: "STOP", advice: `STOP recommend \u2014 ${r}. window nearly exhausted. stop now or it will be force-blocked.`, weekly: wk ?? -1, monthly: mo ?? -1, fiveHour: h5 ?? -1 });
+  const thr = (r) => ({ decision: "THROTTLE", advice: `Throttle recommend \u2014 ${r}. switch to lighter model (${lighter}) or wait for window reset.`, weekly: wk ?? -1, monthly: mo ?? -1, fiveHour: h5 ?? -1 });
+  if (h5 !== null && h5 >= STOP_5H) return stop(`5h window ${h5}% (${h5R})`);
+  if (wk !== null && wk >= STOP_WK) return stop(`weekly ${wk}% (${wkR})`);
+  if (mo !== null && mo >= STOP_MO) return stop(`monthly ${mo}%`);
+  if (h5 !== null && h5 >= THR_5H) return thr(`5h window ${h5}% (${h5R})`);
+  if (wk !== null && wk >= THR_WK) return thr(`weekly ${wk}% (${wkR})`);
+  const parts = [];
+  if (wk !== null) parts.push(`weekly ${wk}%`);
+  if (h5 !== null) parts.push(`5h ${h5}%`);
+  if (mo !== null) parts.push(`monthly ${mo}%`);
+  const summary = parts.length > 0 ? parts.join(" \xB7 ") : "no quota limits detected";
+  const resetInfo = h5R ? ` 5h window ${h5R}.` : wkR ? ` weekly ${wkR}.` : "";
+  return { decision: "GO", advice: `Comfortable \u2014 ${summary}. proceed.${resetInfo}`, weekly: wk ?? -1, monthly: mo ?? -1, fiveHour: h5 ?? -1 };
 }
 var agentCache = /* @__PURE__ */ new Map();
 var currentModel = "";
 var currentProvider = "";
 var currentAgent = "";
 var modelChanged = false;
+var codexbarMissing = false;
+function isCodexbarMissing() {
+  return codexbarMissing;
+}
+function __resetCodexbarMissing() {
+  codexbarMissing = false;
+}
 function isFreeModel(model, provider) {
   if (!model && !provider) return false;
   if (provider === "opencode") return true;
@@ -1682,6 +1741,12 @@ async function UsageCoachPlugin(input) {
     const refreshBackground = () => {
       try {
         if (refreshing) return;
+        if (codexbarMissing) {
+          last = { decision: "GO", advice: "codexbar not installed \u2014 running in GO-only mode (no quota sensing).", weekly: -3, monthly: -3, fiveHour: -3 };
+          lastFetchedAt = Date.now();
+          refreshing = false;
+          return;
+        }
         if (last && !modelChanged && Date.now() - lastFetchedAt < TTL_MS) return;
         refreshing = true;
         modelChanged = false;
@@ -1705,9 +1770,12 @@ async function UsageCoachPlugin(input) {
               providers = await fetchProvidersCoach();
             } catch {
             }
-            if (providers.length > 0 && last.weekly < 0) {
+            if (providers.length > 0 && last.weekly < 0 && last.fiveHour < 0) {
               const p0 = providers[0];
-              last = { ...last, weekly: p0.weekly, fiveHour: p0.fiveHour, monthly: p0.weekly >= 0 ? 0 : -1, advice: p0.advice, decision: p0.weekly >= STOP_WK ? "STOP" : p0.weekly >= THR_WK ? "THROTTLE" : "GO" };
+              const newWeekly = p0.weekly >= 0 ? p0.weekly : last.weekly;
+              const newFiveHour = p0.fiveHour >= 0 ? p0.fiveHour : last.fiveHour;
+              const newDecision = newWeekly >= STOP_WK || newFiveHour >= STOP_5H ? "STOP" : newWeekly >= THR_WK || newFiveHour >= THR_5H ? "THROTTLE" : "GO";
+              last = { ...last, weekly: newWeekly, fiveHour: newFiveHour, advice: p0.advice, decision: newDecision };
             }
             writeState({ ...last, providers, model: currentModel, provider: currentProvider, isFree: false, agent: currentAgent, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
             log(`${last.decision} | weekly=${last.weekly}% 5h=${last.fiveHour}% | providers=${providers.length}`);
@@ -1781,7 +1849,13 @@ async function UsageCoachPlugin(input) {
           let instruction = "";
           if (c.decision === "STOP") instruction = `[${PLUGIN_NAME}] QUOTA limit exceeded. ${c.advice} Stop making further tool calls, finish the in-progress work, then report the quota status to the user.`;
           else if (c.decision === "THROTTLE") instruction = `[${PLUGIN_NAME}] ${c.advice} Hold off on long/heavy tasks.`;
-          else if (c.weekly >= 0) instruction = `[${PLUGIN_NAME}] quota ok \u2014 weekly ${c.weekly}% \xB7 5h ${c.fiveHour}% \xB7 monthly ${c.monthly}%.`;
+          else if (c.weekly >= 0 || c.fiveHour >= 0) {
+            const parts = [];
+            if (c.weekly >= 0) parts.push(`weekly ${c.weekly}%`);
+            if (c.fiveHour >= 0) parts.push(`5h ${c.fiveHour}%`);
+            if (c.monthly >= 0) parts.push(`monthly ${c.monthly}%`);
+            instruction = `[${PLUGIN_NAME}] quota ok \u2014 ${parts.join(" \xB7 ")}.`;
+          }
           if (instruction) output.system.push(instruction);
         } catch (e) {
           log(`system.transform err: ${String(e)}`);
@@ -2645,32 +2719,4 @@ Note: Changes take effect immediately for new generate/grade calls.`,
     return NOOP_HOOKS;
   }
 }
-export {
-  buildGapPrompt,
-  buildScanSummary,
-  checkScanGate,
-  clearSubSession,
-  coach,
-  UsageCoachPlugin as default,
-  detectLanguage,
-  extractImplNotes,
-  extractKeywords,
-  findActiveTaskId,
-  formatReport,
-  humanRemaining,
-  isFreeModel,
-  isHarnessAgent,
-  parseFileList,
-  parseGapAnalysis,
-  parseQuotaResponse,
-  providerAdvice,
-  providerToCodexbar,
-  readHarness,
-  readHarnessCfg,
-  readRules,
-  UsageCoachPlugin as server,
-  setStateDir,
-  updateSubSession,
-  writeHarness,
-  writeHarnessCfg
-};
+export { UsageCoachPlugin as server, UsageCoachPlugin as default };

package/dist/tui.js

@@ -324,7 +324,7 @@ function initializeTui(api, disposeRoot) {
         }
         if (s.providers && s.providers.length > 0) {
           for (const p of s.providers) {
-            nodes.push((() => {
+            if (p.fiveHour >= 0) nodes.push((() => {
               var _el$16 = _$createElement("box"), _el$17 = _$createElement("text"), _el$19 = _$createElement("text"), _el$20 = _$createElement("text"), _el$21 = _$createElement("text"), _el$22 = _$createTextNode(` `), _el$23 = _$createTextNode(`% `);
               _$insertNode(_el$16, _el$17);
               _$insertNode(_el$16, _el$19);
@@ -349,7 +349,7 @@ function initializeTui(api, disposeRoot) {
               });
               return _el$16;
             })());
-            nodes.push((() => {
+            if (p.weekly >= 0) nodes.push((() => {
               var _el$24 = _$createElement("box"), _el$25 = _$createElement("text"), _el$27 = _$createElement("text"), _el$28 = _$createElement("text"), _el$29 = _$createElement("text"), _el$30 = _$createTextNode(` `), _el$31 = _$createTextNode(`% `);
               _$insertNode(_el$24, _el$25);
               _$insertNode(_el$24, _el$27);
@@ -376,7 +376,7 @@ function initializeTui(api, disposeRoot) {
             })());
           }
         } else {
-          nodes.push((() => {
+          if (s.fiveHour >= 0) nodes.push((() => {
             var _el$32 = _$createElement("box"), _el$33 = _$createElement("text"), _el$35 = _$createElement("text"), _el$36 = _$createElement("text"), _el$37 = _$createElement("text"), _el$38 = _$createTextNode(` `), _el$39 = _$createTextNode(`%`);
             _$insertNode(_el$32, _el$33);
             _$insertNode(_el$32, _el$35);
@@ -400,7 +400,7 @@ function initializeTui(api, disposeRoot) {
             });
             return _el$32;
           })());
-          nodes.push((() => {
+          if (s.weekly >= 0) nodes.push((() => {
             var _el$40 = _$createElement("box"), _el$41 = _$createElement("text"), _el$43 = _$createElement("text"), _el$44 = _$createElement("text"), _el$45 = _$createElement("text"), _el$46 = _$createTextNode(` `), _el$47 = _$createTextNode(`%`);
             _$insertNode(_el$40, _el$41);
             _$insertNode(_el$40, _el$43);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "opencode closed-loop usage coach — quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,8 +13,15 @@
     "./tui": {
       "types": "./dist/tui.d.ts",
       "import": "./dist/tui.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
     }
   },
+  "bin": {
+    "usage-coach": "./dist/cli.js"
+  },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",