habithive-code 0.2.4 → 0.3.0

package/src/config.js

@@ -1,97 +1,243 @@
 // habithive-code — opencode config wiring + mode switching.
 //
-// Surgically toggles oh-my-opencode in the opencode config while ALWAYS keeping
-// the habithive plugin loaded, so /habithive-mode works in both modes:
+// One COMPLETE config file set per mode (ADR-0008). The active mode's files sit at
+// their normal paths in ~/.config/opencode; the inactive mode's files wait unchanged
+// in ~/.habithive/modes/<mode>/. A switch only RENAMES files (journaled), never edits
+// them. A missing set is created once from the active files; user config is never
+// rewritten on launch. Hive's own record (~/.habithive/mode) is the active mode.
 //   complex: oh-my-opencode ON  (opencode.jsonc + tui.json) + habithive (tui.json)
 //   simple : oh-my-opencode OFF                              + habithive (tui.json)
-// Preserves every other plugin/key. Atomic writes. Idempotent.
 //
 // We DEPEND on oh-my-opencode via npm (never bundle its code) and pin a tested
-// version. Bump OMO_SPEC in a new habithive-code release after re-testing.
+// version. Bump OMO_SPEC (src/versions.js) in a new habithive-code release after re-testing.
 
-import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import {
+  readFileSync, writeFileSync, existsSync, renameSync, mkdirSync, copyFileSync,
+  unlinkSync, rmSync, openSync, fsyncSync, closeSync,
+} from "node:fs";
+import { join, dirname, basename } from "node:path";
 import { homedir } from "node:os";
-import { fileURLToPath } from "node:url";
+import { readConfig, safeEdit, ConfigParseError } from "./jsonc.js";
+import { STORE_DIR } from "./core.js";
+import { OMO_SPEC } from "./versions.js";
 
-export const OMO_SPEC = "oh-my-openagent@4.19.1"; // pinned, tested version
+export { OMO_SPEC }; // pinned, tested version (defined in versions.js)
 export const CONFIG_DIR = join(homedir(), ".config", "opencode");
 const OPENCODE_JSONC = join(CONFIG_DIR, "opencode.jsonc");
 const OPENCODE_JSON = join(CONFIG_DIR, "opencode.json");
 const TUI_JSON = join(CONFIG_DIR, "tui.json");
+const SCHEMA = "https://opencode.ai/config.json";
+
+export const MODE_FILE = join(STORE_DIR, "mode");
+export const MODES_DIR = join(STORE_DIR, "modes");
+const FILES_FILE = join(MODES_DIR, "files.json");
+const JOURNAL = join(STORE_DIR, "switch.journal");
 
 // file:// URL to this package's plugin entry (works when installed globally or local).
 export const HABITHIVE_PLUGIN_URL = new URL("./plugin.js", import.meta.url).href;
 
-const isOmo = (e) => typeof e === "string" && /oh-my-open(agent|code)/.test(e);
-const isHabithive = (e) => typeof e === "string" && e.includes("habithive");
+// plugin entries are "name" or ["name", options]
+const nm = (e) => (Array.isArray(e) ? e[0] : e);
+export function isOmo(e) { return typeof nm(e) === "string" && /oh-my-open(agent|code)/.test(nm(e)); }
+export function isHabithive(e) { return typeof nm(e) === "string" && (/habit-?hive/.test(nm(e)) || nm(e) === HABITHIVE_PLUGIN_URL); }
 
-function readJson(path) {
-  try {
-    const raw = readFileSync(path, "utf8");
-    return JSON.parse(raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, ""));
-  } catch { return null; }
-}
-function writeAtomic(path, obj) {
-  mkdirSync(CONFIG_DIR, { recursive: true });
+const act = (f) => join(CONFIG_DIR, f);
+const stored = (mode, f) => join(modeDir(mode), f);
+const isMode = (m) => m === "simple" || m === "complex";
+const where = (r) => `${r.file}:${r.line}:${r.column} ${r.message}`;
+
+function put(path, text) { // atomic temp + rename
+  mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.tmp-${process.pid}`;
-  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  writeFileSync(tmp, text, "utf8");
   renameSync(tmp, path);
 }
-const dropOmo = (arr) => (arr || []).filter((e) => !isOmo(e));
-const dropHabithive = (arr) => (arr || []).filter((e) => !isHabithive(e));
-const ensure = (arr, v) => (arr.includes(v) ? arr : [...arr, v]);
-
-// mode: "simple" | "complex". Idempotent. Returns a short summary.
-export function setMode(mode) {
-  const complex = mode === "complex";
-
-  // server plugins (opencode.jsonc): toggle oh-my-opencode only (habithive is TUI-only)
-  {
-    const c = readJson(OPENCODE_JSONC) || { "$schema": "https://opencode.ai/config.json" };
-    let arr = dropOmo(Array.isArray(c.plugin) ? c.plugin : []);
-    if (complex) arr = ensure(arr, OMO_SPEC);
-    c.plugin = arr;
-    writeAtomic(OPENCODE_JSONC, c);
+
+// rename, falling back to copy + fsync + unlink across devices (EXDEV)
+export function moveFile(src, dst) {
+  mkdirSync(dirname(dst), { recursive: true });
+  try { renameSync(src, dst); } catch (e) {
+    if (e.code !== "EXDEV") throw e;
+    const tmp = `${dst}.tmp-${process.pid}`;
+    copyFileSync(src, tmp);
+    const fd = openSync(tmp, "r+");
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(tmp, dst);
+    unlinkSync(src);
+  }
+}
+
+export function modeDir(mode) { return join(MODES_DIR, mode); }
+
+// ---- mode record -----------------------------------------------------------
+
+export function readMode() {
+  try { const m = readFileSync(MODE_FILE, "utf8").trim(); return isMode(m) ? m : null; } catch { return null; }
+}
+export function writeMode(mode) {
+  if (!isMode(mode)) throw new Error(`unknown mode: ${mode}`);
+  put(MODE_FILE, mode + "\n");
+}
+
+// First run with no record: infer once (read-only on user config), then record it.
+export function adoptMode() {
+  let mode = "simple", warning;
+  for (const p of [OPENCODE_JSONC, OPENCODE_JSON, TUI_JSON]) {
+    const r = readConfig(p);
+    if (!r.ok) { mode = "complex"; warning = `cannot read config (${where(r)}); assuming complex mode`; break; }
+    if (Array.isArray(r.value?.plugin) && r.value.plugin.some(isOmo)) mode = "complex";
   }
-  // safety: keep opencode.json in sync only if it already declares plugins
-  if (existsSync(OPENCODE_JSON)) {
-    const c = readJson(OPENCODE_JSON);
-    if (c && Array.isArray(c.plugin)) {
-      let arr = dropOmo(c.plugin);
-      if (complex) arr = ensure(arr, OMO_SPEC);
-      c.plugin = arr;
-      writeAtomic(OPENCODE_JSON, c);
+  writeMode(mode);
+  return warning ? { mode, warning } : { mode };
+}
+
+export function currentMode() { return readMode() ?? adoptMode().mode; }
+
+// ---- per-mode file sets ----------------------------------------------------
+
+// basenames Hive swaps; opencode.json only when it lists oh-my-openagent.
+// Read-only: the list is persisted (once decided) by the first createModeSet.
+export function managedFiles() {
+  try {
+    const l = JSON.parse(readFileSync(FILES_FILE, "utf8"));
+    if (Array.isArray(l) && l.length && l.every((f) => typeof f === "string" && f === basename(f))) return l;
+  } catch { /* not decided yet */ }
+  const r = readConfig(OPENCODE_JSON);
+  const list = ["opencode.jsonc", "tui.json"];
+  // unparseable opencode.json counts as managed so createModeSet aborts naming it
+  if (r.exists && (!r.ok || (Array.isArray(r.value?.plugin) && r.value.plugin.some(isOmo)))) list.push("opencode.json");
+  return list;
+}
+
+export function hasModeSet(mode) { return managedFiles().every((f) => existsSync(stored(mode, f))); }
+
+// absolute paths of a mode's files: CONFIG_DIR if active, its store dir if stored, else null
+export function filesForMode(mode) {
+  if (currentMode() === mode) return managedFiles().map(act);
+  return hasModeSet(mode) ? managedFiles().map((f) => stored(mode, f)) : null;
+}
+
+// the target-mode variant of one active file (v = parsed value, null when missing)
+function variant(f, v, target) {
+  const c = structuredClone(v ?? (f === "opencode.jsonc" ? { $schema: SCHEMA } : {}));
+  const has = Array.isArray(c.plugin), complex = target === "complex";
+  const p = (has ? c.plugin : []).filter((e) => !isOmo(e));
+  if (f === "tui.json" && !p.some(isHabithive)) p.push(HABITHIVE_PLUGIN_URL);
+  if (complex && (has || f !== "opencode.json")) p.push(OMO_SPEC);
+  if (has || f === "tui.json" || (complex && f !== "opencode.json")) c.plugin = p;
+  return c;
+}
+
+// Create the target mode's file set once from the ACTIVE files. Never touches the active files.
+export function createModeSet(target) {
+  if (!isMode(target)) return { ok: false, error: `unknown mode: ${target}` };
+  if (readMode() === target) return { ok: false, error: `${target} mode is already active` };
+  if (hasModeSet(target)) return { ok: true };
+  const files = managedFiles(), out = {};
+  for (const f of files) {
+    const r = readConfig(act(f));
+    if (!r.ok) return { ok: false, error: where(r) };
+    if (r.exists && (r.value === null || typeof r.value !== "object" || Array.isArray(r.value)))
+      return { ok: false, error: `${act(f)}: expected a JSON object` };
+    out[f] = variant(f, r.value, target);
+  }
+  for (const [f, v] of Object.entries(out)) put(stored(target, f), JSON.stringify(v, null, 2) + "\n");
+  if (!existsSync(FILES_FILE)) put(FILES_FILE, JSON.stringify(files, null, 2) + "\n"); // decided
+  return { ok: true };
+}
+
+// ---- journaled rename-only switch ------------------------------------------
+// journal: { from, to, files, had }  (had = files present at the active path when the switch began)
+// per file: active -> stored(from), then stored(to) -> active. State is recovered from existence.
+
+function roll(j, forward) {
+  for (const f of j.files) {
+    const a = act(f), A = stored(j.from, f), B = stored(j.to, f);
+    if (forward) {
+      if (existsSync(B)) { if (j.had.includes(f) && existsSync(a)) moveFile(a, A); moveFile(B, a); }
+      else if (!existsSync(a)) throw new Error(`${f} is missing from both ${j.to} store and config dir`);
+    } else {
+      if (!existsSync(B) && existsSync(a)) moveFile(a, B); // undo store(to) -> active
+      if (j.had.includes(f) && !existsSync(a) && existsSync(A)) moveFile(A, a); // undo active -> store(from)
     }
   }
-  // tui plugins (tui.json): ALWAYS keep habithive; toggle oh-my-opencode
-  {
-    const c = readJson(TUI_JSON) || {};
-    let arr = dropHabithive(dropOmo(Array.isArray(c.plugin) ? c.plugin : []));
-    arr = ensure(arr, HABITHIVE_PLUGIN_URL);
-    if (complex) arr = ensure(arr, OMO_SPEC);
-    c.plugin = arr;
-    writeAtomic(TUI_JSON, c);
+}
+
+const validJournal = (j) => j && isMode(j.from) && isMode(j.to) && j.from !== j.to
+  && Array.isArray(j.files) && Array.isArray(j.had)
+  && j.files.every((f) => typeof f === "string" && f === basename(f)) && j.had.every((f) => j.files.includes(f));
+
+// Complete (or, if that fails, roll back) an interrupted switch. Call at the start of every launch.
+export function recoverSwitch() {
+  if (!existsSync(JOURNAL)) return { recovered: false };
+  let j;
+  try { j = JSON.parse(readFileSync(JOURNAL, "utf8")); } catch { j = null; }
+  if (!validJournal(j)) return { recovered: false, notice: `unreadable ${JOURNAL}; inspect ${MODES_DIR} and ${CONFIG_DIR}, then delete it` };
+  try {
+    roll(j, true);
+    writeMode(j.to);
+    rmSync(JOURNAL, { force: true });
+    return { recovered: true, notice: `completed interrupted switch to ${j.to} mode` };
+  } catch (e) {
+    try {
+      roll(j, false);
+      writeMode(j.from);
+      rmSync(JOURNAL, { force: true });
+      return { recovered: true, notice: `rolled back interrupted switch to ${j.to} mode (${e.message}); still ${j.from} mode` };
+    } catch (e2) {
+      return { recovered: false, notice: `could not recover interrupted switch (${e2.message}); see ${JOURNAL}` };
+    }
   }
-  return `config set to ${mode} mode`;
 }
 
-// Add an MCP server to the opencode config if not already present (in either
-// opencode.jsonc or opencode.json). Non-destructive; preserves other mcp entries.
-export function ensureMcp(name, spec) {
-  const inJson = (() => { const c = readJson(OPENCODE_JSON); return c && c.mcp && c.mcp[name]; })();
-  const c = readJson(OPENCODE_JSONC) || { "$schema": "https://opencode.ai/config.json" };
-  if ((c.mcp && c.mcp[name]) || inJson) return false; // already configured somewhere
-  c.mcp = { ...(c.mcp || {}), [name]: spec };
-  writeAtomic(OPENCODE_JSONC, c);
-  return true;
+// Switch to `mode` by renaming each mode's file set. Never edits file contents once both sets exist.
+export function switchTo(mode) {
+  if (!isMode(mode)) return { ok: false, notices: [], error: `unknown mode: ${mode}` };
+  const notices = [];
+  if (existsSync(JOURNAL)) {
+    const r = recoverSwitch();
+    if (r.notice) notices.push(r.notice);
+    if (existsSync(JOURNAL)) return { ok: false, notices, error: `interrupted switch not recovered (${JOURNAL})` };
+  }
+  const from = currentMode();
+  if (from === mode) return { ok: true, notices };
+  if (!hasModeSet(mode)) {
+    const r = createModeSet(mode);
+    if (!r.ok) return { ok: false, notices, error: r.error };
+  }
+  const files = managedFiles();
+  const j = { from, to: mode, files, had: files.filter((f) => existsSync(act(f))) };
+  put(JOURNAL, JSON.stringify(j));
+  try { roll(j, true); } catch (e) {
+    try { roll(j, false); rmSync(JOURNAL, { force: true }); } catch { /* journal stays for recoverSwitch */ }
+    return { ok: false, notices, error: `switch to ${mode} failed: ${e.message}` };
+  }
+  writeMode(mode);
+  rmSync(JOURNAL, { force: true });
+  notices.push(`each mode keeps its own config — changes made in ${from} mode are not in ${mode} mode`);
+  return { ok: true, notices };
 }
 
-// Is oh-my-opencode currently wired (i.e., are we in complex on disk)?
-export function currentMode() {
-  const c = readJson(OPENCODE_JSONC);
-  return c && Array.isArray(c.plugin) && c.plugin.some(isOmo) ? "complex" : "simple";
+// ---- explicit config edits (setup/update only; never called by a switch) ----
+
+// Add an MCP server if not already present (in the file or its sibling opencode.json).
+// Non-destructive; returns true if added. Throws ConfigParseError when a file is unreadable.
+export function ensureMcp(name, spec, file = PATHS.OPENCODE_JSONC) {
+  const sib = join(dirname(file), "opencode.json");
+  if (sib !== file) {
+    const r = readConfig(sib);
+    if (!r.ok) throw new ConfigParseError(r.file, r.line, r.column, r.message);
+    if (r.value?.mcp?.[name]) return false;
+  }
+  let added = false;
+  safeEdit(file, (c) => {
+    if (c.mcp?.[name]) return c;
+    if (!Object.keys(c).length) c.$schema = SCHEMA;
+    c.mcp = { ...(c.mcp || {}), [name]: spec };
+    added = true;
+    return c;
+  });
+  return added;
 }
 
 export const PATHS = { OPENCODE_JSONC, OPENCODE_JSON, TUI_JSON, CONFIG_DIR };
-export { fileURLToPath };

package/src/core.js

@@ -3,15 +3,18 @@
 // Owns:
 //   1. The model-tree store + resolver, compiled into oh-my-opencode's
 //      oh-my-openagent.json (subagent/category models). Applied on next launch.
-//   2. The on-screen (primary agent) model = opencode's picker state model.json.
+//   2. Helpers over opencode's picker state model.json (recent order) + the
+//      pending-apply marker that finishes a main-agent switch after relaunch.
 //   3. The mode marker used to hand an in-app simple/complex switch to the CLI.
 //
 // Model resolution tree (most specific wins):
 //   agent override  >  category override  >  "all" override  >  baseline
 
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, copyFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { parseJsonc } from "./jsonc.js";
 
 const HOME = homedir();
 export const CONFIG_DIR = join(HOME, ".config", "opencode");
@@ -20,10 +23,14 @@ export const STORE_DIR = join(HOME, ".habithive");
 export const STORE_FILE = join(STORE_DIR, "overrides.json");
 export const BASELINE_FILE = join(STORE_DIR, "baseline.json");
 export const OMO_BACKUP = join(STORE_DIR, "oh-my-openagent.first-backup.json");
+// sha256 of the oh-my-openagent.json text Hive last wrote (tells our writes from the user's/OMO's)
+export const LAST_APPLIED = join(STORE_DIR, "last-applied.sha256");
 export const MODE_MARKER = join(STORE_DIR, "next-mode");
 export const SESSION_MARKER = join(STORE_DIR, "next-session");
-// opencode's native model-picker state — recent[0] is the current on-screen model.
+// opencode's native model-picker state (recent / favorite / variant).
 export const MODEL_STATE = join(HOME, ".local", "state", "opencode", "model.json");
+export const PENDING_APPLY = join(STORE_DIR, "pending-apply.json");
+const PENDING_TTL = 10 * 60 * 1000;
 
 // Authoritative from oh-my-opencode's BuiltinCategoryNameSchema — 8 tiers.
 export const KNOWN_CATEGORIES = [
@@ -60,19 +67,23 @@ export function defaultStore() {
 function readJson(path, fallback) {
   try {
     if (!existsSync(path)) return fallback;
-    const raw = readFileSync(path, "utf8");
-    const stripped = raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
-    return JSON.parse(stripped);
+    const r = parseJsonc(readFileSync(path, "utf8")); // string-safe JSONC (globs/URLs intact)
+    return r.ok ? r.value : fallback;
   } catch { return fallback; }
 }
 
 function writeJsonAtomic(path, obj) {
-  mkdirSync(STORE_DIR, { recursive: true });
+  mkdirSync(dirname(path), { recursive: true });
+  const text = JSON.stringify(obj, null, 2) + "\n";
   const tmp = `${path}.tmp-${process.pid}-${globalThis.performance ? Math.floor(performance.now()) : "t"}`;
-  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  writeFileSync(tmp, text, "utf8");
   renameSync(tmp, path);
+  return text;
 }
 
+const sha = (t) => createHash("sha256").update(t).digest("hex");
+const hasContent = (o) => !!o && typeof o === "object" && Object.keys(o).some((k) => k !== "$schema");
+
 export function loadStore() {
   const s = readJson(STORE_FILE, null);
   if (!s) return defaultStore();
@@ -88,12 +99,20 @@ export function loadStore() {
 
 export function saveStore(store) { writeJsonAtomic(STORE_FILE, store); }
 
+// Snapshot oh-my-openagent.json once (Reset restores it). A missing file is a valid, EMPTY
+// baseline (fresh install: OMO only writes its config when the user does). An empty baseline is
+// re-captured once the file gains content Hive did not write (user/OMO edits), never from our own output.
 export function ensureBaseline() {
   mkdirSync(STORE_DIR, { recursive: true });
-  if (!existsSync(BASELINE_FILE)) {
-    const current = readJson(OMO_CONFIG, {});
+  const saved = existsSync(BASELINE_FILE) ? readJson(BASELINE_FILE, {}) : null;
+  if (saved && hasContent(saved)) return saved;
+  let raw = null;
+  try { raw = existsSync(OMO_CONFIG) ? readFileSync(OMO_CONFIG, "utf8") : null; } catch {}
+  const current = readJson(OMO_CONFIG, {});
+  const ours = raw != null && existsSync(LAST_APPLIED) && readFileSync(LAST_APPLIED, "utf8").trim() === sha(raw);
+  if (!saved || (hasContent(current) && !ours)) {
     writeJsonAtomic(BASELINE_FILE, current);
-    try { if (existsSync(OMO_CONFIG)) copyFileSync(OMO_CONFIG, OMO_BACKUP); } catch {}
+    try { if (raw != null) copyFileSync(OMO_CONFIG, OMO_BACKUP); } catch {}
   }
   return readJson(BASELINE_FILE, {});
 }
@@ -150,11 +169,9 @@ export function compileOmoConfig(store, baseline) {
 
 export function applyStore(store) {
   try {
-    const baseline = ensureBaseline();
-    if (!baseline || !baseline.agents || Object.keys(baseline.agents).length === 0) {
-      return { ok: false, error: "baseline not captured (oh-my-openagent.json empty/missing); refusing to write" };
-    }
-    writeJsonAtomic(OMO_CONFIG, compileOmoConfig(store, baseline));
+    const baseline = ensureBaseline(); // {} on a fresh install: write only the overrides
+    const text = writeJsonAtomic(OMO_CONFIG, compileOmoConfig(store, baseline));
+    writeFileSync(LAST_APPLIED, sha(text) + "\n", "utf8");
     return { ok: true };
   } catch (e) {
     return { ok: false, error: String(e?.message || e) };
@@ -184,7 +201,7 @@ export function effectiveModel(store, baseline, level, target) {
   return null;
 }
 
-// ---- on-screen (primary) model = model.json recent[0] --------------------
+// ---- model.json recent order + pending-apply marker -----------------------
 
 function splitModelId(idStr) {
   const i = String(idStr).indexOf("/");
@@ -192,33 +209,49 @@ function splitModelId(idStr) {
   return { providerID: idStr.slice(0, i), modelID: idStr.slice(i + 1) };
 }
 
-export function currentMainModel() {
+// Rewrite model.json `recent` so opencode's model.cycle_recent moves the agent from -> to.
+// from set: [from, to, ...rest]; else [to, ...rest]. favorite/variant untouched.
+export function arrangeRecent(from, to) {
   try {
-    const s = JSON.parse(readFileSync(MODEL_STATE, "utf8"));
-    const m = s?.recent?.[0];
-    return m ? `${m.providerID}/${m.modelID}` : null;
-  } catch { return null; }
-}
-
-export function setMainModel(idStr) {
-  try {
-    const parts = splitModelId(idStr);
-    if (!parts) return { ok: false, error: "bad model id (expected provider/model)" };
-    let state = {};
-    try { state = JSON.parse(readFileSync(MODEL_STATE, "utf8")); } catch {}
-    if (!Array.isArray(state.recent)) state.recent = [];
-    state.recent = state.recent.filter((m) => !(m.providerID === parts.providerID && m.modelID === parts.modelID));
-    state.recent.unshift(parts);
-    mkdirSync(join(HOME, ".local", "state", "opencode"), { recursive: true });
-    const tmp = `${MODEL_STATE}.tmp-${process.pid}`;
-    writeFileSync(tmp, JSON.stringify(state), "utf8");
-    renameSync(tmp, MODEL_STATE);
+    const t = splitModelId(to);
+    if (!t) return { ok: false, error: "bad model id (expected provider/model)" };
+    const f = from && from !== to ? splitModelId(from) : null;
+    if (from && from !== to && !f) return { ok: false, error: "bad model id (expected provider/model)" };
+    const state = readJson(MODEL_STATE, null);
+    const base = state && typeof state === "object" && !Array.isArray(state) ? state : {};
+    const same = (m, p) => m?.providerID === p.providerID && m?.modelID === p.modelID;
+    const rest = (Array.isArray(base.recent) ? base.recent : []).filter((m) => !same(m, t) && !(f && same(m, f)));
+    mkdirSync(dirname(MODEL_STATE), { recursive: true });
+    writeJsonAtomic(MODEL_STATE, { ...base, recent: f ? [f, t, ...rest] : [t, ...rest] });
     return { ok: true };
   } catch (e) {
     return { ok: false, error: String(e?.message || e) };
   }
 }
 
+export function writePendingApply({ sessionID, agent, from, to }, now = Date.now()) {
+  writeJsonAtomic(PENDING_APPLY, { sessionID, agent, from, to, createdAt: now });
+}
+export function readPendingApply(sessionID, now = Date.now()) {
+  const p = readJson(PENDING_APPLY, null);
+  if (!p || typeof p !== "object" || p.sessionID !== sessionID) return null;
+  return now - p.createdAt <= PENDING_TTL ? p : null;
+}
+export function clearPendingApply() {
+  try { rmSync(PENDING_APPLY, { force: true }); } catch {}
+}
+
+// Agents oh-my-openagent (4.19.1 hooks) reroutes for this model: Sisyphus on older GPTs
+// (gpt-5.4+/5.x-codex are accepted), Hephaestus on non-GPT models.
+export function revertedAgents(modelId, agentKeys, { allowNonGptHephaestus = false } = {}) {
+  const id = String(modelId).split("/").pop().toLowerCase();
+  const gpt = id.includes("gpt");
+  const out = [];
+  if (agentKeys.includes("sisyphus") && gpt && !/gpt-5[.-](?:(?:3[.-])?codex|[4-9]|\d{2,})/i.test(id)) out.push("sisyphus");
+  if (agentKeys.includes("hephaestus") && !gpt && !allowNonGptHephaestus) out.push("hephaestus");
+  return out;
+}
+
 // ---- mode marker (in-app switch handshake with the `habithive` launcher) ------
 
 export function writeNextMode(mode, session) {

package/src/jsonc.js

@@ -0,0 +1,128 @@
+// habithive-code — safe JSONC reader/editor (pure Node ESM, no deps).
+//
+// parseJsonc: comments + trailing commas stripped by a string-aware scanner that
+//   blanks them in place (offsets never shift), so errors map to the original text.
+// safeEdit: parse (abort on error) -> mutate a clone -> no-op if canonically equal
+//   -> timestamped backup -> temp file + rename. Keeps the newest `keep` backups.
+
+import { readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, readdirSync, rmSync, statSync, chmodSync, existsSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+
+export class ConfigParseError extends Error {
+  constructor(file, line, column, reason) {
+    super(`${file}:${line}:${column} ${reason}`);
+    this.name = "ConfigParseError";
+    Object.assign(this, { file, line, column, reason });
+  }
+}
+
+const BAK = ".habithive-bak-";
+
+function strip(text) {
+  const c = text.split(""), n = c.length;
+  const blank = (a, b) => { for (let k = a; k < b; k++) if (c[k] !== "\n" && c[k] !== "\r") c[k] = " "; };
+  let i = 0, comma = -1;
+  if (c[0] === "") c[i++] = " ";
+  while (i < n) {
+    const ch = c[i];
+    if (ch === '"') {
+      for (i++; i < n && c[i] !== '"'; i++) if (c[i] === "\\") i++;
+      i++; comma = -1;
+    } else if (ch === "/" && c[i + 1] === "/") {
+      let j = i; while (j < n && c[j] !== "\n" && c[j] !== "\r") j++;
+      blank(i, j); i = j;
+    } else if (ch === "/" && c[i + 1] === "*") {
+      const j = text.indexOf("*/", i + 2);
+      if (j < 0) return { at: i, why: "Unterminated block comment" };
+      blank(i, j + 2); i = j + 2;
+    } else {
+      if (ch === "}" || ch === "]") { if (comma >= 0) c[comma] = " "; comma = -1; }
+      else if (ch === ",") comma = i;
+      else if (!/\s/.test(ch)) comma = -1;
+      i++;
+    }
+  }
+  return { s: c.join("") };
+}
+
+const posOf = (m) => { const x = /position (\d+)/.exec(m); return x ? +x[1] : null; };
+const atEnd = (m) => /end of JSON input|EOF/i.test(m);
+
+// A prefix is "dead" once it fails for a reason other than running out of input.
+function dead(s, k) {
+  try { JSON.parse(s.slice(0, k)); return false; }
+  catch (e) { const p = posOf(e.message); return !(atEnd(e.message) || (p !== null && p >= k)); }
+}
+
+function errAt(s, msg) {
+  const p = posOf(msg), end = s.trimEnd().length;
+  if (p !== null) return Math.min(p, end);
+  if (atEnd(msg)) return end;
+  let lo = 1, hi = s.length;
+  while (lo < hi) { const mid = (lo + hi) >> 1; dead(s, mid) ? (hi = mid) : (lo = mid + 1); }
+  return lo - 1;
+}
+
+const where = (t, p) => { const a = t.slice(0, p).split("\n"); return { line: a.length, column: a[a.length - 1].length + 1 }; };
+
+export function parseJsonc(text) {
+  const r = strip(text);
+  if (r.why) return { ok: false, ...where(text, r.at), message: r.why };
+  try { return { ok: true, value: JSON.parse(r.s) }; }
+  catch (e) {
+    const message = e.message.replace(/, .* is not valid JSON$/s, "").replace(/( in JSON)? at position \d+( \(line \d+ column \d+\))?/, "");
+    return { ok: false, ...where(text, errAt(r.s, e.message)), message };
+  }
+}
+
+export function readConfig(path) {
+  let raw;
+  try { raw = readFileSync(path, "utf8"); }
+  catch (e) { if (e.code === "ENOENT") return { ok: true, exists: false, value: null, raw: null }; throw e; }
+  const r = parseJsonc(raw);
+  if (r.ok) return { ok: true, exists: true, value: r.value, raw };
+  return { ok: false, exists: true, raw, file: path, line: r.line, column: r.column, message: r.message };
+}
+
+const sortKeys = (v) => Array.isArray(v) ? v.map(sortKeys) : v && typeof v === "object"
+  ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])])) : v;
+const canon = (v) => JSON.stringify(sortKeys(v));
+
+const p2 = (n) => String(n).padStart(2, "0");
+const stamp = (d) => `${d.getFullYear()}${p2(d.getMonth() + 1)}${p2(d.getDate())}-${p2(d.getHours())}${p2(d.getMinutes())}${p2(d.getSeconds())}`;
+
+function prune(path, keep) {
+  const dir = dirname(path), pre = basename(path) + BAK;
+  const key = (f) => { const m = /^(\d{8}-\d{6})(?:-(\d+))?$/.exec(f.slice(pre.length)); return m && [m[1], +(m[2] || 1)]; };
+  const all = readdirSync(dir).filter((f) => f.startsWith(pre) && key(f))
+    .sort((a, b) => { const x = key(a), y = key(b); return x[0] < y[0] ? -1 : x[0] > y[0] ? 1 : x[1] - y[1]; });
+  for (const f of all.slice(0, Math.max(0, all.length - keep))) rmSync(join(dir, f), { force: true });
+}
+
+export function safeEdit(path, mutate, { now = new Date(), keep = 5, createIfMissing = true } = {}) {
+  const r = readConfig(path);
+  if (!r.ok) throw new ConfigParseError(r.file, r.line, r.column, r.message);
+  if (!r.exists && !createIfMissing) return { changed: false };
+  const before = r.exists ? r.value : {};
+  const clone = structuredClone(before);
+  const out = mutate(clone);
+  const next = out === undefined ? clone : out;
+  if (canon(before) === canon(next)) return { changed: false };
+  const res = { changed: true };
+  if (r.exists) {
+    const base = path + BAK + stamp(now);
+    let bak = base;
+    for (let n = 2; existsSync(bak); n++) bak = `${base}-${n}`;
+    copyFileSync(path, bak);
+    res.backup = bak;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
+    if (r.exists) chmodSync(tmp, statSync(path).mode & 0o777);
+    renameSync(tmp, path);
+  } catch (e) { rmSync(tmp, { force: true }); throw e; }
+  prune(path, keep);
+  return res;
+}