opencode-goal-mode 0.3.7 → 0.3.8

package/ARCHITECTURE.md

@@ -15,9 +15,9 @@ configuration directory:
    — a runtime guard that enforces review discipline, blocks destructive shell
    commands, preserves state across compaction and restarts, and exposes
    first-class `goal_*` tools.
-4. **An experimental TUI companion** (`plugins/goal-sidebar.js`) — a separate
-   `{ tui }` plugin module that renders the active goal as a yellow sidebar
-   banner. It is *paired* with the server plugin purely through the on-disk state
+4. **An experimental TUI companion** (`plugins/goal-sidebar.tsx`) — a separate
+   `{ tui }` plugin module that renders Goal sessions as a Goal-owned sidebar
+   todo section. It is *paired* with the server plugin purely through the on-disk state
    snapshot (no extra IPC) and no-ops on any runtime without the slot API.
 
 This document focuses on the plugin, where the engineering lives.
@@ -54,7 +54,7 @@ as plugins. Each module is independently unit-tested.
 | `goal-guard/system.js` | Live state block injected into the system prompt. |
 | `goal-guard/summary.js` | Status/evidence projections, the short goal label, and the sidebar view. |
 | `goal-guard/tools.js` | The `goal_status` / `goal_evidence_map` / `goal_reviewer_memory` / `goal_contract` / `goal_evidence` / `goal_reset` tools. |
-| `goal-guard/sidebar-data.js` | Pure reader that projects the persisted snapshot into the sidebar banner model. |
+| `goal-guard/sidebar-data.js` | Pure reader that projects the persisted snapshot into the sidebar todo model. |
 | `goal-guard/logger.js` | Best-effort logging/toasts over the OpenCode client. |
 
 ## Hooks used
@@ -165,14 +165,15 @@ hooks still load.
 
 ## TUI companion (experimental)
 
-`plugins/goal-sidebar.js` is a TUI plugin module — `export const tui = async (api)
-=> …` — distinct from the server plugin (`@opencode-ai/plugin` types it as a
-`{ tui }` module, mutually exclusive with `{ server }`). It registers a
-`sidebar_content` slot via `api.slots.register({ slots: { sidebar_content } })`
-and renders, in the configured colour (`#FFD700` by default), the short goal
-label plus a `passing/total gates · dirty/ready` line. It renders
-unconditionally: when a task is running with no goal set, it shows a muted grey
-`No goal` (`sidebarView` returns `{ hasGoal: false }`) rather than a blank slot.
+`plugins/goal-sidebar.tsx` is a TUI plugin module — default-exporting `{ id, tui }`
+— distinct from the server plugin. It waits until the persisted state contains an
+active Goal session, then registers a `sidebar_content` slot via
+`api.slots.register({ slots: { sidebar_content } })` and renders the short goal
+label, gate/status line, and structured Goal todos derived from acceptance
+criteria, evidence freshness, dirty state, and missing gates. It starts with a
+brief rainbow foreground effect, then returns to the configured running colour
+(`#FFD700` by default). When there is no active Goal session it does not register
+the slot, so Build and other modes keep OpenCode's native todo section in place.
 
 It is *paired* with the server plugin only through the persisted state file:
 `sidebar-data.js` recomputes the same `stateBaseDir`/`projectKey` path the guard
@@ -187,7 +188,7 @@ progress is visible even without the banner.
 The JSX renderer is verified headlessly with `@opentui/solid`'s `testRender` in
 `tools/visual-test/sidebar-visual.jsx` (`npm run test:visual`, needs Bun + the
 OpenTUI stack): it asserts the rendered text, the exact foreground colours, and
-the bold attribute for goal / "No goal" / ready states. That tool is excluded from
+the bold attribute for Goal todo / done / native-todo-preserved states. That tool is excluded from
 the npm package and from `node --test`/CI.
 
 ## Configuration

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+- Installer docs and `--help` now put the one-command `npx opencode-goal-mode --global`
+  flow first, clarify global vs project targets, and document the merge-safe
+  `tui.json` registration/uninstall behavior.
+- The TUI companion now renders a Goal-owned, structured todo section only for
+  active Goal sessions, with a first-display rainbow effect before returning to
+  normal lifecycle colours. Non-Goal modes render nothing from the Goal plugin so
+  OpenCode's native todo section remains in place.
+- Destructive-command blocking no longer activates Goal enforcement for Build or
+  other non-Goal sessions, preventing non-Goal tasks from being classified as goals.
+
 ## v0.3.7
 
 - **FIX: the sidebar now actually loads.** OpenCode loads a TUI plugin via the

package/README.md

@@ -7,23 +7,24 @@
 [![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, a matrix of specialized
-review subagents, slash commands, a `goal-guard` plugin that enforces review
-discipline and blocks destructive shell commands, and a live goal banner in the
+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.
 
 ## Install
 
-**One command** (needs [Node](https://nodejs.org) 20.11+ and [OpenCode](https://opencode.ai)):
+**One command** (recommended; needs [Node](https://nodejs.org) 20.11+ and a working [OpenCode](https://opencode.ai) install):
 
 ```bash
 npx opencode-goal-mode --global
 ```
 
-Then **restart OpenCode**. That's the whole install — it copies the Goal agent,
-review subagents, slash commands, and the guard plugin into `~/.config/opencode`,
-and registers the sidebar in `~/.config/opencode/tui.json`. In the agent picker
-you'll see only the **`goal`** agent (the reviewers are subagents it drives).
+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. Goal Mode inherits your existing OpenCode model/provider.
 
 <details>
 <summary>Other ways to install</summary>
@@ -33,7 +34,7 @@ you'll see only the **`goal`** agent (the reviewers are subagents it drives).
 npm install -g opencode-goal-mode
 opencode-goal-mode --global          # alias of opencode-goal-mode-install
 
-# Into a single project (writes ./.opencode + ./tui.json)
+# Into a single project (writes ./.opencode, including ./.opencode/tui.json)
 npx opencode-goal-mode
 
 # From source
@@ -41,14 +42,18 @@ git clone https://github.com/devinoldenburg/opencode-goal-mode
 cd opencode-goal-mode && npm ci && npm run install:global
 ```
 
-`--dry-run` previews changes; `--uninstall` removes only what it installed (and its
-tui.json entry), leaving your edits untouched. See [Installer options](#installer-options).
+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).
 </details>
 
-![OpenCode Goal Mode sidebar banner](docs/sidebar-demo.svg)
+![OpenCode Goal Mode sidebar todo section](docs/sidebar-demo.svg)
 
-<sub>↑ The sidebar goal banner: yellow while a goal runs, red when done, grey "No
-goal available" otherwise — see [TUI integration](#tui-integration).</sub>
+<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>
 
 **[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)**
 
@@ -74,8 +79,8 @@ opencode agent list | grep goal
    **cannot** answer `Goal Completed` until every required review gate passes — the
    guard rewrites a premature claim to `Goal Not Completed`. Try a destructive
    command mid-session (e.g. `rm -rf build`) and watch it get blocked. If your
-   OpenCode build supports TUI plugins, the active goal also appears in the sidebar
-   in yellow (experimental — see [TUI integration](#tui-integration)).
+   OpenCode build supports TUI plugins, Goal sessions also get the Goal-owned
+   sidebar todo section (experimental — see [TUI integration](#tui-integration)).
 
 That's it. Everything below is detail.
 
@@ -159,7 +164,12 @@ second) — negligible for a per-tool-call guard:
 ## Requirements
 
 - Node.js 20.11 or newer.
-- OpenCode configured to load local agents, commands, and plugins.
+- OpenCode configured to load local agents, commands, and plugins. The package is
+  tested against `@opencode-ai/plugin` 1.17.6 and declares compatibility with the
+  1.15+ plugin hook surface used here; newer OpenCode builds that change plugin
+  or TUI slot APIs may need a package update.
+- A working OpenCode provider/model; Goal Mode does not configure API keys or
+  choose a model for you.
 
 ## What it adds
 
@@ -192,9 +202,10 @@ second) — negligible for a per-tool-call guard:
   - **TUI toasts**: a toast on each review verdict (PASS/FAIL), with the
     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.js`) that shows
-  the active goal as a shining-yellow banner in the sidebar with a compact gate
-  status line. See [TUI integration](#tui-integration).
+- An **experimental** companion TUI plugin (`plugins/goal-sidebar.tsx`) that, in
+  Goal sessions only, replaces the native todo sidebar area with a Goal-owned,
+  evidence-aware todo section. It shows a brief rainbow effect the first time it
+  appears, then normal goal colours. See [TUI integration](#tui-integration).
 - A test suite validating the analyzer, plugin hooks, state store, install
   safety, and config compatibility.
 
@@ -202,32 +213,38 @@ second) — negligible for a per-tool-call guard:
 
 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.js`) reads that same state to render a live banner.
-
-- **Sidebar goal banner.** In the sidebar's content area, under the session
-  title/context, it shows the current goal with generated status text, colour-coded
-  by lifecycle:
-  - **yellow** — a goal is set and running (`◆ GOAL …` + `in progress · N/M gates`);
-  - **red** — the goal is done (all required gates pass, tree clean: `✓ GOAL …` +
-    `completed · N/M gates passed · K review cycles`);
-  - **grey** — a task is running with no goal set (`No goal available`).
+(`plugins/goal-sidebar.tsx`) reads that same state to render a live todo section.
+
+- **Goal-mode todo replacement.** In a `goal` session, the sidebar content/todo
+  area is replaced by 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 the replacement is
+  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 keep OpenCode's native todo
+    section in the same sidebar position instead of being classified as a goal.
 
   Toggle/recolour with `sidebarBanner`, `sidebarColor` (running), `sidebarDoneColor`
-  (done), `sidebarMutedColor` (no goal), or the `GOAL_GUARD_SIDEBAR_*` env vars.
+  (done), `sidebarMutedColor`, `sidebarRainbowMs`, or the `GOAL_GUARD_SIDEBAR_*`
+  env vars.
 
   **How it loads — important.** TUI plugins are **not** loaded from the `plugins/`
-  dir; OpenCode loads them from `~/.config/opencode/tui.json`. The installer writes
-  that for you (merge-safe):
+  dir; OpenCode loads them from `tui.json`. The Goal sidebar waits to register its
+  `sidebar_content` slot until a real Goal session exists, so non-Goal modes do not
+  get a blank replacement slot. With `--global`, the installer writes
+  `~/.config/opencode/tui.json` for you (merge-safe):
 
   ```json
   { "$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 banner appears in a
-  **session** view (not the home screen). The three states are rendered and
-  asserted — text + exact colours — by a real headless OpenTUI renderer in the
-  [visual test](tools/visual-test/README.md) (`npm run test:visual`, 18/18). 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.
 - **Toasts.** Review verdicts and completion-unlock events surface as toasts
   (`toastOnReview`), and blocked destructive commands / premature completions
@@ -236,16 +253,22 @@ enforcement and writes its state to disk, and an experimental TUI plugin
 ## Installer options
 
 ```bash
+npx opencode-goal-mode --global --dry-run
+npx opencode-goal-mode --global
+opencode-goal-mode-install --global --uninstall
 node scripts/install.mjs --dry-run
 node scripts/install.mjs --target /path/to/opencode-config
 node scripts/install.mjs --global --force
 node scripts/install.mjs --global --uninstall
 ```
 
-The installer records a manifest of the files it writes. On upgrade it replaces
-files it owns but refuses to clobber files you have locally modified unless
-`--force` is passed. `--uninstall` removes only the files it installed and leaves
-your local edits in place.
+Default target rules are simple: `--global` writes to `~/.config/opencode`; no
+flag writes to `./.opencode`; `--target` writes to exactly the directory you pass.
+In every target, the installer copies only `agents/`, `commands/`, `plugins/`,
+writes `.goal-mode-manifest.json`, and merge-safely adds `opencode-goal-mode` to
+`tui.json` in that same target. On upgrade it replaces files it owns but refuses
+to clobber files you have locally modified unless `--force` is passed.
+`--uninstall` removes only owned files and removes only its own `tui.json` entry.
 
 ## Configuration
 
@@ -274,10 +297,11 @@ Or via environment variables (`GOAL_GUARD_*`):
 | `sessionTtlMs` / `GOAL_GUARD_SESSION_TTL_MS` | `86400000` | Idle session TTL. |
 | `toastOnBlock` / `GOAL_GUARD_TOAST_ON_BLOCK` | `true` | Toast when something is blocked. |
 | `toastOnReview` / `GOAL_GUARD_TOAST_ON_REVIEW` | `true` | Toast on each review verdict and when completion unlocks. |
-| `sidebarBanner` / `GOAL_GUARD_SIDEBAR_BANNER` | `true` | Show the experimental yellow goal banner in the TUI sidebar. |
-| `sidebarColor` / `GOAL_GUARD_SIDEBAR_COLOR` | `#FFD700` | Colour of a **running** goal in the sidebar (yellow). |
+| `sidebarBanner` / `GOAL_GUARD_SIDEBAR_BANNER` | `true` | Show the experimental Goal todo section in the TUI sidebar. |
+| `sidebarColor` / `GOAL_GUARD_SIDEBAR_COLOR` | `#FFD700` | Normal colour of a **running** goal after the first-show rainbow. |
 | `sidebarDoneColor` / `GOAL_GUARD_SIDEBAR_DONE_COLOR` | `#FF5555` | Colour of a **done** goal in the sidebar (red). |
-| `sidebarMutedColor` / `GOAL_GUARD_SIDEBAR_MUTED_COLOR` | `#808080` | Colour of the "No goal available" line (grey). |
+| `sidebarMutedColor` / `GOAL_GUARD_SIDEBAR_MUTED_COLOR` | `#808080` | Reserved muted colour for no-goal projections. |
+| `sidebarRainbowMs` / `GOAL_GUARD_SIDEBAR_RAINBOW_MS` | `4500` | First-display rainbow duration for the Goal todo section. |
 
 ## Custom tools
 
@@ -297,7 +321,7 @@ criterion against recorded evidence, reviewer status, gaps, and the next
 required action. The command is backed by the `goal_evidence_map` tool, so it
 uses persisted Goal Guard state rather than relying on transcript memory.
 
-## Validation
+## Contributor validation
 
 ```bash
 npm test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "main": "plugins/goal-sidebar.tsx",
@@ -99,8 +99,14 @@
     "solid-js": "*"
   },
   "peerDependenciesMeta": {
-    "@opencode-ai/plugin": { "optional": true },
-    "@opentui/solid": { "optional": true },
-    "solid-js": { "optional": true }
+    "@opencode-ai/plugin": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
   }
 }

package/plugins/goal-guard/config.js

@@ -28,14 +28,16 @@ export const DEFAULT_CONFIG = Object.freeze({
   toastOnBlock: true,
   /** Emit a TUI toast when a review gate records a PASS/FAIL, and when completion unlocks. */
   toastOnReview: true,
-  /** Show the experimental yellow goal banner in the TUI sidebar (TUI-plugin-capable OpenCode only). */
+  /** Show the experimental goal todo section in the TUI sidebar (TUI-plugin-capable OpenCode only). */
   sidebarBanner: true,
-  /** Foreground colour (hex) for the sidebar goal banner. */
+  /** Foreground colour (hex) for the sidebar goal todo section after the first-show rainbow. */
   sidebarColor: "#FFD700",
   /** Foreground colour (hex) for a completed goal in the sidebar (running → done turns yellow → red). */
   sidebarDoneColor: "#FF5555",
-  /** Foreground colour (hex) for the muted "No goal available" sidebar line. */
+  /** Reserved muted foreground colour for no-goal projections. */
   sidebarMutedColor: "#808080",
+  /** Duration for the first-display rainbow effect on the Goal todo section. */
+  sidebarRainbowMs: 4500,
   /** Phrase that, at the start of an assistant message, claims completion. */
   completionMarker: "Goal Completed",
   /** Replacement marker when completion is blocked. */
@@ -74,6 +76,7 @@ function fromEnv(env) {
     GOAL_GUARD_SIDEBAR_COLOR: ["sidebarColor", (v) => (v == null ? undefined : String(v))],
     GOAL_GUARD_SIDEBAR_DONE_COLOR: ["sidebarDoneColor", (v) => (v == null ? undefined : String(v))],
     GOAL_GUARD_SIDEBAR_MUTED_COLOR: ["sidebarMutedColor", (v) => (v == null ? undefined : String(v))],
+    GOAL_GUARD_SIDEBAR_RAINBOW_MS: ["sidebarRainbowMs", coerceInt],
   };
   for (const [key, [field, coerce]] of Object.entries(map)) {
     if (env[key] !== undefined) out[field] = coerce(env[key], DEFAULT_CONFIG[field]);

package/plugins/goal-guard/guard.js

@@ -136,7 +136,6 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
         const blockDestructive = config.blockDestructive && analysis.destructive;
         const blockNetwork = config.blockNetworkExec && analysis.networkExec;
         if (blockDestructive || blockNetwork) {
-          state.active = true;
           state.dirtyReasons.push(`blocked risky bash: ${analysis.reasons.join("; ") || "destructive"}`);
           if (config.toastOnBlock) logger.toast("Goal Guard blocked a destructive command", "error");
           persist();

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

@@ -1,5 +1,5 @@
 /**
- * Read-only projection of persisted guard state for the TUI sidebar banner.
+ * Read-only projection of persisted guard state for the TUI sidebar todo section.
  *
  * 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
@@ -49,10 +49,9 @@ export function pickSession(snapshot, sessionId) {
 }
 
 /**
- * Build the sidebar banner model for a worktree. ALWAYS returns an object so the
- * sidebar renders unconditionally: `{ hasGoal: false }` when there is no state,
- * no active session, or no goal (render a muted "No goal"); otherwise
- * `{ hasGoal: true, goal, status, … }` (see summary.sidebarView).
+ * Build the sidebar todo model for a worktree. ALWAYS returns an object: `state:
+ * "none"` when there is no Goal session (render nothing and keep native todos), otherwise
+ * `state: "running"|"done", goal, status, todos, …` (see summary.sidebarView).
  *
  * @param {object} opts
  * @param {string} opts.worktree   Project worktree root (same key the guard uses).

package/plugins/goal-guard/summary.js

@@ -27,18 +27,40 @@ export function shortGoalLabel(state, max = 80) {
   return `${base.slice(0, max - 1).trimEnd()}…`;
 }
 
-/** Sentinel for "a task is running but no goal is set" — the sidebar shows a muted "No goal available". */
+/** Sentinel for "no active Goal session" — the TUI plugin renders nothing so native todos remain. */
 export const NO_GOAL = Object.freeze({ state: "none", goal: "", gates: "", status: "" });
 
+function criterionEvidenceFresh(state, criterion) {
+  const entries = Array.isArray(state.evidence) ? state.evidence : [];
+  return entries.some((entry) => evidenceMatchesCriterion(entry, criterion) && evidenceFresh(entry, state));
+}
+
+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();
+    if (!text) continue;
+    items.push({
+      status: criterionEvidenceFresh(state, text) ? "done" : "todo",
+      text: text.length <= 58 ? text : `${text.slice(0, 57).trimEnd()}…`,
+    });
+  }
+  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);
+}
+
 /**
- * Compact projection for the TUI sidebar banner. ALWAYS returns an object with a
+ * 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".
- * State drives colour: "running" = yellow, "done" = red, "none" = grey
- * ("No goal available").
+ * State drives colour: "running" = rainbow first, then yellow; "done" = red;
+ * "none" = render nothing so non-Goal modes keep the native todo section.
  */
 export function sidebarView(state, config) {
   if (!state || !state.active) return NO_GOAL;
@@ -49,6 +71,7 @@ export function sidebarView(state, config) {
   const passing = required.length - missing.length;
   const cycles = Number(state.reviewCycles) || 0;
   const gates = `${passing}/${required.length} gates`;
+  const todos = sidebarTodos(state, required, missing);
   const done = required.length > 0 && missing.length === 0 && !state.dirty;
   if (done) {
     return {
@@ -56,6 +79,8 @@ export function sidebarView(state, config) {
       goal,
       gates,
       status: `completed · ${cycles} review cycle${cycles === 1 ? "" : "s"}`,
+      todoTitle: "Goal todos",
+      todos: todos.length ? todos.map((item) => ({ ...item, status: "done" })) : [{ status: "done", text: "All Goal completion gates are clear" }],
       passing,
       required: required.length,
       reviewCycles: cycles,
@@ -66,6 +91,8 @@ export function sidebarView(state, config) {
     goal,
     gates,
     status: `in progress${state.dirty ? " · changes pending" : ""}`,
+    todoTitle: "Goal todos",
+    todos,
     passing,
     required: required.length,
     reviewCycles: cycles,

package/plugins/goal-sidebar.tsx

@@ -1,13 +1,10 @@
 /** @jsxImportSource @opentui/solid */
 /**
- * Goal Mode — TUI sidebar goal banner.
+ * Goal Mode — TUI sidebar todo section.
  *
- * Renders, in the sidebar's content area, the current goal as three stacked lines:
- *   1. `GOAL  <short AI title>`   (the objective, generated by the Goal agent)
- *   2. `<n>/<m> gates`            (review-gate progress)
- *   3. `<status>`                 (in progress / changes pending / completed …)
- * Colour tracks lifecycle: yellow while running, red when done, grey
- * "No goal available" when a task has no goal set.
+ * In Goal agent sessions this replaces the native-looking todo area with a
+ * Goal-owned, evidence-aware todo section. Non-Goal sessions render nothing here
+ * so Build and other modes keep OpenCode's normal todo section in the same slot.
  *
  * 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
@@ -21,7 +18,7 @@
  * the Node test suite.
  */
 
-import { createSignal, onCleanup, Show } from "solid-js";
+import { createSignal, onCleanup, For, Show } from "solid-js";
 import { sidebarView, NO_GOAL } from "./goal-guard/summary.js";
 import { DEFAULT_CONFIG } from "./goal-guard/config.js";
 
@@ -29,6 +26,7 @@ const DEFAULT_COLOR = "#FFD700"; // running — yellow
 const DEFAULT_DONE = "#FF5555"; // done — red
 const DEFAULT_MUTED = "#808080"; // no goal — grey
 const POLL_MS = 1500;
+const RAINBOW = ["#FF5555", "#FFAA00", "#FFFF55", "#55FF55", "#55FFFF", "#5599FF", "#FF55FF"];
 
 function resolveOptions(options, env) {
   const e = env || {};
@@ -41,6 +39,7 @@ function resolveOptions(options, env) {
     color: options?.sidebarColor || e.GOAL_GUARD_SIDEBAR_COLOR || DEFAULT_COLOR,
     doneColor: options?.sidebarDoneColor || e.GOAL_GUARD_SIDEBAR_DONE_COLOR || DEFAULT_DONE,
     muted: options?.sidebarMutedColor || e.GOAL_GUARD_SIDEBAR_MUTED_COLOR || DEFAULT_MUTED,
+    rainbowMs: Number(options?.sidebarRainbowMs ?? e.GOAL_GUARD_SIDEBAR_RAINBOW_MS ?? 4500),
   };
 }
 
@@ -70,6 +69,7 @@ function pickSession(snapshot, sessionId) {
   if (sessionId) {
     const direct = records.find(([key, st]) => key === sessionId && st.active);
     if (direct) return direct[1];
+    return null;
   }
   const active = records.filter(([, st]) => st.active);
   if (active.length === 0) return null;
@@ -94,43 +94,68 @@ const id = "goal-mode-sidebar";
 /** @type {import("@opencode-ai/plugin/tui").TuiPlugin} */
 const tui = async (api, options) => {
   try {
-    const { enabled, color, doneColor, muted } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
+    const { enabled, color, doneColor, 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;
 
-    api.slots.register({
-      order: 50,
-      slots: {
-        sidebar_content(_ctx, props) {
-          const read = () => {
-            try {
-              return readModel(worktree, props?.session_id) || NO_GOAL;
-            } catch {
-              return NO_GOAL;
-            }
-          };
-          const [model, setModel] = createSignal(read());
-          const timer = setInterval(() => setModel(read()), POLL_MS);
-          onCleanup(() => clearInterval(timer));
-          const fg = () => (model().state === "done" ? doneColor : color);
-          // Three stacked lines: GOAL+title, gates, status — or grey "No goal available".
-          return (
-            <box flexDirection="column" paddingTop={1}>
-              <Show when={model().state !== "none"} fallback={<text fg={muted}>No goal available</text>}>
-                <text fg={fg()}>
-                  <b>GOAL</b>
-                  {`  ${model().goal}`}
-                </text>
-                <text fg={fg()}>{model().gates}</text>
-                <text fg={fg()}>{model().status}</text>
+    let registered = false;
+    const register = () => {
+      if (registered) return;
+      registered = true;
+      api.slots.register({
+        order: 50,
+        slots: {
+          sidebar_content(_ctx, props) {
+            if (!props?.session_id) return undefined;
+            const read = () => {
+              try {
+                return readModel(worktree, 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);
+            const timer = setInterval(() => setModel(read()), POLL_MS);
+            const rainbowTimer = setTimeout(() => setRainbow(false), Math.max(0, rainbowMs || 0));
+            onCleanup(() => clearInterval(timer));
+            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.
+            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>
+                  <For each={model().todos || []}>
+                    {(item, index) => <text fg={lineColor(index() + 2)}>{`${item.status === "done" ? "✓" : "□"} ${item.text}`}</text>}
+                  </For>
+                </box>
               </Show>
-            </box>
-          );
+            );
+          },
         },
-      },
-    });
+      });
+    };
+
+    if (readModel(worktree).state !== "none") {
+      register();
+    } else {
+      const registrationTimer = setInterval(() => {
+        if (readModel(worktree).state !== "none") {
+          clearInterval(registrationTimer);
+          register();
+        }
+      }, POLL_MS);
+    }
   } catch {
     /* TUI runtime missing or API drift — render nothing rather than crash. */
   }

package/scripts/install.mjs

@@ -40,11 +40,13 @@ if (values.help) {
   console.log(`Install or remove OpenCode Goal Mode components.
 
 Usage:
+  npx opencode-goal-mode --global
+  opencode-goal-mode-install --global
   node scripts/install.mjs [--global | --target <dir>] [--force] [--dry-run]
   node scripts/install.mjs --uninstall [--global | --target <dir>] [--dry-run]
 
 Options:
-  --global       Install into ~/.config/opencode.
+  --global       Install into ~/.config/opencode (recommended for everyday use).
   --target DIR   Install into a specific OpenCode config directory.
   --force        Replace destination files even if locally modified.
   --uninstall    Remove files this installer previously wrote (per manifest).
@@ -53,7 +55,8 @@ Options:
 
 The installer records a manifest of the files it writes so that a later
 upgrade can distinguish files it owns (safe to replace) from files you have
-locally customized (left untouched unless --force).`);
+locally customized (left untouched unless --force). It also merge-safely adds
+the Goal sidebar plugin to <target>/tui.json; --uninstall removes that entry.`);
   process.exit(0);
 }
 
@@ -75,6 +78,15 @@ function fileHash(path) {
   return createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 16);
 }
 
+function safeTargetPath(rel) {
+  const dest = resolve(target, rel);
+  const back = relative(target, dest);
+  if (back === "" || back.startsWith("..") || resolve(back) === back) {
+    throw new Error(`Refusing to operate outside target: ${rel}`);
+  }
+  return dest;
+}
+
 /** Recursively list regular files under a directory, returning paths relative to
  * `base`. Uses lstat and skips symlinks so the installer only copies files it can
  * reason about (no following links outside the package tree). */
@@ -140,8 +152,13 @@ function ensureTuiPlugin(remove = false) {
   try {
     const existing = JSON.parse(readFileSync(tuiPath, "utf8"));
     if (existing && typeof existing === "object") data = existing;
-  } catch {
-    /* missing or invalid → start fresh */
+  } catch (err) {
+    if (existsSync(tuiPath)) {
+      if (!values.force) throw new Error(`Refusing to replace invalid ${tuiPath}. Fix it or rerun with --force.`);
+      const backupPath = `${tuiPath}.goal-mode-backup`;
+      if (!values["dry-run"]) copyFileSync(tuiPath, backupPath);
+      console.log(`${values["dry-run"] ? "Would back up" : "Backed up"} invalid ${tuiPath} to ${backupPath}`);
+    }
   }
   if (!Array.isArray(data.plugin)) data.plugin = [];
   const has = data.plugin.includes(TUI_PLUGIN_SPEC);
@@ -164,7 +181,7 @@ if (values.uninstall) {
   const removed = [];
   const kept = [];
   for (const [rel, hash] of Object.entries(manifest.files)) {
-    const dest = join(target, rel);
+    const dest = safeTargetPath(rel);
     if (!existsSync(dest)) continue;
     if (fileHash(dest) === hash) {
       if (!values["dry-run"]) rmSync(dest, { force: true });
@@ -242,7 +259,7 @@ for (const dir of COMPONENT_DIRS) {
 // plugin split into modules), but only if the user hasn't modified them.
 for (const [relKey, oldHash] of Object.entries(manifest.files)) {
   if (newManifestFiles[relKey] !== undefined) continue;
-  const dest = join(target, relKey);
+  const dest = safeTargetPath(relKey);
   if (!existsSync(dest)) continue;
   if (fileHash(dest) === oldHash) {
     if (!values["dry-run"]) rmSync(dest, { force: true });