habithive-code 0.2.4 → 0.3.0

package/src/setup.js

@@ -1,21 +1,30 @@
 // habithive-code — one-command full-stack setup.
-//   1. opencode        — official npm package (installed if missing)          [required]
+//   1. opencode        — pinned version (installed, or moved to the pin)       [required]
 //   2. oh-my-opencode  — pinned version wired into config (npm fetches it)     [required]
 //   3. habithive           — plugin wired into tui.json                            [required]
 //   4. playwright MCP  — wired into the opencode config                        [extra]
-//   5. openspec CLI    — @fission-ai/openspec (npm)                            [extra]
-//   6. graphify CLI    — graphifyy (PyPI, via uv/pip)                          [extra]
+//   5. openspec CLI    — @fission-ai/openspec pinned + intent-driven schema     [extra]
+//   6. graphify CLI    — graphifyy (PyPI, via uv/pip; installed or upgraded)   [extra]
 //   7. bundled skills  — karpathy-guidelines (MIT) + graphify → config/skills  [extra]
 // Nothing is bundled/redistributed except the two skills under skills/. Every
-// tool is installed from its official source. Use `habithive setup --minimal` to
-// skip the extras (4-7).
+// tool is installed from its official source.
+//
+// reconcile() = everything after the recorded mode: the same steps, applied to every
+// mode file set that exists. It never records a mode or renames files; `habithive update`
+// runs it after installing a release, runSetup() runs it and records "complex" on first setup.
 
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { mkdirSync, cpSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { setMode, ensureMcp, OMO_SPEC, PATHS } from "./config.js";
+import { ensureMcp, HABITHIVE_PLUGIN_URL, PATHS, isOmo, isHabithive, readMode, writeMode, currentMode, filesForMode, hasModeSet } from "./config.js";
+import { safeEdit, ConfigParseError } from "./jsonc.js";
+import { OMNIROUTE_MODELS, ensureOmniroute, omnirouteTargets } from "./omniroute.js";
+import { installSchema } from "./openspec.js";
+import { realpathSync } from "node:fs";
+import { OPENCODE_PIN, OMO_SPEC, OPENSPEC_PIN, compareVersions, versionIn, isUnsupportedMajor, opencodeInstallMethod, v2Notice } from "./versions.js";
 
 const c = { reset: "\x1b[0m", cyan: "\x1b[36m", green: "\x1b[32m", yellow: "\x1b[33m", dim: "\x1b[2m", red: "\x1b[31m" };
 const say = (m) => process.stdout.write(m + "\n");
@@ -38,6 +47,52 @@ async function confirm(q, yes) {
   return !/^n/i.test(a.trim());
 }
 
+// Bring opencode to OPENCODE_PIN: install it if missing, else `opencode upgrade <pin>` (works for npm,
+// brew and curl installs). An upgrade failure prints the manual command and setup continues.
+// A different major (OpenCode 2) is never upgraded — it cannot downgrade (404): print the recovery notice, continue.
+// Returns the final version (null only when opencode is missing and could not be installed).
+async function ensureOpencode({ yes = false } = {}) {
+  const ver = () => { // null = missing, "" = present but unparseable
+    const r = spawnSync("opencode", ["--version"], { encoding: "utf8", shell: win, timeout: 5000 });
+    return r.status === 0 ? (versionIn(r.stdout) ?? "") : null;
+  };
+  let v = ver();
+  if (v === null) {
+    warn("opencode not found");
+    if (!(await confirm(`Install opencode ${OPENCODE_PIN} now (npm i -g opencode-ai@${OPENCODE_PIN})?`, yes))) {
+      say(`${c.red}aborted${c.reset} — install opencode first, then re-run: habithive setup`);
+      return null;
+    }
+    step(`installing opencode ${OPENCODE_PIN}…`);
+    if (!run("npm", ["i", "-g", `opencode-ai@${OPENCODE_PIN}`])) { say(`${c.red}✗ opencode install failed${c.reset}`); return null; }
+    v = ver() || OPENCODE_PIN;
+    ok(`opencode ${v} installed`);
+  } else if (compareVersions(v, OPENCODE_PIN) === 0) ok(`opencode ${v} (tested version)`);
+  else if (isUnsupportedMajor(v)) {
+    const [head, ...steps] = v2Notice(v, opencodeInstallMethod()).split("\n");
+    say(`${c.red}! ${head}${c.reset}\n${steps.map((l) => `${c.dim}${l}${c.reset}`).join("\n")}`);
+  } else {
+    step(`moving opencode ${v || "(unknown version)"} → ${OPENCODE_PIN}…`);
+    run("opencode", ["upgrade", OPENCODE_PIN]);
+    const after = ver();
+    if (after && compareVersions(after, OPENCODE_PIN) === 0) { v = after; ok(`opencode ${v} (tested version)`); }
+    else { v = after || v; warn(`opencode upgrade failed — run: opencode upgrade ${OPENCODE_PIN}`); }
+    // opencode 1.19 ends its upgrade output by suggesting `opencode upgrade --major` (OpenCode 2)
+    say(`${c.dim}  ignore opencode's "opencode upgrade --major" suggestion: Hive needs OpenCode 1${c.reset}`);
+  }
+  return v;
+}
+
+// opencode updates only through Hive: set autoupdate:false in the opencode.jsonc of each mode set.
+function pinAutoupdate(files) {
+  return [...new Set(files.filter((f) => base(f) === "opencode.jsonc"))].filter((f) =>
+    safeEdit(f, (cfg) => {
+      if (!Object.keys(cfg).length) cfg.$schema = "https://opencode.ai/config.json";
+      cfg.autoupdate = false;
+      return cfg;
+    }).changed);
+}
+
 // Install the graphify (graphifyy on PyPI) Python CLI — prefer uv, fall back to pip.
 function installGraphify() {
   if (has("uv")) return run("uv", ["tool", "install", "--upgrade", "graphifyy"]);
@@ -47,6 +102,37 @@ function installGraphify() {
          run(py, ["-m", "pip", "install", "-U", "--break-system-packages", "graphifyy"]);
 }
 
+const nm = (e) => (Array.isArray(e) ? e[0] : e); // plugin entry is "name" or ["name", options]
+const put = (a, is, v) => { // drop stale/duplicate managed entries (keep the first v, with its options), append v if absent
+  let seen = false;
+  const r = a.filter((e) => { if (!is(e) && nm(e) !== v) return true; if (nm(e) !== v || seen) return false; return (seen = true); });
+  return seen ? r : [...r, v];
+};
+const base = (f) => f.split(/[\\/]/).pop();
+const cfgErr = (e) => {
+  if (!(e instanceof ConfigParseError)) throw e;
+  say(`${c.red}✗ cannot read ${e.file}:${e.line}:${e.column} — fix it and re-run${c.reset}`);
+  return 1;
+};
+
+// Ensure Hive-managed plugin entries in one mode's file set via safeEdit (backup + no-op when unchanged).
+// A stale entry (old path / old pin) is replaced; every other plugin is left alone. Returns the files changed.
+function wireSet(files, { omo }) {
+  return files.filter((f) => {
+    const n = base(f), tui = n === "tui.json";
+    if (!omo && !tui) return false; // simple set: Hive plugin in tui.json only
+    const fresh = !existsSync(f);
+    return safeEdit(f, (cfg) => {
+      if (fresh && n === "opencode.jsonc") cfg.$schema = "https://opencode.ai/config.json";
+      let a = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+      if (tui) a = put(a, isHabithive, HABITHIVE_PLUGIN_URL);
+      if (omo) a = put(a, isOmo, OMO_SPEC);
+      cfg.plugin = a;
+      return cfg;
+    }).changed;
+  });
+}
+
 // Copy the skills bundled with this package into ~/.config/opencode/skills/.
 function installSkills() {
   const srcDir = fileURLToPath(new URL("../skills", import.meta.url));
@@ -58,46 +144,96 @@ function installSkills() {
   return names;
 }
 
-export async function runSetup({ yes = false, mode = "complex", minimal = false } = {}) {
-  say(`\n${c.cyan}habithive-code setup${c.reset} ${c.dim}— opencode + oh-my-opencode + habithive${minimal ? "" : " + tools + skills"}${c.reset}\n`);
+const tilde = (f) => f.replace(homedir(), "~");
 
-  // 1) opencode (required)
-  if (has("opencode")) ok("opencode already installed");
-  else {
-    warn("opencode not found");
-    if (!(await confirm("Install opencode now (npm i -g opencode-ai)?", yes))) {
-      say(`${c.red}aborted${c.reset} — install opencode first, then re-run: habithive setup`);
-      return 1;
-    }
-    step("installing opencode…");
-    if (!run("npm", ["i", "-g", "opencode-ai"])) { say(`${c.red}✗ opencode install failed${c.reset}`); return 1; }
-    ok("opencode installed");
-  }
+// `hive` is the short alias for habithive; warn when another program already owns that name on PATH.
+const real = (p) => { try { return realpathSync(p); } catch { return null; } };
+function hiveShadowCheck() {
+  try {
+    const r = spawnSync(win ? "where" : "which", ["hive"], { encoding: "utf8", shell: win, timeout: 5000 });
+    const p = r.status === 0 ? (r.stdout || "").split(/\r?\n/)[0].trim() : "";
+    if (!p) return;
+    const mine = realpathSync(fileURLToPath(new URL("../bin/habithive.mjs", import.meta.url)));
+    if ((real(p) ?? p) !== mine) warn(`\`hive\` on your PATH is another program (${p}) — use \`habithive\` instead`);
+  } catch {}
+}
+
+// Bring the machine to this release without touching the mode record: opencode pin, then each Hive-managed
+// entry in EVERY mode file set that exists (oh-my-openagent only in the complex set), then the extras.
+// Returns an exit code. `beforeWire` is runSetup's seam for the first-setup case (returns the files it changed; may throw ConfigParseError).
+export async function reconcile({ yes = false, beforeWire } = {}) {
+  // 1) opencode (required, pinned)
+  if ((await ensureOpencode({ yes })) === null) return 1;
 
-  // 2)+3) wire oh-my-opencode (pinned) + habithive, default complex
+  // 2)+3) wire oh-my-opencode (pinned, complex set only) + habithive + autoupdate:false in each set
   mkdirSync(PATHS.CONFIG_DIR, { recursive: true });
   step(`wiring oh-my-opencode (${OMO_SPEC}) + habithive…`);
-  setMode(mode);
-  ok(`config wired (${mode} mode)`);
+  let changed, sets;
+  try {
+    const first = beforeWire?.() ?? [];
+    const complex = filesForMode("complex"), simple = filesForMode("simple");
+    sets = [...(complex || []), ...(simple || [])];
+    changed = new Set([
+      ...first,
+      ...(complex ? wireSet(complex, { omo: true }) : []),
+      ...(simple ? wireSet(simple, { omo: false }) : []),
+      ...pinAutoupdate(sets),
+    ]);
+  } catch (e) { return cfgErr(e); }
+  ok(`config ${changed.size ? `updated: ${[...changed].map(tilde).join(", ")}` : "already current"} (${currentMode()} mode active) · opencode autoupdate off`);
 
-  if (!minimal) {
-    // 4) playwright MCP
-    if (ensureMcp("playwright", { type: "local", enabled: true, command: "npx", args: ["@playwright/mcp@latest"] }))
-      ok("playwright MCP added"); else ok("playwright MCP already configured");
+  // OmniRoute provider: Hive-owned values reset in each mode set, user additions and any apiKey kept
+  try {
+    const n = omnirouteTargets().filter((f) => safeEdit(f, ensureOmniroute).changed).length;
+    ok(n ? `OmniRoute provider (${Object.keys(OMNIROUTE_MODELS).length} models)` : "OmniRoute provider already current");
+  } catch (e) { return cfgErr(e); }
 
-    // 5) openspec CLI
-    if (has("openspec")) ok("openspec already installed");
-    else { step("installing openspec (@fission-ai/openspec)…"); run("npm", ["i", "-g", "@fission-ai/openspec"]) ? ok("openspec installed") : warn("openspec install skipped/failed"); }
+  // 4) playwright MCP
+  const spec = { type: "local", enabled: true, command: "npx", args: ["@playwright/mcp@latest"] };
+  let added = false;
+  try { for (const f of new Set(sets.filter((f) => base(f) === "opencode.jsonc"))) added = ensureMcp("playwright", spec, f) || added; }
+  catch (e) { return cfgErr(e); }
+  if (added) ok("playwright MCP added"); else ok("playwright MCP already configured");
 
-    // 6) graphify CLI (graphifyy on PyPI)
-    if (has("graphify")) ok("graphify already installed");
-    else { step("installing graphify (graphifyy via uv/pip)…"); installGraphify() ? ok("graphify installed") : warn("graphify install skipped/failed (needs uv or pip)"); }
-
-    // 7) bundled skills → config/skills (loaded by oh-my-opencode in complex mode)
-    const skills = installSkills();
-    if (skills.length) ok(`skills installed: ${skills.join(", ")}`);
+  // 5) openspec CLI — pinned (newer releases reject the intent-driven schema); installed only when it differs
+  const osv = versionIn(spawnSync("openspec", ["--version"], { encoding: "utf8", shell: win, timeout: 5000 }).stdout);
+  if (osv && compareVersions(osv, OPENSPEC_PIN) === 0) ok(`openspec ${osv} (tested version)`);
+  else {
+    step(`installing openspec ${OPENSPEC_PIN}${osv ? ` (was ${osv})` : ""}…`);
+    run("npm", ["i", "-g", `@fission-ai/openspec@${OPENSPEC_PIN}`]) ? ok(`openspec ${OPENSPEC_PIN} installed`) : warn("openspec install failed");
   }
 
+  // 5b) intent-driven schema → user-level OpenSpec schemas folder
+  try {
+    const r = installSchema();
+    ok(r.changed ? `intent-driven schema installed (${tilde(r.path)})` : "intent-driven schema up to date");
+    if (r.backup) say(`${c.dim}  previous copy backed up: ${tilde(r.backup)}${c.reset}`);
+  } catch (e) { warn(`intent-driven schema install failed: ${e?.message || e}`); }
+
+  // 6) graphify CLI (graphifyy on PyPI) — upgraded if uv manages it, else installed/upgraded via uv/pip
+  step("installing/upgrading graphify (graphifyy via uv/pip)…");
+  const uv = has("uv") && /graphifyy/.test(spawnSync("uv", ["tool", "list"], { encoding: "utf8", shell: win }).stdout || "");
+  (uv ? run("uv", ["tool", "upgrade", "graphifyy"]) : installGraphify()) ? ok("graphify up to date") : warn("graphify upgrade failed (needs uv or pip)");
+
+  // 7) bundled skills → config/skills (loaded by oh-my-opencode in complex mode)
+  const skills = installSkills();
+  if (skills.length) ok(`skills installed: ${skills.join(", ")}`);
+  hiveShadowCheck();
+  return 0;
+}
+
+export async function runSetup({ yes = false } = {}) {
+  say(`\n${c.cyan}habithive-code setup${c.reset} ${c.dim}— opencode + oh-my-opencode + habithive + tools + skills${c.reset}\n`);
+
+  // first setup (no mode record): the active files become the complex set, then complex is recorded
+  const firstSetup = readMode() === null;
+  const code = await reconcile({
+    yes,
+    beforeWire: () => (firstSetup && !hasModeSet("complex") ? wireSet([PATHS.OPENCODE_JSONC, PATHS.TUI_JSON], { omo: true }) : []),
+  });
+  if (code !== 0) return code;
+  if (firstSetup) writeMode("complex");
+
   say(`\n${c.green}done.${c.reset} start with:  ${c.cyan}habithive${c.reset}`);
   say(`${c.dim}  habithive            complex mode, new session`);
   say(`  habithive simple     vanilla opencode`);

package/src/spec.js

@@ -0,0 +1,45 @@
+// habithive-code — `hive spec init`: set a project up with OpenSpec + the intent-driven schema.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SCHEMA_NAME, SHIPPED_SCHEMA_DIR, copyTree } from "./openspec.js";
+
+const defaultRun = (cmd, args, { cwd } = {}) => {
+  const r = spawnSync(cmd, args, { cwd, encoding: "utf8", shell: process.platform === "win32" });
+  return { status: r.status ?? 1, stdout: r.stdout || "", stderr: r.stderr || (r.error ? String(r.error.message) : "") };
+};
+
+const SCHEMA_LINE = /^schema:.*$/m;
+
+export async function specInit(dir = process.cwd(), { run = defaultRun, out = (s) => process.stdout.write(s + "\n") } = {}) {
+  if (!existsSync(dir)) { out(`folder not found: ${dir}`); return 1; }
+  if (run("openspec", ["--version"], { cwd: dir }).status !== 0) {
+    out("openspec not found — run: habithive setup");
+    return 1;
+  }
+  const cfg = join(dir, "openspec", "config.yaml");
+  if (existsSync(cfg)) {
+    const m = readFileSync(cfg, "utf8").match(/^schema:\s*(\S+)/m);
+    const cur = m ? m[1].replace(/^["']|["']$/g, "") : "(none)";
+    out(`OpenSpec is already set up here (schema: ${cur})`);
+    if (cur !== SCHEMA_NAME) {
+      out("To switch to intent-driven:");
+      out(`  1. openspec schema fork ${SCHEMA_NAME} ${SCHEMA_NAME}`);
+      out(`  2. set \`schema: ${SCHEMA_NAME}\` in openspec/config.yaml`);
+    }
+    return 0;
+  }
+  const init = run("openspec", ["init", "--tools", "opencode", dir], { cwd: dir });
+  if (init.status !== 0 || !existsSync(cfg)) {
+    out(`openspec init failed${init.stderr ? ": " + init.stderr.trim() : ""}`);
+    return 1;
+  }
+  copyTree(SHIPPED_SCHEMA_DIR, join(dir, "openspec", "schemas", SCHEMA_NAME));
+  const text = readFileSync(cfg, "utf8");
+  const line = `schema: ${SCHEMA_NAME}`;
+  writeFileSync(cfg, SCHEMA_LINE.test(text) ? text.replace(SCHEMA_LINE, line) : line + "\n" + text);
+  const v = run("openspec", ["schema", "validate", SCHEMA_NAME], { cwd: dir });
+  out(`schema validate: ${v.status === 0 ? "ok" : "failed"}${(v.stdout + v.stderr).trim() ? "\n" + (v.stdout + v.stderr).trim() : ""}`);
+  out("Next: commit openspec/ and .opencode/");
+  return 0;
+}

package/src/update.js

@@ -0,0 +1,62 @@
+// habithive-code — daily "new release?" check against the public npm registry.
+// Plain Node/Bun ESM, no deps. Never throws: a failed check is silent and only throttles retries.
+// Cache (~/.habithive/update-check.json): { checkedAt, latest, lastAttemptAt }.
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { STORE_DIR } from "./core.js";
+import { compareVersions } from "./versions.js";
+
+export const UPDATE_CACHE = join(STORE_DIR, "update-check.json");
+export const REGISTRY_URL = process.env.HABITHIVE_REGISTRY_URL || "https://registry.npmjs.org/habithive-code/latest"; // env: test-only stub
+const DAY = 24 * 3600 * 1000, HOUR = 3600 * 1000;
+
+export function installedVersion() {
+  try { return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version || "0.0.0"; } catch { return "0.0.0"; }
+}
+
+export function readCache() {
+  try {
+    const j = JSON.parse(readFileSync(UPDATE_CACHE, "utf8")), out = {};
+    if (Number.isFinite(j?.checkedAt)) out.checkedAt = j.checkedAt;
+    if (typeof j?.latest === "string" && j.latest) out.latest = j.latest;
+    if (Number.isFinite(j?.lastAttemptAt)) out.lastAttemptAt = j.lastAttemptAt;
+    return out;
+  } catch { return {}; }
+}
+
+// due = last success >= 24h ago (or never) and last attempt >= 1h ago (or never)
+export function isDue(cache, now = Date.now()) {
+  const c = cache || {};
+  return (!c.checkedAt || now - c.checkedAt >= DAY) && (!c.lastAttemptAt || now - c.lastAttemptAt >= HOUR);
+}
+
+function writeCache(obj) {
+  try {
+    mkdirSync(dirname(UPDATE_CACHE), { recursive: true });
+    const tmp = `${UPDATE_CACHE}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf8");
+    renameSync(tmp, UPDATE_CACHE);
+  } catch {}
+}
+
+// Latest published version string, or null. Success refreshes the cache; failure keeps it and only stamps lastAttemptAt.
+export async function checkLatest({ now = Date.now(), fetchImpl = globalThis.fetch, timeoutMs = 3000 } = {}) {
+  let latest = null, timer;
+  try {
+    const ac = new AbortController();
+    const timeout = new Promise((_, rej) => { timer = setTimeout(() => { ac.abort(); rej(new Error("timeout")); }, timeoutMs); });
+    const get = (async () => {
+      const r = await fetchImpl(REGISTRY_URL, { headers: { accept: "application/json" }, signal: ac.signal });
+      if (!r || !r.ok) throw new Error(`http ${r?.status}`);
+      return (await r.json())?.version;
+    })();
+    get.catch(() => {}); // a late rejection after the timeout won the race must not go unhandled
+    const v = await Promise.race([get, timeout]);
+    if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) latest = v;
+  } catch {} finally { clearTimeout(timer); }
+  const prev = readCache();
+  writeCache(latest ? { checkedAt: now, latest, lastAttemptAt: now } : { ...prev, lastAttemptAt: now });
+  return latest;
+}
+
+export const updateAvailable = (cache, installed = installedVersion()) => !!cache?.latest && compareVersions(cache.latest, installed) > 0;

package/src/versions.js

@@ -0,0 +1,71 @@
+// habithive-code — the toolchain versions this release is tested against.
+// Both move only with a habithive-code release (see docs/COMPATIBILITY.md); README
+// "Compatibility" quotes them and test/versions.test.mjs keeps the two in sync.
+// Fallback for opencode if a pin is ruled out: 1.18.34.
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+
+export const OPENCODE_PIN = "1.19.4";
+export const OMO_SPEC = "oh-my-openagent@4.19.1"; // 5.x blocked: moves this config to ~/.omo/omo.jsonc (docs/COMPATIBILITY.md #9)
+export const NODE_MIN = "20.19.0"; // OpenSpec 1.5.0 needs it (docs/COMPATIBILITY.md)
+export const OPENSPEC_PIN = "1.5.0"; // 1.14.x rejects the intent-driven schema (ADR step writes outside the change folder)
+
+const parse = (v) => {
+  const m = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-(.+))?$/.exec(String(v ?? "").trim());
+  return m ? { n: [+m[1], +(m[2] || 0), +(m[3] || 0)], pre: m[4] || "" } : { n: [0, 0, 0], pre: "" };
+};
+
+// -1 | 0 | 1 — numeric major.minor.patch; a leading "v" is ignored, a pre-release ("-x")
+// sorts before its release, unparseable counts as 0.0.0.
+export function compareVersions(a, b) {
+  const x = parse(a), y = parse(b);
+  for (let i = 0; i < 3; i++) if (x.n[i] !== y.n[i]) return x.n[i] < y.n[i] ? -1 : 1;
+  if (x.pre === y.pre) return 0;
+  if (!x.pre || !y.pre) return x.pre ? -1 : 1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+// first x.y.z[-pre] in a tool's `--version` output, else null
+export const versionIn = (s) => /\d+\.\d+\.\d+(?:-[\w.]+)?/.exec(String(s ?? ""))?.[0] ?? null;
+
+// OpenCode 2 guard (ADR-0010): Hive needs OpenCode 1. Major of a `--version` text ("opencode v2.1.3"), null if none.
+export const opencodeMajor = (text) => { const v = versionIn(text); return v ? parseInt(v, 10) : null; };
+// true when the installed major differs from OPENCODE_PIN's (unparseable is never "unsupported")
+export const isUnsupportedMajor = (v) => { const m = opencodeMajor(v); return m !== null && m !== opencodeMajor(OPENCODE_PIN); };
+
+const slash = (p) => String(p ?? "").replace(/\\/g, "/");
+const whichOpencode = () => {
+  const r = spawnSync(process.platform === "win32" ? "where" : "which", ["opencode"], { encoding: "utf8", timeout: 2000 });
+  return r.status === 0 ? r.stdout.split(/\r?\n/)[0].trim() || null : null;
+};
+
+// How the opencode on PATH was installed, from its resolved path: npm | brew | curl | unknown. Deps injectable for tests.
+export function opencodeInstallMethod({ which = whichOpencode, realpath = realpathSync, home = homedir() } = {}) {
+  let p; try { p = which(); } catch {}
+  if (!p) return "unknown";
+  try { p = realpath(p); } catch {}
+  p = slash(p);
+  if (p.includes("/@opencode/cli/") || p.includes("/node_modules/")) return "npm";
+  if (["/opt/homebrew/", "/usr/local/Cellar/", "/home/linuxbrew/"].some((b) => p.startsWith(b))) return "brew";
+  if (p.startsWith(`${slash(home)}/.opencode/bin/`)) return "curl";
+  return "unknown";
+}
+
+// Lines telling the user how to get back to OpenCode 1; unknown method lists all three.
+export function recoverySteps(method, pin = OPENCODE_PIN) {
+  const cmds = {
+    npm: ["npm rm -g @opencode/cli", "habithive setup"],
+    brew: ["brew uninstall opencode-v2", "habithive setup"],
+    curl: [`curl -fsSL https://opencode.ai/install | bash -s -- --version ${pin}`],
+  };
+  const lines = cmds[method]
+    ? ["To go back to OpenCode 1:", ...cmds[method].map((c) => `  ${c}`)]
+    : ["Install method not detected — use the one you installed OpenCode 2 with:",
+       ...Object.entries(cmds).flatMap(([m, cs]) => cs.map((c, i) => `  ${i ? "     " : `${m}:`.padEnd(5)} ${c}`))];
+  return [...lines, "Sessions created under OpenCode 2 may not open in OpenCode 1."];
+}
+
+// Full multi-line notice: header line, then the recovery steps.
+export const v2Notice = (version, method, pin = OPENCODE_PIN) =>
+  [`OpenCode ${version} is installed — habithive needs OpenCode 1 (tested ${pin}); complex mode and the model tree do not work on OpenCode 2.`, ...recoverySteps(method, pin)].join("\n");