opencode-goal-mode 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## v0.4.3
+
+### Build mode no longer behaves like a goal
+
+- Switching a session from the `goal` agent to Build (or any non-goal agent) now
+  **deactivates** it: `state.active` tracks the current agent (`isPrimaryAgent`),
+  instead of latching `true` forever. The sidebar also gates on the session's live
+  current agent (its latest message), so when you switch to Build the Goal section
+  disappears and OpenCode's native todos return — and a Build session can no longer
+  invoke the `goal-*` subagents or have its completion claims policed.
+- Goal **worker** subagents (e.g. `goal-implementer`) are no longer activated by
+  their own edits, so Goal completion enforcement is never injected into a worker's
+  prompt. Bookkeeping runs only for active goal sessions and review subagents.
+
+### `npm install -g` now updates everything, automatically
+
+- A global-install `postinstall` runs the installer for you — it copies the
+  components into `~/.config/opencode`, registers the Goal sidebar, and clears
+  OpenCode's stale plugin cache — so `npm install -g opencode-goal-mode` **alone**
+  fully installs or upgrades Goal Mode and the new version actually loads on the
+  next restart. It runs only for global installs, never for repo/dev/dependency
+  installs, and never fails the npm install (it prints a hint if it can't finish).
+
+### Fixes
+
+- **CI green again:** the headless visual test no longer requires
+  `@opentui/solid/jsx-dev-runtime` (the CI visual job was failing).
+- Hardened `gatePassedFresh` against partial/legacy snapshots so the TUI never
+  silently fails to render an active goal.
+- Compaction context is only added for active goal sessions (no stray Goal state in
+  a Build session's compaction summary).
+- Docs: corrected the sidebar description (separate gate/status lines; the label is
+  `GOAL`, not "Goal todos").
+
+## 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

package/README.md

@@ -244,9 +244,11 @@ enforcement and writes its state to disk, and an experimental TUI plugin
   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);
+  - the short goal title (white);
+  - the gate count `passing/total gates` (cyan), on its own line;
+  - the lifecycle status (orange) on its own line — `in progress`, or
+    `completed · N review cycles`. 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
@@ -278,12 +280,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "main": "plugins/goal-sidebar.tsx",
@@ -25,6 +25,7 @@
     "plugins/",
     "research/",
     "scripts/install.mjs",
+    "scripts/postinstall.mjs",
     "ARCHITECTURE.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -51,7 +52,8 @@
     "ci": "npm run validate && npm run audit",
     "prepublishOnly": "npm run ci && npm run publish:check",
     "install:local": "node scripts/install.mjs",
-    "install:global": "node scripts/install.mjs --global"
+    "install:global": "node scripts/install.mjs --global",
+    "postinstall": "node scripts/postinstall.mjs"
   },
   "keywords": [
     "opencode",

package/plugins/goal-guard/gates.js

@@ -71,7 +71,7 @@ export function requiredGates(state, config) {
 
 /** A gate is satisfied when its latest verdict is PASS and newer than the last edit. */
 export function gatePassedFresh(state, agent) {
-  const v = state.latestVerdict[agent];
+  const v = state.latestVerdict?.[agent];
   if (!v || v.verdict !== "PASS") return false;
   return v.seq > (state.lastEditSeq || 0);
 }

package/plugins/goal-guard/guard.js

@@ -93,7 +93,10 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
       try {
         if (!inp?.sessionID) return;
         const state = store.stateFor(inp.sessionID);
-        if (isPrimaryAgent(inp.agent)) state.active = true;
+        // `active` reflects whether this session is CURRENTLY a Goal session. Switching
+        // the session's agent to Build (or anything non-goal) must deactivate it, or
+        // the sidebar/guard would keep treating an explicit Build session as a goal.
+        if (inp.agent) state.active = isPrimaryAgent(inp.agent);
         const text = partsText(out?.parts);
         if (text && state.active) {
           // Accumulate goal text (bounded) so contextual gates can be derived.
@@ -115,7 +118,10 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
         if (!normalized) return;
         const state = store.stateFor(normalized);
         state.currentAgent = inp.agent;
-        if (isPrimaryAgent(inp.agent)) state.active = true;
+        // Track the current mode: a session is active (a goal) only while its agent
+        // is the goal primary. Switching to Build/Plan/etc. deactivates it so the
+        // Goal sidebar and enforcement stop treating it as a goal.
+        if (inp.agent) state.active = isPrimaryAgent(inp.agent);
       } catch {
         /* ignore */
       }
@@ -178,13 +184,14 @@ 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;
+        // Goal bookkeeping runs only for an active Goal session, or for a REVIEW
+        // subagent's own child session (so the agent-path can capture its verdict).
+        // It must NOT run for a Build/Plan/custom session, nor for a non-review goal
+        // WORKER child session (e.g. goal-implementer/goal-explorer) — otherwise that
+        // worker's edits would mark it dirty and activate it, leaking goal completion
+        // enforcement into a worker's prompt. Destructive-command blocking lives in
+        // tool.execute.before and still applies in every mode.
+        if (!state.active && !isReviewAgent(state.currentAgent)) return;
         const tool = inp?.tool;
         const isReviewing = isReviewAgent(state.currentAgent);
 
@@ -278,6 +285,7 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
       try {
         if (!inp?.sessionID || !out || !Array.isArray(out.context)) return;
         const state = store.stateFor(inp.sessionID);
+        if (!state.active) return; // only preserve goal state for active Goal sessions
         out.context.push(
           `Goal Guard state: ${summarizeState(state, config)}. Preserve Goal Contract, Verification Ledger, ` +
             `Review Ledger, Reviewer Memory, review cycle count, dirty state, and open findings across compaction.`,

package/plugins/goal-sidebar.tsx

@@ -23,7 +23,7 @@
  * 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";
 
@@ -31,9 +31,11 @@ const DEFAULT_COLOR = "#FFD700"; // running — GOAL label, yellow
 const DEFAULT_DONE = "#FF5555"; // done — red
 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 · status line (running) — cyan accent
+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 GOAL_AGENT = "goal"; // the primary Goal agent id (mirrors agents.js PRIMARY_AGENT)
 const RAINBOW = ["#FF5555", "#FFAA00", "#FFFF55", "#55FF55", "#55FFFF", "#5599FF", "#FF55FF"];
 
 function resolveOptions(options, env) {
@@ -85,16 +87,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";
@@ -106,27 +119,74 @@ const tui = async (api, options) => {
     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,
         slots: {
           sidebar_content(_ctx, props) {
             if (!props?.session_id) return undefined;
+            // The session's CURRENT agent, from its latest message (mirrors the
+            // reference OpenCode TUI plugin). This is the authoritative, immediate
+            // signal of whether the session is in Goal mode right now — so when the
+            // user switches to Build (or any non-goal agent) the Goal section vanishes
+            // and OpenCode's native todos return, without waiting for persisted state.
+            const currentAgent = () => {
+              try {
+                const msgs = api?.state?.session?.messages?.(props.session_id);
+                if (Array.isArray(msgs)) {
+                  for (let i = msgs.length - 1; i >= 0; i--) {
+                    const a = msgs[i] && msgs[i].agent;
+                    if (a) return String(a).toLowerCase();
+                  }
+                }
+              } catch {
+                /* messages API unavailable — fall back to persisted goal state */
+              }
+              return undefined;
+            };
             const read = () => {
               try {
-                return readModel(worktree, props?.session_id) || NO_GOAL;
+                const agent = currentAgent();
+                // Render only in Goal mode. "goal" and its `goal-*` subagents count as
+                // Goal mode (so the section doesn't flicker out while reviewers run);
+                // any other primary agent (build/plan/custom) renders nothing here.
+                const goalMode = !agent || agent === GOAL_AGENT || agent.startsWith(`${GOAL_AGENT}-`);
+                if (!goalMode) return 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 isRainbow = () => rainbow() && model().state === "running";
             // Settled (post-rainbow) colour for each header line. When done, every
@@ -136,7 +196,8 @@ const tui = async (api, options) => {
               if (model().state === "done") return doneColor;
               if (kind === "label") return color; // GOAL — yellow
               if (kind === "title") return TITLE_COLOR; // goal title — bright white
-              return META_COLOR; // gates · status — cyan
+              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) => {
@@ -144,17 +205,19 @@ const tui = async (api, options) => {
               if (item.status === "done") return TODO_DONE_COLOR;
               return model().state === "done" ? doneColor : muted;
             };
-            // Goal sessions render a Goal-owned todo section (GOAL label, then the goal
-            // title, status, and structured todos — each on its own line). Non-Goal /
-            // no-goal sessions returned undefined above, so native todos remain.
+            // 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, "label")}><b>{model().label || "GOAL"}</b></text>
                   <text fg={lineColor(1, "title")}>{model().goal}</text>
-                  <text fg={lineColor(2, "meta")}>{`${model().gates} · ${model().status}`}</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={todoColor(index() + 3, item)}>{`${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

@@ -183,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
 // ---------------------------------------------------------------------------
@@ -205,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) {
@@ -302,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.");

package/scripts/postinstall.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Auto-setup on a GLOBAL install.
+ *
+ * When a user runs `npm install -g opencode-goal-mode` (a fresh install OR an
+ * upgrade), this runs the installer for them so that, with a single command, the
+ * package's components are (re)copied into `~/.config/opencode`, the Goal sidebar
+ * is registered in `tui.json`, and OpenCode's stale plugin cache is cleared so the
+ * just-installed version actually loads. That makes `npm install -g` "really
+ * update" — no separate `opencode-goal-mode --global` step required.
+ *
+ * Safety:
+ *  - Runs ONLY for global installs (npm sets `npm_config_global`). Repo development
+ *    (`npm ci` / `npm install`) and installs as a project dependency are no-ops, so
+ *    this never writes to a user's config when it shouldn't.
+ *  - Best-effort: it NEVER fails the npm install. Any problem prints a one-line
+ *    hint to run `opencode-goal-mode --global` manually and exits 0.
+ */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+function isGlobalInstall() {
+  const g = process.env.npm_config_global;
+  return g === "true" || g === "1" || g === true;
+}
+
+if (!isGlobalInstall()) {
+  // Local/dev/dependency install — do not touch the user's OpenCode config.
+  process.exit(0);
+}
+
+try {
+  const installer = join(dirname(fileURLToPath(import.meta.url)), "install.mjs");
+  console.log("opencode-goal-mode: global install detected — updating ~/.config/opencode…");
+  const res = spawnSync(process.execPath, [installer, "--global"], { stdio: "inherit" });
+  // spawnSync does not throw on a non-zero exit (e.g. the installer refused to
+  // overwrite a file you edited). Surface a clear, actionable hint instead of
+  // leaving only the child's raw error.
+  if (res.error || res.status !== 0) {
+    console.warn(
+      "opencode-goal-mode: auto-setup didn't fully complete. " +
+        "Run `opencode-goal-mode --global` manually (add --force to replace files you've edited), then restart OpenCode.",
+    );
+  }
+} catch (err) {
+  console.warn(
+    `opencode-goal-mode: auto-setup skipped (${(err && err.message) || err}). ` +
+      "Run `opencode-goal-mode --global` to finish, then restart OpenCode.",
+  );
+}
+// Never fail `npm install`, regardless of the installer's outcome.
+process.exit(0);