quoxcli 0.4.0 → 0.5.0

package/lib/quoxon/extensions.js

@@ -9,22 +9,30 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
+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 = os.homedir()) => path.join(home, '.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 }));
+    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()) {
@@ -53,6 +61,53 @@ export function extSetEnabled(name, enabled, file = extListPath()) {
   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);
@@ -77,6 +132,24 @@ export function packageEntry(dir) {
   } 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).
@@ -87,11 +160,11 @@ export async function resolveExtension(name, { env = process.env, importer = def
   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})` }; }
+    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})` }; }
+  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');
@@ -102,7 +175,7 @@ export async function resolveExtension(name, { env = process.env, importer = def
       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})` }; }
+      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;
@@ -113,13 +186,26 @@ export async function resolveExtension(name, { env = process.env, importer = def
   return { ok: false, notFound: true, tried };
 }
 
-/** An extension module -> { name, version, commands, create } or null. Accepts default export or the module itself. */
+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');
-  return { name: ext.name || fallbackName, version: ext.version || null, commands, create };
+  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 ------------------------------------------------------------------------------
@@ -139,7 +225,7 @@ export function buildFleet(hosts) {
   };
 }
 
-export function buildSnapshot({ org = null, items = [], health = {}, loops = [], event = null, fleet = null, evidence = null, sessions = null } = {}) {
+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),
@@ -153,6 +239,8 @@ export function buildSnapshot({ org = null, items = [], health = {}, loops = [],
   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,
@@ -161,7 +249,7 @@ export function buildSnapshot({ org = null, items = [], health = {}, loops = [],
     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 = { kind: event.kind, text: event.text, level: event.level || 'info' };
+  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;
 }
 
@@ -177,37 +265,213 @@ export function pickDraft(item, n, option) {
   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), preselect(n, option), changed() } are the window's own actions. getSettings() feeds create().
- * Loaded extensions all receive the same deduped, 1/s-throttled snapshot.
+ * 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 = () => ({}) } = {}) {
-  const loaded = new Map(); // name -> { ext, inst, where }
+  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; const prevLoops = new Map(); let prevCount = 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 sendAll = (state) => {
-    const key = JSON.stringify(state);
-    if (key === lastKey) return;
+  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 === 'open_approval' && Number.isInteger(msg.n) && msg.n >= 1) { handlers.openApproval?.(msg.n); return true; }
-      if (msg.type === 'pick' && Number.isInteger(msg.n) && msg.n >= 1) { handlers.preselect?.(msg.n, msg.option); return true; }
-      if (msg.type === 'alert_ack') { event = null; handlers.changed?.(); return true; }
+      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()],
@@ -224,10 +488,15 @@ export function createExtensionHost({ importer = defaultImporter, env = process.
           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().` };
-          let inst;
-          try { inst = ext.create({ emit: emitFor(name), log, settings: getSettings() }); } catch (e) { return { ok: false, text: `${name} could not start: ${e?.message || e}` }; }
-          loaded.set(name, { ext, inst, where: r.where });
-          lastKey = null; lastSent = 0; pending = null; event = null; prevLoops.clear(); prevCount = null;
+          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); }
@@ -235,37 +504,128 @@ export function createExtensionHost({ importer = defaultImporter, env = process.
       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) return { ok: true, text: `${name} was not loaded.` };
-      loaded.delete(name);
-      if (!loaded.size) { pending = null; lastKey = null; if (timer) { clearTimer(timer); timer = null; } }
-      try { l.inst?.close?.(); } catch (e) { log(`extension ${name} close failed: ${e?.message || e}`); }
+      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.` };
+      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()));
     },
-    unloadAll() { for (const n of [...loaded.keys()]) host.unload(n); },
-    /** Slash commands of loaded extensions only. -> [{ name, help, ext }] */
-    commands: () => [...loaded.values()].flatMap((l) => l.ext.commands.map((c) => ({ name: c.name, help: c.help || '', ext: l.ext.name }))),
     async runCommand(cmd, args, ctx = {}) {
       for (const l of loaded.values()) {
         const c = l.ext.commands.find((x) => x.name === cmd);
-        if (c) { try { return { handled: true, result: await c.run(args, { ...ctx, extension: l.ext.name, loaded: host.loadedNames() }) }; } catch (e) { return { handled: true, error: e?.message || String(e) }; } }
+        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')) event = { kind: 'loop', text: `${l.title || l.id} ${l.status}`, level: l.status === 'failed' ? 'error' : 'ok' };
+        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) event = { kind: 'approval', text: `${items.length} waiting`, level: 'warn' };
+      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 = buildSnapshot({ ...input, event });
+      const state = snap();
       const wait = THROTTLE_MS - (now() - lastSent);
       if (wait <= 0 && !timer) { pending = null; sendAll(state); return; }
       pending = state;