opencode-goal-mode 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## v0.4.2
+
+### The sidebar Goal section now actually renders in the live TUI
+
+- **Root-cause fix.** The `sidebar_content` slot bailed at mount with
+  `return undefined` whenever no goal existed *yet* — but the goal is normally set
+  *after* the sidebar mounts, so the polling component never started and the Goal
+  section never appeared. The slot now **always mounts a reactive, polling
+  component** and reveals the section (via `<Show>`) the moment the goal is
+  recorded. Verified by driving the real OpenCode TUI in a PTY.
+- **Stale plugin cache.** OpenCode caches TUI plugins under
+  `~/.cache/opencode/packages/<name>@<spec>/` and never re-checks npm, so upgrades
+  kept loading the *old* sidebar build. The installer now clears that cache on
+  install and uninstall, so a restart picks up the installed version.
+- The first-display rainbow now triggers when the goal first appears (not at
+  mount, when there may be no goal yet).
+- The sidebar resolves state under both the worktree and directory path keys, so a
+  path-key mismatch can't hide an active goal.
+
+### Sidebar layout
+
+- The gate count and the lifecycle status are now on **separate lines**, each in
+  its own colour (GOAL = yellow, title = white, gates = cyan, status = orange).
+
+### Native todos are replaced in goal mode
+
+- The `goal` agent no longer uses the native `todowrite` tool (it is disabled in
+  Goal Mode). Because OpenCode renders native todos as their own sidebar slot, the
+  only way to replace them is to stop producing them — so in a goal session the
+  native todo list stays empty and the structured Goal-owned section is what shows.
+  Build and every other mode keep their native todos.
+
+## v0.4.1
+
+### Restructured Goal sidebar todo section
+
+- The sidebar Goal section is now a proper stacked, multi-colour layout instead of
+  one run of text: a bold **`GOAL`** label on its own line (yellow while running,
+  red when done), then the goal title, then a `passing/total gates · status` line —
+  each line in its own highlight colour (GOAL yellow, title white, status cyan) so
+  they never blend together. It opens with a first-display per-line rainbow, then
+  settles.
+- Removed the noisy `· changes pending` suffix from the status line; pending work
+  now surfaces as a structured todo row instead.
+- Better, more structured todos: one row per acceptance criterion (✓ when fresh
+  evidence covers it), a re-verify row when the tree changed, and one row per
+  still-missing review gate by friendly name (e.g. "Pass Security Reviewer").
+- In a goal session the section takes over the sidebar `sidebar_content` slot;
+  because OpenCode renders the native todo list as that slot's fallback, it
+  replaces the native list on builds that use replace/single-winner slot mode and
+  sits alongside it otherwise. Non-goal and no-goal sessions render nothing, so
+  the native todo list stays in place.
+
+### Build mode is never treated as a goal
+
+- Hardened the guard so a Build/Plan/custom session never accumulates goal state.
+  `tool.execute.after` bookkeeping (dirty flag, edits, verification, verdicts) now
+  runs only for active Goal sessions (and goal-namespace subagent sessions for
+  verdict capture). Destructive-command blocking still applies in every mode.
+
+### Installer
+
+- `--global` now resolves the home directory via `$HOME` and falls back to the OS
+  home dir, so it works in shells/containers where `$HOME` is unset.
+- Verified the full install → idempotent re-run → conflict-protection → uninstall
+  lifecycle end-to-end on macOS (Node 24) and in clean Linux containers (Apple
+  `container`, Node 20 and Node 24) using the real `npm install -g <tarball>` path.
+- Moved **Install** to the top of the README and documented dry-run/uninstall.
+
 ## v0.4.0
 
 ### Goal-only subagents

package/README.md

@@ -1,40 +1,38 @@
 # OpenCode Goal Mode
 
-[![npm version](https://img.shields.io/npm/v/opencode-goal-mode?color=2da44e&label=npm)](https://www.npmjs.com/package/opencode-goal-mode)
-[![npm downloads](https://img.shields.io/npm/dm/opencode-goal-mode?color=2da44e)](https://www.npmjs.com/package/opencode-goal-mode)
-[![CI](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/ci.yml/badge.svg)](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/ci.yml)
-[![Release](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/publish.yml/badge.svg)](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/publish.yml)
-[![license](https://img.shields.io/npm/l/opencode-goal-mode?color=2da44e)](LICENSE)
-[![node](https://img.shields.io/node/v/opencode-goal-mode?color=2da44e)](package.json)
-
 Strict Goal Mode for OpenCode: a primary `goal` agent, specialized review
 subagents, slash commands, a `goal-guard` plugin that enforces review discipline
-and blocks destructive shell commands, and a live Goal-owned todo section in the
-TUI sidebar.
+and blocks destructive shell commands, and a structured Goal-owned todo section
+in the TUI sidebar.
 
 ## Install
 
-**One command** (recommended; needs [Node](https://nodejs.org) 20.11+ and a working [OpenCode](https://opencode.ai) install):
+**One command.** Needs [Node](https://nodejs.org) 20.11+ and a working
+[OpenCode](https://opencode.ai). Works on macOS and Linux:
 
 ```bash
 npm install -g opencode-goal-mode && opencode-goal-mode --global
 ```
 
-Then **restart OpenCode**. That's the whole install: it copies the Goal agent,
+Then **restart OpenCode**. That's the whole install — it copies the Goal agent,
 review subagents, slash commands, and guard plugin into `~/.config/opencode`, and
 merge-safely registers the Goal todo sidebar in `~/.config/opencode/tui.json`.
 In the agent picker you'll see only the **`goal`** agent; reviewers are subagents
-it drives automatically. The global install keeps the TUI package resolvable on
-future OpenCode starts; Goal Mode inherits your existing OpenCode model/provider.
+it drives automatically. The install is **idempotent** (re-run it to upgrade in
+place), never touches files you've edited, and `--uninstall` removes exactly what
+it added. Goal Mode inherits your existing OpenCode model/provider.
 
 <details>
 <summary>Other ways to install</summary>
 
 ```bash
-# Global npm install, then run the installer
+# Global npm install, then run the installer separately
 npm install -g opencode-goal-mode
 opencode-goal-mode --global          # alias of opencode-goal-mode-install
 
+# Preview first, then install (no writes on --dry-run)
+opencode-goal-mode --global --dry-run
+
 # Temporary npx install (server-side components work; for the TUI sidebar,
 # prefer the global install above so OpenCode can resolve the package later)
 npx opencode-goal-mode --global
@@ -42,6 +40,9 @@ npx opencode-goal-mode --global
 # Into a single project (writes ./.opencode, including ./.opencode/tui.json)
 npx opencode-goal-mode
 
+# Clean removal of everything it installed (incl. its tui.json entry)
+opencode-goal-mode --global --uninstall
+
 # From source
 git clone https://github.com/devinoldenburg/opencode-goal-mode
 cd opencode-goal-mode && npm ci && npm run install:global
@@ -49,16 +50,23 @@ cd opencode-goal-mode && npm ci && npm run install:global
 
 Use global install for normal daily use. Use project install only when you want
 Goal Mode scoped to one repo and your OpenCode build reads project `.opencode`
-config, including `.opencode/tui.json`. `--dry-run` previews changes;
-`--uninstall` removes only what it installed (and its `tui.json` entry), leaving
-your edits untouched. See [Installer options](#installer-options).
+config, including `.opencode/tui.json`. See [Installer options](#installer-options).
 </details>
 
+[![npm version](https://img.shields.io/npm/v/opencode-goal-mode?color=2da44e&label=npm)](https://www.npmjs.com/package/opencode-goal-mode)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-goal-mode?color=2da44e)](https://www.npmjs.com/package/opencode-goal-mode)
+[![CI](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/ci.yml/badge.svg)](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/ci.yml)
+[![Release](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/publish.yml/badge.svg)](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/publish.yml)
+[![license](https://img.shields.io/npm/l/opencode-goal-mode?color=2da44e)](LICENSE)
+[![node](https://img.shields.io/node/v/opencode-goal-mode?color=2da44e)](package.json)
+
 ![OpenCode Goal Mode sidebar todo section](docs/sidebar-demo.svg)
 
-<sub>↑ In Goal mode, the sidebar todo slot becomes a Goal-owned todo section with
-a first-display rainbow effect, then normal goal colours. Build and other modes
-keep OpenCode's native todo section — see [TUI integration](#tui-integration).</sub>
+<sub>↑ In goal mode, the Goal plugin takes over the sidebar todo section with a
+structured, evidence-aware Goal todo list — a bold `GOAL` label, then the goal
+title, gate progress, and per-acceptance/gate todo rows, each on its own line in
+its own colour, with a first-display rainbow. Build and every other mode keep
+OpenCode's native todo section — see [TUI integration](#tui-integration).</sub>
 
 **[Quick start](#quick-start) · [Why it's different](#why-its-different) · [Benchmarks](#benchmarks-honest-edition) · [TUI integration](#tui-integration) · [Configuration](#configuration) · [Releasing](#releasing) · [Architecture](ARCHITECTURE.md)**
 
@@ -218,9 +226,10 @@ second) — negligible for a per-tool-call guard:
     reviewer's friendly name, and a single "completion unlocked" toast the moment
     the last required gate clears.
 - An **experimental** companion TUI plugin (`plugins/goal-sidebar.tsx`) that, in
-  Goal sessions only, adds a Goal-owned, evidence-aware todo section to the
-  sidebar. It shows a brief rainbow effect the first time it appears, then normal
-  goal colours. See [TUI integration](#tui-integration).
+  Goal sessions only, takes over the sidebar todo area with a structured,
+  evidence-aware Goal todo list (`GOAL` label, goal title, gate progress, and
+  todo rows — each on its own line in its own colour). It shows a first-display
+  rainbow, then normal goal colours. See [TUI integration](#tui-integration).
 - A test suite validating the analyzer, plugin hooks, state store, install
   safety, and config compatibility.
 
@@ -230,18 +239,29 @@ Goal Mode is a **plugin pair**: the server-side `goal-guard` plugin owns
 enforcement and writes its state to disk, and an experimental TUI plugin
 (`plugins/goal-sidebar.tsx`) reads that same state to render a live todo section.
 
-- **Goal-owned todo section.** In a `goal` session, the sidebar gains a Goal-owned
-  todo section: short goal title, gate progress, lifecycle status, and structured
-  todo rows derived from acceptance criteria, evidence freshness, dirty state, and
-  missing review gates. It starts with a brief rainbow foreground effect
-  (`sidebarRainbowMs`) so it is immediately visible, then returns to the normal
-  lifecycle colours:
-  - **yellow** — a goal is set and running;
-  - **red** — the goal is done (all required gates pass and the tree is clean);
-  - **no render** — Build and every non-Goal mode render nothing here, so they
-    keep OpenCode's native todo section instead of being classified as a goal. The
-    section is scoped to the session that owns the goal: a Build session in the
-    same worktree never inherits another session's goal.
+- **Goal-owned todo section.** In a `goal` session with a goal set, the Goal
+  plugin renders its own structured todo section into the sidebar's `sidebar_content`
+  slot, stacked on separate lines, each in its own colour so it never reads as one
+  run of text:
+  - a bold **`GOAL`** label (yellow while running, red when done);
+  - the short goal title;
+  - a `passing/total gates · status` line (lifecycle only — no "changes pending"
+    noise; pending work shows as a todo row instead);
+  - structured todo rows derived from real guard state: one per acceptance
+    criterion (✓ when fresh evidence covers it), a re-verify row when the tree
+    changed, and one row per still-missing review gate by friendly name
+    (e.g. "Pass Security Reviewer").
+
+  It opens with a first-display rainbow (`sidebarRainbowMs`) so the takeover is
+  visible, then settles to the lifecycle colours (running → yellow label; done →
+  red). Because OpenCode renders the native todo list as that slot's *fallback*,
+  on builds that render `sidebar_content` in replace/single-winner mode the Goal
+  section **replaces** the native todo list while a goal is active; in append mode
+  it sits alongside it. In every case:
+  - **no render** — Build and every non-Goal mode (and a Goal session before a
+    goal is set) render nothing here, so OpenCode's native todo section stays in
+    the same position. The section is scoped to the session that owns the goal: a
+    Build session in the same worktree never inherits another session's goal.
 
   Toggle/recolour with `sidebarBanner`, `sidebarColor` (running), `sidebarDoneColor`
   (done), `sidebarMutedColor`, `sidebarRainbowMs`, or the `GOAL_GUARD_SIDEBAR_*`
@@ -258,12 +278,18 @@ enforcement and writes its state to disk, and an experimental TUI plugin
   { "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-goal-mode"] }
   ```
 
-  Restart OpenCode after install so it picks up the TUI plugin (it resolves the
-  package and provides the `@opentui/solid` runtime). The Goal todo section appears
-  in a **Goal session** view (not the home screen and not Build mode). The visual
-  harness renders it with a headless OpenTUI renderer in
-  [visual test](tools/visual-test/README.md) (`npm run test:visual`). The
-  enforcement core is a separate server plugin and works regardless of the sidebar.
+  OpenCode installs the referenced package into its own plugin cache
+  (`~/.cache/opencode/packages/`) and provides the `@opentui/solid` + `solid-js`
+  runtime to it. It does **not** re-check that cache for newer versions, so the
+  installer clears the cached copy on install/uninstall — that's why an upgrade
+  needs only a restart to load the new sidebar. Restart OpenCode after install. The
+  Goal todo section appears in a **Goal session** view (not the home screen and not
+  Build mode), and because the Goal agent does its own todo tracking (native
+  `todowrite` is disabled in Goal Mode), it replaces — rather than sits beside —
+  the native todo list while a goal is active. The visual harness renders the
+  component headlessly in [visual test](tools/visual-test/README.md)
+  (`npm run test:visual`); the enforcement core is a separate server plugin and
+  works regardless of the sidebar.
 - **Toasts.** Review verdicts and completion-unlock events surface as toasts
   (`toastOnReview`), and blocked destructive commands / premature completions
   toast as before (`toastOnBlock`).

package/agents/goal.md

@@ -28,7 +28,7 @@ permission:
     "/projects/**": allow
     "~/.config/opencode/**": allow
     "~/.local/share/opencode/tool-output/**": allow
-  todowrite: allow
+  todowrite: deny
   question: allow
   webfetch: allow
   websearch: allow
@@ -103,7 +103,7 @@ Operating loop:
 1. Establish the Goal Contract, constraints, current state, and acceptance criteria.
 2. If essential information is missing, ask all necessary clarifying questions immediately at the beginning. Do not defer avoidable questions into the build phase.
 3. Delegate research and discovery before editing. Use subagents to inspect local files, map structures, trace code paths, research docs, identify verification commands, and gather external web evidence.
-4. Create and maintain a todo list for any non-trivial goal. Keep exactly one active item while working.
+4. Track progress through the Goal Contract acceptance criteria and the guard's evidence/gate state, not the native todo tool. Goal Mode owns the sidebar todo section: it derives a live, structured todo list from the acceptance criteria (checked off as you record evidence), dirty state, and outstanding review gates. Do not use `todowrite` (it is disabled in Goal Mode so the native todo list never competes with the Goal-owned section); call `goal_status`/`goal_evidence_map` when you need the current checklist.
 5. Implement the goal yourself in the main agent unless a bounded implementation subtask is explicitly safer to delegate.
 6. Run or delegate relevant checks, tests, builds, linters, typechecks, previews, or manual verification planning.
 7. When you believe the goal is finished, immediately run a strict review cycle before telling the user. The review must compare the original prompt and Goal Contract against the actual result.

package/docs/sidebar-demo.svg

@@ -1,28 +1,31 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="360" viewBox="0 0 1000 360" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" role="img" aria-label="OpenCode Goal Mode sidebar: a Goal session shows a bold 'Goal todos' section with a first-display rainbow (running), turning red when done, with gate progress and todo rows. Build and other modes render no Goal section and keep OpenCode's native todo list.">
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="452" viewBox="0 0 1000 452" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" role="img" aria-label="OpenCode Goal Mode sidebar: in a goal session the plugin renders a stacked Goal todo section — a bold GOAL label, the goal title, a gates/status line, and per-gate todo rows — each on its own line in its own colour, opening with a first-display rainbow then settling (GOAL yellow, title white, status cyan) and turning red when done. Build and other modes render no Goal section and keep OpenCode's native todo list.">
   <defs>
     <style>
       .win { fill: #0d1117; stroke: #30363d; stroke-width: 1; }
       .bar { fill: #161b22; }
       .dot { stroke-width: 0; }
       .title { fill: #8b949e; font-size: 12px; }
-      .label { fill: #8b949e; font-size: 11px; letter-spacing: 0.5px; }
-      .lbl  { font-size: 13px; font-weight: 700; }
-      .ln   { font-size: 13px; }
-      .sm   { font-size: 12px; }
+      .hdr { fill: #8b949e; font-size: 11px; letter-spacing: 0.5px; }
+      .lbl { font-size: 13px; font-weight: 700; }
+      .ln  { font-size: 13px; }
+      .sm  { font-size: 12px; }
       .chat { fill: #c9d1d9; font-size: 12px; }
       .dim { fill: #6e7681; font-size: 12px; }
       .ok { fill: #2da44e; font-size: 12px; }
-      .nat { fill: #8b949e; font-size: 12px; }
       .div { stroke: #30363d; stroke-width: 1; }
-      /* first-display rainbow: the guard colours each sidebar line with a
-         successive rainbow hue (RAINBOW[index]) before settling to yellow. */
-      .r0 { fill: #FF5555; } .r1 { fill: #FFAA00; } .r2 { fill: #FFFF55; }
-      .red { fill: #FF5555; }
+      /* first-display rainbow — successive hues per line (RAINBOW[index]) */
+      .r0 { fill: #FF5555; } .r1 { fill: #FFAA00; } .r2 { fill: #FFFF55; } .r3 { fill: #55FF55; }
+      /* settled running palette */
+      .label { fill: #FFD700; }  /* GOAL — yellow */
+      .gtitle { fill: #FFFFFF; } /* goal title — bright white */
+      .meta { fill: #8BE9FD; }   /* gates · status — cyan */
+      .todo { fill: #808080; }   /* pending todo rows — grey */
+      .done { fill: #FF5555; }   /* done state — red */
+      .check { fill: #50FA7B; }  /* ✓ done rows — green */
     </style>
   </defs>
 
-  <!-- window -->
-  <rect class="win" x="1" y="1" width="998" height="358" rx="8"/>
+  <rect class="win" x="1" y="1" width="998" height="450" rx="8"/>
   <rect class="bar" x="1" y="1" width="998" height="30" rx="8"/>
   <rect class="bar" x="1" y="20" width="998" height="11"/>
   <circle class="dot" cx="20" cy="16" r="5" fill="#ff5f56"/>
@@ -30,8 +33,7 @@
   <circle class="dot" cx="56" cy="16" r="5" fill="#27c93f"/>
   <text class="title" x="86" y="20">opencode — goal mode</text>
 
-  <!-- vertical divider between chat and sidebar -->
-  <line class="div" x1="470" y1="31" x2="470" y2="359"/>
+  <line class="div" x1="470" y1="31" x2="470" y2="451"/>
 
   <!-- chat pane (left) -->
   <text class="dim"  x="20" y="58">▌ goal</text>
@@ -40,30 +42,37 @@
   <text class="ok"   x="20" y="126">✓ Security Reviewer → PASS</text>
   <text class="ok"   x="20" y="148">✓ Verifier → PASS</text>
   <text class="dim"  x="20" y="170">▸ Diff Reviewer running…</text>
-  <text class="dim"  x="20" y="206">Build / Plan / custom agents cannot</text>
-  <text class="dim"  x="20" y="224">invoke the goal-* reviewers — they are</text>
-  <text class="dim"  x="20" y="242">locked to the Goal agent.</text>
+  <text class="dim"  x="20" y="212">Build / Plan / custom agents cannot</text>
+  <text class="dim"  x="20" y="230">invoke the goal-* reviewers, and never</text>
+  <text class="dim"  x="20" y="248">get a Goal section in their sidebar.</text>
 
-  <!-- sidebar pane (right) -->
-  <!-- Goal session, RUNNING (first-display rainbow: line 0 red, 1 orange, 2 yellow) -->
-  <text class="label" x="490" y="56">GOAL SESSION · running · first-display rainbow</text>
-  <line class="div" x1="490" y1="64" x2="980" y2="64"/>
-  <text x="490" y="86"><tspan class="lbl r0">Goal todos</tspan><tspan class="ln r0">  Ship the OAuth refactor</tspan></text>
-  <text class="sm r1" x="490" y="104">0/5 gates · in progress</text>
-  <text class="sm r2" x="490" y="122">□ Clear review gates: goal-prompt-auditor,</text>
-  <text class="sm r2" x="490" y="138">goal-reviewer, goal-diff-reviewer…</text>
-  <text class="dim" x="490" y="156">↳ then settles to yellow while running</text>
+  <!-- Panel 1: running, first-display rainbow -->
+  <text class="hdr" x="490" y="52">GOAL SESSION · running · first-display rainbow</text>
+  <line class="div" x1="490" y1="60" x2="980" y2="60"/>
+  <text class="lbl r0" x="490" y="80">GOAL</text>
+  <text class="ln r1"  x="490" y="98">Ship the OAuth refactor</text>
+  <text class="sm r2"  x="490" y="116">0/5 gates · in progress</text>
+  <text class="sm r3"  x="490" y="134">□ Pass Prompt Auditor</text>
 
-  <!-- Goal session, DONE (red) -->
-  <text class="label" x="490" y="196">GOAL SESSION · done</text>
-  <line class="div" x1="490" y1="204" x2="980" y2="204"/>
-  <text x="490" y="226"><tspan class="lbl red">Goal todos</tspan><tspan class="ln red">  Fix the parser bug</tspan></text>
-  <text class="sm red" x="490" y="244">5/5 gates · completed · 2 review cycles</text>
-  <text class="sm red" x="490" y="262">✓ Record Goal Contract acceptance criteria</text>
+  <!-- Panel 2: running, settled (distinct colours per line) -->
+  <text class="hdr" x="490" y="166">GOAL SESSION · running · settled colours</text>
+  <line class="div" x1="490" y1="174" x2="980" y2="174"/>
+  <text class="lbl label" x="490" y="194">GOAL</text>
+  <text class="ln gtitle" x="490" y="212">Ship the OAuth refactor</text>
+  <text class="sm meta"   x="490" y="230">3/5 gates · in progress</text>
+  <text class="sm todo"   x="490" y="248">□ Pass Security Reviewer</text>
 
-  <!-- Build / non-Goal: native todos remain (no Goal section, no "No goal") -->
-  <text class="label" x="490" y="300">BUILD / OTHER MODE</text>
-  <line class="div" x1="490" y1="308" x2="980" y2="308"/>
-  <text class="nat" x="490" y="330">▢ OpenCode's native todo section</text>
-  <text class="dim" x="490" y="348">(no Goal section is rendered here)</text>
+  <!-- Panel 3: done (red) -->
+  <text class="hdr" x="490" y="280">GOAL SESSION · done</text>
+  <line class="div" x1="490" y1="288" x2="980" y2="288"/>
+  <text class="lbl done" x="490" y="308">GOAL</text>
+  <text class="ln done"  x="490" y="326">Fix the parser bug</text>
+  <text class="sm done"  x="490" y="344">5/5 gates · completed · 2 review cycles</text>
+  <text class="sm check" x="490" y="362">✓ All acceptance criteria covered</text>
+
+  <!-- Panel 4: build / other mode → native todos, no Goal section -->
+  <text class="hdr" x="490" y="394">BUILD / OTHER MODE</text>
+  <line class="div" x1="490" y1="402" x2="980" y2="402"/>
+  <text class="todo" x="490" y="422" font-size="12">▢ OpenCode's native todo section</text>
+  <text class="dim"  x="490" y="440">(no Goal section is rendered here)</text>
 </svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "main": "plugins/goal-sidebar.tsx",

package/plugins/goal-guard/guard.js

@@ -178,6 +178,13 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
     async "tool.execute.after"(inp, out) {
       try {
         const state = store.stateFor(inp?.sessionID);
+        // Goal bookkeeping is GOAL-ONLY. A Build/Plan/custom session must never have
+        // its edits, mutations, verification, or verdicts recorded as goal state —
+        // otherwise the guard would treat a non-Goal message/task as if it were a
+        // goal. Only an active Goal session (or a goal-namespace subagent's own
+        // session, for verdict capture) is tracked. Destructive-command blocking is
+        // handled in tool.execute.before and still applies in every mode.
+        if (!state.active && !isGoalAgent(state.currentAgent)) return;
         const tool = inp?.tool;
         const isReviewing = isReviewAgent(state.currentAgent);
 

package/plugins/goal-guard/summary.js

@@ -4,6 +4,7 @@
  */
 
 import { requiredGates, missingGates, gatePassedFresh } from "./gates.js";
+import { prettyAgentName } from "./agents.js";
 
 /**
  * A short, single-line label for the current goal.
@@ -35,33 +36,55 @@ function criterionEvidenceFresh(state, criterion) {
   return entries.some((entry) => evidenceMatchesCriterion(entry, criterion) && evidenceFresh(entry, state));
 }
 
+function clip(text, max) {
+  const s = String(text || "").replace(/\s+/g, " ").trim();
+  return s.length <= max ? s : `${s.slice(0, max - 1).trimEnd()}…`;
+}
+
+/**
+ * Structured, ordered todo rows for the sidebar. Each row is a concrete, checkable
+ * step toward Goal completion — acceptance criteria first (✓ when fresh evidence
+ * covers them), then a re-verify nudge if the tree changed, then ONE row per still-
+ * missing review gate (friendly name, e.g. "Pass Security Reviewer"). This is the
+ * Goal plugin's own todo system: it is derived from real guard state (contract,
+ * evidence freshness, dirty flag, required gates), not transcript memory, so it
+ * tracks completion truthfully and updates as gates clear.
+ */
 function sidebarTodos(state, required, missing) {
   const criteria = Array.isArray(state?.contract?.acceptanceCriteria) ? state.contract.acceptanceCriteria : [];
   const items = [];
-  for (const criterion of criteria.slice(0, 5)) {
-    const text = String(criterion || "").replace(/\s+/g, " ").trim();
+  for (const criterion of criteria.slice(0, 4)) {
+    const text = clip(criterion, 52);
     if (!text) continue;
-    items.push({
-      status: criterionEvidenceFresh(state, text) ? "done" : "todo",
-      text: text.length <= 58 ? text : `${text.slice(0, 57).trimEnd()}…`,
-    });
+    items.push({ status: criterionEvidenceFresh(state, text) ? "done" : "todo", text });
   }
-  if (state?.dirty) items.push({ status: "todo", text: "Rerun verification and reviews after latest changes" });
-  if (missing.length > 0) items.push({ status: "todo", text: `Clear review gates: ${missing.slice(0, 3).join(", ")}${missing.length > 3 ? "…" : ""}` });
-  if (items.length === 0 && required.length > 0) items.push({ status: "todo", text: "Record Goal Contract acceptance criteria" });
-  return items.slice(0, 7);
+  if (state?.dirty) items.push({ status: "todo", text: "Re-verify & re-review after recent edits" });
+  // One row per missing/stale review gate, by friendly name — more scannable than a
+  // comma-joined id list and it shows exactly which reviewer is still owed.
+  for (const gate of missing.slice(0, 4)) {
+    items.push({ status: "todo", text: `Pass ${prettyAgentName(gate)}` });
+  }
+  if (items.length === 0 && required.length > 0) {
+    items.push({ status: "todo", text: "Record the Goal Contract & acceptance criteria" });
+  }
+  return items.slice(0, 8);
 }
 
 /**
  * Compact projection for the TUI sidebar todo section. ALWAYS returns an object with a
- * three-way `state`, plus three lines that stack vertically in the sidebar:
- *   - `goal`   → line 1: the short AI goal title.
- *   - `gates`  → line 2: the gate count, e.g. "0/7 gates".
- *   - `status` → line 3: the lifecycle status, e.g. "in progress · changes pending"
- *                or "completed · 2 review cycles".
+ * three-way `state`, plus lines that stack vertically in the sidebar — each rendered
+ * on its OWN line in a distinct colour so it never reads as one run of text:
+ *   - `label`  → line 1: the fixed "GOAL" header (yellow when running, red when done).
+ *   - `goal`   → line 2: the short AI goal title.
+ *   - `gates`  → line 3: gate count + lifecycle, e.g. "3/5 gates · in progress" or
+ *                "5/5 gates · completed · 2 review cycles". No "changes pending"
+ *                noise — pending work surfaces as a structured todo row instead.
+ *   - `todos`  → following lines: structured acceptance/verification/gate todos.
  * State drives colour: "running" = rainbow first, then yellow; "done" = red;
- * "none" = render nothing so non-Goal modes keep the native todo section.
+ * "none" = render nothing so non-Goal / no-goal sessions keep the native todo section.
  */
+export const GOAL_LABEL = "GOAL";
+
 export function sidebarView(state, config) {
   if (!state || !state.active) return NO_GOAL;
   const goal = shortGoalLabel(state);
@@ -76,10 +99,11 @@ export function sidebarView(state, config) {
   if (done) {
     return {
       state: "done",
+      label: GOAL_LABEL,
       goal,
       gates,
       status: `completed · ${cycles} review cycle${cycles === 1 ? "" : "s"}`,
-      todoTitle: "Goal todos",
+      todoTitle: GOAL_LABEL,
       todos: todos.length ? todos.map((item) => ({ ...item, status: "done" })) : [{ status: "done", text: "All Goal completion gates are clear" }],
       passing,
       required: required.length,
@@ -88,10 +112,11 @@ export function sidebarView(state, config) {
   }
   return {
     state: "running",
+    label: GOAL_LABEL,
     goal,
     gates,
-    status: `in progress${state.dirty ? " · changes pending" : ""}`,
-    todoTitle: "Goal todos",
+    status: "in progress",
+    todoTitle: GOAL_LABEL,
     todos,
     passing,
     required: required.length,

package/plugins/goal-sidebar.tsx

@@ -2,11 +2,14 @@
 /**
  * Goal Mode — TUI sidebar todo section.
  *
- * In Goal agent sessions this adds a Goal-owned, evidence-aware todo section to
- * the sidebar. Non-Goal sessions render nothing here so Build and other modes
- * keep OpenCode's normal todo section. The section is strictly per-session: it is
- * keyed by props.session_id, so a Build session in the same worktree never
- * inherits another session's goal.
+ * In Goal agent sessions this renders a Goal-owned, evidence-aware todo section
+ * into the sidebar_content slot (GOAL label, goal title, gate/status line, and
+ * structured todo rows). OpenCode renders the native todo list as that slot's
+ * fallback, so in replace/single-winner slot mode this REPLACES the native todos
+ * while a goal is active; rendering nothing (non-Goal or no-goal sessions) brings
+ * the native todos back. The section is strictly per-session: it is keyed by
+ * props.session_id, so a Build session in the same worktree never inherits
+ * another session's goal.
  *
  * How OpenCode loads this: TUI plugins are listed in `~/.config/opencode/tui.json`
  * (NOT the plugins/ dir) and resolved via the package's `exports["./tui"]`. The
@@ -20,13 +23,17 @@
  * the Node test suite.
  */
 
-import { createSignal, onCleanup, For, Show } from "solid-js";
+import { createSignal, createEffect, onCleanup, For, Show } from "solid-js";
 import { sidebarView, NO_GOAL } from "./goal-guard/summary.js";
 import { DEFAULT_CONFIG } from "./goal-guard/config.js";
 
-const DEFAULT_COLOR = "#FFD700"; // running — yellow
+const DEFAULT_COLOR = "#FFD700"; // running — GOAL label, yellow
 const DEFAULT_DONE = "#FF5555"; // done — red
-const DEFAULT_MUTED = "#808080"; // no goal — grey
+const DEFAULT_MUTED = "#808080"; // pending todo rows — grey
+const TITLE_COLOR = "#FFFFFF"; // goal title line (running) — bright, distinct from the yellow GOAL label
+const META_COLOR = "#8BE9FD"; // gates line (running) — cyan accent
+const STATUS_COLOR = "#FFB86C"; // status line (running) — orange, distinct from the cyan gates line
+const TODO_DONE_COLOR = "#50FA7B"; // ✓ done todo rows — green
 const POLL_MS = 1500;
 const RAINBOW = ["#FF5555", "#FFAA00", "#FFFF55", "#55FF55", "#55FFFF", "#5599FF", "#FF55FF"];
 
@@ -79,16 +86,27 @@ function pickSession(snapshot, sessionId) {
   return null;
 }
 
-function readModel(worktree, sessionId) {
-  try {
-    const snapshot = readSnapshot(worktree);
-    if (!snapshot) return NO_GOAL;
-    const record = pickSession(snapshot, sessionId);
-    if (!record) return NO_GOAL;
-    return sidebarView(record, DEFAULT_CONFIG);
-  } catch {
-    return NO_GOAL;
+/**
+ * Resolve the sidebar model for a session, trying each candidate worktree key in
+ * turn. The guard persists keyed by `worktree || directory`; the TUI may surface
+ * either path, so we try both (worktree first) rather than risk a key mismatch
+ * that would hide an active goal and leave the native todos showing.
+ */
+function readModel(worktrees, sessionId) {
+  const keys = (Array.isArray(worktrees) ? worktrees : [worktrees]).filter(Boolean);
+  for (const wt of keys) {
+    try {
+      const snapshot = readSnapshot(wt);
+      if (!snapshot) continue;
+      const record = pickSession(snapshot, sessionId);
+      if (!record) continue;
+      const view = sidebarView(record, DEFAULT_CONFIG);
+      if (view && view.state !== "none") return view;
+    } catch {
+      /* try the next candidate */
+    }
   }
+  return NO_GOAL;
 }
 
 const id = "goal-mode-sidebar";
@@ -96,11 +114,13 @@ const id = "goal-mode-sidebar";
 /** @type {import("@opencode-ai/plugin/tui").TuiPlugin} */
 const tui = async (api, options) => {
   try {
-    const { enabled, color, doneColor, rainbowMs } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
+    const { enabled, color, doneColor, muted, rainbowMs } = 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;
+    // The guard keys persisted state by worktree (falling back to directory).
+    // Surface both so a path-key mismatch can't hide an active goal.
+    const worktrees = [api.state?.path?.worktree, api.state?.path?.directory];
 
     api.slots.register({
         order: 50,
@@ -109,32 +129,69 @@ const tui = async (api, options) => {
             if (!props?.session_id) return undefined;
             const read = () => {
               try {
-                return readModel(worktree, props?.session_id) || NO_GOAL;
+                return readModel(worktrees, props?.session_id) || NO_GOAL;
               } catch {
                 return NO_GOAL;
               }
             };
-            const initial = read();
-            if (initial.state === "none") return undefined;
-            const [model, setModel] = createSignal(initial);
-            const [rainbow, setRainbow] = createSignal((rainbowMs || 0) > 0);
+            // ALWAYS mount a reactive, polling component — do NOT bail when there is
+            // no goal yet. The goal is normally recorded AFTER the sidebar mounts
+            // (the user opens the session, then states the goal), so the slot must
+            // keep polling and let <Show> reveal the section when the goal appears.
+            // Returning undefined at mount (the old behavior) meant the poll never
+            // ran and the Goal section never showed even once a goal existed.
+            const first = read();
+            const [model, setModel] = createSignal(first);
             const timer = setInterval(() => setModel(read()), POLL_MS);
-            const rainbowTimer = setTimeout(() => setRainbow(false), Math.max(0, rainbowMs || 0));
             onCleanup(() => clearInterval(timer));
+            // First-display rainbow: starts the moment a goal FIRST appears. If a goal
+            // is already present at mount it starts immediately; otherwise the effect
+            // fires when the goal later appears (the common case — the goal is set
+            // after the sidebar mounts). Either way it settles after rainbowMs.
+            const [rainbow, setRainbow] = createSignal(false);
+            let rainbowStarted = false;
+            let rainbowTimer;
+            const startRainbow = () => {
+              if (rainbowStarted || (rainbowMs || 0) <= 0) return;
+              rainbowStarted = true;
+              setRainbow(true);
+              rainbowTimer = setTimeout(() => setRainbow(false), Math.max(0, rainbowMs));
+            };
+            if (first.state !== "none") startRainbow();
+            createEffect(() => {
+              if (model().state !== "none") startRainbow();
+            });
             onCleanup(() => clearTimeout(rainbowTimer));
-            const fg = () => (model().state === "done" ? doneColor : color);
-            const lineColor = (index = 0) => (rainbow() && model().state === "running" ? RAINBOW[index % RAINBOW.length] : fg());
-            // Goal sessions render a Goal-owned todo section; non-Goal sessions return undefined so native todos remain.
+            const isRainbow = () => rainbow() && model().state === "running";
+            // Settled (post-rainbow) colour for each header line. When done, every
+            // line is red; while running each line gets its OWN highlight colour so
+            // the GOAL label, the goal title, and the status never read as one text.
+            const settled = (kind) => {
+              if (model().state === "done") return doneColor;
+              if (kind === "label") return color; // GOAL — yellow
+              if (kind === "title") return TITLE_COLOR; // goal title — bright white
+              if (kind === "gates") return META_COLOR; // gate count — cyan
+              return STATUS_COLOR; // lifecycle status — orange
+            };
+            const lineColor = (index, kind) => (isRainbow() ? RAINBOW[index % RAINBOW.length] : settled(kind));
+            const todoColor = (index, item) => {
+              if (isRainbow()) return RAINBOW[index % RAINBOW.length];
+              if (item.status === "done") return TODO_DONE_COLOR;
+              return model().state === "done" ? doneColor : muted;
+            };
+            // Goal sessions render a Goal-owned todo section — GOAL label, goal title,
+            // gate count, lifecycle status, then structured todos — EACH on its own
+            // line in its own colour. Non-Goal / no-goal sessions returned undefined
+            // above, so the native todo section shows instead.
             return (
               <Show when={model().state !== "none"}>
                 <box flexDirection="column" paddingTop={1}>
-                  <text fg={lineColor(0)}>
-                    <b>{model().todoTitle || "Goal todos"}</b>
-                    {`  ${model().goal}`}
-                  </text>
-                  <text fg={lineColor(1)}>{`${model().gates} · ${model().status}`}</text>
+                  <text fg={lineColor(0, "label")}><b>{model().label || "GOAL"}</b></text>
+                  <text fg={lineColor(1, "title")}>{model().goal}</text>
+                  <text fg={lineColor(2, "gates")}>{model().gates}</text>
+                  <text fg={lineColor(3, "status")}>{model().status}</text>
                   <For each={model().todos || []}>
-                    {(item, index) => <text fg={lineColor(index() + 2)}>{`${item.status === "done" ? "✓" : "□"} ${item.text}`}</text>}
+                    {(item, index) => <text fg={todoColor(index() + 4, item)}>{`${item.status === "done" ? "✓" : "□"} ${item.text}`}</text>}
                   </For>
                 </box>
               </Show>

package/scripts/install.mjs

@@ -15,6 +15,7 @@ import {
 import { join, resolve, relative, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { parseArgs } from "node:util";
 
 const { values } = parseArgs({
@@ -67,8 +68,18 @@ if (values.global && values.target) {
 function resolveTarget() {
   if (values.target) return resolve(String(values.target));
   if (values.global) {
-    const home = process.env.HOME;
-    if (!home) throw new Error("Cannot resolve HOME for --global install");
+    // OpenCode reads global config from ~/.config/opencode. Resolve home from $HOME,
+    // falling back to the OS home dir (homedir() works where $HOME is unset, e.g.
+    // some CI/container shells) so --global doesn't fail in those environments.
+    let home = process.env.HOME;
+    if (!home) {
+      try {
+        home = homedir();
+      } catch {
+        home = "";
+      }
+    }
+    if (!home) throw new Error("Cannot resolve a home directory for --global install. Pass --target <dir> instead.");
     return join(home, ".config", "opencode");
   }
   return resolve(process.cwd(), ".opencode");
@@ -172,6 +183,35 @@ function ensureTuiPlugin(remove = false) {
   return true;
 }
 
+/**
+ * OpenCode caches TUI plugins under `~/.cache/opencode/packages/<name>@<spec>/`
+ * and does NOT re-check npm for a newer version, so after an upgrade it keeps
+ * loading the OLD sidebar build. Removing our cache entries forces OpenCode to
+ * re-fetch the just-installed version on its next start. Returns the dirs cleared.
+ */
+function refreshTuiPluginCache() {
+  const base = (process.env.XDG_CACHE_HOME && process.env.XDG_CACHE_HOME.trim()) || join(homedir() || "", ".cache");
+  const pkgRoot = join(base, "opencode", "packages");
+  if (!existsSync(pkgRoot)) return [];
+  let entries;
+  try {
+    entries = readdirSync(pkgRoot);
+  } catch {
+    return [];
+  }
+  const ours = entries
+    .filter((name) => name === pkg.name || name.startsWith(`${pkg.name}@`))
+    .map((name) => join(pkgRoot, name));
+  for (const dir of ours) {
+    try {
+      if (!values["dry-run"]) rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+  return ours;
+}
+
 // ---------------------------------------------------------------------------
 // Uninstall
 // ---------------------------------------------------------------------------
@@ -194,6 +234,8 @@ if (values.uninstall) {
   const tuiRemoved = ensureTuiPlugin(true);
   if (!values["dry-run"]) pruneEmptyDirs(target, Object.keys(manifest.files));
   if (tuiRemoved) console.log(`${values["dry-run"] ? "Would remove" : "Removed"} the sidebar entry from ${join(target, "tui.json")}`);
+  const cachedCleared = refreshTuiPluginCache();
+  if (cachedCleared.length) console.log(`${values["dry-run"] ? "Would clear" : "Cleared"} OpenCode's cached TUI plugin (${cachedCleared.length}).`);
   const verb = values["dry-run"] ? "Would remove" : "Removed";
   console.log(`${verb} ${removed.length} Goal Mode files from ${target}.`);
   if (kept.length) {
@@ -291,4 +333,8 @@ console.log(
   `Files copied: ${summary.copied.length}; unchanged: ${summary.unchanged.length}; pruned: ${summary.pruned.length}`,
 );
 if (tuiAdded) console.log(`Registered the experimental sidebar in ${join(target, "tui.json")}`);
+const cacheCleared = refreshTuiPluginCache();
+if (cacheCleared.length) {
+  console.log(`${values["dry-run"] ? "Would clear" : "Cleared"} OpenCode's stale TUI plugin cache so the sidebar reloads at the installed version.`);
+}
 console.log("Restart OpenCode for agents, commands, and plugins to load.");