quoxcli 0.3.1 → 0.5.0

package/lib/quoxon/api.js

@@ -2,6 +2,7 @@
  * QUOXON server calls. Thin wrapper over the CLI client so the app can be
  * driven by a fake (demo + tests). All routes per docs/QUOXON_EVENTS_v1.md.
  */
+import { otherOrgsWaiting } from '../core/crossOrgApprovals.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { rememberEmail } from '../core/auth.js';
 import { isSessionDead } from './sessionDead.js'; // not signin.js: that loads React + Ink (QUOXON-LATENCY)
@@ -9,23 +10,28 @@ import { buildStreamQuery } from '../commands/chat.js';
 import { loadBundledAssistantsRoster } from '../core/agentAlias.js';
 import { bundledIdentities } from './objects/fetch.js';
 import { recordHeldSlot } from '../commands/slot.js';
-import { askGripe, settleGripe } from '../commands/gripe.js';
+import { askGripe, settleGripe, fileDeterministically } from '../commands/gripe.js';
+import { gripeQueue, fileOrQueue, makeRetryFiler } from './gripeQueue.js';
 import { sendFeedback } from './feedback.js';
 import { fromObjective, fromExecution, fromApproval, sortRows } from './roster.js';
 import { normChoice } from './model.js';
 import { normPrefs as normModelPrefs } from './modelPrefs.js';
 import { createRowsStore } from './rowsStore.js';
 import { createObjectsApi } from './objects/fetch.js';
+import { createDragonReads } from './dragonReads.js';
 import { createKillerApi } from './slash/killerApi.js';
 import { createUndoOps } from './slash/undoApi.js';
 import { resolveDashboardBase, resolveCollectorBase, detectLanIp } from './hostUrls.js';
 import { grantBody } from './consent.js';
+import { runCallMe } from '../core/callMe.js';
 import { loadJourney } from './onboarding/journey.js';
 import { joinServiceUrl } from '../core/config.js';
 import { runVmCommand } from '../core/vmTui.js';
 import { fetchActivity, heldLines } from '../core/hyperion.js';
 import { createPeekFetchers, peekId } from '../core/peek.js';
 import { askAside } from '../core/aside.js';
+import { exportConversationBundle } from '../evidence/bundleExport.js';
+import { addActionItem, listBoard, moveActionItem } from '../core/actionItems.js';
 
 const missing = (e) => e?.status === 404 || e?.status === 405 || e?.status === 501;
 /** Server steer refusal label -> client reason. Unknown labels are 'ambiguous', never "finished". */
@@ -71,13 +77,39 @@ const vaultFailure = (e) => ({ ok: false, status: e?.status, message: e?.message
 const slotsUnlicensed = (e) => e?.status === 403 && /not licen[cs]ed/i.test(`${e?.code || ''} ${e?.body?.error || ''} ${e?.message || ''}`);
 
 /** PRESENCE: only a person at a real terminal is "back". --print, pipes, proof runs and agents are not. */
+const NOTES_OFF = 'NotesQ is not available for this org. Ask an org admin to enable the NotesQ plugin (dashboard, Plugins), or check `quox notes ls` in a terminal.';
+export function noteParts(text) {
+  const t = String(text || '').trim();
+  const first = t.split('\n')[0].trim();
+  const title = first.length > 60 ? `${first.slice(0, 60).trimEnd()}…` : first;
+  return { title, markdown: `# ${title}\n\n${t}\n` };
+}
+async function createNoteFrom(client, text) {
+  const { title, markdown } = noteParts(text);
+  try {
+    const ep = resolveEndpoint('notesq.notes.create');
+    const d = await client.post(ep.path, { service: ep.service, retries: 0, body: { scope: 'org', markdown, properties: {} } });
+    const n = d?.note || {};
+    if (!n.id) return { ok: false, message: 'NotesQ answered without a note id, so nothing is confirmed saved. Check quox notes ls.' };
+    return { ok: true, id: n.id, title: n.title || title };
+  } catch (e) {
+    if (e?.status === 402) return { ok: false, message: 'NotesQ is not licensed for this org. ' + NOTES_OFF };
+    if (e?.status === 403 || e?.status === 404 || e?.status === 503) return { ok: false, message: NOTES_OFF };
+    if (!e?.status && /timed out|timeout|ECONNRESET|socket hang up|network|fetch failed|ETIMEDOUT/i.test(e?.message || '')) return { ok: false, maybeSaved: true, message: 'The save may still have gone through (the server was slow). /notes shows your recent notes; I won\'t retry automatically so you don\'t get a duplicate.' }; // request was sent: the outcome is unknown, not a failure
+    return { ok: false, message: `Could not save the note: ${e?.message || 'request failed'}${e?.status ? ` (HTTP ${e.status})` : ''}.` };
+  }
+}
 export function isInteractiveHuman({ stdin = process.stdin, stdout = process.stdout, env = process.env } = {}) {
   return Boolean(stdin?.isTTY && stdout?.isTTY) && !env.CI;
 }
 
-export function createApi({ client, config, auth, windowOrg = null, reattachBackoff = REATTACH_BACKOFF_MS }) {
+/** A one-line title within the tasks service's 200 character cap. */
+const clipTitle = (g) => { const t = String(g ?? '').replace(/\s+/g, ' ').trim(); return t.length > 200 ? `${t.slice(0, 199)}…` : t; };
+
+export function createApi({ client, config, auth, windowOrg = null, clientForOrg = null, reattachBackoff = REATTACH_BACKOFF_MS, gripeQueuePath = undefined, listSessions = null, awayRetryMs = 3000 }) {
   let holderSessionFn = null;
   const orgId = () => { try { return auth.getOrgId(); } catch { return null; } };
+  const gripeStore = gripeQueue(gripeQueuePath);
   const rowsStore = createRowsStore({ client, config, orgId });
   let credsSeen = null; // credentials-file mtime last seen (credentialsChanged)
   const userId = () => { try { return config.getAuth?.()?.user_id || null; } catch { return null; } };
@@ -134,12 +166,13 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
     err.code = 'reattach_failed';
     throw err;
   }
+const HUMAN_TUI = { 'X-Quox-Human-Action': 'tui' }; // DND contract: only a human action in the TUI sends this, never a restart or internal path
   /** PRESENCE auto-clear: the human's own first real action. -> { ok, cleared, welcome } (welcome once: { away_text, via }). Never throws. */
   async function noteActivity(action, { quiet = false, interactive = isInteractiveHuman() } = {}) {
     if (!interactive) return { ok: false, cleared: false, welcome: null, skipped: 'not interactive' };
     try {
       const ep = resolveEndpoint('presence.activity');
-      const d = await client.post(ep.path, { service: ep.service, retries: 0, timeout: 6000, body: { action, org_id: orgId(), ...(quiet ? { quiet: true } : {}) } });
+      const d = await client.post(ep.path, { service: ep.service, retries: 0, timeout: 6000, headers: HUMAN_TUI, body: { action, org_id: orgId(), ...(quiet ? { quiet: true } : {}) } });
       return { ok: true, cleared: d?.cleared === true, welcome: d?.welcome || null };
     } catch (e) { return { ok: false, cleared: false, welcome: null, status: e?.status || null }; }
   }
@@ -147,9 +180,13 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
     ...createKillerApi({ client }),
     orgId,
     undoOps: createUndoOps({ client, orgId }), // /undo
+    /** /note: same call as `quox notes new` (org scope). -> { ok, id, title } | { ok:false, message } */
+    createNote: (text) => createNoteFrom(client, text),
     userId,
     /** /peek <id>: the same lookup as `quox peek`, in this window's org. -> peekId result */
     peek: (id) => peekId(id, createPeekFetchers({ client, orgId })),
+    /** /evidence, /ward: the signed bundle of one conversation, written to ~/quox-evidence (same export as `quox evidence bundle`). */
+    evidenceExport: (corr) => exportConversationBundle({ client, corr }),
     /** /aside: a no-tools, no-conversation question (core/aside.js). turns = recent exchanges, read-only context. */
     aside: (question, turns = []) => askAside(client, { question, turns }),
     /** @mention hosts: the Bastion inventory (same read as `quox fleet hosts`). -> [{ id, group, health }] */
@@ -158,6 +195,25 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 8000 });
       return (listOf(d, 'hosts') || []).map(h => ({ id: h.id, group: h.group || '', health: h.status?.health || '' }));
     },
+    /** QUOXON objective offer: `quox objective create <goal> --checkpoint` + `start` (same endpoints). -> { id, status } */
+    async startObjective(goal, loop = null) {
+      const c = resolveEndpoint('objectives.create');
+      // QLOOP: a loop offer creates a LOOP (server-derived scope + goal), never a plan under the loop's name.
+      const body = loop ? { title: String(goal).slice(0, 200), description: String(goal), execution_mode: 'loop', capability_scope: loop.capability_scope, goal_condition: loop.goal_condition,
+        ...(loop.until ? { until: loop.until } : {}), ...(loop.every_seconds ? { every_seconds: loop.every_seconds } : {}), ...(loop.max_iterations ? { max_iterations: loop.max_iterations } : {}), ...(loop.max_duration_seconds ? { max_duration_ms: loop.max_duration_seconds * 1000 } : {}), ...(Array.isArray(loop.done_check) && loop.done_check.length ? { done_check: loop.done_check } : {}) }
+        : { title: clipTitle(goal), description: String(goal), checkpoint_after_each_task: true }; // the tasks service caps a title at 200; the whole ask rides in the description
+      const made = await client.post(c.path, { service: c.service, body });
+      if (!made?.id) throw new Error('the server answered without an objective id');
+      const st = resolveEndpoint('objectives.start', { id: made.id });
+      const started = await client.post(st.path, { service: st.service, body: {} });
+      return { id: made.id, status: started?.status || 'started' };
+    },
+    /** An objective with its tasks (the same read as `quox objective get`), for the chat's report-back. */
+    async objectiveGet(id) {
+      const ep = resolveEndpoint('objectives.get', { id: encodeURIComponent(id) });
+      const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 8000 });
+      return d?.objective || d;
+    },
     /** @mention tasks: the newest objectives (one read, cached by the composer for the session). -> [{ id, title, status }] */
     async mentionTasks() {
       const ep = resolveEndpoint('objectives.list');
@@ -203,6 +259,7 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
     },
     /** Inline object views (objects/): skill, workflow, crystal, agent, memory, rules, proof, reconcile. */
     objects: createObjectsApi({ client, orgId, profile: config?._effectiveProfile || null }),
+    dragonReads: createDragonReads({ client }), // the companion dragons' jobs: bounded read-only reads (dragonReads.js)
     /** /model choice persisted on the active profile ({ provider, model? } only, never a key); null = auto. */
     modelChoice() { try { return normChoice(config.getActiveProfile?.()?.chat_model); } catch { return null; } },
     setModelChoice(choice) {
@@ -455,6 +512,27 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       try { const r = await fetch(`${String(base).replace(/\/+$/, '')}/install`, { method: 'GET', signal: ctl.signal }); try { await r.body?.cancel?.(); } catch { /* drained */ } return { ok: r.ok, status: r.status }; }
       catch { return null; } finally { clearTimeout(t); }
     },
+    /** TUI-STATUS: the registered server this quox runs on -> { name, role, remote } | null (unregistered or any failure). */
+    async serverChip() {
+      const { resolveServerChip } = await import('./serverChip.js');
+      const { loadRegistry } = await import('../server/devServers.js');
+      let registry = { servers: {} };
+      try { registry = { servers: (await loadRegistry({ client })).servers }; } catch { /* unreadable registry: no purpose shown */ }
+      return resolveServerChip({
+        registry,
+        url: config.getActiveProfile?.()?.url || config.getBaseUrl?.() || null,
+        listHosts: async () => { const ep = resolveEndpoint('v1.fleet.hosts.list'); const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 5000 }); return d?.hosts || d; }
+      });
+    },
+    /** DEVFLEET: the registered dev servers (same rows as `quox server list`) -> rows[]; throws on a Bastion read failure. */
+    async devServers() {
+      const [{ loadRegistry, buildRows, hereIdentity }] = [await import('../server/devServers.js')];
+      const ep = resolveEndpoint('v1.fleet.hosts.list');
+      const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 5000 });
+      const hosts = d?.hosts || d;
+      if (!Array.isArray(hosts)) throw new Error('unexpected response');
+      { const reg = await loadRegistry({ client }); return buildRows(hosts, { servers: reg.servers, defaults: reg.defaults }, hereIdentity()); }
+    },
     serverUrl() { try { return new URL(config.getServiceUrl('collector')).origin; } catch { return null; } },
     /** /config settings on the active profile. */
     settings() { try { const q = config.getActiveProfile?.()?.quoxon; return q && typeof q === 'object' ? { ...q } : {}; } catch { return {}; } },
@@ -478,16 +556,23 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
      * file when the agent did not). The client asks the user first, so the agent is told to file without asking.
      * -> { ok:true, response, url, superseded, notes } | { ok:false, message }.
      */
-    async gripe(text, { yes = true } = {}) {
-      try {
-        const options = { yes };
-        const data = await askGripe({ client, complaint: text, yes, orgId: orgId() });
-        const r = await settleGripe({ client, data, complaint: text, options, orgId: orgId() });
-        return { ok: true, response: r.response, url: r.url, superseded: r.superseded, notes: r.notes };
-      } catch (e) {
-        return { ok: false, message: e?.status ? `HTTP ${e.status}: ${e.message}` : (e?.message || 'failed') };
-      }
+    async gripe(text, { yes = true, repo = null } = {}) {
+      return fileOrQueue({
+        text, repo, queue: gripeStore,
+        run: async (key) => {
+          const options = { yes, idempotencyKey: key, queueRetryable: true, ...(repo ? { repo } : {}) };
+          const data = await askGripe({ client, complaint: text, yes, orgId: orgId() });
+          const r = await settleGripe({ client, data, complaint: text, options, orgId: orgId() });
+          return { response: r.response, url: r.url, superseded: r.superseded, notes: r.notes };
+        },
+      });
     },
+    /** GRIPE-QUEUE: file what is queued (at most once per 2 minutes). -> { ran, filed:[{text,url}], expired:[{text}], pending }. */
+    async gripeRetry({ force = false } = {}) {
+      return gripeStore.retry(makeRetryFiler({ fileDeterministically, client, orgId: orgId() }), { force });
+    },
+    /** GRIPE-QUEUE: queued plus recently filed gripes, oldest first. */
+    gripes() { return gripeStore.list(); },
     /**
      * /feedback: POST the previewed payload to the public quox.ai feedback API (not the org's server, not GitHub).
      * Anonymous by design: no token, cookie, org or profile goes with it. -> { ok:true, id, url } | { ok:false, message }.
@@ -503,6 +588,31 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       if (!rows) throw new Error('unexpected response');
       return rows.filter(r => r.is_enabled !== false && r.is_enabled !== 0).map(r => r.plugin_id).filter(Boolean);
     },
+    /** /todo: add an Action Tracker item as the logged-in user (the same core as `quox actions add`). Throws on failure. -> the item. */
+    async todoAdd(text) { return addActionItem(client, { title: text }); },
+    /** /todos: the whole board { backlog, doing, done }, every page. Throws on failure so it never reads as "none". */
+    async todoList() { return listBoard(client); },
+    /** /todo move: move one item (real id) to todo, doing or done. -> the item. */
+    async todoMove(id, status) { return moveActionItem(client, id, status); },
+    /** /callmeforapprovals: { action, after, quiet } -> { data, changed } (same core as `quox approvals call-me`). Throws on failure. */
+    async callMe(args) { return runCallMe(client, args); },
+    /** -> [{ plugin_id, version, is_enabled, ... }] every plugin installed for the org (GET plugins.list, as `quox plugin list`). Throws on failure. */
+    async pluginList() {
+      const id = orgId();
+      if (!id) throw new Error('no org');
+      const ep = resolveEndpoint('plugins.list', { orgId: id });
+      const rows = listOf(await client.get(ep.path, { service: ep.service, retries: 0 }), 'plugins', 'data', 'items');
+      if (!rows) throw new Error('unexpected response');
+      return rows;
+    },
+    /** One installed plugin's record (GET plugins.get, as `quox plugin get`), or null when unknown (404). */
+    async pluginGet(pluginId) {
+      const id = orgId();
+      if (!id) throw new Error('no org');
+      const ep = resolveEndpoint('plugins.get', { orgId: id, pluginId });
+      try { const d = await client.get(ep.path, { service: ep.service, retries: 0 }); return d?.plugin || d; }
+      catch (e) { if (e?.status === 404) return null; throw e; }
+    },
     /** Fleet hosts already connected (tips skip the QuoxAgent tip when > 0). GET agents list; throws on failure so a failure never reads as "no hosts". */
     async hostCount() {
       const ep = resolveEndpoint('v1.agents.list');
@@ -522,24 +632,108 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
      * ("quox1 (Adam)"); `fast` answers once the line is in the slot, without waiting on the chat-app bridges.
      * -> { ok:true, message } | { ok:false, message, status }.
      */
+    /**
+     * Does this slot name exist in one of the user's OWN orgs? Reads only, never sends. Same rules as slotSay: name@org
+     * targets one membership; two other orgs holding the name is { found:true, ambiguous:true } (the send path then asks).
+     * -> { found:boolean, ambiguous?:true }. Throws when the membership list itself cannot be read.
+     */
+    async slotLocate(name) {
+      const slug = (x) => String(x || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+      const clientFor = async (oid) => (oid === orgId() ? client : clientForOrg(oid));
+      const listed = async (oid, nm) => {
+        const ep = resolveEndpoint('v1.slots.list');
+        const rows = listOf(await (await clientFor(oid)).get(ep.path, { service: ep.service, retries: 0 }), 'slots') || [];
+        return rows.some(r => String(r?.name || '').toLowerCase() === String(nm).toLowerCase());
+      };
+      const oe = resolveEndpoint('orgs.list'); const d = await client.get(oe.path, { service: oe.service });
+      const orgs = (Array.isArray(d) ? d : (d?.organizations || d?.orgs || d?.data || [])).filter(o => o?.id).map(o => ({ id: o.id, name: o.name || o.id }));
+      const at = String(name).indexOf('@');
+      if (at > 0) {
+        const raw = String(name).slice(at + 1); const frag = slug(raw);
+        const hit = frag ? orgs.filter(o => o.id === raw || slug(o.name) === frag) : [];
+        const pick = hit.length ? hit : orgs.filter(o => frag && slug(o.name).startsWith(frag));
+        if (pick.length !== 1 || !clientForOrg) return { found: false };
+        return { found: await listed(pick[0].id, String(name).slice(0, at)) };
+      }
+      if (await listed(orgId(), name)) return { found: true };
+      if (!clientForOrg) return { found: false };
+      const hits = [];
+      for (const o of orgs) { if (o.id === orgId()) continue; try { if (await listed(o.id, name)) hits.push(o); } catch { /* an org that cannot be listed is not a candidate */ } }
+      return hits.length > 1 ? { found: true, ambiguous: true } : { found: hits.length === 1 };
+    },
     /** SLOTS-REPLY2: the window registers how to name its checkout session; slotSay then sends it as holder_session. */
     bindHolderSession(fn) { holderSessionFn = typeof fn === 'function' ? fn : null; },
-    async slotSay(name, text, { from = null, fast = false, roomSession = null, fromSlot = null, holderSession = holderSessionFn ? holderSessionFn() : null } = {}) {
-      const ep = resolveEndpoint('v1.slots.say', { name });
-      try {
+    async slotSay(name, text, { from = null, fast = false, roomSession = null, fromSlot = null, holderSession = holderSessionFn ? holderSessionFn() : null, anyOrg = true } = {}) {
+      const send = async (cl, oid) => {
+        const ep = resolveEndpoint('v1.slots.say', { name });
         // SLOTS-REPLY: fromSlot is this window's held slot, its reply address (the server verifies the hold).
-        const d = await client.post(ep.path, { service: ep.service, retries: 0, body: { text, org_id: orgId(), ...(roomSession ? { room_session: roomSession } : from ? { from } : {}), ...(!roomSession && fromSlot ? { from_slot: fromSlot } : {}), ...(!roomSession && holderSession ? { holder_session: holderSession } : {}), ...(fast ? { bridge_report: false } : {}) } });
+        const d = await cl.post(ep.path, { service: ep.service, retries: 0, body: { text, org_id: oid, ...(roomSession ? { room_session: roomSession } : from ? { from } : {}), ...(!roomSession && fromSlot ? { from_slot: fromSlot } : {}), ...(!roomSession && holderSession ? { holder_session: holderSession } : {}), ...(fast ? { bridge_report: false } : {}) } });
         return { ok: true, message: d?.message || null, roomPending: d?.room_pending === true, presence: d?.presence || null, humanPresence: d?.human_presence || null };
-      } catch (e) {
+      };
+      const fail = (e) => {
         if (slotsUnlicensed(e)) return { ok: false, unlicensed: true, status: 403, message: SLOTS_UNLICENSED };
         return { ok: false, message: e?.status === 404 ? `no slot named ${name}` : (e?.message || 'failed'), status: e?.status || null };
+      };
+      // The user's own memberships (orgs.list is scoped to the caller); nothing outside this list is ever tried.
+      const memberOrgs = async () => {
+        try {
+          const oe = resolveEndpoint('orgs.list'); const d = await client.get(oe.path, { service: oe.service });
+          return (Array.isArray(d) ? d : (d?.organizations || d?.orgs || d?.data || [])).filter(o => o?.id).map(o => ({ id: o.id, name: o.name || o.id }));
+        } catch { return []; }
+      };
+      const slug = (x) => String(x || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+      const clientFor = async (oid) => (oid === orgId() ? client : clientForOrg(oid));
+      const at = String(name).indexOf('@');
+      if (at > 0) { // name@org: exactly that membership, never the others
+        const base = String(name).slice(0, at); const frag = slug(String(name).slice(at + 1));
+        const orgs = anyOrg && clientForOrg ? await memberOrgs() : [];
+        const hit = frag ? orgs.filter(o => o.id === String(name).slice(at + 1) || slug(o.name) === frag) : [];
+        const pick = hit.length ? hit : orgs.filter(o => frag && slug(o.name).startsWith(frag));
+        if (pick.length !== 1) return { ok: false, status: 404, message: pick.length ? `"${name}" matches several of your orgs: ${pick.map(o => `${base}@${slug(o.name)}`).join(', ')}` : `no slot named ${name}` };
+        try { const r = await send(await clientFor(pick[0].id), pick[0].id); return { ...r, viaOrgId: pick[0].id, viaOrgName: pick[0].name }; } catch (e) { return { ...fail(e), viaOrgId: pick[0].id, viaOrgName: pick[0].name }; }
       }
+      let first;
+      try { return await send(client, orgId()); } catch (e) { first = fail(e); }
+      // HITL-INBOX-BAR: a window in another org cannot see a slot that lives in the profile's home org. Same user, same
+      // sessions (not a cross-tenant leak): look in the user's other orgs only, each on a token for THAT org.
+      if (!anyOrg || first.status !== 404 || !clientForOrg) return first;
+      const tried = new Set([orgId()]);
+      const orgs = await memberOrgs();
+      const nameOf = (oid) => orgs.find(o => o.id === oid)?.name || null;
+      // 1. Find it without sending: list slots per other org. Two orgs hold the name: ask, never pick.
+      const hits = [];
+      for (const o of orgs) {
+        if (tried.has(o.id)) continue;
+        try {
+          const ep = resolveEndpoint('v1.slots.list');
+          const rows = listOf(await (await clientFor(o.id)).get(ep.path, { service: ep.service, retries: 0 }), 'slots') || [];
+          if (rows.some(r => String(r?.name || '').toLowerCase() === String(name).toLowerCase())) hits.push(o);
+        } catch { /* an org that cannot be listed is not a candidate here; the probe below still covers it */ }
+      }
+      if (hits.length > 1) {
+        const choices = hits.map(o => ({ orgId: o.id, orgName: o.name, ref: `${name}@${slug(o.name)}` }));
+        return { ok: false, ambiguous: true, choices, status: null, message: `"${name}" exists in more than one of your orgs: ${choices.map(c => `${c.ref} (${c.orgName})`).join(', ')}. Say which, e.g. /say ${choices[0].ref} ...` };
+      }
+      const order = hits.map(o => o.id);
+      if (!order.length) { // nothing listed it: fall back to trying the home org, then each membership
+        try { const home = config.getAuth?.()?.org_id; if (home) order.push(home); } catch { /* no home org known */ }
+        for (const o of orgs) order.push(o.id);
+      }
+      for (const oid of order) {
+        if (tried.has(oid)) continue; tried.add(oid);
+        try {
+          const cl = await clientFor(oid);
+          const r = await send(cl, oid);
+          return { ...r, viaOrgId: oid, viaOrgName: nameOf(oid) };
+        } catch (e) { const f = fail(e); if (f.status !== 404) return { ...f, viaOrgId: oid, viaOrgName: nameOf(oid) }; } // the slot is there but refused: that is the real answer
+      }
+      return first;
     },
     /** QUOXON-BROADCAST: fan a message out to the org's held slots. -> { ok:true, data } | { ok:false, message, status }. */
-    async slotBroadcast({ text, slots = null, priority = 'normal', ack = false, from = null } = {}) {
+    async slotBroadcast({ text, slots = null, priority = 'normal', ack = false, active = false, dryRun = false, from = null } = {}) {
       const ep = resolveEndpoint('v1.slots.broadcast');
       try {
-        const data = await client.post(ep.path, { service: ep.service, retries: 0, body: { text, priority, ack, org_id: orgId(), ...(slots ? { slots } : {}), ...(from ? { from } : {}) } });
+        const data = await client.post(ep.path, { service: ep.service, retries: 0, body: { text, priority, ack, ...(active ? { active: true } : {}), ...(dryRun ? { dry_run: true } : {}), org_id: orgId(), ...(slots ? { slots } : {}), ...(from ? { from } : {}) } });
         return { ok: true, data };
       } catch (e) {
         if (slotsUnlicensed(e)) return { ok: false, unlicensed: true, status: 403, message: SLOTS_UNLICENSED };
@@ -563,6 +757,18 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       const ep = resolveEndpoint('v1.slots.broadcast.ack', { id });
       try { return { ok: true, data: await client.post(ep.path, { service: ep.service, retries: 0, body: { slot, org_id: orgId() } }) }; } catch (e) { return { ok: false, message: e?.message || 'failed', status: e?.status || null }; }
     },
+    /** QLOOP-LIVE: the org's loops, newest first (GET /api/v1/loops) -> { loops:[{ objective_id, title, state, created_at }] }. */
+    async loopList() {
+      return client.get('/api/v1/loops', { service: 'collector', retries: 0, timeout: 8000, query: { limit: 20 } });
+    },
+    /** QLOOP-LIVE: one loop's snapshot (GET /api/v1/loops/:id). Throws on failure (the card decides what a failure means). */
+    async loopSnapshot(id) {
+      return client.get(`/api/v1/loops/${encodeURIComponent(id)}`, { service: 'collector', retries: 0, timeout: 8000 });
+    },
+    /** QLOOP-LIVE: one loop's events (SSE; ?since resumes). Yields { event_seq, type, ... }; ends after loop.finished or a drop. */
+    async *loopEvents(id, { since = null } = {}, signal) {
+      yield* client.stream(`/api/v1/loops/${encodeURIComponent(id)}/events`, { service: 'collector', query: { since }, signal, untilClose: true });
+    },
     /** QUOXON-MESH: the slot's live messages (SSE). Yields { type: 'connected' | 'slot.message' | 'reconnect' }. */
     async *slotStream(name, { since = null, excludeFrom = null, session = null } = {}, signal) {
       const ep = resolveEndpoint('v1.slots.stream', { name });
@@ -678,6 +884,20 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       if (!windowOrg) { const e = new Error('Org switching is not available in this mode.'); e.code = 'no_window_org'; throw e; }
       return windowOrg.switchTo(targetId);
     },
+    /**
+     * "also make default" from the /org picker: the same profile-wide change as `quox org switch <org>` in a shell
+     * (moves the shared session and rewrites the profile's stored org + token). This window's own org is untouched.
+     */
+    async makeOrgDefault(targetId) {
+      const ep = resolveEndpoint('auth.switch-org');
+      const data = await client.post(ep.path, { service: ep.service, body: { org_id: targetId } });
+      if (!data?.org?.id) { const e = new Error('The server did not confirm the switch.'); e.code = 'switch_failed'; throw e; }
+      const a = config.getAuth() || {};
+      a.org_id = data.org.id; a.org_name = data.org.name; a.org_slug = data.org.slug; a.org_role = data.role;
+      if (data.access_token) a.access_token = data.access_token;
+      config.setAuth(a);
+      return { id: data.org.id, name: data.org.name };
+    },
     /** The window's own org id when it differs from the profile's (carried across /restart), else null. */
     windowOrgId: () => windowOrg?.current()?.id || null,
     /** -> [{ id, name, description, edition, version, decayState }] ; the org's QSKL procedural skills (read-only list; Crystals are a separate store). */
@@ -716,8 +936,26 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
           return l.map(e => fromExecution(e, now, { userId: userId() })).filter(Boolean);
         })
       ]);
+      // Attached agents (org list, owner/admin) and this box's live `claude --resume` processes. Neither is a work row:
+      // they ride on the source as `items` and /roster prints them (rosterSessions.js).
+      const itemsSrc = (id, label, fn) => fn().then(
+        (items) => ({ id, label, state: 'connected', rows: [], items, count: items.length }),
+        (e) => ({ id, label, rows: [], items: [], count: 0, state: missing(e) ? 'unavailable' : 'error', note: missing(e) ? 'no list endpoint on this server' : (e?.message || 'failed') }));
+      const extra = await Promise.all([
+        itemsSrc('agents', 'attached agents', async () => {
+          const ep = resolveEndpoint('agent-attach.list');
+          const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+          const l = listOf(d, 'attaches'); if (!l) throw new Error('unexpected response');
+          return l;
+        }),
+        itemsSrc('boxsessions', "this box's sessions", async () => {
+          if (listSessions) return await listSessions();
+          const [{ listLiveSessions }, { spawnSync }] = await Promise.all([import('../core/governedSession.js'), import('node:child_process')]);
+          return listLiveSessions({ spawnSync, pid: process.pid });
+        })
+      ]);
       const unlisted = [
-        { id: 'agents', label: 'attached agents', state: 'unavailable', count: 0, note: 'no org-wide list endpoint' },
+        ...extra.map(({ rows, ...rest }) => rest),
         { id: 'devsessions', label: 'dev sessions', state: 'unavailable', count: 0, note: 'listed per host only (quox dev sessions <host>)' }
       ];
       return { rows: sortRows(parts.flatMap(p => p.rows)), sources: [...parts.map(({ rows, ...rest }) => rest), ...unlisted] };
@@ -753,18 +991,31 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       return { situation, approvals };
     },
     /** PRESENCE: PUT /api/v1/presence (/afk, /sleep, /back, a typed turn). -> { ok:true, presence, notice } | { ok:false, message, status }. */
-    async setPresence(state, { note, slots } = {}) {
+    async setPresence(state, { note, slots, dnd = false, human = false } = {}) {
       const ep = resolveEndpoint('presence.set');
       try {
-        const d = await client.put(ep.path, { service: ep.service, retries: 0, timeout: 8000, body: { state, org_id: orgId(), ...(note ? { note } : {}), ...(Array.isArray(slots) && slots.length ? { slots } : {}) } });
+        const d = await client.put(ep.path, { service: ep.service, retries: 0, timeout: 8000, ...(human ? { headers: HUMAN_TUI } : {}), body: { state, org_id: orgId(), ...(dnd ? { dnd: true } : {}), ...(note ? { note } : {}), ...(Array.isArray(slots) && slots.length ? { slots } : {}) } });
         return { ok: true, presence: d?.presence || null, notice: d?.notice || null };
       } catch (e) { return { ok: false, message: e?.message || 'failed', status: e?.status || null }; }
     },
+    /** AFK-SURVIVES-RESTART: read-only GET /api/v1/presence/me. -> { ok:true, presence } | { ok:false, status }. Never throws, never writes. */
+    async getPresence() {
+      try {
+        const ep = resolveEndpoint('presence.get', { who: 'me' });
+        const d = await client.get(ep.path, { service: ep.service, query: { org_id: orgId() }, retries: 0, timeout: 6000 });
+        return { ok: true, presence: d?.presence || null };
+      } catch (e) { return { ok: false, message: e?.message || 'failed', status: e?.status || null }; }
+    },
     noteActivity,
     /** E5 /away: GET /api/v1/away?since=<iso> -> { since, until, items, activity, blind }. Throws on non-2xx. */
     async away(since) {
       const ep = resolveEndpoint('away.digest');
-      return client.get(ep.path, { service: ep.service, query: { since }, retries: 0, timeout: 15000 });
+      const read = () => client.get(ep.path, { service: ep.service, query: { since }, retries: 0, timeout: 15000 });
+      const first = await read();
+      // AWAY-RETRY: the first calls after a fresh sign-in can time out; try those sources once more before saying "Can't see".
+      if (!(first?.blind || []).some((b) => /timed? ?out|timeout/i.test(String(b?.reason || '')))) return first;
+      await new Promise((r) => setTimeout(r, awayRetryMs));
+      try { return (await read()) || first; } catch { return first; } // the retry also failing leaves the honest first answer
     },
     /** Facts for /observers, each part on its own: { lucid, learning:[{ id, label, state, text }] }. */
     async observers() {
@@ -823,6 +1074,31 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       }
     },
     /** /connect status: the org vault list (the only source a user can read). -> { ok:true, rows } | { ok:false, error }. */
+    /** LAZY-AI-CLI: which vendor CLIs (claude-code, codex) this server has. Never throws. */
+    async providerCliStatus() {
+      const ep = resolveEndpoint('v1.providers.cli.status');
+      try {
+        const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+        return Array.isArray(d?.tools) ? { ok: true, tools: d.tools } : { ok: false, error: 'unexpected response' };
+      } catch (e) { return { ok: false, status: e?.status, missing: missing(e), error: e?.status ? `HTTP ${e.status} ${e.message || ''}`.trim() : (e?.message || 'failed') }; }
+    },
+    /** The install plan: source, exact package + version, download size. Instance admin only (403 otherwise). Never throws. */
+    async providerCliPlan(tool) {
+      const ep = resolveEndpoint('v1.providers.cli.plan', { tool });
+      try { const d = await client.get(ep.path, { service: ep.service, retries: 0 }); return d?.ok ? d : { ok: false, error: d?.message || 'unexpected response' }; }
+      catch (e) { return { ok: false, status: e?.status, missing: missing(e), error: e?.body?.message || e?.message || 'failed' }; }
+    },
+    /** Start an install job (the server audits it). Never throws. */
+    async providerCliInstall(tool, { approvalId = null } = {}) {
+      const ep = resolveEndpoint('v1.providers.cli.install', { tool });
+      try { return await client.post(ep.path, { service: ep.service, body: approvalId ? { approval_id: approvalId } : {}, retries: 0 }); }
+      catch (e) { return { ok: false, status: e?.status, error: e?.body?.message || e?.message || 'failed' }; }
+    },
+    async providerCliJob(id) {
+      const ep = resolveEndpoint('v1.providers.cli.job', { id });
+      try { return await client.get(ep.path, { service: ep.service, retries: 0 }); }
+      catch (e) { return { state: 'unknown', error: e?.message || 'failed', status: e?.status }; }
+    },
     async connections() {
       try {
         const ep = resolveEndpoint('vault.list', { orgId: orgId() });
@@ -905,12 +1181,68 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
     /** /hyperion: held VMs and who holds them, one line each (read only, GET /api/v1/proxmox/activity). */
     async hyperion() { const data = await fetchActivity(client); return { lines: heldLines(data), tone: data.nodes_error || data.pool_error ? 'warn' : undefined }; },
     approvals: listApprovals,
+    /** HITL-INBOX-BAR: the owner's latest inbox items (any kind, active), newest first. Throws on failure, never reads as empty. */
+    async inboxItems({ limit = 30, page = 1 } = {}) {
+      const ep = resolveEndpoint('inbox.list', { orgId: orgId() });
+      const data = await client.get(ep.path, { service: ep.service, query: page > 1 ? { limit, page } : { limit } });
+      const items = data?.items || data?.data || data || [];
+      return Array.isArray(items) ? items : [];
+    },
+    /** TUI-MAIL: connected InboxQ mailboxes (GET /api/v1/inboxq/accounts, the `quox mail accounts` read). Throws on failure, never reads as none. */
+    async mailAccounts() {
+      const ep = resolveEndpoint('inboxq.accounts.list');
+      const data = await client.get(ep.path, { service: ep.service, retries: 0 });
+      return Array.isArray(data?.accounts) ? data.accounts : [];
+    },
+    /** TUI-MAIL: triaged messages (GET /api/v1/inboxq/messages, the `quox mail list` read). Throws on failure. */
+    async mailMessages({ limit = 10, zone } = {}) {
+      const ep = resolveEndpoint('inboxq.messages.list');
+      const data = await client.get(ep.path, { service: ep.service, retries: 0, query: { limit, offset: 0, ...(zone ? { zone } : {}) } });
+      return Array.isArray(data?.messages) ? data.messages : [];
+    },
+    /** TUI-MAIL: one message with its stored body (GET /api/v1/inboxq/messages/:id, read only: no body fetch from the mailbox). */
+    async mailMessage(id) {
+      const ep = resolveEndpoint('inboxq.messages.get', { id });
+      const data = await client.get(ep.path, { service: ep.service, retries: 0 });
+      return data?.message || null;
+    },
+    /** Every inbox item, paged (100 per page, capped at maxPages). Throws on failure, never returns a partial list as the whole. */
+    async inboxAllItems({ pageSize = 100, maxPages = 20 } = {}) {
+      const ep = resolveEndpoint('inbox.list', { orgId: orgId() });
+      const all = [];
+      for (let page = 1; page <= maxPages; page++) {
+        const data = await client.get(ep.path, { service: ep.service, query: { limit: pageSize, page } });
+        const items = data?.items || data?.data || (Array.isArray(data) ? data : []);
+        all.push(...items);
+        if (!(data?.pagination?.has_more) || !items.length) break;
+      }
+      return all;
+    },
+    /** One inbox item in full (the server marks it read for this user as a side effect). */
+    async inboxItem(itemId) {
+      const ep = resolveEndpoint('inbox.get', { orgId: orgId(), itemId: encodeURIComponent(itemId) });
+      const data = await client.get(ep.path, { service: ep.service });
+      return data?.item || data;
+    },
+    /** Mark one inbox item read (PATCH .../inbox/:id/read). */
+    async inboxMarkRead(itemId, isRead = true) {
+      const ep = resolveEndpoint('inbox.get', { orgId: orgId(), itemId: encodeURIComponent(itemId) });
+      return client.patch(`${ep.path}/read`, { service: ep.service, body: { is_read: Boolean(isRead) } });
+    },
     /** Org-wide approvals awaiting a human (the dashboard header's server-side count, inbox stats awaiting_human). */
     async approvalStats() {
       const ep = resolveEndpoint('inbox.stats.list', { orgId: orgId() });
       const d = await client.get(ep.path, { service: ep.service });
       return { pending: Number(d?.pending_approvals ?? 0), awaiting: Number(d?.awaiting_human ?? 0) };
     },
+    /** Approvals waiting in the user's OTHER orgs: counts only, per-org stats on that org's own token (core/crossOrgApprovals). */
+    async otherOrgApprovals() { return otherOrgsWaiting({ client, currentOrgId: orgId() }); },
+    /** APPROVALS-AUTO: another org's open approvals, read with the caller's OWN token (auth checks membership of the URL org, not the token's org claim). */
+    async approvalsInOrg(org) {
+      const ep = resolveEndpoint('inbox.approvals.open', { orgId: org });
+      const data = await client.get(ep.path, { service: ep.service, retries: 0 });
+      return Array.isArray(data?.approvals) ? data.approvals.map((a) => a.item).filter(Boolean) : [];
+    },
     /** GET /api/v1/approvals/:id/result -> { status, result, executed_at } ; null when unknown (404) */
     async approvalResult(approvalId) {
       const ep = resolveEndpoint('v1.approvals.result', { id: approvalId });
@@ -918,14 +1250,14 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       catch (e) { if (e?.status === 404) return null; throw e; }
     },
     /** quox ask: answer a decision with one of its option keys (and an optional note). */
-    async answerDecision(itemId, option, { note = null, stepUp = null, bulk = false } = {}) {
-      const ep = resolveEndpoint('inbox.respond', { orgId: orgId(), itemId });
+    async answerDecision(itemId, option, { note = null, stepUp = null, bulk = false, org = null } = {}) {
+      const ep = resolveEndpoint('inbox.respond', { orgId: org || orgId(), itemId }); // org: APPROVALS-AUTO answers another org's card by its URL org (the server checks membership of THAT org)
       const r = await client.post(ep.path, { service: ep.service, headers: stepUp || {}, body: { action: 'answer', option, ...(bulk ? { bulk: true } : {}), ...(note ? { comment: String(note).slice(0, 4000) } : {}) } });
       if (stepUp && Object.keys(stepUp).length) noteActivity('answer', { quiet: true }); // PRESENCE: answering is the owner being back
       return r;
     },
-    async respond(itemId, action, { via = null, stepUp = null, reason = null, bulk = false } = {}) {
-      const ep = resolveEndpoint('inbox.respond', { orgId: orgId(), itemId });
+    async respond(itemId, action, { via = null, stepUp = null, reason = null, bulk = false, org = null } = {}) {
+      const ep = resolveEndpoint('inbox.respond', { orgId: org || orgId(), itemId });
       const tag = via ? `via quoxon ${via}` : 'via quoxon';
       const why = reason ? String(reason).trim().slice(0, 4000) : '';
       const r = await client.post(ep.path, { service: ep.service, headers: stepUp || {}, body: { action, ...(bulk ? { bulk: true } : {}), comment: why ? `${why} (${tag})` : tag, ...(why ? { reason: why } : {}) } });
@@ -943,6 +1275,11 @@ export function createApi({ client, config, auth, windowOrg = null, reattachBack
       const ep = resolveEndpoint('stepup.status');
       return client.get(ep.path, { service: ep.service });
     },
+    /** /verify-email: the SAME endpoint `quox admin users verify-email` calls. The server's checks are the only gate; the caller supplies a fresh one-shot step-up token. */
+    async verifyEmail({ email, reason, userId = null, stepUp = {} }) {
+      const ep = resolveEndpoint('admin.users.verify_email');
+      return client.post(ep.path, { service: ep.service, headers: stepUp, body: { email, reason, ...(userId ? { user_id: userId } : {}) } });
+    },
     /** QUOXON-STEPUP part B: override ONE blocked action. Needs a live override-scoped step-up token. */
     async override({ blockId, blockType, reason, agentId = null, action = null, stepUp = {} }) {
       const ep = resolveEndpoint('safety.override');