habithive-code 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to habithive-code are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-12
+
+### Breaking
+
+- The model tree moved from `/model` to `/hive-models` (alias `hivemodels`). Hive no longer registers `/model`.
+- Node.js 20.19 or later is required (OpenSpec 1.5.0 minimum). Hive checks at start and explains how to upgrade.
+- `--minimal` is accepted but ignored with a notice. Setup always installs everything: OpenSpec, graphify, skills, Playwright MCP and OmniRoute.
+- Toolchain versions are pinned and move only with a Hive release: opencode 1.19.4, oh-my-openagent 4.19.1, OpenSpec 1.5.0. Setup moves your installs to these versions.
+- opencode self-update is turned off (`autoupdate: false`). Use `habithive update`.
+- OpenCode 2 is not supported. Do not run `opencode upgrade --major`; complex mode and the model tree do not work on OpenCode 2.
+- Launching `habithive` no longer repairs or rewrites opencode config. Repair happens in `habithive setup` and `habithive update`.
+
+### Added
+
+- `habithive update`: installs the latest `habithive-code` from npm, then re-applies the release pins and config steps. Your mode, model overrides, baseline and other config are kept. For a source checkout it prints `git pull` instructions instead.
+- Update notice: the TUI plugin checks npm at most once every 24 hours (cached, silent offline) and shows a toast when a newer version exists.
+- `hive` as a second name for the `habithive` command. Setup warns if another `hive` program is on PATH.
+- `habithive spec init`: sets up a project with OpenSpec and the `intent-driven` schema. See the spec workflow chapter in `docs/guide/`.
+- The `intent-driven` schema ships with the package and is installed to OpenSpec's user-level data directory by setup and update.
+- OmniRoute provider with 38 `auto/*` models, installed by setup and update. No API key is shipped; add yours with `/connect`. `habithive --gateway <ip>` sets the gateway address for a developer.
+- "This screen (live)" in `/hive-models`, which opens opencode's native model picker with no relaunch.
+- OpenCode 2 detection in the launcher, `habithive status` and setup, with recovery steps for npm, brew and curl installs. When setup moves opencode to the tested version, it tells you to ignore opencode's `opencode upgrade --major` suggestion.
+- A warning when a chosen model will be rerouted by oh-my-openagent (Sisyphus with older GPT models, Hephaestus with non-GPT models).
+- `docs/COMPATIBILITY.md` (tested version set and findings), the user guide in `docs/guide/`, and this changelog.
+- Tests for the config editor, versions, update, OmniRoute, OpenSpec, spec init and a package check that fails on any IPv4 address in published files.
+
+### Changed
+
+- Mode switching renames between two complete config file sets (`~/.habithive/modes/<mode>/`) instead of editing config. A launch in the active mode writes nothing. The mode is recorded in `~/.habithive/mode`.
+- All setup and update writes go through a safe JSONC editor: comments and trailing commas are tolerated, strings are never altered, nothing is written if the file does not parse, a timestamped backup is made first, and unchanged files are not rewritten. A file Hive changes is saved as plain JSON: every setting is kept, comments and layout are not (the backup keeps them).
+- Main-agent model changes are automatic: Hive writes config, relaunches into the same session, then moves the on-screen agent to the chosen model. If that cannot be confirmed, the native picker opens with the model at the top of Recent.
+- Relaunch is safer: never while a permission or question prompt is open, works on older plugin APIs, does not quit an opencode that `habithive` did not start, and tells you when the quit did not happen.
+- Menu labels show the configured model and mark changes that wait for a relaunch.
+- "ALL" is now "Everything (agents + tiers)".
+- Setup upgrades an existing graphify install; OpenSpec is held at the pin.
+- OmniRoute entries are Hive-owned: name, adapter and the 38 models are reset on each setup or update. Models you added and any existing `apiKey` or base URL are kept.
+- The published package contains no gateway address. OmniRoute is installed with the placeholder `http://localhost:20128/v1`.
+
+### Fixed
+
+- A trailing comma in `opencode.jsonc` no longer causes your config to be overwritten with a minimal file.
+- Glob strings such as `"src/**/*.ts"` and URLs are no longer corrupted by comment stripping.
+- Launching `habithive` and switching modes no longer rewrite your config, so they no longer remove your comments.
+- Fresh install: with no `oh-my-openagent.json`, the baseline was empty and every model change was refused ("baseline not captured"). An empty baseline is now valid and is re-captured once the file gains content Hive did not write.
+- "Main agent - this screen" never took effect, and "All main agents" skipped the agent on screen. Both are replaced by the automatic flow above.
+- A misleading "run: habithive update" line on OpenCode 2, and `habithive setup` trying `opencode upgrade <pin>` against OpenCode 2.
+- A user-edited copy of the `intent-driven` schema is backed up to `~/.habithive/schema-backups/`, not into OpenSpec's schemas folder, which lists every folder as a schema.
+
+### Removed
+
+- The "Quick" section of the model tree, including "Main agent - this screen".
+- The `--minimal` install mode (see Breaking).
+- The `/model` command registration (see Breaking).
+
+### Upgrading from 0.2.x
+
+`habithive update` does not exist in 0.2.4 or earlier. Upgrade once by hand, then use it from then on:
+
+```bash
+npm i -g habithive-code@latest && habithive setup
+habithive update      # for every later release
+```
+
+Check that `node --version` is 20.19 or later first. If you were on a newer opencode than 1.19.4, setup moves it to the pin. If you ran `opencode upgrade --major`, follow the recovery steps that `habithive status` prints.
+
+Setup leaves you in complex mode. If you used simple mode, run `habithive simple` once afterwards; your simple-mode settings are kept.
+
+Setup saves the opencode config files it changes (usually `~/.config/opencode/opencode.jsonc`) as plain JSON. Every setting is kept, but comments and layout are removed. The original is saved next to the file as `opencode.jsonc.habithive-bak-<timestamp>`. Hive keeps only the newest 5 backups per file, so copy out any comments you want soon after upgrading.
+
+## [0.2.4] - 2026-08-20
+
+See the previous README for details.
+
+## [0.2.3] - 2026-08-20
+
+See the previous README for details.
+
+## [0.2.2] - 2026-08-20
+
+See the previous README for details.
+
+## [0.2.1] - 2026-08-20
+
+See the previous README for details.
+
+## [0.2.0] - 2026-08-20
+
+First release on the public npm registry (published 2026-08-20). See the previous README for details.

package/README.md

@@ -1,158 +1,129 @@
-# habithive-code
+# habithive-code (Hive)
 
-A thin **control layer for [opencode](https://github.com/sst/opencode)** that makes
-two things effortless:
+Hive is a control layer for [opencode](https://github.com/sst/opencode). It gives you a one-command install, live switching between simple and complex mode, a model tree for the [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) agents, an OmniRoute provider, a spec workflow (OpenSpec with the `intent-driven` schema), and a few bundled skills and tools.
 
-1. **Mode switching** — flip between **complex** (full [oh-my-opencode](https://github.com/code-yeongyu/oh-my-openagent) — for hard tasks) and **simple** (vanilla opencode — for everyday use) with one command or an in-app menu, **resuming the same session**.
-2. **A model tree** — set models across oh-my-opencode's many agents/categories from a single menu instead of hand-editing JSON.
+Hive does not bundle opencode or oh-my-openagent. It installs them from their official sources under their own licenses. The command is `habithive`; `hive` is the same command.
 
-> habithive-code does **not** bundle opencode or oh-my-opencode. It installs / points to
-> them from their official sources under their own licenses. All credit for those
-> projects belongs to their authors (see [Credits](#credits)).
+## Quick start
 
-## Prerequisites
-
-- **Node.js ≥ 18**
-- Internet access to fetch `opencode` and `oh-my-openagent` on first `habithive setup` (nothing else is required up front)
-
-## Install
+Prerequisites: Node.js 20.19 or newer (for example `nvm install 22`) and internet access for the first setup.
 
 ```sh
 npm i -g habithive-code
-habithive setup            # full stack (below).  add --minimal to skip the extras
+habithive setup          # installs and wires everything
+habithive                # complex mode, new session
 ```
 
-### Clone from source (GitLab)
-
-For development, or if you'd rather run from a checkout than the published package:
+To use OmniRoute, enable it once with the gateway address your team gives you, then add your key inside opencode:
 
 ```sh
-git clone https://repository.hclhealthcare.in/hive/habit-hive-code.git
-cd habit-hive-code
-npm test                        # sanity check — expect "16 passed, 0 failed"
-node bin/habithive.mjs status   # smoke test without installing anything globally
-npm i -g .                      # optional: makes `habithive` available globally from this checkout
-habithive setup                 # wire opencode + oh-my-opencode + the habithive plugin
+habithive --gateway <ip>      # Hive adds http:// and port 20128
+# in opencode: /connect -> OmniRoute -> paste your key
 ```
 
-Cloning requires a GitLab account with access to the `hive` group on
-`repository.hclhealthcare.in` — ask your GitLab admin to add you if you don't have it yet.
-
-`habithive setup` sets up, from each tool's **official source** (nothing but the two
-skills is bundled):
-
-| # | Component | How | Type |
-|---|-----------|-----|------|
-| 1 | **opencode** | `npm i -g opencode-ai` (if missing) | required |
-| 2 | **oh-my-opencode** | pinned `oh-my-openagent@4.19.1` wired into config | required |
-| 3 | **habithive** plugin | wired into `tui.json` | required |
-| 4 | **playwright MCP** | added to the opencode `mcp` config | extra |
-| 5 | **openspec** | `npm i -g @fission-ai/openspec` (MIT) | extra |
-| 6 | **graphify** | `graphifyy` from PyPI via `uv`/`pip` (MIT) | extra |
-| 7 | **skills** | `karpathy-guidelines` (MIT) + `graphify` → `~/.config/opencode/skills/` | extra |
-
-Extras load/run in **complex mode**. `habithive setup --minimal` installs only 1–3.
-Bundled skills and their licenses are listed in [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).
-> Note: the bundled `graphify` skill was authored for Claude Code's subagent runtime;
-> it drives the `graphify` (graphifyy) CLI and may need tuning under opencode.
-
-## Use
-
-```sh
-habithive                 # complex mode, NEW session
-habithive simple          # vanilla opencode (oh-my-opencode off; the habithive switcher stays)
-habithive complex         # full mode
-habithive -c              # continue the last session
-habithive -s <id>         # continue a specific session
-habithive status          # show current mode
-```
+Full walk-through: [Getting started](docs/guide/01-getting-started.md).
+
+## What you get
+
+| Component | What it is | Where it comes from |
+|-----------|------------|---------------------|
+| opencode | The coding agent, pinned to the tested version | npm `opencode-ai` |
+| oh-my-openagent | Agent harness that complex mode enables, pinned | npm `oh-my-openagent@4.19.1` |
+| Hive TUI plugin | Wordmark, `/habithive` menu, model tree, mode switch | this package |
+| Playwright MCP | Browser tools for agents (`@playwright/mcp`) | added to the opencode `mcp` config |
+| OpenSpec + intent-driven schema | Spec CLI pinned at **1.5.0**, plus the team schema | npm `@fission-ai/openspec`; schema shipped here |
+| graphify | Knowledge-graph CLI (`graphifyy`) | PyPI, via `uv` or `pip` |
+| Bundled skills | `karpathy-guidelines` and `graphify` | `skills/` in this package |
+| OmniRoute | Provider with 38 `auto/*` models | written into both modes' config |
+
+OpenSpec is pinned at **1.5.0** because newer releases reject the `intent-driven` schema. The Node 20.19 minimum comes from OpenSpec. There is no minimal install: setup always installs everything.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `habithive` | Complex mode, new session |
+| `habithive simple` / `habithive complex` | Launch in that mode |
+| `habithive -c` | Continue the last session |
+| `habithive -s <id>` | Continue a specific session |
+| `habithive setup` | Install opencode, oh-my-openagent, the plugin, extras and skills |
+| `habithive update` | Install the latest release from npm and re-apply its pins |
+| `habithive status` | Show the current mode and any queued switch |
+| `habithive --gateway <ip>` | Point OmniRoute at your team's gateway |
+| `hive spec init [path]` | Set up OpenSpec with the `intent-driven` schema in a project |
 
 Inside opencode:
 
-- `/habithive` — menu (set model · switch mode · reset)
-- `/model` — the model tree (below)
-- `/habithive-mode` — switch simple ⇄ complex (relaunches, same session)
+| Slash command | What it does |
+|---------------|--------------|
+| `/habithive` | Menu: model tree, switch mode, reset |
+| `/hive-models` (alias `/hivemodels`) | The model tree |
+| `/habithive-mode` | Switch simple or complex and reopen the same session |
+| `/models` | opencode's own model picker |
+| `/connect` | Add a provider key (OmniRoute, others) |
 
-The home screen shows a **HABITHIVE** wordmark, and the launcher prints a clean
-`▸ habithive` line on start and on exit (with the exact `habithive -c` / `habithive -s <id>`
-resume commands).
+## Guide
 
-## The model tree (`/model`)
+The guide lives in [docs/guide](docs/guide/README.md).
 
-```
-Quick
-  Main agent — this screen          → opencode's on-screen model (model.json)
-  ALL — on-screen + subagents+tiers
-Main agents (primary)               → also set the on-screen model
-  ★ All main agents (set together)
-  sisyphus · prometheus · atlas · hephaestus (GPT-only)
-Subagents                           → oh-my-openagent.json (own model each)
-  ★ All sub agents (set together)
-  oracle · explore · librarian · multimodal-looker · metis · momus · sisyphus-junior
-Categories (tiers)                  → oh-my-openagent.json
-  ultrabrain · deep · quick · visual-engineering · artistry · writing · unspecified-low · unspecified-high
-```
+1. [Getting started](docs/guide/01-getting-started.md): prerequisites, install, setup, first launch.
+2. [Modes](docs/guide/02-modes.md): simple and complex mode, switching.
+3. [Model tree](docs/guide/03-model-tree.md): setting models per agent and tier.
+4. [OmniRoute](docs/guide/04-omniroute.md): provider, gateway, key.
+5. [Spec workflow](docs/guide/05-spec-workflow.md): OpenSpec and the `intent-driven` schema.
+6. [Agents, skills and tools](docs/guide/06-agents-skills-tools.md): what is bundled.
+7. [Updates and versions](docs/guide/07-updates-and-versions.md): `habithive update`, pins.
+8. [Files and safety](docs/guide/08-files-and-safety.md): every file Hive touches, guarantees, uninstall.
+9. [Troubleshooting](docs/guide/09-troubleshooting.md): symptom, cause, fix.
 
-Precedence: **agent > category > all > default**. Each group has a **★ set-together**
-row. Changes to subagents/tiers live in `oh-my-openagent.json` and apply on the next
-launch (habithive reopens your session automatically after a change).
+## Compatibility
 
-## How it works
+Each release is tested against exactly one opencode and one oh-my-openagent version (defined in `src/versions.js`).
 
-- **Mode switch** toggles `oh-my-openagent` in your opencode config (keeping the habithive
-  plugin loaded in both modes) and relaunches opencode. A mode change can't be live —
-  oh-my-opencode initializes at startup — so habithive relaunches you into the **same session**.
-- **On-screen model** = opencode's picker state (`~/.local/state/opencode/model.json`).
-  **Subagent/category models** = `oh-my-openagent.json`. habithive writes the right layer for
-  each level of the tree.
-- Your original `oh-my-openagent.json` is snapshotted to `~/.habithive/baseline.json`
-  (with a byte-copy backup) so **Reset** restores it exactly.
+| Component | Tested version |
+|-----------|----------------|
+| opencode (`OPENCODE_PIN`) | **1.19.4** |
+| oh-my-openagent (`OMO_SPEC`) | **4.19.1** (5.x is not supported yet) |
 
-## Compatibility
+`habithive setup` installs opencode 1.19.4, or moves an existing install to it with `opencode upgrade 1.19.4`.
 
-Tested against: **opencode 1.18.x**, **oh-my-openagent 4.19.x** (pinned in the installer).
-opencode auto-updates its own binary; if a release changes internals, open an issue.
+Setup also writes `"autoupdate": false` into `opencode.jsonc` in both modes' config sets, so opencode does not update itself past the tested version. Versions move only when a Hive release does: run `habithive update`. If the running opencode is not the tested version, the launcher and the in-app plugin each show a one-line warning and carry on.
 
-## Migrating from the previous package name
+Hive needs OpenCode 1. OpenCode 2 has a new plugin format and oh-my-openagent's agents do not run on it. **Do not run `opencode upgrade --major`** (opencode 1.19 suggests it). If OpenCode 2 is installed, the launcher, `habithive status` and `habithive setup` say so and show how to go back; setup never runs `opencode upgrade` against it. Use the command for how you installed OpenCode 2:
 
-`habithive-code` is a rebrand of an earlier package that used a different name and
-plugin entry. `habithive setup` only manages its own plugin entry, so if the old
-package is still installed or wired into your opencode config, both load together
-and you'll see two wordmarks stacked on the home screen. Fix it once with:
+- npm: `npm rm -g @opencode/cli`, then `habithive setup`
+- Homebrew: `brew uninstall opencode-v2`, then `habithive setup`
+- curl installer: `curl -fsSL https://opencode.ai/install | bash -s -- --version 1.19.4`
 
-```sh
-npm rm -g maliv-code
-rm -rf ~/.maliv
-node -e "
-const fs=require('fs'), os=require('os'), path=require('path');
-const p=path.join(os.homedir(),'.config','opencode','tui.json');
-const c=JSON.parse(fs.readFileSync(p,'utf8'));
-c.plugin=(c.plugin||[]).filter(e=>!String(e).includes('maliv'));
-fs.writeFileSync(p, JSON.stringify(c,null,2)+'\n');
-console.log('cleaned:', p);
-"
-habithive setup
-```
-This is a one-time cleanup — anyone installing `habithive-code` fresh, who never had
-the old package, can skip this section entirely.
+Sessions created under OpenCode 2 may not open in OpenCode 1. Per-version findings are in [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
 
 ## Uninstall
 
+Switch to the mode whose config you want to keep first: deleting `~/.habithive` also deletes the other mode's stored config set.
+
 ```sh
-habithive simple           # (optional) drop back to vanilla first
+habithive complex      # switches back to complex mode; quit opencode when it opens
 npm rm -g habithive-code
+npm rm -g @fission-ai/openspec                         # optional
+rm -rf ~/.local/share/openspec/schemas/intent-driven   # optional
 rm -rf ~/.habithive
 ```
-Then remove the `habithive` / `oh-my-openagent` lines from `~/.config/opencode/tui.json`
-and `opencode.jsonc` if you want them gone.
+
+Then remove the Hive and oh-my-openagent entries from `~/.config/opencode/tui.json` and `opencode.jsonc`. Details: [Files and safety](docs/guide/08-files-and-safety.md#uninstall).
+
+## Patch notes
+
+See [CHANGELOG.md](CHANGELOG.md).
 
 ## Credits
 
-Built entirely on the work of others — habithive-code only orchestrates them:
+Hive only orchestrates the work of others:
+
+- [opencode](https://github.com/sst/opencode), the AI coding agent this runs on.
+- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) by code-yeongyu, the harness complex mode enables (Sustainable Use License 1.0).
 
-- **[opencode](https://github.com/sst/opencode)** — the AI coding agent this runs on.
-- **[oh-my-opencode / oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent)** by **code-yeongyu** — the agent harness that "complex" mode enables (Sustainable Use License 1.0).
+Bundled skills and their licenses: [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
 
 ## License
 
-habithive-code is [MIT](./LICENSE). opencode and oh-my-opencode remain under their own licenses.
+habithive-code is [MIT](LICENSE). opencode and oh-my-openagent remain under their own licenses.

package/bin/habithive.mjs

@@ -7,21 +7,32 @@
 //   habithive -s <id>        continue a specific session
 //   habithive new            fresh session (default)
 //   habithive setup          install opencode (if missing) + wire oh-my-opencode + habithive
+//   habithive update         install the latest release from npm + reconcile the machine to it
+//   habithive spec init [path]  scaffold OpenSpec (intent-driven) in a project
+//   habithive --gateway <ip>  point OmniRoute at your team's gateway (IP only)
 //   habithive status         show current mode + any queued in-app switch
+//   (hidden) habithive reconcile [--yes]   setup minus the mode change; update runs it
 //
 // Default is a fresh session. In-app /habithive-mode queues a switch + quits; this
 // loop relaunches in the queued mode with --continue (same session).
 
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { setMode, currentMode } from "../src/config.js";
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { currentMode, readMode, switchTo, recoverSwitch, isHabithive, PATHS } from "../src/config.js";
 import { readNextMode, readNextSession, clearNextMode } from "../src/core.js";
-import { runSetup } from "../src/setup.js";
+import { runSetup, reconcile } from "../src/setup.js";
+import { specInit } from "../src/spec.js";
+import { gatewayURL, setGateway } from "../src/omniroute.js";
+import { ConfigParseError } from "../src/jsonc.js";
+import { checkLatest, installedVersion } from "../src/update.js";
+import { NODE_MIN, OPENCODE_PIN, compareVersions, versionIn, isUnsupportedMajor, opencodeInstallMethod, v2Notice } from "../src/versions.js";
 
 const C = {
   reset: "\x1b[0m", dim: "\x1b[2m", bold: "\x1b[1m", cyan: "\x1b[36m",
   violet: "\x1b[38;2;124;58;237m", // #7c3aed
-  white: "\x1b[97m",
+  white: "\x1b[97m", yellow: "\x1b[33m", red: "\x1b[31m",
 };
 let VERSION = "0.1.0";
 try { VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version || VERSION; } catch {}
@@ -38,13 +49,46 @@ function help() {
     `habithive-code v${VERSION}\n\n` +
     `usage: habithive [simple|complex] [-c | -s <id>] [project]\n` +
     `       habithive setup     install opencode + oh-my-opencode + habithive\n` +
-    `       habithive status    show current mode\n\n` +
+    `       habithive update    install the latest release + re-apply its pins\n` +
+    `       habithive status    show current mode\n` +
+    `       habithive --gateway <ip>   point OmniRoute at your team's gateway (IP only)\n` +
+    `       hive spec init [path]   scaffold OpenSpec (intent-driven) in a project\n\n` +
+    `hive and habithive are the same command.\n` +
     `default: complex mode, new session. -c continue last, -s <id> continue specific.\n`,
   );
 }
 
 function runOpencode(args) {
-  return spawnSync("opencode", args, { stdio: "inherit", shell: process.platform === "win32" }).status ?? 0;
+  return spawnSync("opencode", args, { stdio: "inherit", shell: process.platform === "win32", env: { ...process.env, HABITHIVE_LAUNCHER: "1" } }).status ?? 0;
+}
+
+// Hint only: string-search the active tui.json (never parsed, never edited) for a
+// Hive plugin file:// URL whose target is gone (e.g. the global npm install moved).
+function staleHint() {
+  try {
+    for (const [u] of readFileSync(PATHS.TUI_JSON, "utf8").matchAll(/file:\/\/[^"'\s,\]]+/g)) {
+      if (!isHabithive(u) && !/habit-?hive/.test(u)) continue;
+      let p; try { p = fileURLToPath(u); } catch { continue; }
+      if (!existsSync(p)) { process.stdout.write(`${C.yellow}!${C.reset} habithive plugin path is stale — run: habithive setup\n`); return; }
+    }
+  } catch {}
+}
+
+const opencodeVersion = () => versionIn(spawnSync("opencode", ["--version"], { encoding: "utf8", shell: process.platform === "win32", timeout: 2000 }).stdout);
+
+// Hint only, once per process (2 s cap, never blocks): warn when opencode is not the tested version.
+// A different major (OpenCode 2, ADR-0010) gets the recovery notice instead; the launch continues.
+let drift = false;
+function driftHint() {
+  if (drift) return;
+  drift = true;
+  try {
+    const v = opencodeVersion();
+    if (isUnsupportedMajor(v)) {
+      const [head, ...steps] = v2Notice(v, opencodeInstallMethod()).split("\n");
+      process.stdout.write(`${C.red}! ${head}${C.reset}\n${steps.map((l) => `${C.dim}${l}${C.reset}`).join("\n")}\n`);
+    } else if (v && compareVersions(v, OPENCODE_PIN) !== 0) process.stdout.write(`${C.yellow}!${C.reset} opencode ${v} is not the tested ${OPENCODE_PIN} — run: habithive update\n`);
+  } catch {}
 }
 
 // Newest session id (the one just used) — `opencode session list` is newest-first.
@@ -56,14 +100,84 @@ function lastSessionId() {
   } catch { return null; }
 }
 
+const real = (p) => { try { return realpathSync(p); } catch { return null; } };
+const out = (m) => process.stdout.write(m + "\n");
+
+// habithive update: npm install of the latest release, then the NEW version's reconcile (so its pins apply).
+// A global install that links to a source checkout is never overwritten from npm.
+async function update() {
+  const win = process.platform === "win32";
+  const pkgRoot = real(fileURLToPath(new URL("..", import.meta.url)));
+  const g = spawnSync("npm", ["root", "-g"], { encoding: "utf8", shell: win });
+  const gRoot = g.status === 0 ? real(g.stdout.trim()) : null; // realpath of the dir, not of the package: a link stays a link
+  const globalPkg = gRoot && join(gRoot, "habithive-code");
+
+  if (pkgRoot !== globalPkg) {
+    out(`${C.yellow}!${C.reset} running from a source checkout: ${pkgRoot}\n  update it with: git -C ${pkgRoot} pull && habithive update`);
+    return reconcile({ yes: true });
+  }
+
+  const latest = await checkLatest(), installed = installedVersion();
+  let now = installed;
+  if (latest && compareVersions(latest, installed) > 0) {
+    out(`${C.cyan}▸${C.reset} updating habithive-code ${installed} → ${latest}…`);
+    if (spawnSync("npm", ["i", "-g", "habithive-code@latest"], { stdio: "inherit", shell: win }).status !== 0) {
+      out(`${C.red}✗ npm install failed — fix npm's global prefix permissions (see README) and retry${C.reset}`);
+      return 1;
+    }
+    try { now = JSON.parse(readFileSync(join(globalPkg, "package.json"), "utf8")).version || latest; } catch { now = latest; }
+  } else if (latest === null) out(`${C.yellow}!${C.reset} could not reach the npm registry — reconciling the installed version`);
+  else out(`${C.cyan}▸${C.reset} habithive-code ${installed} is the latest`);
+
+  const r = spawnSync(process.execPath, [join(globalPkg, "bin", "habithive.mjs"), "reconcile", "--yes"], { stdio: "inherit" });
+  if (r.status !== 0) return r.status ?? 1;
+  out(`\nrestart opencode to load habithive v${now}`);
+  return 0;
+}
+
 async function main() {
-  const argv = process.argv.slice(2);
+  if (compareVersions(process.versions.node, NODE_MIN) < 0) {
+    process.stderr.write(`habithive needs Node.js 20.19 or newer (running ${process.versions.node}) — upgrade, e.g. \`nvm install 22\`\n`);
+    process.exit(1);
+  }
+  let argv = process.argv.slice(2);
+  if (argv.some((a) => a === "--minimal" || a === "--min")) {
+    argv = argv.filter((a) => a !== "--minimal" && a !== "--min");
+    out("--minimal is no longer supported — installing everything");
+  }
+
+  // --gateway <ip>: enable OmniRoute on this machine, then exit (never launches opencode)
+  const gi = argv.indexOf("--gateway");
+  if (gi >= 0) {
+    const val = argv[gi + 1];
+    if (!val || val.startsWith("-")) { process.stderr.write("usage: habithive --gateway <ip>\n"); process.exit(1); }
+    const g = gatewayURL(val);
+    if (!g.ok) { process.stderr.write(`${g.error}\n`); process.exit(1); }
+    try {
+      const { files } = setGateway(g.url);
+      out(`OmniRoute enabled (${g.url}) — add your key with /connect`);
+      out(`${C.dim}${files.length ? `updated: ${files.join(", ")}` : "already set"}${C.reset}`);
+    } catch (e) {
+      if (!(e instanceof ConfigParseError)) throw e;
+      process.stderr.write(`cannot read ${e.file}:${e.line}:${e.column}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
 
   // subcommands
-  if (argv[0] === "setup") { process.exit(await runSetup({ yes: argv.includes("--yes") || argv.includes("-y"), minimal: argv.includes("--minimal") })); }
+  if (argv[0] === "setup") { process.exit(await runSetup({ yes: argv.includes("--yes") || argv.includes("-y") })); }
+  if (argv[0] === "reconcile") { process.exit(await reconcile({ yes: argv.includes("--yes") || argv.includes("-y") })); }
+  if (argv[0] === "spec") {
+    if (argv[1] === "init" && argv.length <= 3) process.exit(await specInit(argv[2] ? resolve(argv[2]) : process.cwd()));
+    out("usage: hive spec init [path]");
+    process.exit(1);
+  }
+  if (argv[0] === "update") { process.exit(await update()); }
   if (argv[0] === "status") {
     const q = readNextMode();
-    process.stdout.write(`habithive: ${currentMode()} mode${q ? ` · queued → ${q}` : ""}\n`);
+    process.stdout.write(`habithive: ${readMode() ?? currentMode()} mode${q ? ` · queued → ${q}` : ""}\n`);
+    try { const v = opencodeVersion(); if (isUnsupportedMajor(v)) out(`${C.red}!${C.reset} OpenCode ${v} is not supported — run habithive to see how to go back to OpenCode 1`); } catch {}
     process.exit(0);
   }
   if (argv.includes("-h") || argv.includes("--help")) { help(); process.exit(0); }
@@ -82,10 +196,18 @@ async function main() {
     else passthru.push(a);
   }
 
+  const rec = recoverSwitch(); // finish/roll back an interrupted mode switch
+  if (rec?.notice) process.stdout.write(`${C.dim}${rec.notice}${C.reset}\n`);
+  staleHint();
   clearNextMode();
   // relaunch loop: honor an in-app queued mode switch, preserving the session
   for (;;) {
-    setMode(mode);
+    if (mode !== currentMode()) { // a switch only renames files; a normal launch writes no config
+      const r = switchTo(mode);
+      r.notices.forEach((n) => process.stdout.write(`${C.dim}${n}${C.reset}\n`));
+      if (!r.ok) { process.stdout.write(`${C.yellow}habithive: ${r.error}${C.reset}\n`); mode = currentMode(); }
+    }
+    driftHint();
     banner(mode, contArgs.length > 0);
     runOpencode([...contArgs, ...passthru]);
     const next = readNextMode();