opencode-goal-mode 0.2.4 → 0.3.0

package/plugins/goal-guard/sidebar-data.js

@@ -0,0 +1,71 @@
+/**
+ * Read-only projection of persisted guard state for the TUI sidebar banner.
+ *
+ * The sidebar plugin runs in OpenCode's TUI process, separate from the server
+ * plugin that owns the live store. The two are paired through the same on-disk
+ * snapshot the server plugin already writes (persistence.js). This module reads
+ * that snapshot and projects the active session's goal into a compact banner
+ * model. It is pure and synchronous (a cheap file read), so it is unit-testable
+ * without a TUI runtime.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateBaseDir, projectKey } from "./persistence.js";
+import { DEFAULT_CONFIG } from "./config.js";
+import { sidebarView } from "./summary.js";
+
+/** Absolute path of the guard's state file for a given worktree. */
+export function sidebarStateFile(worktree, env = process.env) {
+  return join(stateBaseDir(env), `${projectKey(worktree)}.json`);
+}
+
+/** Defensive normalisation so a partial/legacy record never throws in projection. */
+function normalize(record) {
+  const st = record && typeof record === "object" ? record : {};
+  if (!Array.isArray(st.stickyGates)) st.stickyGates = [];
+  if (!Array.isArray(st.changedFiles)) st.changedFiles = [];
+  if (!st.latestVerdict || typeof st.latestVerdict !== "object") st.latestVerdict = {};
+  return st;
+}
+
+/**
+ * Choose which session's goal to show: the most-recently-touched ACTIVE session
+ * (optionally preferring an explicit sessionId when it is present and active).
+ */
+export function pickSession(snapshot, sessionId) {
+  if (!snapshot || !Array.isArray(snapshot.sessions)) return null;
+  const records = snapshot.sessions
+    .filter((e) => Array.isArray(e) && e.length === 2)
+    .map(([key, st]) => [key, normalize(st)]);
+  if (sessionId) {
+    const direct = records.find(([key, st]) => key === sessionId && st.active);
+    if (direct) return direct[1];
+  }
+  const active = records.filter(([, st]) => st.active);
+  if (active.length === 0) return null;
+  active.sort((a, b) => (b[1].touchedAt || 0) - (a[1].touchedAt || 0));
+  return active[0][1];
+}
+
+/**
+ * Build the sidebar banner model for a worktree, or null if there is nothing to
+ * show. Returns { goal, status, allowed, … } (see summary.sidebarView).
+ *
+ * @param {object} opts
+ * @param {string} opts.worktree   Project worktree root (same key the guard uses).
+ * @param {string} [opts.sessionId]
+ * @param {object} [opts.config]
+ * @param {Record<string,string|undefined>} [opts.env]
+ */
+export function readSidebarModel({ worktree, sessionId, config = DEFAULT_CONFIG, env = process.env } = {}) {
+  let snapshot;
+  try {
+    snapshot = JSON.parse(readFileSync(sidebarStateFile(worktree, env), "utf8"));
+  } catch {
+    return null; // no state yet, or unreadable — show nothing.
+  }
+  const record = pickSession(snapshot, sessionId);
+  if (!record) return null;
+  return sidebarView(record, config);
+}

package/plugins/goal-guard/summary.js

@@ -5,6 +5,39 @@
 
 import { requiredGates, missingGates, gatePassedFresh } from "./gates.js";
 
+/**
+ * A short, single-line human label for the current goal — preferring the
+ * recorded Goal Contract's original request, falling back to the captured goal
+ * text. Collapses whitespace and truncates to `max` chars for compact display
+ * (status reports, the TUI sidebar banner).
+ */
+export function shortGoalLabel(state, max = 80) {
+  const raw = String(state?.contract?.original || state?.goalText || "").replace(/\s+/g, " ").trim();
+  if (!raw) return "";
+  // Prefer the first sentence/clause if it is reasonably short.
+  const firstSentence = raw.split(/(?<=[.!?])\s/)[0];
+  const base = firstSentence.length > 0 && firstSentence.length <= max ? firstSentence : raw;
+  if (base.length <= max) return base;
+  return `${base.slice(0, max - 1).trimEnd()}…`;
+}
+
+/**
+ * Compact projection for the TUI sidebar banner: the short goal label, a
+ * one-line gate/dirty status, and whether completion is currently allowed.
+ * Returns null when there is no active goal worth showing.
+ */
+export function sidebarView(state, config) {
+  if (!state || !state.active) return null;
+  const goal = shortGoalLabel(state);
+  if (!goal) return null;
+  const required = requiredGates(state, config);
+  const missing = missingGates(state, config);
+  const passing = required.length - missing.length;
+  const allowed = required.length > 0 && missing.length === 0 && !state.dirty;
+  const status = `${passing}/${required.length} gates` + (state.dirty ? " · dirty" : "") + (allowed ? " · ready" : "");
+  return { goal, status, allowed, reviewCycles: state.reviewCycles, passing, required: required.length, dirty: Boolean(state.dirty) };
+}
+
 export function summarizeState(state, config) {
   const verdictSummary =
     state.verdicts
@@ -50,6 +83,7 @@ export function statusReport(state, config) {
   const missing = missingGates(state, config);
   return {
     active: Boolean(state.active),
+    goal: shortGoalLabel(state),
     dirty: Boolean(state.dirty),
     reviewCycles: state.reviewCycles,
     requiredGates: required,

package/plugins/goal-guard/tools.js

@@ -38,10 +38,16 @@ export function createGoalTools({ store, config, persist }) {
       async execute(_args, ctx) {
         const state = store.stateFor(ctx.sessionID);
         const report = statusReport(state, config);
+        const goal = report.goal ? `“${report.goal}” — ` : "";
         return {
-          title: `Goal status: completion ${report.completionAllowed ? "allowed" : "blocked"}`,
+          title: `Goal status: ${goal}completion ${report.completionAllowed ? "allowed" : "blocked"}`,
           output: JSON.stringify(report, null, 2),
-          metadata: { completionAllowed: report.completionAllowed, reviewCycles: report.reviewCycles },
+          metadata: {
+            goal: report.goal,
+            completionAllowed: report.completionAllowed,
+            reviewCycles: report.reviewCycles,
+            missingGates: report.missingGates,
+          },
         };
       },
     }),

package/plugins/goal-guard.js

@@ -179,7 +179,9 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
         // records against that same session (never another), so it can neither
         // mis-credit a sibling session nor break the parent goal, which the task
         // path already covers. Split by tool type so the two never double-count.
+        const wasAllowed = completionAllowed(state, config);
         let recordedAgent = null;
+        let recordedVerdict = null;
         if (tool === "task") {
           const sub = normalizedSubagent(inp);
           if (isReviewAgent(sub)) {
@@ -188,6 +190,7 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
             if (verdict) {
               recordVerdict(store, state, sub, verdict, text);
               recordedAgent = sub;
+              recordedVerdict = verdict;
             }
           }
         } else if (isReviewAgent(state.currentAgent)) {
@@ -196,12 +199,22 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
           if (verdict) {
             recordVerdict(store, state, state.currentAgent, verdict, text);
             recordedAgent = state.currentAgent;
+            recordedVerdict = verdict;
           }
         }
 
         if (recordedAgent === CYCLE_CLOSING_AGENT) {
           maybeClearDirtyOnFinalPass(state, config);
         }
+
+        // Surface review progress in the TUI: a toast per recorded verdict, and a
+        // single celebratory toast the moment the last required gate clears.
+        if (recordedAgent && recordedVerdict && config.toastOnReview) {
+          logger.toast(`Goal Guard: ${recordedAgent} → ${recordedVerdict}`, recordedVerdict === "PASS" ? "success" : "warning");
+          if (!wasAllowed && completionAllowed(state, config)) {
+            logger.toast("Goal Guard: all required gates passed — completion unlocked", "success");
+          }
+        }
         persist();
       } catch {
         /* never break a turn */

package/plugins/goal-sidebar.js

@@ -0,0 +1,141 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * Goal Mode — experimental TUI sidebar banner.
+ *
+ * EXPERIMENTAL. This is a TUI plugin module (the companion to the server-side
+ * goal-guard plugin). It renders the current goal as a short, shining-yellow
+ * banner in the OpenCode sidebar, with a compact `passing/total gates ·
+ * dirty/ready` status line, and updates as reviews land.
+ *
+ * It only does anything inside a TUI-plugin-capable OpenCode (one exposing
+ * `api.slots.register`). On any older runtime, missing API, or render error it
+ * silently no-ops — it can never break your TUI.
+ *
+ * Pairing: it reads the SAME on-disk snapshot the goal-guard server plugin
+ * writes (see goal-guard/persistence.js), so the two stay in sync with no extra
+ * IPC. The pure projection (`summary.sidebarView`) is shared with the server
+ * plugin and unit-tested via goal-guard/sidebar-data.js; only the file read and
+ * state-path computation are reimplemented here.
+ *
+ * Runtime constraints (mirrored from working OpenCode TUI plugins):
+ *  - TUI plugin modules export `export default { id, tui }`.
+ *  - The Bun TUI plugin runtime does NOT support top-level ESM imports of Node
+ *    built-ins, so `node:fs`/`node:path`/`node:os`/`node:crypto` are `require()`d
+ *    lazily inside functions. Top-level imports of regular packages (solid-js)
+ *    and of our Node-built-in-free local modules are fine.
+ *  - This file uses Solid/opentui JSX and is loaded only by OpenCode's (Bun) TUI
+ *    runtime, which transpiles it; it is never imported by the Node test suite.
+ */
+
+import { createSignal, onCleanup, Show } from "solid-js";
+import { sidebarView } from "./goal-guard/summary.js";
+import { DEFAULT_CONFIG } from "./goal-guard/config.js";
+
+const DEFAULT_COLOR = "#FFD700"; // shining yellow
+const POLL_MS = 1500;
+
+function resolveOptions(options, env) {
+  const e = env || {};
+  const enabledOpt = options?.sidebarBanner;
+  const enabledEnv = e.GOAL_GUARD_SIDEBAR_BANNER;
+  const disabled =
+    enabledOpt === false || enabledEnv === "0" || enabledEnv === "false" || enabledEnv === "off";
+  const color = options?.sidebarColor || e.GOAL_GUARD_SIDEBAR_COLOR || DEFAULT_COLOR;
+  return { enabled: !disabled, color };
+}
+
+/**
+ * Read the guard's persisted snapshot for a worktree. The state-path logic is
+ * kept identical to goal-guard/persistence.js (stateBaseDir + projectKey); node
+ * built-ins are required lazily to satisfy the TUI runtime.
+ */
+function readSnapshot(worktree) {
+  try {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const os = require("node:os");
+    const crypto = require("node:crypto");
+    const xdg = process.env.XDG_STATE_HOME && process.env.XDG_STATE_HOME.trim();
+    const base = xdg || path.join(os.homedir(), ".local", "state");
+    const key = crypto.createHash("sha256").update(String(worktree || "default")).digest("hex").slice(0, 16);
+    const file = path.join(base, "opencode", "goal-guard", `${key}.json`);
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Most-recently-touched active session, preferring an explicit active sessionId. */
+function pickSession(snapshot, sessionId) {
+  if (!snapshot || !Array.isArray(snapshot.sessions)) return null;
+  const records = snapshot.sessions
+    .filter((e) => Array.isArray(e) && e.length === 2)
+    .map(([key, st]) => [key, st && typeof st === "object" ? st : {}]);
+  if (sessionId) {
+    const direct = records.find(([key, st]) => key === sessionId && st.active);
+    if (direct) return direct[1];
+  }
+  const active = records.filter(([, st]) => st.active);
+  if (active.length === 0) return null;
+  active.sort((a, b) => (b[1].touchedAt || 0) - (a[1].touchedAt || 0));
+  return active[0][1];
+}
+
+function readModel(worktree, sessionId) {
+  const snapshot = readSnapshot(worktree);
+  if (!snapshot) return null;
+  const record = pickSession(snapshot, sessionId);
+  if (!record) return null;
+  try {
+    return sidebarView(record, DEFAULT_CONFIG);
+  } catch {
+    return null;
+  }
+}
+
+export const id = "goal-mode-sidebar";
+
+/** @type {import("@opencode-ai/plugin/tui").TuiPlugin} */
+export const tui = async (api, options) => {
+  try {
+    const { enabled, color } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
+    if (!enabled) return;
+    if (!api?.slots?.register) return; // runtime without the slot API → no-op.
+
+    const worktree = api.state?.path?.worktree || api.state?.path?.directory;
+
+    api.slots.register({
+      order: 50,
+      slots: {
+        sidebar_content(_ctx, props) {
+          const read = () => {
+            try {
+              return readModel(worktree, props?.session_id);
+            } catch {
+              return null;
+            }
+          };
+          const [model, setModel] = createSignal(read());
+          const timer = setInterval(() => setModel(read()), POLL_MS);
+          onCleanup(() => clearInterval(timer));
+          return (
+            <Show when={model()}>
+              <box flexDirection="column">
+                <text fg={color}>
+                  {"◆ "}
+                  <b>GOAL</b>
+                  {`  ${model().goal}`}
+                </text>
+                <text fg={color}>{model().status}</text>
+              </box>
+            </Show>
+          );
+        },
+      },
+    });
+  } catch {
+    /* TUI runtime missing or API drift — render nothing rather than crash. */
+  }
+};
+
+export default { id, tui };

package/research/benchmarks.md

@@ -4,81 +4,87 @@ Reproducible measurement of the destructive-command guard from a repository
 checkout. Run:
 
 ```bash
-npm run bench          # detection / false-positive / latency benchmark
-npm run bench:truthfulness  # print the completion truthfulness benchmark JSON
-npm run bench:compare  # regenerate the capability-comparison chart
+npm run bench                # external + fixture benchmarks → results.json + charts
+node benchmarks/external.mjs # external benchmark only (add --json for full detail)
+npm run bench:truthfulness   # print the completion-enforcement fixture JSON
+npm run bench:compare        # regenerate the capability-comparison chart
 ```
 
 `npm run bench` writes `docs/benchmarks/results.json` and the SVG charts the
 README embeds.
 
-## Methodology
-
-- **Corpus** (`benchmarks/corpus.mjs`): 71 real shell commands a coding agent
-  might emit, each labeled `destructive` (a guard must block) or `safe` (a guard
-  must not block). Split into families: *classic* (plain `rm -rf`, `git reset
-  --hard`), *obfuscated* (the bypass corpus — substitutions, wrappers, `bash -c`,
-  interpreters, weaponized git), *remote-exec* (`curl | sh`), and *safe*
-  (read-only and quoted-text commands, including ones the old guard
-  false-positived).
-- **Baseline** (`benchmarks/legacy-analyzer.mjs`): the original regex classifier,
-  preserved **verbatim** from the first published release (commit `130956d`), so
-  the comparison is apples-to-apples against the same code that shipped.
-- **A command counts as "blocked"** when the analyzer flags it `destructive` or
-  `networkExec` (the two signals `tool.execute.before` throws on). `mutating`
-  marks the session dirty but does not block, so it is not counted here.
-- **Metrics**: detection rate (recall over destructive commands),
-  false-positive rate (safe commands wrongly blocked), and per-command latency.
-- **False Completion Dataset** (`benchmarks/completion-corpus.mjs`): labeled final
-  answer scenarios for premature and valid completion claims. It checks whether
-  `completion.js` blocks missing review-cycle lines, zero cycles, stale reviews,
-  mismatched cycle counts, missing contextual gates, and allows inactive or valid
-  completions.
-- **Truthfulness Score** (`benchmarks/truthfulness.mjs`): weighted score over the
-  dataset: 65% decision accuracy (blocked vs allowed) and 35% reason accuracy for
-  blocked false-completion claims.
-
-## Results
-
-Representative run (Node 22, single-threaded; latency varies by machine, the
-accuracy figures do not):
-
-| Metric | Legacy regex guard | Goal Mode analyzer |
+## Why this was rewritten
+
+The previous benchmark reported "20.8% → 100% detection, 21.7% → 0% false
+positives" on a **71-command corpus the analyzer's author wrote**. The analyzer
+was, in effect, the specification of that corpus, so 100%/0% mostly restated
+"my code passes my own examples." Those numbers are still produced — but they are
+now labeled as *regression fixtures*, and the headline figure comes from an
+**external corpus the analyzer was never fitted to**.
+
+## Headline: external corpus
+
+- **Source**: real example commands from
+  [tldr-pages](https://github.com/tldr-pages/tldr) (`common`, `linux`, `osx`
+  English pages), pinned by commit in `benchmarks/external-corpus.json`. These
+  are written by hundreds of contributors with no knowledge of this analyzer, so
+  it cannot have been tuned to them. `tldr` `{{placeholder}}` tokens and
+  `[-f|--force]` alternative-flag notation are canonicalized into literal
+  commands by `benchmarks/build-external-corpus.mjs`.
+- **Ground-truth labels** come from `labelDestructive()` in that builder: a
+  deliberately simple, transparent rule (primary utility ∈ a fixed irreversible
+  set; specific destructive `git` subcommands; `curl|wget … | sh`). It is
+  intentionally **independent of the analyzer's own logic**. No automatic labeler
+  is perfect, so the benchmark prints every disagreement for audit rather than
+  hiding them.
+- **Sampling**: all destructive examples found are kept (they are rare in real
+  docs); safe examples are stride-sampled to a cap. This imbalance is recorded in
+  the corpus `totals` and disclosed here so it is not mistaken for a base rate.
+
+Representative run (sample of 704 commands: 104 destructive, 600 safe):
+
+| On real third-party commands | Legacy regex guard | Goal Mode analyzer |
 | --- | --- | --- |
-| Detection rate | **20.8%** (10/48) | **100%** (48/48) |
-| False-positive rate | **21.7%** (5/23) | **0%** (0/23) |
-| Detection — classic | 100% | 100% |
-| Detection — obfuscated | 0% (0/35) | 100% (35/35) |
-| Detection — remote-exec | 0% (0/3) | 100% (3/3) |
-| Latency per command | ~2.3 µs | ~3.8 µs |
-
-False Completion Dataset run:
-
-| Metric | Goal Mode |
-| --- | --- |
-| Truthfulness score | **100.0%** |
-| Decision accuracy | **100.0%** |
-| Reason accuracy | **100.0%** |
-| False-completion block rate | **100.0%** |
-| Valid-completion allow rate | **100.0%** |
-
-The legacy guard catches only the *classic* family and misses every obfuscated
-and remote-execution command, while wrongly blocking 1-in-5 benign commands. The
-tokenizer catches the entire corpus with zero false positives, for an extra
-~1.5 µs per command on this run — negligible for a per-tool-call guard (still
-hundreds of thousands of classifications per second).
+| Detection rate | 53.8% | **93.3%** |
+| False-positive rate | 0.2% | 0.2% |
+
+Reading the result honestly:
+
+- The remaining Goal Mode misses are almost entirely un-flagged single-target
+  `rm <file>` (and `rm -i`/`-v`/`-d`), which the guard **intentionally permits**:
+  it blocks `rm -r`/`rm -f`, command-substitution/`bash -c`/interpreter deletes,
+  and remote exec, but not a plain single-file `rm`. Under the strict
+  every-`rm`-is-destructive labeler these are counted as misses.
+- The one counted false positive (`git filter-repo …`) genuinely rewrites
+  history, so the real-world false-positive rate is effectively zero. Run
+  `node benchmarks/external.mjs --json` to see the full miss / false-positive
+  lists.
+- This benchmark directly drove real fixes: `mkfs.<fstype>` variants, `srm`, and
+  `mkswap` were missing from the analyzer and were added after the external run
+  exposed them.
+
+## Curated regression fixtures (a spec, not a survey)
+
+`benchmarks/corpus.mjs` (71 commands) and `benchmarks/completion-corpus.mjs`
+(9 completion-claim cases) define the patterns the analyzer must catch and the
+completion-policy decisions it must make. They pass **by construction** and exist
+to prevent regressions. The 100%/0% / "all cases pass" numbers there are not
+measured accuracy — treat them as a checklist the code is required to satisfy.
+
+- **Baseline** for the fixture comparison (`benchmarks/legacy-analyzer.mjs`) is
+  the original regex classifier, preserved **verbatim** from the first published
+  release (commit `130956d`), so it is the author's own prior code, not a
+  strawman built to lose.
+- **A command counts as "blocked"** when the analyzer flags it `destructive` or
+  `networkExec` (the signals `tool.execute.before` throws on). `mutating` marks
+  the session dirty but does not block, so it is not counted.
 
 ## Honesty notes
 
-- The corpus is hand-built to exercise the known bypass classes; it is a
-  capability benchmark, not a claim of catching *every* possible obfuscation
-  (the analyzer fails open on un-analyzable dynamic commands — see
-  [shell-hardening.md](shell-hardening.md)).
-- The latency comparison is intentionally shown even though the new analyzer is
-  slower: the win is accuracy, and the parse cost is still only a few
-  microseconds per tool-call candidate.
-- "100% on this corpus" means 100% of the labeled set; new bypass classes that
-  are discovered get added to the corpus and fixed (that is how the second-wave
-  findings — `sudo -u`, `pnpm dlx`, interpreter shell-out — entered it).
-- The Truthfulness Score is corpus truthfulness for mechanical completion claims,
-  not a global claim that an LLM's prose is semantically true in every domain.
+- The analyzer fails **open** on un-analyzable dynamic commands (deferring to the
+  host's permission rules); it is defense-in-depth, not a jail — see
+  [shell-hardening.md](shell-hardening.md).
+- The latency comparison is shown even though the tokenizer is slower than a
+  regex: the win is accuracy, and the parse cost is ~1µs per candidate.
+- The completion-enforcement fixtures verify mechanical completion-claim policy,
+  not that an LLM's prose is semantically true in every domain.