quoxcli 0.0.0-stage → 0.2.0

package/lib/core/agentAlias.js

@@ -0,0 +1,163 @@
+/**
+ * Agent display-name alias resolution — DEVSUITE-GRIPE-P7 / quox#567 (CLI
+ * half only; server-side alias resolution stays open in #567).
+ *
+ * `quox agent attach vulcan` failed because the registry id is `forge` —
+ * "VULCAN" is only the agent's display name (identity.name in
+ * src/config/entities/assistants/forge.json), never sent to any API. This
+ * module resolves a non-matching agent id case-insensitively against the
+ * core assistants roster BEFORE the attach/detach/attach-status/
+ * attach-heartbeat/exec/grant-attach commands call the real API, so the
+ * canonical registry id is always what goes over the wire.
+ *
+ * Two sources, combined:
+ *   - the collector's no-auth-gate `/api/v1/tools/agents` route, which is
+ *     the live, authoritative list of agent ids this deployment currently
+ *     recognises (but carries NO display names — it's a tool-permission
+ *     map keyed by id);
+ *   - the bundled assistants roster (src/config/entities/assistants/*.json,
+ *     shipped inside this same repo checkout) for identity.name /
+ *     identity.shortName, the only source of display names.
+ * A live-roster failure (network down, route not deployed yet) degrades to
+ * the bundled roster's own id set rather than blocking alias resolution
+ * entirely.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// cli/lib/core/agentAlias.js -> cli/lib -> cli -> repo root -> src/config/...
+const DEFAULT_ASSISTANTS_DIR = path.resolve(__dirname, '../../../src/config/entities/assistants');
+
+/**
+ * Read the bundled assistants roster. Tolerant of a missing directory (a
+ * standalone CLI install without the dashboard source tree alongside it)
+ * and of individual malformed files — one bad entry must never break alias
+ * resolution for every other agent.
+ *
+ * @returns {Array<{id: string, name: string|null, shortName: string|null}>}
+ */
+export function loadBundledAssistantsRoster(dir = DEFAULT_ASSISTANTS_DIR) {
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+
+  const roster = [];
+  for (const file of files) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+      if (raw?.id) {
+        roster.push({
+          id: raw.id,
+          name: raw.identity?.name || null,
+          shortName: raw.identity?.shortName || null,
+        });
+      }
+    } catch {
+      // Skip an unreadable/malformed file rather than failing the whole load.
+    }
+  }
+  return roster;
+}
+
+/**
+ * Pure resolver, exported for unit tests: no filesystem or network access.
+ *
+ * @param {string} requestedId - what the user typed
+ * @param {Set<string>} validIds - agent ids this deployment currently recognises
+ * @param {Array<{id: string, name: string|null, shortName: string|null}>} roster
+ * @returns {{id: string, aliasLabel: string|null}} aliasLabel is the display
+ *   name to print (`alias: <aliasLabel> -> <id>`), or null when the input
+ *   was already a valid id (no alias happened).
+ */
+export function resolveAgentAliasPure(requestedId, validIds, roster) {
+  if (!requestedId || typeof requestedId !== 'string') {
+    throw new Error('Agent id is required.');
+  }
+
+  // Exact, case-sensitive match against a known id: pass through untouched.
+  // This is the common case and must never be affected by alias lookup.
+  if (validIds.has(requestedId)) {
+    return { id: requestedId, aliasLabel: null };
+  }
+
+  const lower = requestedId.toLowerCase();
+  for (const entry of roster) {
+    // Never alias to an id this deployment doesn't currently recognise.
+    if (!validIds.has(entry.id)) continue;
+    const name = entry.name?.toLowerCase();
+    const shortName = entry.shortName?.toLowerCase();
+    if (name === lower || shortName === lower) {
+      return { id: entry.id, aliasLabel: entry.name || entry.shortName || requestedId.toUpperCase() };
+    }
+  }
+
+  throw new Error(
+    `Unknown agent "${requestedId}": not a registry id, and no matching display name in the assistants roster. `
+    + 'Run `quox agent list` to see valid ids.'
+  );
+}
+
+/**
+ * Resolve a possibly-display-name agent id against the live collector
+ * roster plus the bundled assistants roster, printing exactly one
+ * `alias: <NAME> -> <id>` line on a hit. Callers must use the RETURNED
+ * canonical id for every subsequent call — the display name is never sent
+ * to the API.
+ *
+ * Printed unconditionally (never suppressed under -o json/quiet, unlike
+ * printInfo): a silent semantic remap of what agent id you are talking to
+ * is exactly the kind of thing a scripted/JSON caller most needs to see.
+ *
+ * @param {object} client - the CLI's HTTP client (ctx.client)
+ * @param {string} requestedId
+ * @param {{print?: (line: string) => void, rosterDir?: string}} [opts]
+ * @returns {Promise<string>} the canonical agent id
+ */
+export async function resolveAgentId(client, requestedId, opts = {}) {
+  const print = opts.print || ((line) => console.log(line));
+  const roster = loadBundledAssistantsRoster(opts.rosterDir);
+
+  // CORTEX-BENCH: an exact core id resolves to itself whatever the live list
+  // says (absent from it, it passes through as a custom id and the server
+  // decides), so skip the round trip that cost every exec 60ms-1.4s.
+  if (roster.some((r) => r.id === requestedId)) return requestedId;
+
+  let validIds = null;
+  try {
+    const ep = resolveEndpoint('v1.tools.agents.list');
+    const data = await client.get(ep.path, { service: ep.service, noAuth: true });
+    const ids = Object.keys(data?.agentTools || {});
+    if (ids.length > 0) validIds = new Set(ids);
+  } catch {
+    // Live lookup is an optimisation, not a hard requirement -- fall
+    // through to the bundled roster's own id set below.
+  }
+  if (!validIds) validIds = new Set(roster.map((r) => r.id));
+
+  let resolved;
+  try {
+    resolved = resolveAgentAliasPure(requestedId, validIds, roster);
+  } catch (err) {
+    // A non-empty id that matches neither a core-registry id nor a display
+    // name may be a user/org-created custom assistant (auth `assistants`
+    // table) — the core roster this resolver knows never lists those.
+    // QUOXIDENTITY custom-attach (CLI half): the client must not gate an id
+    // the server can now resolve. Pass it through and let the server be the
+    // authority — the attach-kit endpoint resolves a custom assistant
+    // org-scoped, or returns a clean 404 for a genuine typo. (An empty id
+    // still throws the original 'Agent id is required.' error.)
+    if (!requestedId || typeof requestedId !== 'string') throw err;
+    print(`note: "${requestedId}" is not a core registry agent, trying it as a custom/org assistant (server resolves or rejects).`);
+    return requestedId;
+  }
+  if (resolved.aliasLabel) print(`alias: ${resolved.aliasLabel} -> ${resolved.id}`);
+  return resolved.id;
+}

package/lib/core/approvalContext.js

@@ -0,0 +1,61 @@
+/**
+ * HITL-CONTEXT (owner 2026-10-07): render an approval item's
+ * payload.approval_context (built server-side by the collector at request
+ * time) for `quox inbox list` / `quox inbox show`. Pure, so it is testable.
+ */
+
+function clip(text, n) {
+  const s = String(text == null ? '' : text).replace(/\s+/g, ' ').trim();
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+export function getApprovalContext(item) {
+  const c = item && item.payload && item.payload.approval_context;
+  return c && typeof c === 'object' ? c : null;
+}
+
+/** Ordered [label, value] pairs: Source, On behalf of, Reason, Method, Command, Why approval, Risk, Expires. */
+export function approvalContextFields(c) {
+  if (!c) return [];
+  const rows = [];
+  const rb = c.requested_by || {};
+  let source = c.source_label || rb.agent_label || 'unknown';
+  if (rb.profile) source += ` · profile ${rb.profile}`;
+  rows.push(['Source', source]);
+  if (c.on_behalf_of) {
+    const ob = c.on_behalf_of;
+    let v = ob.user_name || ob.user_id || 'unknown user';
+    if (ob.request_excerpt) v += `, asked: "${ob.request_excerpt}"`;
+    if (ob.conversation_id) v += ` (conversation ${ob.conversation_id})`;
+    rows.push(['On behalf of', v]);
+  }
+  const r = c.reason || {};
+  rows.push(['Reason', r.text ? `${r.text}${r.source === 'inferred' ? ' (inferred, not stated by the caller)' : ''}` : 'none given']);
+  const m = c.method || {};
+  rows.push(['Method', `${m.tool || '?'} via ${m.transport || '?'}${m.target ? ` on ${m.target}` : ''}`]);
+  if (m.command) rows.push(['Command', m.command]);
+  else if (m.args) rows.push(['Args', m.args]);
+  if (c.why_approval && c.why_approval.label) rows.push(['Why approval', c.why_approval.label]);
+  if (c.risk) rows.push(['Risk', c.risk]);
+  if (c.expires_at) rows.push(['Expires', c.expires_at]);
+  return rows;
+}
+
+/** Plain-text block for `quox inbox show`. */
+export function formatApprovalContext(c) {
+  const rows = approvalContextFields(c);
+  if (rows.length === 0) return '';
+  const w = Math.max(...rows.map(([k]) => k.length));
+  return ['Approval context', ...rows.map(([k, v]) => `  ${k.padEnd(w)}  ${v}`)].join('\n');
+}
+
+/** Short columns for `quox inbox list`. */
+export function approvalListColumns(item) {
+  const c = getApprovalContext(item);
+  if (!c) return { source: '', reason: '' };
+  const r = c.reason || {};
+  return {
+    source: clip(c.source_label || '', 40),
+    reason: r.text ? clip(`${r.text}${r.source === 'inferred' ? ' (inferred)' : ''}`, 60) : '',
+  };
+}

package/lib/core/auth.js

@@ -0,0 +1,350 @@
+/**
+ * Auth module for QuoxCLI
+ *
+ * Handles login, logout, token storage, and auto-refresh.
+ * Tokens stored in config profile's auth field.
+ */
+
+import { QuoxAuthError, QuoxApiError, QuoxTransientAuthError } from './errors.js';
+import { loadResidentProfile, residentLogin, resolveResidentBaseUrl } from './residentAuth.js';
+
+// A resident agent has no refresh token: its expired-access-token seam is
+// re-running the signed challenge exchange, not demanding `quox login`,
+// since there is no human at the terminal to run it. Kept as a standalone helper
+// so createAuth()'s refresh() stays the single seam client.js already calls
+// on a 401, per quox#453 phase 15.
+async function refreshResident(config, baseUrl, storedAuth) {
+  let profile;
+  try {
+    profile = loadResidentProfile(storedAuth.resident_profile_path);
+  } catch (err) {
+    throw new QuoxAuthError(`Resident re-authentication failed: ${err.message}`);
+  }
+
+  // The caller passes getServiceUrl('auth'), which can port-swap to
+  // loopback :3101 and be unreachable from a remote host, so the resident
+  // rules (bootstrap instance_url / explicit profile URL) come FIRST. But
+  // edge-only was its own outage (2026-08-23, both residents): on the
+  // control box the edge is self-signed https, the systemd unit has no CA
+  // trust, and the one URL that does work there is exactly the
+  // services-aware one the caller passed (plain-http loopback auth). Try
+  // the resident-rules URL, then fall back to the caller's, and only die
+  // if both refuse. An unattended runner must exhaust its options before
+  // giving up: Option A persistence depends on this.
+  const candidates = [...new Set([resolveResidentBaseUrl(config, profile), baseUrl].filter(Boolean))];
+
+  let tokenData;
+  const failures = [];
+  const errs = [];
+  for (const candidate of candidates) {
+    try {
+      tokenData = await residentLogin({ baseUrl: candidate, profile });
+      break;
+    } catch (err) {
+      failures.push(`${candidate}: ${err.message}`);
+      errs.push(err);
+    }
+  }
+  if (!tokenData) {
+    // Every candidate failed for a reason that clears by itself (429, 5xx,
+    // connection refused/reset/timeout): surface a typed transient error so a
+    // long-lived listener can back off instead of dying.
+    const isTransient = (e) => e instanceof QuoxTransientAuthError
+      || (!(e instanceof QuoxAuthError) && /fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|socket hang up|timed? ?out/i.test(`${e?.message} ${e?.cause?.code || ''} ${e?.cause?.message || ''}`));
+    if (errs.length > 0 && errs.every(isTransient)) {
+      const waits = errs.map((e) => e.retryAfterMs).filter((n) => Number.isFinite(n));
+      throw new QuoxTransientAuthError(`Resident re-authentication failed: ${failures.join('; ')}`, waits.length ? Math.max(...waits) : null);
+    }
+    throw new QuoxAuthError(`Resident re-authentication failed: ${failures.join('; ')}`);
+  }
+
+  const authData = {
+    ...storedAuth,
+    access_token: tokenData.access_token,
+    user_id: tokenData.user?.id ?? storedAuth.user_id,
+    email: tokenData.user?.email ?? storedAuth.email,
+    org_role: tokenData.user?.role ?? storedAuth.org_role,
+    actor_type: tokenData.user?.actor_type ?? storedAuth.actor_type,
+    host_id: tokenData.user?.host_id ?? storedAuth.host_id,
+    expires_at: Date.now() + (tokenData.expires_in || 900) * 1000,
+  };
+  config.setAuth(authData, { refresh: true });
+  return tokenData;
+}
+
+// When a password-backed session dead-ends (revoked or expired) the only
+// recovery is an interactive `quox login`, which an unattended agent cannot
+// run. A resident profile, if one is configured, IS that recovery: durable,
+// passwordless, self-renewing. Build a one-line pointer to it, preferring a
+// resident on the same org as the profile that just died. Returns '' when no
+// resident profile exists (nothing useful to suggest). Never throws — a
+// hint-builder must not become a new failure seam in the auth path.
+function residentProfileHint(config, deadOrgId = null) {
+  try {
+    const residents = typeof config.listResidentProfiles === 'function'
+      ? config.listResidentProfiles()
+      : [];
+    if (!residents.length) return '';
+    const sameOrg = deadOrgId ? residents.find(r => r.orgId === deadOrgId) : null;
+    const pick = sameOrg || residents[0];
+    return ` For unattended automation use the durable resident profile instead: `
+      + `\`quox -p ${pick.name} <command>\` (Ed25519, no password, self-renews — never needs re-login).`;
+  } catch {
+    return '';
+  }
+}
+
+export function createAuth(config) {
+  return {
+    async login(baseUrl, email, password, orgId) {
+      const url = `${baseUrl}/api/auth/login`;
+      const body = { email, password };
+      if (orgId) body.org_id = orgId;
+
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+
+      const data = await res.json();
+
+      if (!res.ok) {
+        throw new QuoxApiError(res.status, data.error, data.message || 'Login failed');
+      }
+
+      // Store auth data
+      const authData = {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        user_id: data.user?.id,
+        email: data.user?.email,
+        display_name: data.user?.display_name,
+        org_id: data.org?.id || null,
+        org_name: data.org?.name || null,
+        org_slug: data.org?.slug || null,
+        org_role: data.org?.role || null,
+        mfa_required: data.mfa_required,
+        expires_at: Date.now() + (data.expires_in || 900) * 1000,
+      };
+
+      config.setAuth(authData);
+      return { ...data, authData };
+    },
+
+    async verifyMfa(baseUrl, token, code) {
+      const url = `${baseUrl}/api/mfa/verify`;
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token}`,
+        },
+        body: JSON.stringify({ code }),
+      });
+
+      const data = await res.json();
+      if (!res.ok) {
+        throw new QuoxApiError(res.status, data.error, data.message || 'MFA verification failed');
+      }
+
+      // Update stored token if new one issued
+      if (data.access_token) {
+        const auth = config.getAuth();
+        auth.access_token = data.access_token;
+        auth.mfa_required = false;
+        if (data.expires_in) auth.expires_at = Date.now() + data.expires_in * 1000;
+        config.setAuth(auth);
+      }
+
+      return data;
+    },
+
+    async logout(baseUrl) {
+      const auth = config.getAuth();
+      if (auth?.access_token) {
+        try {
+          await fetch(`${baseUrl}/api/auth/logout`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${auth.access_token}` },
+          });
+        } catch {
+          // Best-effort server-side logout
+        }
+      }
+      config.clearAuth();
+    },
+
+    async refresh(baseUrl) {
+      const auth = config.getAuth();
+
+      // Resident agents authenticate via a signed challenge, not a refresh
+      // token; see refreshResident() above.
+      if (auth?.kind === 'resident') {
+        return refreshResident(config, baseUrl, auth);
+      }
+
+      if (!auth?.refresh_token) {
+        throw new QuoxAuthError('No refresh token. Please login again.');
+      }
+
+      // The token goes in the BODY. POST /api/auth/refresh reads
+      // `req.cookies.refresh_token || req.body.refresh_token` and never looks
+      // at the Authorization header, so sending it only as a Bearer header
+      // meant the server saw no token at all: it answered `no_refresh_token`,
+      // /health answered OK, and the clearing branch below destroyed a
+      // perfectly good session. That is the "logged in, then Session expired
+      // twenty minutes later" outage, logged three separate times before
+      // anyone read the transport rather than the error text. Verified live
+      // 2026-08-24: header -> no_refresh_token, body -> invalid_refresh_token.
+      // The header is kept because it costs nothing and other deployments may
+      // read it.
+      const res = await fetch(`${baseUrl}/api/auth/refresh`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${auth.refresh_token}`,
+        },
+        body: JSON.stringify({ refresh_token: auth.refresh_token }),
+      });
+
+      let data = null;
+      try { data = await res.json(); } catch { /* non-JSON error body */ }
+      if (!res.ok) {
+        // Only a DEFINITIVE rejection (401/403) means the refresh token is
+        // dead. A 5xx or gateway hiccup must NOT destroy the stored session:
+        // on 2026-08-15 a wiped profile here erased the only copy of a
+        // rejected refresh token before anyone could diagnose WHY the auth
+        // service rejected it.
+        // `no_refresh_token` means the REQUEST carried nothing, not that the
+        // stored token is dead. Clearing on it turns a client-side transport
+        // fault into a lost session, which is exactly how the header/body bug
+        // above cost three re-logins in one night before it was found.
+        if ((data && data.error) === 'no_refresh_token') {
+          throw new QuoxAuthError(
+            'The auth service received no refresh token, so it could not tell whether yours is valid. '
+            + 'Stored session KEPT. This is a client/transport fault, not an expiry — retry, and report it if it persists.'
+          );
+        }
+
+        if (res.status === 401 || res.status === 403) {
+          // A 401 from refresh means one of TWO very different things, and
+          // destroying the session on the wrong one costs the user their login.
+          //
+          //   (a) the refresh token really is dead  -> clearing is correct
+          //   (b) the auth service is not READY yet -> clearing is data loss
+          //
+          // 2026-08-19: rebuilding the auth container logged out every CLI
+          // session, twice in one evening, because a starting service answers
+          // 401 before it can answer properly. For an autonomous agent that is
+          // a hard stop mid-task; for a customer it is a surprise re-login
+          // after any routine restart. The old comment here already refused to
+          // clear on a 5xx for the same reason — this is the same hazard one
+          // status code over.
+          //
+          // So ask the service whether it is healthy before believing it about
+          // the token. Unreachable or unhealthy means we learned nothing about
+          // the token, and a session is far more expensive to lose than a
+          // command is to retry.
+          let healthy = false;
+          try {
+            const h = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(3000) });
+            healthy = h.ok;
+          } catch {
+            healthy = false;
+          }
+          if (!healthy) {
+            throw new QuoxAuthError(
+              `Auth service is not healthy right now (refresh returned ${res.status} but /health did not answer OK). ` +
+              `Stored session KEPT — this is very likely a restart or deploy in progress. Retry in a moment.`
+            );
+          }
+          config.clearAuth({ refresh: true });
+          throw new QuoxAuthError(
+            `Session expired (refresh rejected: ${(data && data.error) || res.status}). Please login again.`
+            + residentProfileHint(config, auth?.org_id),
+          );
+        }
+        throw new QuoxAuthError(`Token refresh failed (${res.status}); stored session kept. Retry, or login again if this persists.`);
+      }
+
+      auth.access_token = data.access_token;
+      // The route does not rotate the refresh token today. If it ever starts,
+      // silently dropping the new one would make the NEXT refresh fail and
+      // clear the session: the same outage with a different first cause.
+      if (data.refresh_token) auth.refresh_token = data.refresh_token;
+      if (data.expires_in) auth.expires_at = Date.now() + data.expires_in * 1000;
+      config.setAuth(auth, { refresh: true });
+      return data;
+    },
+
+    getTokens() {
+      return config.getAuth();
+    },
+
+    isLoggedIn() {
+      // Precedence, matching client.js: a stored USER token is what we
+      // actually authenticate with, so it decides this answer. A configured
+      // QUOX_SERVICE_KEY still counts as authenticated on its own, but only
+      // as the automation/daemon fallback when nobody has logged in.
+      //
+      // Checking the env var first was a live bug (quoxai/quox#404): dev
+      // boxes export QUOX_SERVICE_KEY globally, so the CLI reported
+      // "logged in" off the ambient key while sending the wrong credential.
+      const auth = config.getAuth();
+      // QUOX_FORCE_SERVICE_KEY: a daemon that owns its key deliberately bypasses
+      // any stored session (see client.js), so the key alone decides here.
+      if (process.env.QUOX_FORCE_SERVICE_KEY && process.env.QUOX_SERVICE_KEY) return true;
+      if (auth?.access_token) return true;
+      return !!process.env.QUOX_SERVICE_KEY;
+    },
+
+    isExpired() {
+      // A forced service key is not a locally-tracked JWT: never "expired".
+      if (process.env.QUOX_FORCE_SERVICE_KEY && process.env.QUOX_SERVICE_KEY) return false;
+      // A stored user token is the credential in play (see isLoggedIn), so
+      // its expiry is the one that matters — an ambient service key must not
+      // suppress the expiry signal, or client.js's 401 auto-refresh path
+      // (which only fires when isExpired() is true) would never refresh a
+      // genuinely expired session.
+      const auth = config.getAuth();
+      if (auth?.access_token) {
+        if (!auth.expires_at) return true;
+        return Date.now() > auth.expires_at;
+      }
+      // Service-key mode: not a JWT with a locally-tracked expiry, so treat
+      // it as never expired and never attempt a refresh for it.
+      if (process.env.QUOX_SERVICE_KEY) return false;
+      if (!auth?.expires_at) return true;
+      return Date.now() > auth.expires_at;
+    },
+
+    requireAuth() {
+      if (!this.isLoggedIn()) {
+        // Name the PROFILE. "Run `quox login`" alone sent the owner in a
+        // circle on 2026-08-23: he ran `quox login`, saw it succeed, then
+        // `quox -p moo dev enable` still refused, because the login had
+        // stored its session in whichever profile was active at the time
+        // while -p pointed at a different one. The advice was literally
+        // true and still useless, because it omitted the only detail that
+        // mattered.
+        const name = typeof config.getActiveProfileName === 'function' ? config.getActiveProfileName() : null;
+        const activeOrgId = config.getAuth()?.org_id || null;
+        if (name) {
+          throw new QuoxAuthError(
+            `Not authenticated on profile "${name}". Run \`quox -p ${name} login\`. `
+            + `Note that \`quox login\` without -p logs into whichever profile is active, which may not be this one.`
+            + residentProfileHint(config, activeOrgId)
+          );
+        }
+        throw new QuoxAuthError(`Not authenticated. Run \`quox login\` first.${residentProfileHint(config, activeOrgId)}`);
+      }
+    },
+
+    getOrgId(overrideOrg) {
+      if (overrideOrg) return overrideOrg;
+      const auth = config.getAuth();
+      return auth?.org_id || null;
+    },
+  };
+}