opencode-usage-coach 0.12.0 → 0.13.0

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) {
+    lines.push(` 5h ${bar(q.fiveHour)} ${q.fiveHour}%`);
+    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

@@ -1,9 +1,9 @@
 // src/index.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, appendFileSync as appendFileSync2, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync2, appendFileSync as appendFileSync3, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
 import { spawn, spawnSync } from "child_process";
 import { createHash } from "crypto";
-import { homedir } from "os";
-import { join as join2, resolve, dirname as dirname2 } from "path";
+import { homedir as homedir2 } from "os";
+import { join as join3, resolve, dirname as dirname2 } from "path";
 import { tool } from "@opencode-ai/plugin";
 
 // src/domain.ts
@@ -221,6 +221,18 @@ function autoLinkKeywords(nodeId, keywords, minOverlap = 2, maxLinks = 8) {
 }
 
 // src/web-search.ts
+import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+import { homedir } from "os";
+var WS_LOG_FILE = process.env.UC_STATE_DIR ? join2(process.env.UC_STATE_DIR, "web-search.log") : join2(homedir(), ".cache", "opencode-usage-coach", "web-search.log");
+function wsLog(msg) {
+  try {
+    mkdirSync2(join2(WS_LOG_FILE, ".."), { recursive: true });
+    appendFileSync2(WS_LOG_FILE, `${(/* @__PURE__ */ new Date()).toISOString()} ${msg}
+`);
+  } catch {
+  }
+}
 var FRAMEWORK_DOCS = {
   "react": { name: "React", docs: "https://react.dev", githubOrg: "facebook" },
   "solid-js": { name: "Solid.js", docs: "https://solidjs.com", githubOrg: "solidjs" },
@@ -283,7 +295,7 @@ async function ghFetch(url, signal) {
     const errs = ghError?.errors;
     const errMsg = ghError?.message ?? ghErrorText.slice(0, 300);
     const detail = errs ? errs.map((e) => typeof e === "string" ? e : `${e?.field ?? "?"}: ${e?.message ?? e?.code ?? JSON.stringify(e)}`).join("; ") : "";
-    console.error(JSON.stringify({
+    wsLog(JSON.stringify({
       level: "error",
       module: "web-search",
       event: "gh-fetch-error",
@@ -319,7 +331,9 @@ async function tier1OfficialDocs(query, fws, results, docRefs, seen, signal) {
     const entry = FRAMEWORK_DOCS[fw];
     if (!entry?.githubOrg) continue;
     try {
-      const fullQ = `${cleanQuery} org:${entry.githubOrg}`;
+      const orgPart = ` org:${entry.githubOrg}`;
+      const truncated = cleanQuery.slice(0, GH_QUERY_MAX - orgPart.length);
+      const fullQ = `${truncated}${orgPart}`;
       const url = `https://api.github.com/search/issues?q=${encodeURIComponent(fullQ)}&per_page=3`;
       const data = await ghFetch(url, signal);
       for (const item of data.items ?? []) {
@@ -332,7 +346,7 @@ async function tier1OfficialDocs(query, fws, results, docRefs, seen, signal) {
       }
     } catch (e) {
       const m = errMessage(e);
-      console.error(`[web-search] tier1 ${fw}: ${m}`);
+      wsLog(`[web-search] tier1 ${fw}: ${m}`);
       errors.push(`tier1:${fw}:${m.slice(0, 80)}`);
     }
   }
@@ -355,7 +369,7 @@ async function tier2GitHubIssues(query, results, seen, signal) {
     }
   } catch (e) {
     const m = errMessage(e);
-    console.error(`[web-search] tier2: ${m}`);
+    wsLog(`[web-search] tier2: ${m}`);
     errors.push(`tier2:${m.slice(0, 80)}`);
   }
   return errors;
@@ -379,7 +393,7 @@ async function tier3GitHubCode(query, results, seen, signal) {
     }
   } catch (e) {
     const m = errMessage(e);
-    console.error(`[web-search] tier3: ${m}`);
+    wsLog(`[web-search] tier3: ${m}`);
     errors.push(`tier3:${m.slice(0, 80)}`);
   }
   return errors;
@@ -405,7 +419,7 @@ async function searchContext(query, frameworks, keyDeps, timeoutMs) {
     }
   } catch (e) {
     const m = errMessage(e);
-    console.error(`[web-search] unexpected error: ${m}`);
+    wsLog(`[web-search] unexpected error: ${m}`);
     errors.push(`unexpected:${m.slice(0, 80)}`);
   } finally {
     clearTimeout(timer);
@@ -423,49 +437,49 @@ var DEFAULT_MAX_STEPS = Number(process.env.UC_MAX_STEPS ?? 30) || 30;
 var WATCHDOG_POLL_MS = Math.max(1e3, Number(process.env.UC_WATCHDOG_POLL_MS ?? 3e3) || 3e3);
 var WALL_TIMEOUT_MS = Math.max(1, Number(process.env.UC_WALL_TIMEOUT_MIN ?? 30) || 30) * 60 * 1e3;
 var DEFAULT_MAX_QUESTIONS = Math.max(1, Math.round(Number(process.env.UC_MAX_QUESTIONS ?? 7)) || 7);
-var PIPE_LOG = join2(homedir(), ".cache", "opencode-usage-coach", "pipeline.log");
+var PIPE_LOG = join3(homedir2(), ".cache", "opencode-usage-coach", "pipeline.log");
 function pipeLog(msg) {
   try {
-    mkdirSync2(dirname2(PIPE_LOG), { recursive: true });
-    appendFileSync2(PIPE_LOG, `[SERVER] ${(/* @__PURE__ */ new Date()).toISOString()} ${msg}
+    mkdirSync3(dirname2(PIPE_LOG), { recursive: true });
+    appendFileSync3(PIPE_LOG, `[SERVER] ${(/* @__PURE__ */ new Date()).toISOString()} ${msg}
 `);
   } catch {
   }
 }
 pipeLog(`MODULE LOADED | node=${process.version} | pid=${process.pid}`);
-var STATE_DIR = join2(homedir(), ".cache", "opencode-usage-coach");
-var STATE_FILE = join2(STATE_DIR, "state.json");
-var LOG_FILE = join2(STATE_DIR, "coach.log");
+var STATE_DIR = join3(homedir2(), ".cache", "opencode-usage-coach");
+var STATE_FILE = join3(STATE_DIR, "state.json");
+var LOG_FILE = join3(STATE_DIR, "coach.log");
 function projectStateDir(dir) {
   const abs = resolve(dir || ".");
   const h = createHash("sha1").update(abs).digest("hex").slice(0, 12);
-  return join2(homedir(), ".cache", "opencode-usage-coach", "projects", h);
+  return join3(homedir2(), ".cache", "opencode-usage-coach", "projects", h);
 }
 function setStateDir(dir) {
   STATE_DIR = process.env.UC_STATE_DIR ?? projectStateDir(dir);
-  STATE_FILE = join2(STATE_DIR, "state.json");
-  LOG_FILE = join2(STATE_DIR, "coach.log");
+  STATE_FILE = join3(STATE_DIR, "state.json");
+  LOG_FILE = join3(STATE_DIR, "coach.log");
 }
 var NOOP_HOOKS = {};
 function log(msg) {
   try {
-    appendFileSync2(LOG_FILE, `${(/* @__PURE__ */ new Date()).toISOString()} ${msg}
+    appendFileSync3(LOG_FILE, `${(/* @__PURE__ */ new Date()).toISOString()} ${msg}
 `);
   } catch {
   }
 }
 function writeState(c) {
   try {
-    mkdirSync2(STATE_DIR, { recursive: true });
+    mkdirSync3(STATE_DIR, { recursive: true });
     writeFileSync2(STATE_FILE, JSON.stringify({ ...c, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }));
   } catch {
   }
 }
 function rulesFile() {
-  return join2(STATE_DIR, "rules.md");
+  return join3(STATE_DIR, "rules.md");
 }
 function failuresFile() {
-  return join2(STATE_DIR, "failures.ndjson");
+  return join3(STATE_DIR, "failures.ndjson");
 }
 function readRules() {
   try {
@@ -477,7 +491,7 @@ function readRules() {
   }
 }
 function implNotesFile() {
-  return join2(STATE_DIR, "impl-notes.md");
+  return join3(STATE_DIR, "impl-notes.md");
 }
 var IMPL_NOTE_INSTRUCTION = `
 ## Implementation Notes (important!)
@@ -524,8 +538,8 @@ ${notes}
 Source: generate task "${shortTask}"
 
 `;
-    mkdirSync2(STATE_DIR, { recursive: true });
-    appendFileSync2(implNotesFile(), entry);
+    mkdirSync3(STATE_DIR, { recursive: true });
+    appendFileSync3(implNotesFile(), entry);
   } catch (e) {
     log(`appendImplNotes err: ${String(e)}`);
   }
@@ -716,7 +730,7 @@ function extractKeywords(text) {
   }
 }
 function harnessFile(sessionID) {
-  return join2(STATE_DIR, sessionID || "_default", "harness.json");
+  return join3(STATE_DIR, sessionID || "_default", "harness.json");
 }
 function readHarness(sessionID) {
   try {
@@ -730,7 +744,7 @@ function readHarness(sessionID) {
 function writeHarness(sessionID, h) {
   try {
     const f = harnessFile(sessionID);
-    mkdirSync2(dirname2(f), { recursive: true });
+    mkdirSync3(dirname2(f), { recursive: true });
     h.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     writeFileSync2(f, JSON.stringify(h, null, 2));
   } catch {
@@ -753,7 +767,7 @@ function mutateHarness(sessionID, fn) {
   return next;
 }
 function interviewFile(sessionID) {
-  return join2(STATE_DIR, sessionID || "_default", "interview.json");
+  return join3(STATE_DIR, sessionID || "_default", "interview.json");
 }
 function readInterview(sessionID) {
   try {
@@ -767,7 +781,7 @@ function readInterview(sessionID) {
 function writeInterview(sessionID, s) {
   try {
     const f = interviewFile(sessionID);
-    mkdirSync2(dirname2(f), { recursive: true });
+    mkdirSync3(dirname2(f), { recursive: true });
     s.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     writeFileSync2(f, JSON.stringify(s, null, 2));
   } catch {
@@ -965,7 +979,7 @@ function parseFileList(rawList, baseDir) {
     let testPattern;
     let testFramework;
     for (const mf of manifestFiles) {
-      const full = join2(baseDir, mf);
+      const full = join3(baseDir, mf);
       if (existsSync2(full)) {
         try {
           const content = JSON.parse(readFileSync2(full, "utf8"));
@@ -1295,15 +1309,15 @@ function readHarnessCfg(dir) {
     return {};
   };
   return {
-    ...tryRead(join2(homedir(), ".config", "opencode-usage-coach", "harness.config.json")),
-    ...tryRead(join2(dir, "harness.config.json"))
+    ...tryRead(join3(homedir2(), ".config", "opencode-usage-coach", "harness.config.json")),
+    ...tryRead(join3(dir, "harness.config.json"))
   };
 }
 function writeHarnessCfg(updates) {
-  const configDir = join2(homedir(), ".config", "opencode-usage-coach");
-  const configPath = join2(configDir, "harness.config.json");
+  const configDir = join3(homedir2(), ".config", "opencode-usage-coach");
+  const configPath = join3(configDir, "harness.config.json");
   try {
-    mkdirSync2(configDir, { recursive: true });
+    mkdirSync3(configDir, { recursive: true });
     const existing = (() => {
       try {
         return JSON.parse(readFileSync2(configPath, "utf8"));
@@ -1335,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;
@@ -1403,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 } });
@@ -1410,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;
@@ -1420,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);
@@ -1448,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 {
       }
     }
@@ -1496,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")) {
@@ -1572,13 +1595,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;
@@ -1607,6 +1634,13 @@ 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;
@@ -1668,6 +1702,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;
@@ -2031,8 +2071,8 @@ Then: harness_done(). Follow the [usage-coach NEXT] directive each tool returns.
           async execute(args, _ctx) {
             const rec = { ts: (/* @__PURE__ */ new Date()).toISOString(), task: args.task, prompt: args.prompt, gradeResult: args.gradeResult, model: args.model, revisions: args.revisions };
             try {
-              mkdirSync2(STATE_DIR, { recursive: true });
-              appendFileSync2(failuresFile(), JSON.stringify(rec) + "\n");
+              mkdirSync3(STATE_DIR, { recursive: true });
+              appendFileSync3(failuresFile(), JSON.stringify(rec) + "\n");
             } catch (e) {
               log(`record_failure err: ${String(e)}`);
             }
@@ -2157,8 +2197,8 @@ Keep it concrete and actionable.`;
             const rule = out;
             try {
               const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-              mkdirSync2(STATE_DIR, { recursive: true });
-              appendFileSync2(rulesFile(), `## Rule (${date})
+              mkdirSync3(STATE_DIR, { recursive: true });
+              appendFileSync3(rulesFile(), `## Rule (${date})
 ${rule}
 Origin: ${args.task}
 
@@ -2632,6 +2672,7 @@ Note: Changes take effect immediately for new generate/grade calls.`,
   }
 }
 export {
+  __resetCodexbarMissing,
   buildGapPrompt,
   buildScanSummary,
   checkScanGate,
@@ -2641,9 +2682,11 @@ export {
   detectLanguage,
   extractImplNotes,
   extractKeywords,
+  fetchQuotaWithRetry,
   findActiveTaskId,
   formatReport,
   humanRemaining,
+  isCodexbarMissing,
   isFreeModel,
   isHarnessAgent,
   parseFileList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "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",