opencode-usage-coach 0.8.1 → 0.8.3

package/agents/usage-coach-harness.md

@@ -50,14 +50,15 @@ The user's message is the task source. If it has multiple distinct parts, decomp
 DEPENDENT tasks (B needs A) → always sequential `generate` calls, regardless of quota.
 
 1. Call `harness_start(name, N)` to register the run on the panel.
-2. **PRE-FLIGHT — unknown_scan:** Call `unknown_scan({prompt, tasks: [{id, title}, ...]})`.
+2. **DIAGNOSIS GATE — unknown_scan (REQUIRED, not optional):** Call `unknown_scan({prompt, tasks: [{id, title}, ...]})`.
+   This is enforced: if you skip it, `generate` will inject a ⚠ warning into the sub-session prompt.
    Review the report:
    - If QUESTIONS are flagged → ask the user concisely, then adjust tasks.
    - If TASK REFINEMENTS are suggested → apply via `task_update` (split/add/remove).
-   - If UNKNOWN UNKNOWNS with high impact are found → acknowledge them in the
-     generate prompts (the domain DB injection will help, but explicitly call them out).
-   This step prevents wasted steps from wrong assumptions. Skip only if the
-   task is trivially clear.
+   - If UNKNOWN UNKNOWNS with high impact are found → they will be auto-injected into
+     generate prompts via scanSummary, but you should explicitly acknowledge them.
+   You may skip unknown_scan ONLY for: revisions (applying grade feedback), trivial
+   single-file edits, or empty directories. Skipping must be a conscious choice.
 3. For each task i (1..N):
    a. `task_update(i, title, "generating")`.
    b. **Generate** — call `generate({ prompt: "Task: {title}. Perform it for real in the current directory (write/edit files)." })`. The generator model runs in a sub-session and writes files directly — its return value is a summary, NOT the work itself.
@@ -72,6 +73,7 @@ DEPENDENT tasks (B needs A) → always sequential `generate` calls, regardless o
 4. When all tasks are done → `harness_done()`.
 
 ## Rules
+- **Diagnose before acting.** Never implement a fix based on a problem description without verifying what actually happened. Read logs, check source code, reproduce the issue. If you find yourself writing code within 60 seconds of reading a problem, STOP and verify your assumptions first.
 - **Follow the [usage-coach NEXT] directive each tool returns.** `harness_start`, `generate`, and `grade` all append a `NEXT` line telling you exactly what to call next. This makes the loop deterministic — do not improvise the sequence, follow `NEXT`.
 - In the loop, do NOT do the work yourself — call `generate`/`grade` (they run the configured models). You orchestrate. (Outside the loop, for trivial requests, act directly.)
 - Call `task_update` on every state transition — the sidebar panel reads it for live visibility.

package/dist/index.js

@@ -837,11 +837,48 @@ function writeUnknownScan(sessionID, result) {
     const h = readHarness(sessionID);
     if (h) {
       h.unknownScan = result;
+      h.scanDone = true;
+      h.scanSummary = buildScanSummary(result);
       writeHarness(sessionID, h);
     }
   } catch {
   }
 }
+function buildScanSummary(r) {
+  const lines = [];
+  if (r.unknownUnknowns?.length) {
+    lines.push(`Unknown Unknowns (${r.unknownUnknowns.length}):`);
+    for (const uu of r.unknownUnknowns.slice(0, 5)) {
+      lines.push(`  [${uu.impact?.toUpperCase() ?? "?"}] ${uu.finding}${uu.mitigation ? ` \u2192 ${uu.mitigation}` : ""}`);
+    }
+  }
+  if (r.unknownKnowns?.length) {
+    lines.push(`Implicit knowledge (${r.unknownKnowns.length}):`);
+    for (const uk of r.unknownKnowns.slice(0, 5)) {
+      lines.push(`  \u2139 ${uk.finding}`);
+    }
+  }
+  if (r.questions?.length) {
+    lines.push(`Pending questions (${r.questions.length}):`);
+    for (const q of r.questions.slice(0, 5)) {
+      lines.push(`  [Q] ${q.question}`);
+    }
+  }
+  return lines.join("\n");
+}
+function checkScanGate(sessionID) {
+  try {
+    const h = readHarness(sessionID);
+    if (!h || !h.scanRequired) return { warning: null, summary: null };
+    if (h.scanDone) return { warning: null, summary: h.scanSummary ?? null };
+    return {
+      warning: `\u26A0 DIAGNOSIS GATE: unknown_scan was NOT called before this generate. You are generating without pre-flight gap analysis. Blind spots (unknown unknowns) may cause wrong assumptions and waste steps. Call unknown_scan first, OR proceed consciously accepting the risk.`,
+      summary: null
+    };
+  } catch {
+    return { warning: null, summary: null };
+  }
+}
 function readHarnessCfg(dir) {
   const tryRead = (p) => {
     try {
@@ -1275,12 +1312,15 @@ async function UsageCoachPlugin(input) {
           description: "Start the harness: register the total task count on the panel. Call once when the harness loop begins. IMPORTANT: each generate/generate_batch sub-session is step-limited (default 30). If any task seems too large, split it into smaller subtasks BEFORE starting \u2014 oversized tasks will timeout.",
           args: { name: tool.schema.string(), total: tool.schema.number() },
           async execute(args, ctx) {
-            writeHarness(ctx.sessionID, { name: args.name, total: args.total, current: 0, tasks: [], usage: {}, active: true, startedAt: (/* @__PURE__ */ new Date()).toISOString() });
+            writeHarness(ctx.sessionID, { name: args.name, total: args.total, current: 0, tasks: [], usage: {}, active: true, scanRequired: true, startedAt: (/* @__PURE__ */ new Date()).toISOString() });
             return `Harness '${args.name}' started (${args.total} tasks).
 
-PRE-FLIGHT (unknown_scan): Before starting generate, call unknown_scan to check for blind spots. This scans the codebase against your tasks and finds gaps (unknown unknowns) that could waste steps if discovered late.
+\u26A0 DIAGNOSIS GATE \u2014 unknown_scan is REQUIRED before generate/generate_batch.
   unknown_scan({ prompt: "<user request>", tasks: [{id:1, title:"..."}, ...] })
-Review the report: if questions are flagged, ask the user first. If task splits are suggested, adjust via task_update. THEN proceed to the loop below.
+  If you skip it, generate will inject a \u26A0 warning into the sub-session prompt.
+  Review the report: if QUESTIONS are flagged \u2192 ask the user first. If TASK
+  REFINEMENTS are suggested \u2192 apply via task_update. Unknown unknowns found will
+  be automatically injected into generate prompts as context.
 
 STEP LIMIT (default ${DEFAULT_MAX_STEPS}): each generate call creates a sub-session that is automatically aborted if it exceeds ${DEFAULT_MAX_STEPS} assistant steps. Before starting the loop, review each task: can it be completed in a focused, single-pass effort? If a task seems too broad (multiple files, multiple features, open-ended research), SPLIT it now into 2-3 smaller subtasks. A timeout wastes quota \u2014 split upfront.
 
@@ -1643,6 +1683,22 @@ ${priorNotes}
               log(`generate impl-notes read err: ${String(e)}`);
             }
             prefix += IMPL_NOTE_INSTRUCTION;
+            const gate = checkScanGate(ctx.sessionID);
+            if (gate.warning) {
+              prefix = `${gate.warning}
+
+---
+
+` + prefix;
+            }
+            if (gate.summary) {
+              prefix = `Pre-flight scan findings (from unknown_scan \u2014 heed these):
+${gate.summary}
+
+---
+
+` + prefix;
+            }
             const genTaskId = findActiveTaskId(ctx.sessionID, "generating");
             const maxSteps = args.max_steps ?? DEFAULT_MAX_STEPS;
             const out = await runModel(
@@ -1699,8 +1755,20 @@ ${priorNotes}
             const rules = readRules();
             const priorNotes = readImplNotes(5);
             const maxSteps = args.max_steps ?? DEFAULT_MAX_STEPS;
+            const gate = checkScanGate(ctx.sessionID);
+            const gatePrefix = gate.warning ? `${gate.warning}
+
+---
+
+` : gate.summary ? `Pre-flight scan findings (from unknown_scan \u2014 heed these):
+${gate.summary}
+
+---
+
+` : "";
             const runOne = async (t) => {
-              let prefix = rules ? `Lessons learned from previous failures (apply where relevant):
+              let prefix = gatePrefix;
+              prefix += rules ? `Lessons learned from previous failures (apply where relevant):
 ${rules}
 
 ---

package/dist/tui.js

@@ -83,8 +83,11 @@ var TLABEL = {
   completed: "done",
   failed: "fail",
   timed_out: "timeout",
-  halted_quota: "quota-halt"
+  halted_quota: "quota-halt",
+  stale: "STALE"
 };
+var STALE_MS = 5 * 6e4;
+var HIDE_MS = 30 * 6e4;
 function barFill(p) {
   const n = p <= 0 ? 0 : Math.max(1, Math.min(10, Math.round(p / 10)));
   return "\u2588".repeat(n);
@@ -365,79 +368,89 @@ function initializeTui(api, disposeRoot) {
         return _el$46;
       })());
     }
-    if (h && h.tasks.length > 0) {
-      nodes.push((() => {
-        var _el$48 = _$createElement("text");
-        _$insertNode(_el$48, _$createTextNode(` `));
-        return _el$48;
-      })());
-      nodes.push((() => {
-        var _el$50 = _$createElement("text"), _el$51 = _$createTextNode(`harness: `), _el$52 = _$createTextNode(` `), _el$53 = _$createTextNode(`/`);
-        _$insertNode(_el$50, _el$51);
-        _$insertNode(_el$50, _el$52);
-        _$insertNode(_el$50, _el$53);
-        _$insert(_el$50, () => h.name, _el$52);
-        _$insert(_el$50, () => h.current, _el$53);
-        _$insert(_el$50, () => h.total, null);
-        _$effect((_$p) => _$setProp(_el$50, "style", st("textMuted"), _$p));
-        return _el$50;
-      })());
-      for (const t of h.tasks) {
-        const sKey = statusKey[t.status] ?? "text";
-        const lbl = TLABEL[t.status] ?? t.status;
-        const rev = t.revisions > 0 && t.status === "revising" ? `(${t.revisions})` : "";
-        const mdl = t.model ? ` ${t.model.split("/").pop() ?? t.model}` : "";
-        const hasSub = !!t.subSessionId;
-        const subStepStr = hasSub && t.subStep !== void 0 && t.subStep > 0 ? ` step:${t.subStep}` : "";
-        const subEl = hasSub && t.subElapsed !== void 0 ? ` ${t.subElapsed}s` : "";
-        const subWarn = hasSub && (t.subElapsed ?? 0) > 300;
-        const elapsed = t.startedAt ? Math.max(0, Math.round((Date.now() - new Date(t.startedAt).getTime()) / 1e3)) : 0;
-        const taskEl = t.status === "completed" || t.status === "failed" ? "" : elapsed > 0 ? ` ${elapsed}s` : "";
-        const displayEl = hasSub ? subEl : taskEl;
-        const lineKey = subWarn ? "warning" : sKey;
+    if (h && h.tasks.length > 0 && h.active !== false) {
+      const hAge = h.updatedAt ? Date.now() - new Date(h.updatedAt).getTime() : 0;
+      const hasActiveSub = h.tasks.some((t) => !!t.subSessionId);
+      const isStale = !hasActiveSub && hAge > STALE_MS;
+      const shouldHide = hAge > HIDE_MS && !hasActiveSub;
+      if (shouldHide) {
+      } else {
         nodes.push((() => {
-          var _el$54 = _$createElement("text"), _el$55 = _$createTextNode(` \u25CF `), _el$56 = _$createTextNode(` `), _el$57 = _$createTextNode(` `);
-          _$insertNode(_el$54, _el$55);
-          _$insertNode(_el$54, _el$56);
-          _$insertNode(_el$54, _el$57);
-          _$insert(_el$54, () => t.id, _el$56);
-          _$insert(_el$54, mdl, _el$56);
-          _$insert(_el$54, lbl, _el$57);
-          _$insert(_el$54, rev, _el$57);
-          _$insert(_el$54, subStepStr, _el$57);
-          _$insert(_el$54, displayEl, _el$57);
-          _$insert(_el$54, () => t.title, null);
-          _$effect((_$p) => _$setProp(_el$54, "style", st(lineKey), _$p));
-          return _el$54;
+          var _el$48 = _$createElement("text");
+          _$insertNode(_el$48, _$createTextNode(` `));
+          return _el$48;
         })());
-        const pv = t.model ? (t.model.split("/")[0] ?? "").split("-")[0] : "";
-        const provCoach = pv ? s?.providers?.find((p) => p.id === pv || pv && p.id.startsWith(pv) || pv && pv.startsWith(p.id)) : s?.providers?.[0];
-        const rawPct = provCoach?.fiveHour ?? s?.fiveHour ?? -1;
-        const pct = rawPct < 0 ? 0 : rawPct;
-        const pctLabel = rawPct < 0 ? "n/a" : `${rawPct}%`;
         nodes.push((() => {
-          var _el$58 = _$createElement("box"), _el$59 = _$createElement("text"), _el$61 = _$createElement("text"), _el$62 = _$createElement("text"), _el$63 = _$createElement("text"), _el$64 = _$createTextNode(` `);
-          _$insertNode(_el$58, _el$59);
-          _$insertNode(_el$58, _el$61);
-          _$insertNode(_el$58, _el$62);
-          _$insertNode(_el$58, _el$63);
-          _$setProp(_el$58, "flexDirection", "row");
-          _$insertNode(_el$59, _$createTextNode(` 5h `));
-          _$insert(_el$61, () => barFill(pct));
-          _$insert(_el$62, () => barEmpty(pct));
-          _$insertNode(_el$63, _el$64);
-          _$insert(_el$63, pctLabel, null);
-          _$effect((_p$) => {
-            var _v$11 = st("text"), _v$12 = st("text");
-            _v$11 !== _p$.e && (_p$.e = _$setProp(_el$61, "style", _v$11, _p$.e));
-            _v$12 !== _p$.t && (_p$.t = _$setProp(_el$62, "style", _v$12, _p$.t));
-            return _p$;
-          }, {
-            e: void 0,
-            t: void 0
-          });
-          return _el$58;
+          var _el$50 = _$createElement("text"), _el$51 = _$createTextNode(`harness: `), _el$52 = _$createTextNode(` `), _el$53 = _$createTextNode(`/`);
+          _$insertNode(_el$50, _el$51);
+          _$insertNode(_el$50, _el$52);
+          _$insertNode(_el$50, _el$53);
+          _$insert(_el$50, () => h.name, _el$52);
+          _$insert(_el$50, () => h.current, _el$53);
+          _$insert(_el$50, () => h.total, null);
+          _$insert(_el$50, isStale ? " (stale)" : "", null);
+          _$effect((_$p) => _$setProp(_el$50, "style", st("textMuted"), _$p));
+          return _el$50;
         })());
+        for (const t of h.tasks) {
+          const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "timed_out", "halted_quota"]);
+          const displayStatus = isStale && !TERMINAL.has(t.status) ? "stale" : t.status;
+          const sKey = statusKey[displayStatus] ?? "text";
+          const lbl = TLABEL[displayStatus] ?? displayStatus;
+          const rev = t.revisions > 0 && t.status === "revising" ? `(${t.revisions})` : "";
+          const mdl = t.model ? ` ${t.model.split("/").pop() ?? t.model}` : "";
+          const hasSub = !!t.subSessionId;
+          const subStepStr = hasSub && t.subStep !== void 0 && t.subStep > 0 ? ` step:${t.subStep}` : "";
+          const subEl = hasSub && t.subElapsed !== void 0 ? ` ${t.subElapsed}s` : "";
+          const subWarn = hasSub && (t.subElapsed ?? 0) > 300;
+          const elapsed = t.startedAt ? Math.max(0, Math.round((Date.now() - new Date(t.startedAt).getTime()) / 1e3)) : 0;
+          const taskEl = t.status === "completed" || t.status === "failed" ? "" : elapsed > 0 ? ` ${elapsed}s` : "";
+          const displayEl = hasSub ? subEl : taskEl;
+          const lineKey = subWarn ? "warning" : sKey;
+          nodes.push((() => {
+            var _el$54 = _$createElement("text"), _el$55 = _$createTextNode(` \u25CF `), _el$56 = _$createTextNode(` `), _el$57 = _$createTextNode(` `);
+            _$insertNode(_el$54, _el$55);
+            _$insertNode(_el$54, _el$56);
+            _$insertNode(_el$54, _el$57);
+            _$insert(_el$54, () => t.id, _el$56);
+            _$insert(_el$54, mdl, _el$56);
+            _$insert(_el$54, lbl, _el$57);
+            _$insert(_el$54, rev, _el$57);
+            _$insert(_el$54, subStepStr, _el$57);
+            _$insert(_el$54, displayEl, _el$57);
+            _$insert(_el$54, () => t.title, null);
+            _$effect((_$p) => _$setProp(_el$54, "style", st(lineKey), _$p));
+            return _el$54;
+          })());
+          const pv = t.model ? (t.model.split("/")[0] ?? "").split("-")[0] : "";
+          const provCoach = pv ? s?.providers?.find((p) => p.id === pv || pv && p.id.startsWith(pv) || pv && pv.startsWith(p.id)) : s?.providers?.[0];
+          const rawPct = provCoach?.fiveHour ?? s?.fiveHour ?? -1;
+          const pct = rawPct < 0 ? 0 : rawPct;
+          const pctLabel = rawPct < 0 ? "n/a" : `${rawPct}%`;
+          nodes.push((() => {
+            var _el$58 = _$createElement("box"), _el$59 = _$createElement("text"), _el$61 = _$createElement("text"), _el$62 = _$createElement("text"), _el$63 = _$createElement("text"), _el$64 = _$createTextNode(` `);
+            _$insertNode(_el$58, _el$59);
+            _$insertNode(_el$58, _el$61);
+            _$insertNode(_el$58, _el$62);
+            _$insertNode(_el$58, _el$63);
+            _$setProp(_el$58, "flexDirection", "row");
+            _$insertNode(_el$59, _$createTextNode(` 5h `));
+            _$insert(_el$61, () => barFill(pct));
+            _$insert(_el$62, () => barEmpty(pct));
+            _$insertNode(_el$63, _el$64);
+            _$insert(_el$63, pctLabel, null);
+            _$effect((_p$) => {
+              var _v$11 = st("text"), _v$12 = st("text");
+              _v$11 !== _p$.e && (_p$.e = _$setProp(_el$61, "style", _v$11, _p$.e));
+              _v$12 !== _p$.t && (_p$.t = _$setProp(_el$62, "style", _v$12, _p$.t));
+              return _p$;
+            }, {
+              e: void 0,
+              t: void 0
+            });
+            return _el$58;
+          })());
+        }
       }
     }
     return (() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "opencode closed-loop usage coach — quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
   "type": "module",
   "main": "./dist/index.js",