quoxcli 0.4.0 → 0.5.0

package/lib/core/quoxglyph.js

@@ -30,6 +30,7 @@ export const ICONS = {
   quoxseo: '📈 QUOXSEO', reach: '💥 REACH', vulcan: '🌋 VULCAN',
   quoxvoice: '📞 QUOXVOICE', quoxsecurity: '🛡️ QUOXSECURITY', quoxpert: '🎓 QUOXPERT',
   quoxslots: '📍 QUOXSLOTS',
+  gripe: '📣 GRIPE',
   quox: 'Ⓠ QUOX'
 };
 export const BUDGETS = { VERB_MAX: 48, RESULT_MAX: 40, LINE_MAX: 120, TREE_MAX: 6, TABLE_MAX: 6 };
@@ -74,7 +75,7 @@ export function line(surface, verb, opts = {}) {
   const col = on();
   const name = brandName(iconFor(surface), col);
   const sep = col ? `${DIM}│${R}` : '│';
-  let tail = opts.result ? trunc(opts.result, BUDGETS.RESULT_MAX) : '';
+  let tail = opts.result ? trunc(opts.result, opts.max || BUDGETS.RESULT_MAX) : '';
   if (opts.ms !== undefined) {
     const d = col ? `${DIM}${opts.ms}ms${R}` : `${opts.ms}ms`;
     tail = tail ? `${tail} ${col ? DIM + '·' + R : '·'} ${d}` : d;
@@ -85,6 +86,26 @@ export function line(surface, verb, opts = {}) {
   return tail ? `${name} ${sep} ${v} ${sep} ${tail}` : `${name} ${sep} ${v}`;
 }
 
+const GRIPE_TITLE_MAX = 50;
+const gripeTitle = (t) => trunc(String(t || '').split('\n')[0].trim(), GRIPE_TITLE_MAX);
+
+/** GRIPE-1460: `📣 GRIPE │ filed #N owner/repo │ "title" ✔` for an issue URL (the URL itself goes on the next line). */
+export function gripeFiledLine(url, title) {
+  const m = /github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)/.exec(String(url || ''));
+  const verb = m ? `filed #${m[2]} ${m[1]}` : 'filed issue';
+  return line('gripe', verb, { result: `"${gripeTitle(title)}"`, status: 'ok', max: GRIPE_TITLE_MAX + 2 });
+}
+
+/** GRIPE-1460: a gripe saved earlier and filed on retry: `📣 GRIPE │ queued gripe filed │ <url> ✔`. */
+export function gripeQueuedFiledLine(url) {
+  return line('gripe', 'queued gripe filed', { result: String(url), status: 'ok', max: 200 });
+}
+
+/** GRIPE-1460: `📣 GRIPE │ file "title" │ ✖ <exact error>`. */
+export function gripeFailedLine(title, error) {
+  return line('gripe', `file "${trunc(gripeTitle(title), 30)}"`, { result: `${STATUS.fail.glyph} ${error}`, max: 400 });
+}
+
 /** Gradient progress meter: ▰▰▰▱ done/total (or pct when total omitted). */
 export function meter(done, total, width = 8) {
   const col = on();

package/lib/core/router.js

@@ -8,6 +8,7 @@
  * output is tested without a router.
  */
 import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxUserError } from './errors.js';
 
 /** verb -> the tool it runs. All read-only (aoclClassification layer 1, autonomy FULL). */
 export const ROUTER_TOOLS = Object.freeze({
@@ -21,6 +22,18 @@ export const ROUTER_TOOLS = Object.freeze({
   inventory: 'mikrotik_discovery_inventory',
 });
 
+/** The tool route refused because this identity lacks the router grant: say that, keep the plumbing in detail. */
+function notPermitted(tool, raw, path) {
+  const err = new QuoxUserError('This identity is not allowed to read the router: the router tools are not granted to it.', {
+    next: 'run it from an identity that has the router tools (`quox config profile list`), or ask an org owner or admin to grant them.',
+    code: 'not_permitted',
+  });
+  err.debug = { tool, route: `POST ${path}`, server_said: raw }; // --json and --verbose only; never the headline
+  err.toolError = raw;
+  err.tool = tool;
+  return err;
+}
+
 export function makeRouterExec({ client, orgId }) {
   return async function exec(tool, input = {}) {
     const ep = resolveEndpoint('v1.tools.execute');
@@ -28,6 +41,7 @@ export function makeRouterExec({ client, orgId }) {
     if (orgId) body.org_id = orgId;
     const data = await client.post(ep.path, { service: ep.service, body });
     if (data && data.success === false) {
+      if (/not granted to agent/i.test(String(data.error || ''))) throw notPermitted(tool, data.error, ep.path);
       const detail = data.detail ? ` (${data.detail})` : '';
       const err = new Error(`${tool} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}${detail}`);
       err.toolError = data.error || 'unknown error';

package/lib/core/stepUpPrompt.js

@@ -0,0 +1,99 @@
+/**
+ * DS-010 / quox#1335: the CLI half of the human step-up PIN.
+ *
+ * The SERVER decides what needs a person and answers 403 step_up_required. This helper only reacts:
+ * on a terminal it asks for the PIN with hidden input, trades it for a short-lived step-up token
+ * (POST /api/auth/me/step-up, the same endpoint the Quox terminal uses) and retries the call ONCE with
+ * the token. Rules, all deliberate:
+ *   - the PIN is read from a hidden prompt only. NEVER from argv, an env var or a file: an agent that can
+ *     set an env var or a flag could supply it, and then the PIN proves nothing about a person
+ *   - the PIN is never logged, echoed or put in an error message; the token is never stored
+ *   - no terminal: refuse with a plain message saying a person must run it interactively
+ */
+import { QuoxUserError } from './errors.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const PIN_RE = /^\d{6}$/;
+export const MAX_PIN_TRIES = 3;
+export const STEP_UP_HEADER = 'x-step-up-token';
+const NO_PIN_NEXT = 'set one in the dashboard: Settings > Account > Approval PIN, then run this again in a terminal.';
+
+export function isStepUpRequired(err) {
+  return Boolean(err && err.status === 403 && err.body && err.body.error === 'step_up_required');
+}
+
+/** Real IO: hidden prompt via inquirer; a terminal means a TTY on both stdin and stdout. */
+export function defaultPinIO() {
+  return {
+    isTTY: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    promptPin: async (message) => {
+      const { default: inquirer } = await import('inquirer');
+      const a = await inquirer.prompt([{ type: 'password', name: 'pin', message, mask: '*' }]);
+      return a.pin;
+    },
+  };
+}
+
+function nonTtyError(what) {
+  return new QuoxUserError(`${what} needs your step-up PIN, and there is no terminal to ask for it on.`, {
+    next: 'run this command yourself in an interactive terminal; it will ask for the PIN with hidden input. The PIN cannot be passed as a flag or an environment variable.',
+    exitCode: 4, code: 'step_up_required',
+  });
+}
+
+/**
+ * Run `run(extraHeaders)`; if the server says step-up is required, get a token from the person and run it once more.
+ * @param {(headers:object)=>Promise<any>} run   performs the guarded request, merging `headers` into it
+ * @param {{client:any, orgId?:string|null, scope?:string, io?:object, what?:string}} opts
+ */
+export async function withStepUp(run, { client, orgId = null, scope = 'approve', io = defaultPinIO(), what = 'This approval' } = {}) {
+  try {
+    return await run({});
+  } catch (err) {
+    if (!isStepUpRequired(err)) throw err;
+    if (err.body?.reason === 'non_human') {
+      throw new QuoxUserError(`${what} needs a person. This login is an agent or service identity, which can never approve it.`, {
+        next: 'a person must approve it from their own login (the dashboard, or `quox` in their terminal).', exitCode: 4, code: 'step_up_human_only',
+      });
+    }
+    if (err.body?.pin_set === false) {
+      throw new QuoxUserError(`${what} needs your step-up PIN, and you have not set one yet.`, { next: NO_PIN_NEXT, exitCode: 4, code: 'no_pin_set' });
+    }
+    if (!io.isTTY()) throw nonTtyError(what);
+    const token = await collectToken({ client, orgId, scope, io, what });
+    return run({ [STEP_UP_HEADER]: token });
+  }
+}
+
+async function collectToken({ client, orgId, scope, io, what }) {
+  const ep = resolveEndpoint('stepup.verify');
+  for (let attempt = 1; attempt <= MAX_PIN_TRIES; attempt += 1) {
+    let pin = await io.promptPin(`${what} needs your step-up PIN (6 digits, hidden):`);
+    if (!PIN_RE.test(String(pin ?? ''))) {
+      pin = null;
+      if (attempt < MAX_PIN_TRIES) continue;
+      throw new QuoxUserError('A step-up PIN is exactly 6 digits. Nothing was approved.', { exitCode: 4, code: 'bad_pin_format' });
+    }
+    try {
+      const body = { pin, scopes: [scope] };
+      if (orgId) body.org_id = orgId;
+      const r = await client.post(ep.path, { service: ep.service, body });
+      pin = null;
+      if (r && r.step_up_token) return r.step_up_token;
+      throw new QuoxUserError('The server did not issue a step-up token. Nothing was approved.', { exitCode: 4, code: 'step_up_failed' });
+    } catch (e) {
+      pin = null;
+      if (e instanceof QuoxUserError) throw e;
+      const code = e?.body?.error || e?.code;
+      if (e?.status === 409 || code === 'no_pin_set') throw new QuoxUserError('You have not set a step-up PIN yet.', { next: NO_PIN_NEXT, exitCode: 4, code: 'no_pin_set' });
+      if (e?.status === 423 || code === 'pin_locked') throw new QuoxUserError('PIN entry is locked after too many wrong tries.', { next: 'wait for the lock to pass, or approve from the dashboard.', exitCode: 4, code: 'pin_locked' });
+      if (e?.status === 403 && code === 'step_up_human_only') throw new QuoxUserError(`${what} needs a person; this login is an agent identity.`, { next: 'approve from a human login.', exitCode: 4, code: 'step_up_human_only' });
+      if (e?.status === 401 || code === 'wrong_pin') {
+        if (attempt >= MAX_PIN_TRIES) throw new QuoxUserError('Wrong PIN. Nothing was approved.', { exitCode: 4, code: 'wrong_pin' });
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw new QuoxUserError('Wrong PIN. Nothing was approved.', { exitCode: 4, code: 'wrong_pin' });
+}

package/lib/core/version.js

@@ -18,7 +18,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
-export const BASE_VERSION = '0.4.0';
+export const BASE_VERSION = '0.5.0';
 
 // The CLI source root (…/cli). version.js lives at cli/lib/core/, so two
 // levels up is the tree whose HEAD identifies the running build.

package/lib/core/walkthrough.js

@@ -3,13 +3,16 @@
  * card at a time, using the same card and reply rules as the TUI (quoxon/approvalsView.js). Identity is the decision id.
  * io = { readLine(prompt) -> Promise<string|null>, write(line), answer(item, key, note) -> Promise<void> }.
  */
-import { isDecision, walkCard, walkReply, walkNotYesNo, walkNoCatch, walkSummary } from '../quoxon/approvalsView.js';
+import { isDestructive } from '../quoxon/destructive.js';
+import { isDecision, needsPin, approvalAsWalkItem, walkCard, walkReply, walkNotYesNo, walkNoCatch, walkSummary } from '../quoxon/approvalsView.js';
 
 export async function runWalkthrough(items, io) {
-  const decs = (items || []).filter(isDecision);
-  if (!decs.length) { io.write('No question is waiting for you.'); return { answered: [], skipped: [], left: [] }; }
+  // Questions AND policy-held approval cards (kind approval, shaped as yes/no cards); other inbox kinds are not cards.
+  const decs = (items || []).filter((it) => isDecision(it) || it?.kind === 'approval').map(approvalAsWalkItem);
+  if (!decs.length) { io.write('No question or approval is waiting for you.'); return { answered: [], skipped: [], left: [] }; }
   const st = { answered: [], skipped: [], left: [] };
-  io.write(`${decs.length} question${decs.length === 1 ? '' : 's'} waiting for you. One at a time: a choice, then an optional note.`);
+  const nApp = decs.filter((d) => d.__approval).length;
+  io.write(`${decs.length - nApp ? `${decs.length - nApp} question${decs.length - nApp === 1 ? '' : 's'}` : ''}${decs.length - nApp && nApp ? ' and ' : ''}${nApp ? `${nApp} approval${nApp === 1 ? '' : 's'}` : ''} waiting for you. One at a time: a choice, then an optional note.`);
   for (let i = 0; i < decs.length; i++) {
     const it = decs[i]; const card = walkCard(it, i + 1, decs.length);
     io.write(''); card.lines.forEach((l) => io.write(l));
@@ -21,7 +24,8 @@ export async function runWalkthrough(items, io) {
       if (rep.notYesNo) { io.write(walkNotYesNo(it)); continue; }
       if (rep.defer) { st.skipped.push(it.title || it.id); break; }
       if (rep.ask) { io.write(`  Asked by ${it.payload.session || 'a session'} (id ${it.id}). ${it.payload.why || 'No further reason was given.'}`); continue; }
-      if (it.payload.high_risk === true && rep.key !== 'n') { io.write('  High risk: a yes needs your PIN, which this plain terminal cannot take. Answer it in `quox` with /approvals walkthrough, or skip it here.'); continue; }
+      if (needsPin(it) && rep.key !== 'n') { io.write('  High risk: a yes needs your PIN, which this walkthrough cannot take. Run `quox approvals approve <id>` (it asks for the PIN) or answer in `quox` with /approvals walkthrough, or skip it here.'); continue; }
+      if (it.__approval && rep.key === 'y' && isDestructive(it)) { io.write('  This deletes something: its name must be typed, which this walkthrough does not take. Run `quox approvals approve <id>` in a terminal, or skip it.'); continue; }
       try { await io.answer(it, rep.key, rep.note || null); }
       catch (e) { io.write(`  Not answered (${e.message}). The question stays open.`); continue; }
       const label = it.payload.options.find((o) => o.key === rep.key).label;

package/lib/dragon/select.js

@@ -1,5 +1,5 @@
 /**
- * Dragon companions (Lucid, Hyperion, Seer, Sentinel, Drago, Cipher): which one, whether to show it, and where its art lives.
+ * Dragon companions (Lucid, Hyperion, Seer, Sentinel, Drago, Cipher, Vulcan, Quoxperticus): which one, whether to show it, and where its art lives.
  * Pure. The art, animation and activity reducer stay in quoxai/dragonlab (integration/companions-v1);
  * Quox only chooses and loads. See docs/dragons/COMPANION-UX.md for the decisions behind each rule.
  */
@@ -10,7 +10,7 @@ import { fileURLToPath } from 'node:url';
 export const VENDORED_DRAGONLAB = fileURLToPath(new URL('../../vendor/dragonlab', import.meta.url));
 
 /** Registry agent ids (and display names) to approved dragon. Others, including quox/commanderq, get none. */
-export const AGENT_DRAGON = Object.freeze({ lucid: 'lucid', hyperion: 'hyperion', atlas: 'hyperion', seer: 'seer', sentinel: 'sentinel', warden: 'sentinel', security_lead: 'drago', drago: 'drago', cipher: 'cipher' });
+export const AGENT_DRAGON = Object.freeze({ lucid: 'lucid', hyperion: 'hyperion', atlas: 'hyperion', seer: 'seer', sentinel: 'sentinel', warden: 'sentinel', security_lead: 'drago', drago: 'drago', cipher: 'cipher', vulcan: 'vulcan', forge: 'vulcan', quoxperticus: 'quoxperticus' });
 export const COMPANION_MODES = ['on', 'greeting', 'off'];
 /** One-line change: the owner decides this after his Mac check (docs/dragons/COMPANION-UX.md section 4). */
 export const DEFAULT_COMPANION_MODE = 'on';

package/lib/quoxon/EXTENSIONS.md

@@ -1,23 +1,146 @@
-# quoxon extensions
+# quoxon extensions: contract v1
 
-Optional npm packages that add a surface to quoxon (a MIDI pad deck, a status bar). Core ships none and knows none by name.
+Optional npm packages that add a surface to quoxon (a MIDI pad deck, a status bar, a fleet board). Core ships none and knows none by name.
+An extension can OPEN an approval or PRESELECT an answer. It can never resolve one, and it never polls Quox: data is pushed to it.
 
-**Loading.** Nothing loads unless the package is installed AND listed in `~/.quox/extensions.json`
+## Loading
+
+Nothing loads unless the package is installed AND listed in `~/.quox/extensions.json`
 (`quox ext add|remove|list <pkg>`; `/ext list|on|off <name>` inside quoxon). Install with `npm i -g <pkg>`.
+Set env `QUOX_EXT_LIST=<path>` to use another list file (default `~/.quox/extensions.json`), for `quox ext` and quoxon alike (dev and tests).
 Resolution order: env `QUOX_EXT_<NAME>_MODULE` (name upper-cased, non-alphanumerics to `_`), a local `import(name)`,
-then the global npm root (`dirname(execPath)/../lib/node_modules` first, then `npm root -g` once, cached).
-`/ext list` names where each was found; a miss lists where it looked.
-
-**Module.** Default export (or the module itself):
-`{ name, version, commands?: [{ name: '/deck', help, run(args, ctx) }], create({ emit, log, settings }) -> { update(state), close() } }`.
-Its slash commands exist only while it is loaded. `run` may return a string or `{ text, tone }`.
-
-**State** (`update(state)`, deduped, at most 1/s):
-`{ org:{id,name}, approvals:{count, items:[{n,id,risk:'low'|'high',title,agent,options?:[{key,label}]}]}, health:{<name>:'ok'|'warn'|'down'},
-loops:[{id,title,turn,max,status}], fleet:{total,online,offline,warn,hosts:[{name,state:'ok'|'warn'|'down'}] (max 16)},
-evidence:{chain:'ok'|'broken'|'unknown', checked_at}, sessions:{active}, event?:{kind,text,level} }`.
-`fleet` comes from a 30 s poll of the host list while an extension is loaded. `evidence.chain` is `unknown` until quoxon holds a chain status.
-
-**emit.** `{type:'open_approval', n}` opens approval n; `{type:'pick', n, option}` only fills the composer with the
-answer command (the user presses Enter, high risk still needs the step-up PIN); `{type:'alert_ack'}` clears the event.
-An extension can never resolve an approval. emit is ignored once the extension is unloaded.
+then the global npm root. `/ext list` names where each was found; a miss lists where it looked.
+
+**contractVersion** (integer, this document is `1`). The host refuses an extension whose `contractVersion` is above what it supports,
+with a line in `/ext list`: `needs extension contract v2, this quoxon supports v1`. An extension with no `contractVersion` is a
+pre-contract (legacy) extension: it loads, and `emit` may use `n` without `id` (see F2). Declare `contractVersion: 1` to get the strict rules.
+
+## Module
+
+Default export (or the module itself):
+
+```ts
+interface Extension {
+  name: string; version?: string;
+  contractVersion?: 1;
+  commands?: Command[];
+  settings?: SettingDef[];
+  create(ctx: { emit(msg: Emit): boolean; log(text: string): void; settings: Record<string, string|number|boolean>; invalidate(): void }): Instance;
+}
+interface Instance {
+  update?(state: State): void;                 // deduped; see Freshness
+  close?(): void | Promise<void>;              // see Close
+  panel?: Panel;                               // see Panels (one panel per extension)
+  onSettings?(next: Record<string, string|number|boolean>): void;
+  onEmitResult?(r: { ok: boolean; reason?: string; msg: Emit }): void;
+}
+```
+
+`panel`, `onSettings` and `onEmitResult` live on the object `create()` returns. There is no module-level `onSettings`.
+
+## Commands
+
+```ts
+interface Command {
+  name: `/${string}`; help?: string;
+  subcommands?: { name: string; help?: string }[];   // feed /help and Tab completion
+  run(args: string[], ctx: { raw: string; say(text: string, tone?: 'ok'|'warn'|'accent'|'dim'): void; extension: string; loaded: string[] }): string | { text: string; tone?: string } | Promise<...>;
+}
+```
+
+`args` is the text after the command split on whitespace; `ctx.raw` is the same text unsplit. Commands exist only while the extension is loaded.
+A thrown error is printed as `<cmd>: <message>`, never crashes the window.
+
+## State
+
+`update(state)` is deduped (a push identical except `at` is dropped) and sent at most once per second.
+
+```ts
+interface State {
+  at: string;                 // ISO time of this push
+  stale?: true;               // present only when the host's last successful server read is over 60 s old
+  org: { id: string|null; name: string|null };
+  approvals: { count: number; items: { n: number; id: string|null; risk: 'low'|'high'; title: string; agent: string|null; options?: { key: string; label: string }[] }[] };
+  health: Record<string, 'ok'|'warn'|'down'>;
+  loops: { id: string; title: string; turn: number; max: number; status: string }[];
+  fleet: { total: number; online: number; offline: number; warn: number; hosts: { name: string; state: 'ok'|'warn'|'down' }[] };  // hosts max 16, may be empty
+  evidence: { chain: 'ok'|'broken'|'unknown'; checked_at: string|null };   // PLACEHOLDER: always 'unknown' until quoxon holds a chain status
+  sessions: { active: number };
+  event?: { seq: number; id?: string; kind: string; text: string; level: 'info'|'ok'|'warn'|'error' };
+}
+```
+
+**Freshness.** `state.at` is set on every push. While any extension is loaded the host pushes a heartbeat every 15 s, even when nothing
+changed, so `at` keeps moving. `stale: true` means the data may be old (the server was not read for over 60 s): show it as such.
+
+**Event ids.** `event.seq` is a positive integer, monotonic within one quoxon window session and never reused; a new event gets the next number,
+the seq changes only when `kind`, `text`, `level` or `id` changes: a repeat of the held event keeps its seq until `alert_ack`. `event.id` appears only when the server supplied one.
+
+`fleet` comes from a 30 s poll of the host list while an extension is loaded.
+
+## emit
+
+```ts
+type Emit =
+  | { type: 'open_approval'; id: string; n?: number }
+  | { type: 'pick'; id: string; n?: number; option: string }
+  | { type: 'alert_ack' };
+```
+
+`id` (from `approvals.items[].id`) is REQUIRED for `open_approval` and `pick`. `n` is display-only; when `id` and `n` disagree, `id` wins
+(logged). An unknown, missing or already-resolved `id` is refused through `onEmitResult({ ok:false, reason, msg })`, and is never retargeted
+to another item. `pick` only fills the composer with the answer command: the user presses Enter, high risk still needs the step-up PIN.
+`alert_ack` clears the event. emit returns `true` when accepted and is ignored once the extension is unloaded.
+(Legacy extensions without `contractVersion` may omit `id` and use `n`.)
+
+## Panels and tabs
+
+```ts
+interface Panel {
+  title: string;
+  render(a: { width: number; height: number; focused: boolean; theme: Theme }): string[];   // pure
+  onKey?(key: string): boolean;     // true = consumed, see Keys
+  onFocus?(): void; onBlur?(): void;
+}
+```
+
+```ts
+interface Theme { name: 'dark'|'light'|'mono'; color: boolean; unicode: boolean }
+```
+
+The host owns the tab strip, shown only when one or more panels exist. The panel region sits above the composer, height
+`min(12, 40% of terminal rows)`, collapsed until a panel is focused or opened. `/ext tab <name>` focuses (and opens) a panel; `/ext tab off`
+collapses; Ctrl+] cycles focus through the panels; Esc returns keys to the composer (the panel stays open). While focused, keys go to
+`onKey` first; a key it does not consume is dropped. The panel never receives `escape` or `ctrl+]`: the host consumes both.
+
+**Keys.** `onKey(key)` gets one of `up down left right enter tab backspace space home end pageup pagedown`, otherwise the single typed
+character (`a`, `?`, `/`), or `ctrl+<c>` / `alt+<c>` for the modifier combinations the terminal reports. Pasted text arrives one
+character at a time.
+
+`render` must be pure and fast. The 50 ms budget is wall-clock per render call (`performance.now`). The host clips the result to `height` lines and `width` columns. A render that throws, or takes over 50 ms,
+shows `panel error` in its place and is retried no sooner than 5 s later; it never crashes the window. The panel re-renders on every state
+push and on `invalidate()` (passed to `create`, throttled to 4 per second).
+
+## Settings
+
+```ts
+interface SettingDef { key: string; type: 'string'|'number'|'bool'|'enum'; default: string|number|boolean; help: string; choices?: string[] }
+```
+
+Values live in `~/.quox/extensions.json` on the extension's entry as `settings: { <key>: value }`. `create({ settings })` receives the resolved
+object (defaults overlaid with stored values). `/ext set <name> <key> <value>` validates by type (number: `Number()` and it must be a finite number; bool: `true|yes|on|1` or
+`false|no|off|0`, case-insensitive, anything else is rejected with a message; enum: an exact match to one of `choices`; string: any text), stores it, and calls `onSettings(next)` on the running instance.
+`/ext settings <name>` lists each key with its value, default and help. The extension must be loaded and listed.
+
+## Close
+
+`close()` may return a promise. The host awaits it for at most 500 ms, then drops the instance anyway and logs it. It must be idempotent
+(the host may call it twice) and must free every timer, interval, watcher, device and process listener, because hot reload calls it on each change.
+
+## Hot reload
+
+While an extension is loaded, quoxon watches its `package.json` (`fs.watch`, 2 s debounce, plus a 30 s stat poll because global installs
+replace directories). When the version or mtime changes it awaits `close()` on the old instance (500 ms cap), drops its commands and panel,
+re-imports the entry with a cache-busting `?v=<version>-<mtime>`, and calls `create()` again, then prints `↻ <name> updated <old> -> <new>`.
+Only the entry module is re-imported. A failed reload leaves the old instance closed, prints the error once, and shows `failed: <error>` in
+`/ext list` until the next change. Watchers and timers are cleared on `/ext off`, unload and exit.