quoxcli 0.3.1 → 0.5.0

package/lib/quoxon/extensions.js

@@ -0,0 +1,636 @@
+/**
+ * Extension host (QUOXON, 2026-10-26; contract: EXTENSIONS.md). Optional npm packages that add surfaces to quoxon
+ * (a MIDI pad deck, a status bar, ...). Nothing loads unless the package is installed AND listed in
+ * ~/.quox/extensions.json (`quox ext add <pkg>`, `/ext list|on|off <name>`). Core knows nothing about any one extension:
+ * it pushes one generic snapshot (buildSnapshot) and accepts three emit actions (open_approval, pick, alert_ack).
+ * An extension can OPEN an approval or PRESELECT an answer; it can never resolve one.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+export const THROTTLE_MS = 1000;
+export const RELOAD_DEBOUNCE_MS = 2000; // fs.watch burst -> one check
+export const HEARTBEAT_MS = 15000;      // contract v1 F3: a push this often while any extension is loaded
+export const STALE_MS = 60000;          // state.stale once the last good server read is older than this
+export const CLOSE_TIMEOUT_MS = 500;    // F7: close() is awaited this long, then the instance is dropped
+export const PANEL_SLOW_MS = 50;        // F1: a render slower than this is an error
+export const PANEL_RETRY_MS = 5000;     // F1: a failed panel is not rendered again for this long
+export const INVALIDATE_MS = 250;       // F1: invalidate() is throttled to 4 per second
+export const RELOAD_POLL_MS = 30000;    // stat poll fallback: global installs replace directories, which kills file watches
+export const notInstalled = (name) => `not installed: npm i -g ${name}`;
+const HEALTH = new Set(['ok', 'warn', 'down']);
+const CHAIN = new Set(['ok', 'broken', 'unknown']);
+const FLEET_MAX = 16;
+
+// ---- the listing: ~/.quox/extensions.json ---------------------------------------------------------------------------
+export const extListPath = (home) => (home === undefined && process.env.QUOX_EXT_LIST) || path.join(home ?? os.homedir(), '.quox', 'extensions.json'); // QUOX_EXT_LIST overrides the default location
+const validName = (n) => typeof n === 'string' && /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(n);
+
+export function readExtList(file = extListPath()) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return (Array.isArray(j?.extensions) ? j.extensions : []).filter((x) => validName(x?.name)).map((x) => ({ name: x.name, enabled: x.enabled !== false, ...(x.settings && typeof x.settings === 'object' && !Array.isArray(x.settings) ? { settings: x.settings } : {}) }));
+  } catch { return []; } // no file or unreadable: nothing is listed, so nothing loads
+}
+export function writeExtList(list, file = extListPath()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ extensions: list }, null, 2) + '\n');
+}
+export function extAdd(name, file = extListPath()) {
+  if (!validName(name)) return { ok: false, text: `"${name}" is not a package name.` };
+  const list = readExtList(file);
+  const had = list.find((x) => x.name === name);
+  if (had) had.enabled = true; else list.push({ name, enabled: true });
+  writeExtList(list, file);
+  return { ok: true, text: `${name} is listed. It loads in quoxon once installed (npm i -g ${name}).` };
+}
+export function extRemove(name, file = extListPath()) {
+  const list = readExtList(file);
+  if (!list.some((x) => x.name === name)) return { ok: false, text: `${name} is not listed.` };
+  writeExtList(list.filter((x) => x.name !== name), file);
+  return { ok: true, text: `${name} is no longer listed.` };
+}
+export function extSetEnabled(name, enabled, file = extListPath()) {
+  const list = readExtList(file);
+  const it = list.find((x) => x.name === name);
+  if (!it) return { ok: false, text: `${name} is not listed. quox ext add ${name}` };
+  it.enabled = enabled; writeExtList(list, file);
+  return { ok: true, text: `${name} ${enabled ? 'enabled' : 'disabled'}.` };
+}
+
+// ---- settings (contract v1): typed, stored on the listing entry ------------------------------------------------------
+const SETTING_TYPES = new Set(['string', 'number', 'bool', 'enum']);
+/** Declared settings -> clean defs. Bad entries (no key, unknown type, enum without choices) are dropped. */
+export function normalizeSettingDefs(arr) {
+  const out = [];
+  for (const d of Array.isArray(arr) ? arr : []) {
+    if (!d || typeof d.key !== 'string' || !/^[A-Za-z_][\w.-]*$/.test(d.key) || !SETTING_TYPES.has(d.type)) continue;
+    if (d.type === 'enum' && !(Array.isArray(d.choices) && d.choices.length)) continue;
+    out.push({ key: d.key, type: d.type, default: d.default, help: String(d.help || ''), ...(d.type === 'enum' ? { choices: d.choices.map(String) } : {}) });
+  }
+  return out;
+}
+/** A typed value from raw text (or an already-typed value). -> { ok:true, value } | { ok:false, error } */
+export function coerceSetting(def, raw) {
+  const t = typeof raw === 'string' ? raw.trim() : raw;
+  if (def.type === 'string') return typeof raw === 'string' ? { ok: true, value: raw } : { ok: false, error: `${def.key} is a string.` };
+  if (def.type === 'number') {
+    const n = typeof t === 'number' ? t : (t === '' || t == null ? NaN : Number(t));
+    return Number.isFinite(n) ? { ok: true, value: n } : { ok: false, error: `${def.key} must be a number (got "${raw}").` };
+  }
+  if (def.type === 'bool') {
+    if (typeof t === 'boolean') return { ok: true, value: t };
+    if (/^(true|on|yes|1)$/i.test(String(t))) return { ok: true, value: true };
+    if (/^(false|off|no|0)$/i.test(String(t))) return { ok: true, value: false };
+    return { ok: false, error: `${def.key} must be true or false (got "${raw}").` };
+  }
+  return typeof raw === 'string' && def.choices.includes(raw) ? { ok: true, value: raw } : { ok: false, error: `${def.key} must be one of: ${def.choices.join(', ')} (got "${raw}").` };
+}
+/** Defaults overlaid with stored values; a stored value that no longer validates falls back to the default. */
+export function resolveSettings(defs, stored = {}) {
+  const out = {};
+  for (const d of defs) {
+    const c = stored && Object.hasOwn(stored, d.key) ? coerceSetting(d, stored[d.key]) : { ok: false };
+    out[d.key] = c.ok ? c.value : d.default;
+  }
+  return out;
+}
+export function readExtSettings(name, file = extListPath()) { return readExtList(file).find((x) => x.name === name)?.settings || {}; }
+export function extStoreSetting(name, key, value, file = extListPath()) {
+  const list = readExtList(file);
+  const it = list.find((x) => x.name === name);
+  if (!it) return { ok: false, text: `${name} is not listed. quox ext add ${name}` };
+  it.settings = { ...(it.settings || {}), [key]: value };
+  writeExtList(list, file);
+  return { ok: true };
+}
+
+// ---- resolution: env override, local, global ------------------------------------------------------------------------
+export const envKey = (name) => `QUOX_EXT_${String(name).replace(/^@/, '').replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}_MODULE`;
+const defaultImporter = (spec) => import(spec);
+const NOT_FOUND = (e) => e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND';
+
+let npmRootCache; // `npm root -g` runs at most once per process
+export function globalNpmRoot(run = execFileSync) {
+  if (npmRootCache !== undefined) return npmRootCache;
+  try { npmRootCache = String(run('npm', ['root', '-g'], { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] })).trim() || null; } catch { npmRootCache = null; }
+  return npmRootCache;
+}
+export const _resetNpmRootCache = () => { npmRootCache = undefined; };
+
+/** The file a package directory imports: exports["."] (import/default), module, main, index.js. */
+export function packageEntry(dir) {
+  try {
+    const pj = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const ex = pj.exports;
+    const root = typeof ex === 'string' ? ex : (ex?.['.'] ?? ex);
+    const pick = typeof root === 'string' ? root : (root?.import || root?.default || (typeof root?.import === 'object' ? root.import.default : null));
+    return path.join(dir, pick || pj.module || pj.main || 'index.js');
+  } catch { return path.join(dir, 'index.js'); }
+}
+
+/** The entry file a bare specifier resolves to from here, or null (the importer may be a test double). */
+function localEntry(name) {
+  try { const u = import.meta.resolve(name); return u.startsWith('file:') ? fileURLToPath(u) : null; } catch { return null; }
+}
+/** Nearest package.json at or above an entry file, or null. */
+export function findPackageJson(entry) {
+  if (!entry) return null;
+  let dir = path.dirname(entry);
+  for (let i = 0; i < 8; i++) {
+    const f = path.join(dir, 'package.json');
+    if (fs.existsSync(f)) return f;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/**
+ * Find and import one extension. Order: QUOX_EXT_<NAME>_MODULE, local import(name), then the global npm root
+ * (dirname(execPath)/../lib/node_modules first, which costs no spawn; `npm root -g` once, cached, only if that misses).
+ * -> { ok:true, mod, where } | { ok:false, notFound:true, tried:[...] } | { ok:false, error }
+ */
+export async function resolveExtension(name, { env = process.env, importer = defaultImporter, execPath = process.execPath, npmRoot = globalNpmRoot, exists = fs.existsSync } = {}) {
+  const tried = [];
+  const ov = env?.[envKey(name)];
+  if (ov) {
+    tried.push(`${envKey(name)}=${ov}`);
+    try { return { ok: true, mod: await importer(path.isAbsolute(ov) ? pathToFileURL(ov).href : ov), where: `env ${envKey(name)} (${ov})`, entry: path.isAbsolute(ov) ? ov : null }; }
+    catch (e) { return { ok: false, error: e?.message || String(e), tried }; } // an override that fails is an error, never a silent fall-through
+  }
+  tried.push(`local import('${name}')`);
+  try { return { ok: true, mod: await importer(name), where: `local (${name})`, entry: localEntry(name) }; }
+  catch (e) { if (!NOT_FOUND(e)) return { ok: false, error: e?.message || String(e), tried }; }
+  const roots = [];
+  const guess = path.join(path.dirname(execPath || ''), '..', 'lib', 'node_modules');
+  roots.push(guess);
+  let spawned = false;
+  for (let i = 0; i < 2; i++) {
+    for (const root of roots.splice(0)) {
+      const dir = path.join(root, name);
+      tried.push(`global ${dir}`);
+      if (!exists(dir)) continue;
+      try { return { ok: true, mod: await importer(pathToFileURL(packageEntry(dir)).href), where: `global (${dir})`, entry: packageEntry(dir) }; }
+      catch (e) { return { ok: false, error: e?.message || String(e), tried }; }
+    }
+    if (spawned) break;
+    spawned = true;
+    const g = npmRoot();
+    if (g && path.resolve(g) !== path.resolve(guess)) roots.push(g);
+  }
+  return { ok: false, notFound: true, tried };
+}
+
+export const CONTRACT_VERSION = 1; // the highest extension contract this host supports (EXTENSIONS.md)
+/** "a b  c" -> ['a','b','c']; arrays pass through. */
+export const splitArgs = (a) => (Array.isArray(a) ? a.map(String) : String(a ?? '').split(/\s+/).filter(Boolean));
+
+/** An extension module -> { name, version, contractVersion, commands, settings, create } or null. Accepts default export or the module itself. */
+export function normalizeExtension(mod, fallbackName) {
+  const ext = mod?.default && typeof mod.default === 'object' ? mod.default : mod;
+  const create = typeof ext?.create === 'function' ? ext.create : (typeof mod?.createDeck === 'function' ? mod.createDeck : null); // createDeck: quoxdeck v1
+  if (!create) return null;
+  const commands = (Array.isArray(ext.commands) ? ext.commands : []).filter((c) => /^\/[a-z][\w-]*$/i.test(c?.name || '') && typeof c.run === 'function')
+    .map((c) => ({ ...c, subcommands: (Array.isArray(c.subcommands) ? c.subcommands : []).filter((x) => typeof x?.name === 'string' && x.name).map((x) => ({ name: x.name, help: String(x.help || '') })) }));
+  const cv = ext.contractVersion;
+  return { name: ext.name || fallbackName, version: ext.version || null, contractVersion: cv === undefined ? null : cv, commands, settings: normalizeSettingDefs(ext.settings), create };
+}
+/** null = supported; otherwise the refusal line shown in /ext list. */
+export function contractRefusal(ext) {
+  const cv = ext.contractVersion;
+  if (cv == null) return null; // legacy: no contract declared
+  if (!Number.isInteger(cv) || cv < 1) return `invalid contractVersion ${JSON.stringify(cv)} (must be an integer, 1 or more)`;
+  return cv > CONTRACT_VERSION ? `needs extension contract v${cv}, this quoxon supports v${CONTRACT_VERSION}` : null;
+}
+
+// ---- the snapshot every extension gets ------------------------------------------------------------------------------
+function itemRisk(it) {
+  return it?.privileged === true || it?.payload?.privileged === true || it?.risk === 'high' || it?.payload?.risk === 'high' ? 'high' : 'low';
+}
+const hostState = (s) => (s === 'ok' || s === 'warn' || s === 'down' ? s : (/^(down|offline|failed|unreachable)$/i.test(s || '') ? 'down' : (/^(warn|warning|degraded)$/i.test(s || '') ? 'warn' : 'ok')));
+
+/** Pure. fleet input: [{id|name, health|state}] or null. */
+export function buildFleet(hosts) {
+  if (!Array.isArray(hosts)) return { total: 0, online: 0, offline: 0, warn: 0, hosts: [] };
+  const list = hosts.map((h) => ({ name: String(h.name ?? h.id ?? '').slice(0, 60), state: hostState(h.state ?? h.health) }));
+  return {
+    total: list.length, online: list.filter((h) => h.state !== 'down').length,
+    offline: list.filter((h) => h.state === 'down').length, warn: list.filter((h) => h.state === 'warn').length,
+    hosts: list.slice(0, FLEET_MAX)
+  };
+}
+
+export function buildSnapshot({ org = null, items = [], health = {}, loops = [], event = null, fleet = null, evidence = null, sessions = null, at = null, stale = false } = {}) {
+  const list = (items || []).map((it, i) => {
+    const row = {
+      n: i + 1, id: it.id ?? null, risk: itemRisk(it),
+      title: String(it.title || it.summary || it.payload?.title || it.payload?.question || it.payload?.summary || '').slice(0, 120),
+      agent: it.agent || it.requester || it.payload?.agent || null
+    };
+    const opts = Array.isArray(it.payload?.options) ? it.payload.options.filter((o) => o?.key != null).map((o) => ({ key: String(o.key), label: String(o.label ?? o.key) })) : [];
+    if (opts.length) row.options = opts;
+    return row;
+  });
+  const h = {};
+  for (const [k, v] of Object.entries(health || {})) if (HEALTH.has(v)) h[k] = v;
+  const state = {
+    ...(at ? { at } : {}),
+    ...(stale ? { stale: true } : {}),
+    org: { id: org?.id ?? null, name: org?.name ?? null },
+    approvals: { count: list.length, items: list },
+    health: h,
+    loops: (loops || []).map((l) => ({ id: l.id, title: String(l.title || ''), turn: Number(l.turn) || 0, max: Number(l.max) || 0, status: l.status || 'running' })),
+    fleet: Array.isArray(fleet) ? buildFleet(fleet) : (fleet && typeof fleet === 'object' ? { total: fleet.total | 0, online: fleet.online | 0, offline: fleet.offline | 0, warn: fleet.warn | 0, hosts: (fleet.hosts || []).slice(0, FLEET_MAX) } : buildFleet(null)),
+    evidence: { chain: CHAIN.has(evidence?.chain) ? evidence.chain : 'unknown', checked_at: evidence?.checked_at ?? null },
+    sessions: { active: Math.max(0, Number(sessions?.active) || 0) }
+  };
+  if (event) state.event = { ...(event.seq != null ? { seq: event.seq } : {}), ...(event.id != null ? { id: String(event.id) } : {}), kind: event.kind, text: event.text, level: event.level || 'info' };
+  return state;
+}
+
+/** What the composer is filled with when an extension picks an option; the user still presses Enter. null = nothing to preselect. */
+export function pickDraft(item, n, option) {
+  if (!item) return null;
+  const opt = String(option ?? '').trim();
+  if (!opt) return null;
+  const keys = (item.payload?.options || []).map((o) => String(o.key));
+  if (keys.length) return keys.includes(opt) ? `/answer ${n} ${opt}` : null;
+  if (/^(y|yes|approve)$/i.test(opt)) return `/approve ${n}`;
+  if (/^(n|no|deny)$/i.test(opt)) return `/deny ${n} `;
+  return null;
+}
+
+// ---- panels: pure helpers --------------------------------------------------------------------------------------------
+const ANSI = /^\x1b\[[0-9;?]*[ -/]*[@-~]/;
+/** Clip one line to `width` visible columns, keeping escape sequences (they take no width). Closes colour if it cut. */
+export function clipLine(line, width) {
+  const str = String(line ?? '').replace(/[\r\n]+/g, ' ');
+  let out = ''; let w = 0; let sawEsc = false;
+  for (let i = 0; i < str.length;) {
+    const m = str[i] === '\x1b' ? ANSI.exec(str.slice(i, i + 32)) : null;
+    if (m) { out += m[0]; i += m[0].length; sawEsc = true; continue; }
+    const cp = String.fromCodePoint(str.codePointAt(i));
+    if (w + 1 > width) return out + (sawEsc ? '\x1b[0m' : '');
+    out += cp; w += 1; i += cp.length;
+  }
+  return out;
+}
+/** What the panel region shows for a render result: an array of strings, at most `height` lines of `width` columns. */
+export function clipPanel(lines, width, height) {
+  const arr = Array.isArray(lines) ? lines : [];
+  return arr.slice(0, Math.max(0, height)).map((l) => clipLine(l, Math.max(0, width)));
+}
+/** Panel region height: min(12, 40% of the terminal rows), at least 1. */
+export const panelHeight = (rows) => Math.max(1, Math.min(12, Math.floor((Number(rows) || 24) * 0.4)));
+/** A keys.js event, or one typed character, as the name a panel's onKey receives (EXTENSIONS.md). null = nothing to deliver. */
+export function panelKeyName(e) {
+  if (typeof e === 'string') return e === ' ' ? 'space' : e;
+  if (e?.type === 'text') return e.text === ' ' ? 'space' : e.text;
+  if (e?.type !== 'key') return null;
+  const n = String(e.name);
+  const m = /^(ctrl|alt)-(.)$/.exec(n);
+  if (m) return `${m[1]}+${m[2]}`;
+  return n === 'newline' ? 'enter' : n;
+}
+const isoOf = (ms) => new Date(ms).toISOString();
+
+// ---- the host -------------------------------------------------------------------------------------------------------
+/**
+ * handlers: { openApproval(n, id), preselect(n, option, id), changed(), note(text, tone) } are the window's own actions;
+ * openApproval/preselect returning exactly false means "that id is not there", and the emit is refused.
+ * getSettings() feeds create() for extensions that declare no settings (legacy). listFile is where per-extension settings live.
+ * Loaded extensions all receive the same deduped, 1/s-throttled snapshot, plus a heartbeat every 15 s.
+ */
+export function createExtensionHost({ importer = defaultImporter, env = process.env, execPath, npmRoot, exists, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout,
+  handlers = {}, log = () => {}, getSettings = () => ({}), listFile = undefined, perf = () => performance.now(),
+  watch = (f, cb) => fs.watch(f, { persistent: false }, cb), statFn = (f) => fs.statSync(f), readText = (f) => fs.readFileSync(f, 'utf8'),
+  setPoll = setInterval, clearPoll = clearInterval } = {}) {
+  const loaded = new Map(); // name -> { ext, inst, where, entry, settings }
+  const watches = new Map(); // name -> { pkgPath, entry, sig, version, watcher, debounce, poll, busy }
+  const failed = new Map(); // name -> error text, for /ext list
+  let lastInput = null;
+  const starting = new Map();
+  let lastSent = 0; let lastKey = null; let pending = null; let timer = null;
+  let event = null; let eventSig = null; const prevLoops = new Map(); let prevCount = null; let seq = 0;
+  let beat = null;
+  const closedInsts = new WeakSet(); const closings = new Set();
+  const panelErr = new Map(); // name -> retry-after ms
+  let focus = null; let shown = null; // panel name with the keys / panel name that is open
+  let invTimer = null; let lastInv = 0;
+  /** A new event gets the next seq only when kind, text, level or id differ from the one held; a repeat keeps its seq until alert_ack. */
+  const raise = (ev) => {
+    const sig = [ev.kind, ev.text, ev.level, ev.id ?? ''].join('\u0000');
+    if (event && eventSig === sig) return;
+    event = { seq: ++seq, ...ev }; eventSig = sig;
+  };
+  const listArg = () => (listFile ? [listFile] : []);
+
+  const stale = () => lastInput?.readOkAt != null && now() - Number(lastInput.readOkAt) > STALE_MS;
+  const snap = () => buildSnapshot({ ...lastInput, event, at: isoOf(now()), stale: stale() });
+  const dedupeKey = (state) => JSON.stringify({ ...state, at: undefined });
+  const sendAll = (state, force = false) => {
+    const key = dedupeKey(state);
+    if (!force && key === lastKey) return;
+    lastKey = key; lastSent = now();
+    for (const [name, l] of loaded) { try { l.inst?.update?.(state); } catch (e) { log(`extension ${name} update failed: ${e?.message || e}`); } }
+    if (panelNames().length) handlers.changed?.(); // panels re-render on every push
+  };
+  const flush = () => { timer = null; if (pending && loaded.size) { const s = pending; pending = null; sendAll(s); } };
+  const startBeat = () => {
+    if (beat || !loaded.size) return;
+    beat = setPoll(() => { if (!loaded.size || !lastInput) return; pending = null; sendAll(snap(), true); }, HEARTBEAT_MS);
+    beat?.unref?.();
+  };
+  const stopBeat = () => { if (beat) { clearPoll(beat); beat = null; } };
+
+  // ---- close: async-tolerant, 500 ms cap, at most once per instance --------------------------------------------------
+  /** Calls close() now (synchronously), then waits up to 500 ms for a returned promise. Never throws. */
+  function closeInst(name, inst) {
+    if (!inst || closedInsts.has(inst)) return Promise.resolve();
+    closedInsts.add(inst);
+    let r;
+    try { r = inst.close?.(); } catch (e) { log(`extension ${name} close failed: ${e?.message || e}`); return Promise.resolve(); }
+    if (!r || typeof r.then !== 'function') return Promise.resolve();
+    let to;
+    const timeout = new Promise((res) => { to = setTimer(() => res('timeout'), CLOSE_TIMEOUT_MS); });
+    const p = Promise.race([r.then(() => 'done', (e) => { log(`extension ${name} close failed: ${e?.message || e}`); return 'error'; }), timeout])
+      .then((v) => { if (v === 'timeout') log(`extension ${name} close() did not finish in ${CLOSE_TIMEOUT_MS}ms; dropped`); })
+      .finally(() => { clearTimer(to); closings.delete(p); });
+    closings.add(p);
+    return p;
+  }
+
+  // ---- panels ------------------------------------------------------------------------------------------------------
+  const panelOf = (name) => { const p = loaded.get(name)?.inst?.panel; return p && typeof p.render === 'function' ? p : null; };
+  function panelNames() { return [...loaded.keys()].filter((n) => panelOf(n)); }
+  const safe = (name, what, fn) => { try { return fn(); } catch (e) { log(`extension ${name} panel ${what} failed: ${e?.message || e}`); return undefined; } };
+  const invalidateFor = (name) => () => {
+    if (!loaded.has(name) && !starting.has(name)) return;
+    const wait = INVALIDATE_MS - (now() - lastInv);
+    if (wait <= 0 && !invTimer) { lastInv = now(); handlers.changed?.(); return; }
+    if (!invTimer) invTimer = setTimer(() => { invTimer = null; lastInv = now(); handlers.changed?.(); }, Math.max(wait, 0));
+  };
+  const dropPanelState = (name) => { panelErr.delete(name); if (focus === name) focus = null; if (shown === name) shown = null; };
+
+  // ---- emit: by stable id (contract v1) ----------------------------------------------------------------------------
+  const emitFor = (name) => (msg) => {
+    if (!loaded.has(name) || !msg || typeof msg !== 'object') return false; // ignored unless this extension is loaded
+    const result = (ok, reason) => { try { loaded.get(name)?.inst?.onEmitResult?.({ ok, ...(reason ? { reason } : {}), msg }); } catch (e) { log(`extension ${name} onEmitResult failed: ${e?.message || e}`); } return ok; };
+    try {
+      if (msg.type === 'alert_ack') { event = null; eventSig = null; handlers.changed?.(); return result(true); }
+      if (msg.type !== 'open_approval' && msg.type !== 'pick') return false;
+      let n = null;
+      if (msg.id != null && msg.id !== '') {
+        const idx = (lastInput?.items || []).findIndex((it) => it?.id != null && String(it.id) === String(msg.id));
+        if (idx < 0) return result(false, 'unknown or already resolved id');
+        n = idx + 1;
+        if (Number.isInteger(msg.n) && msg.n !== n) log(`extension ${name}: emit n=${msg.n} disagrees with id ${msg.id} (now [${n}]); id wins`);
+      } else if (loaded.get(name).ext.contractVersion == null && Number.isInteger(msg.n) && msg.n >= 1) {
+        n = msg.n; // legacy (no contractVersion) extensions may still address by n
+      } else return result(false, 'id is required');
+      const id = msg.id != null && msg.id !== '' ? String(msg.id) : undefined;
+      const r = msg.type === 'open_approval' ? handlers.openApproval?.(n, id) : handlers.preselect?.(n, msg.option, id);
+      return r === false ? result(false, 'unknown or already resolved id') : result(true);
+    } catch (e) { log(`extension ${name} emit failed: ${e?.message || e}`); }
+    return false;
+  };
+
+  const settingsFor = (ext, name) => {
+    if (!ext.settings.length) return getSettings(); // legacy: an extension that declares none gets the window settings
+    return resolveSettings(ext.settings, readExtSettings(name, ...listArg()));
+  };
+  const makeInst = (name, ext, settings) => ext.create({ emit: emitFor(name), log, settings, invalidate: invalidateFor(name) });
+
+  // ---- hot reload: a loaded extension's package.json changes on disk -> close, re-import (cache-busted), create again ----
+  const sigOf = (pkgPath) => {
+    let version = null; let mtime = 0;
+    try { version = JSON.parse(readText(pkgPath)).version ?? null; } catch { /* unreadable mid-install: treated as no version */ }
+    try { mtime = Math.floor(statFn(pkgPath).mtimeMs); } catch { return null; } // gone mid-install: wait for the next check
+    return { version, mtime, key: `${version}|${mtime}` };
+  };
+  const stopWatch = (name) => {
+    const w = watches.get(name); if (!w) return;
+    watches.delete(name);
+    if (w.debounce) clearTimer(w.debounce);
+    if (w.poll) clearPoll(w.poll);
+    try { w.watcher?.close?.(); } catch { /* already closed */ }
+  };
+  const openWatcher = (name, w) => {
+    try {
+      w.watcher = watch(w.pkgPath, () => { if (w.debounce) clearTimer(w.debounce); w.debounce = setTimer(() => { w.debounce = null; check(name); }, RELOAD_DEBOUNCE_MS); });
+      w.watcher?.on?.('error', () => { try { w.watcher?.close?.(); } catch { /* ignore */ } w.watcher = null; }); // the poll re-arms it
+    } catch { w.watcher = null; }
+  };
+  const startWatch = (name, entry) => {
+    stopWatch(name);
+    const pkgPath = findPackageJson(entry); if (!pkgPath) return;
+    const s = sigOf(pkgPath); if (!s) return;
+    const w = { pkgPath, entry, sig: s.key, version: s.version, watcher: null, debounce: null, poll: null, busy: false };
+    watches.set(name, w);
+    openWatcher(name, w);
+    w.poll = setPoll(() => { if (!w.watcher) openWatcher(name, w); check(name); }, RELOAD_POLL_MS);
+    w.poll?.unref?.();
+  };
+  async function check(name) {
+    const w = watches.get(name); if (!w || w.busy) return;
+    const s = sigOf(w.pkgPath); if (!s || s.key === w.sig) return;
+    w.busy = true;
+    const old = w.version; const was = loaded.get(name); const order = [...loaded.keys()];
+    w.sig = s.key; w.version = s.version; // recorded first: a failed reload is reported once, not every poll
+    try {
+      if (was) { loaded.delete(name); await closeInst(name, was.inst); } // async close: awaited up to 500 ms, then dropped
+      if (!watches.has(name)) return; // unloaded while closing
+      const mod = await importer(`${pathToFileURL(w.entry).href}?v=${s.version}-${s.mtime}`);
+      if (!watches.has(name)) return; // unloaded while importing
+      const ext = normalizeExtension(mod, name);
+      if (!ext) throw new Error('the package has no create()');
+      const refusal = contractRefusal(ext);
+      if (refusal) throw new Error(refusal);
+      const settings = settingsFor(ext, name);
+      const inst = makeInst(name, ext, settings);
+      loaded.set(name, { ext, inst, where: was?.where || null, entry: w.entry, settings });
+      if (was) { const cur = new Map(loaded); loaded.clear(); for (const n of order) if (cur.has(n)) loaded.set(n, cur.get(n)); for (const [n, v] of cur) if (!loaded.has(n)) loaded.set(n, v); } // keep the tab position
+      failed.delete(name);
+      if (focus === name) { if (panelOf(name)) safe(name, 'onFocus', () => panelOf(name).onFocus?.()); else dropPanelState(name); }
+      panelErr.delete(name);
+      lastKey = null; lastSent = 0; pending = null;
+      if (lastInput) sendAll(snap());
+      handlers.note?.(old === s.version ? `↻ ${name} reloaded` : `↻ ${name} updated ${old ?? '?'} -> ${s.version ?? '?'}`, 'ok');
+    } catch (e) {
+      const msg = `${name} reload failed: ${e?.message || e}`;
+      dropPanelState(name);
+      failed.set(name, e?.message || String(e));
+      handlers.note?.(msg, 'warn');
+    } finally { w.busy = false; if (!loaded.size) stopBeat(); handlers.changed?.(); }
+  }
+
+  const host = {
+    failure: (name) => failed.get(name) || null,
+    watching: () => [...watches.keys()],
+    armed: () => loaded.size > 0,
+    isLoaded: (name) => loaded.has(name),
+    loadedNames: () => [...loaded.keys()],
+    where: (name) => loaded.get(name)?.where || null,
+    /** emit as one extension (tests and the shim); extensions get their own bound emit in create(). */
+    emit: (msg, name) => (name ? emitFor(name)(msg) : [...loaded.keys()].some((n) => emitFor(n)(msg))),
+    async load(name) {
+      if (loaded.has(name)) return { ok: true, text: `${name} is already loaded.` };
+      if (starting.has(name)) return starting.get(name);
+      const p = (async () => {
+        try {
+          const r = await resolveExtension(name, { env, importer, execPath, npmRoot, exists });
+          if (!r.ok && r.notFound) return { ok: false, notFound: true, text: `${name} ${notInstalled(name)} (looked in: ${r.tried.join('; ')})`, tried: r.tried };
+          if (!r.ok) return { ok: false, text: `${name} could not load: ${r.error}` };
+          const ext = normalizeExtension(r.mod, name);
+          if (!ext) return { ok: false, text: `${name} could not load: the package has no create().` };
+          const refusal = contractRefusal(ext);
+          if (refusal) { failed.set(name, refusal); handlers.changed?.(); return { ok: false, refused: true, text: `${name} ${refusal}` }; }
+          let inst; const settings = settingsFor(ext, name);
+          try { inst = makeInst(name, ext, settings); } catch (e) { return { ok: false, text: `${name} could not start: ${e?.message || e}` }; }
+          loaded.set(name, { ext, inst, where: r.where, entry: r.entry || null, settings });
+          failed.delete(name);
+          if (r.entry) startWatch(name, r.entry);
+          lastKey = null; lastSent = 0; pending = null; event = null; eventSig = null; prevLoops.clear(); prevCount = null;
+          startBeat();
+          handlers.changed?.();
+          return { ok: true, text: `${ext.name} is on (found: ${r.where}).`, ext };
+        } finally { starting.delete(name); }
+      })();
+      starting.set(name, p);
+      return p;
+    },
+    /** Sync: the extension is gone from the host at once; any async close() finishes in the background (see closing). */
+    unload(name) {
+      const l = loaded.get(name);
+      if (!l) { const had = watches.has(name) || failed.has(name); stopWatch(name); failed.delete(name); return { ok: true, text: had ? `${name} is off.` : `${name} was not loaded.` }; }
+      loaded.delete(name); stopWatch(name); failed.delete(name);
+      if (focus === name) safe(name, 'onBlur', () => l.inst?.panel?.onBlur?.());
+      dropPanelState(name);
+      if (!loaded.size) { pending = null; lastKey = null; stopBeat(); if (timer) { clearTimer(timer); timer = null; } if (invTimer) { clearTimer(invTimer); invTimer = null; } }
+      const closing = closeInst(name, l.inst);
+      handlers.changed?.();
+      return { ok: true, text: `${name} is off.`, closing };
+    },
+    /** Unloads everything; resolves once every close() has finished or been dropped (500 ms each, in parallel). */
+    unloadAll() { for (const n of [...loaded.keys()]) host.unload(n); return Promise.all([...closings]).then(() => undefined); },
+    /** Slash commands of loaded extensions only. -> [{ name, help, ext, subcommands }] */
+    commands: () => [...loaded.values()].flatMap((l) => l.ext.commands.map((c) => ({ name: c.name, help: c.help || '', ext: l.ext.name, subcommands: c.subcommands }))),
+    /** Subcommand names for Tab completion: complete('/fleet', 'st') -> [{ name, help }]. */
+    complete(cmd, prefix = '') {
+      const c = host.commands().find((x) => x.name === cmd);
+      return (c?.subcommands || []).filter((x) => x.name.startsWith(String(prefix).toLowerCase()));
+    },
+    async runCommand(cmd, args, ctx = {}) {
+      for (const l of loaded.values()) {
+        const c = l.ext.commands.find((x) => x.name === cmd);
+        if (c) {
+          const raw = Array.isArray(args) ? args.join(' ') : String(args ?? '');
+          const say = ctx.say || ((t, tone) => handlers.note?.(t, tone));
+          try { return { handled: true, result: await c.run(splitArgs(args), { ...ctx, say, raw, extension: l.ext.name, loaded: host.loadedNames() }) }; } catch (e) { return { handled: true, error: e?.message || String(e) }; }
+        }
+      }
+      return { handled: false };
+    },
+
+    // ---- settings ----
+    settingsInfo(name) {
+      const l = loaded.get(name);
+      if (!l) return { ok: false, text: `${name} is not loaded. /ext on ${name}` };
+      if (!l.ext.settings.length) return { ok: false, text: `${name} declares no settings.` };
+      return { ok: true, defs: l.ext.settings, values: resolveSettings(l.ext.settings, readExtSettings(name, ...listArg())) };
+    },
+    setSetting(name, key, raw) {
+      const info = host.settingsInfo(name); if (!info.ok) return info;
+      const def = info.defs.find((d) => d.key === key);
+      if (!def) return { ok: false, text: `${name} has no setting "${key}". Keys: ${info.defs.map((d) => d.key).join(', ')}` };
+      const c = coerceSetting(def, raw);
+      if (!c.ok) return { ok: false, text: c.error };
+      const st = extStoreSetting(name, key, c.value, ...listArg());
+      if (!st.ok) return st;
+      const l = loaded.get(name);
+      const next = resolveSettings(l.ext.settings, readExtSettings(name, ...listArg()));
+      l.settings = next;
+      try { l.inst?.onSettings?.(next); } catch (e) { log(`extension ${name} onSettings failed: ${e?.message || e}`); }
+      return { ok: true, text: `${name} ${key} = ${JSON.stringify(c.value)}` };
+    },
+
+    // ---- panels and tabs ----
+    panels: () => panelNames().map((n) => ({ name: n, title: String(panelOf(n).title || n), focused: focus === n, open: shown === n })),
+    focused: () => focus,
+    shown: () => shown,
+    regionHeight: panelHeight,
+    /** The lines for the open panel (or `name`), clipped to the region. Pure for the extension; errors become 'panel error'. */
+    renderPanel(name, { width = 80, height = 12, theme = { name: 'dark', color: true, unicode: true } } = {}) {
+      const p = panelOf(name); if (!p) return [];
+      const retry = panelErr.get(name);
+      if (retry != null && now() < retry) return clipPanel(['panel error'], width, height);
+      const fail = (why) => { panelErr.set(name, now() + PANEL_RETRY_MS); log(`extension ${name} panel ${why}`); return clipPanel(['panel error'], width, height); };
+      const t0 = perf(); let out;
+      try { out = p.render({ width, height, focused: focus === name, theme }); } catch (e) { return fail(`render failed: ${e?.message || e}`); }
+      if (perf() - t0 > PANEL_SLOW_MS) return fail(`render took over ${PANEL_SLOW_MS}ms`);
+      panelErr.delete(name);
+      return clipPanel(out, width, height);
+    },
+    focusPanel(name) {
+      if (!panelOf(name)) return { ok: false, text: loaded.has(name) ? `${name} has no panel.` : `${name} is not loaded. /ext on ${name}` };
+      if (focus === name) { shown = name; return { ok: true, text: `${name} panel focused. Esc returns to the composer.` }; }
+      if (focus) safe(focus, 'onBlur', () => panelOf(focus)?.onBlur?.());
+      focus = name; shown = name;
+      safe(name, 'onFocus', () => panelOf(name).onFocus?.());
+      handlers.changed?.();
+      return { ok: true, text: `${name} panel focused. Esc returns to the composer.` };
+    },
+    /** Esc: keys go back to the composer; the panel stays open. */
+    blur() {
+      if (!focus) return false;
+      const n = focus; focus = null;
+      safe(n, 'onBlur', () => panelOf(n)?.onBlur?.());
+      handlers.changed?.();
+      return true;
+    },
+    /** /ext tab off: blur and collapse. */
+    hidePanel() { host.blur(); const was = shown; shown = null; if (was) handlers.changed?.(); return Boolean(was); },
+    /** Ctrl+]: next panel (the first when the composer has the keys). -> the name, or null with no panels. */
+    cycle() {
+      const names = panelNames(); if (!names.length) return null;
+      const next = names[(names.indexOf(focus) + 1) % names.length]; // indexOf -1 -> the first
+      host.focusPanel(next); return next;
+    },
+    /** Route one key. Returns true when the host consumed it (a panel has the keys), false when the composer keeps it. */
+    key(key) {
+      if (!focus) return false;
+      if (key === 'ctrl-]' || key === 'ctrl+]') { host.cycle(); return true; }
+      if (key === 'escape' || key === 'esc') { host.blur(); return true; }
+      const p = panelOf(focus);
+      if (!p) { focus = null; return false; }
+      try { p.onKey?.(key); } catch (e) { panelErr.set(focus, now() + PANEL_RETRY_MS); log(`extension ${focus} panel onKey failed: ${e?.message || e}`); }
+      handlers.changed?.();
+      return true; // while a panel has the keys, nothing leaks into the composer
+    },
+
+    /** Push the current snapshot inputs: derives an event from changes, throttles to one update per second. */
+    push(input) {
+      lastInput = input;
+      if (!loaded.size) return;
+      const items = input?.items || [];
+      for (const l of input?.loops || []) {
+        const was = prevLoops.get(l.id);
+        if (was && was !== l.status && (l.status === 'done' || l.status === 'failed')) raise({ ...(l.eventId != null ? { id: l.eventId } : {}), kind: 'loop', text: `${l.title || l.id} ${l.status}`, level: l.status === 'failed' ? 'error' : 'ok' });
+        prevLoops.set(l.id, l.status);
+      }
+      if (prevCount != null && items.length > prevCount) raise({ ...(input?.eventId != null ? { id: input.eventId } : {}), kind: 'approval', text: `${items.length} waiting`, level: 'warn' });
+      prevCount = items.length;
+      const state = snap();
+      const wait = THROTTLE_MS - (now() - lastSent);
+      if (wait <= 0 && !timer) { pending = null; sendAll(state); return; }
+      pending = state;
+      if (!timer) timer = setTimer(flush, Math.max(wait, 0));
+    }
+  };
+  return host;
+}