quoxcli 0.2.0 → 0.4.0

package/lib/core/auth.js

@@ -5,6 +5,7 @@
  * Tokens stored in config profile's auth field.
  */
 
+import { readFileSync, statSync, openSync, closeSync, unlinkSync } from 'node:fs';
 import { QuoxAuthError, QuoxApiError, QuoxTransientAuthError } from './errors.js';
 import { loadResidentProfile, residentLogin, resolveResidentBaseUrl } from './residentAuth.js';
 
@@ -94,11 +95,79 @@ function residentProfileHint(config, deadOrgId = null) {
   }
 }
 
+// QUOX_TOKEN_FILE: the W4 builder principal (SDK-TEAM design v2, 2.1.3) runs
+// on ONE agent token that an owner-side helper writes to a file and rewrites
+// near expiry. The builder holds no refresh token, no user session and no
+// service key, so this mode is exclusive and fails CLOSED: the file's token or
+// nothing, never the profile, never an ambient QUOX_SERVICE_KEY. Its "refresh"
+// is re-reading the file; it never calls the auth service and never writes or
+// clears the profile.
+function tokenFilePath() {
+  return process.env.QUOX_TOKEN_FILE || null;
+}
+
+function readTokenFile(file) {
+  let st;
+  try {
+    st = statSync(file);
+  } catch {
+    throw new QuoxAuthError(`QUOX_TOKEN_FILE ${file} is not readable. The owner-side builder helper writes it; is the lease live?`);
+  }
+  if (st.mode & 0o004) {
+    throw new QuoxAuthError(`QUOX_TOKEN_FILE ${file} is readable by other users (mode ${(st.mode & 0o777).toString(8)}); refusing to use it. Expected 0640 or tighter.`);
+  }
+  const token = readFileSync(file, 'utf8').trim();
+  if (!token) throw new QuoxAuthError(`QUOX_TOKEN_FILE ${file} is empty.`);
+  return { access_token: token, expires_at: jwtExpiryMs(token), token_file: file };
+}
+
+// Expiry only, for the client's "looks expired, try the refresh seam" signal.
+// Not verification: the server verifies. Undecodable means no local expiry.
+function jwtExpiryMs(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8'));
+    return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Keep the last login email on the profile (not a secret) so a signed-out session can prefill /login. */
+export function rememberEmail(config, email) {
+  try {
+    const prof = config.getActiveProfile?.();
+    if (prof && email && prof.last_email !== email) { prof.last_email = email; config.save?.(); }
+  } catch { /* best-effort */ }
+}
+
+// Cross-process refresh lock (wx file next to the credentials). Returns a release function. Never throws:
+// after the wait it proceeds unlocked, because a stuck lock must not sign anyone out.
+async function acquireRefreshLock(file, { staleMs = 20000, waitMs = 20000 } = {}) {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      closeSync(openSync(file, 'wx', 0o600));
+      return () => { try { unlinkSync(file); } catch { /* already gone */ } };
+    } catch (e) {
+      if (e.code !== 'EEXIST') return () => {};
+      try {
+        if (Date.now() - statSync(file).mtimeMs > staleMs) { try { unlinkSync(file); } catch { /* raced */ } continue; }
+      } catch { continue; }
+      if (Date.now() > deadline) return () => {};
+      await new Promise(r => setTimeout(r, 25));
+    }
+  }
+}
+
 export function createAuth(config) {
   return {
     async login(baseUrl, email, password, orgId) {
+      if (tokenFilePath()) {
+        throw new QuoxAuthError('QUOX_TOKEN_FILE is set: this principal runs on its issued token only and cannot log in as a user.');
+      }
       const url = `${baseUrl}/api/auth/login`;
-      const body = { email, password };
+      // client: 'cli' marks this a CLI/TUI sign-in so the server gives it the longer CLI session window.
+      const body = { email, password, client: 'cli' };
       if (orgId) body.org_id = orgId;
 
       const res = await fetch(url, {
@@ -129,6 +198,7 @@ export function createAuth(config) {
       };
 
       config.setAuth(authData);
+      rememberEmail(config, email);
       return { ...data, authData };
     },
 
@@ -175,7 +245,52 @@ export function createAuth(config) {
       config.clearAuth();
     },
 
+    /**
+     * Refresh the session. Stale-sign-in safe: serialised across processes by a lock file next to the
+     * credentials, and it adopts credentials another window or `quox login` wrote since this process
+     * loaded. A fresh token on disk is reused with no server call (so two windows never spend one
+     * rotating refresh token twice); a rejected refresh re-reads disk and retries ONCE if it changed.
+     */
     async refresh(baseUrl) {
+      if (tokenFilePath() || typeof config.reloadAuth !== 'function' || typeof config.refreshLockFile !== 'function') {
+        return this._refreshOnce(baseUrl);
+      }
+      const lock = await acquireRefreshLock(config.refreshLockFile());
+      try {
+        if (config.reloadAuth() && config.getAuth()?.access_token && !this.isExpired()) {
+          return { access_token: config.getAuth().access_token, reused: true };
+        }
+        const sent = config.getAuth()?.refresh_token;
+        try {
+          return await this._refreshOnce(baseUrl);
+        } catch (e) {
+          if (e?.code === 'session_expired') {
+            config.reloadAuth();
+            const now = config.getAuth();
+            if (now?.refresh_token && now.refresh_token !== sent) {
+              if (!this.isExpired()) return { access_token: now.access_token, reused: true };
+              return await this._refreshOnce(baseUrl);
+            }
+          }
+          throw e;
+        }
+      } finally {
+        lock();
+      }
+    },
+
+    async _refreshOnce(baseUrl) {
+      const tokenFile = tokenFilePath();
+      if (tokenFile) {
+        const before = this._tokenFileLast;
+        const now = readTokenFile(tokenFile);
+        const stillExpired = now.expires_at && Date.now() > now.expires_at;
+        if (stillExpired || (before && now.access_token === before)) {
+          throw new QuoxAuthError(`QUOX_TOKEN_FILE ${tokenFile} has not been renewed; the owner-side helper re-mints it. Not falling back to any other credential.`);
+        }
+        this._tokenFileLast = now.access_token;
+        return { access_token: now.access_token };
+      }
       const auth = config.getAuth();
 
       // Resident agents authenticate via a signed challenge, not a refresh
@@ -199,14 +314,24 @@ export function createAuth(config) {
       // 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 }),
-      });
+      // QUOXON-FW12: a timeout or network error says nothing about the token.
+      // It is TRANSIENT (tokens kept, caller backs off and retries), never
+      // "signed out". 2026-10-14 02:50: a slow auth service signed the owner out
+      // of a session the server still held active.
+      let res;
+      try {
+        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 }),
+          signal: AbortSignal.timeout(15000),
+        });
+      } catch (e) {
+        throw new QuoxTransientAuthError(`Quox server is slow or unreachable (${e?.name === 'TimeoutError' ? 'refresh timed out' : (e?.cause?.code || e?.message || 'network error')}). Stored session KEPT; retrying.`);
+      }
 
       let data = null;
       try { data = await res.json(); } catch { /* non-JSON error body */ }
@@ -221,7 +346,7 @@ export function createAuth(config) {
         // 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(
+          throw new QuoxTransientAuthError(
             '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.'
           );
@@ -254,18 +379,25 @@ export function createAuth(config) {
             healthy = false;
           }
           if (!healthy) {
-            throw new QuoxAuthError(
+            throw new QuoxTransientAuthError(
               `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(
+          const dead = new QuoxAuthError(
             `Session expired (refresh rejected: ${(data && data.error) || res.status}). Please login again.`
             + residentProfileHint(config, auth?.org_id),
           );
+          // Machine-readable, so the TUI can say WHY (idle_timeout | max_session, from the server's session policy).
+          dead.code = 'session_expired';
+          // A revoke carries no `reason`; keep the error so the card can still say why (SIGNOUT-WIPE).
+          dead.reason = (data && data.reason) || ((data && data.error) === 'session_revoked' ? 'session_revoked' : null);
+          throw dead;
         }
-        throw new QuoxAuthError(`Token refresh failed (${res.status}); stored session kept. Retry, or login again if this persists.`);
+        // 5xx / 429 / anything not a definitive 401/403: the token was never judged.
+        const ra = Number(res.headers?.get?.('retry-after'));
+        throw new QuoxTransientAuthError(`Token refresh failed (${res.status}); stored session kept. Retry, or login again if this persists.`, Number.isFinite(ra) && ra > 0 ? ra * 1000 : null);
       }
 
       auth.access_token = data.access_token;
@@ -279,10 +411,20 @@ export function createAuth(config) {
     },
 
     getTokens() {
+      const tokenFile = tokenFilePath();
+      if (tokenFile) {
+        const t = readTokenFile(tokenFile);
+        this._tokenFileLast = t.access_token;
+        return t;
+      }
       return config.getAuth();
     },
 
     isLoggedIn() {
+      const tokenFile = tokenFilePath();
+      if (tokenFile) {
+        try { readTokenFile(tokenFile); return true; } catch { return false; }
+      }
       // 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
@@ -300,6 +442,15 @@ export function createAuth(config) {
     },
 
     isExpired() {
+      const tokenFile = tokenFilePath();
+      if (tokenFile) {
+        try {
+          const { expires_at } = readTokenFile(tokenFile);
+          return expires_at ? Date.now() > expires_at : false;
+        } catch {
+          return true;
+        }
+      }
       // 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

package/lib/core/callerSource.js

@@ -22,7 +22,7 @@ import { join, basename } from 'node:path';
 export const APPROVAL_GATED_TOOLS = new Set([
   'loop_halt', 'slot_assign', 'bob_dispatch_build', 'email_send', 'send_notification',
   'remote_ssh', 'ssh_exec', 'db_query', 'alerts_manage', 'backup_run',
-  'keeper_backup_create', 'deploy_template', 'gemini_generate', 'perplexity_research',
+  'keeper_backup_create', 'deploy_template',
   'system_admin', 'proxmox_vm_action', 'calendar_event_create',
 ]);
 

package/lib/core/cliBuild.js

@@ -0,0 +1,62 @@
+/**
+ * KEEPER-REEXEC: which quox build is installed, read from files only (cheap enough to check on
+ * every keeper control poll, no git or child process). A git checkout (the dev box runs quox from
+ * a detached worktree) reports its HEAD sha; an npm install reports `v<version>`. null = unknown,
+ * and an unknown build never triggers a re-exec or a takeover.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SHA_RE = /^[0-9a-f]{40,64}$/;
+const read = (p) => { try { return readFileSync(p, 'utf-8').trim(); } catch { return null; } };
+
+function gitDirFor(root) {
+  const dotGit = join(root, '.git');
+  if (!existsSync(dotGit)) return null;
+  try {
+    if (statSync(dotGit).isDirectory()) return dotGit;
+  } catch { return null; }
+  const m = /^gitdir:\s*(.+)$/m.exec(read(dotGit) || '');
+  if (!m) return null;
+  return isAbsolute(m[1]) ? m[1] : resolve(root, m[1]);
+}
+
+function resolveRef(gitDir, ref) {
+  const loose = read(join(gitDir, ref));
+  if (loose && SHA_RE.test(loose)) return loose;
+  const commonRel = read(join(gitDir, 'commondir'));
+  const common = commonRel ? (isAbsolute(commonRel) ? commonRel : resolve(gitDir, commonRel)) : null;
+  if (common) {
+    const c = read(join(common, ref));
+    if (c && SHA_RE.test(c)) return c;
+  }
+  for (const d of [gitDir, common].filter(Boolean)) {
+    const packed = read(join(d, 'packed-refs')) || '';
+    for (const line of packed.split('\n')) {
+      const [sha, name] = line.trim().split(/\s+/);
+      if (name === ref && SHA_RE.test(sha)) return sha;
+    }
+  }
+  return null;
+}
+
+/** cliDir = the CLI package dir (holds package.json); its parent may be the git root. */
+export function readInstalledBuild(cliDir) {
+  try {
+    for (const root of [cliDir, dirname(cliDir)]) {
+      const gd = gitDirFor(root);
+      if (!gd) continue;
+      const head = read(join(gd, 'HEAD'));
+      if (!head) continue;
+      if (SHA_RE.test(head)) return head;
+      const m = /^ref:\s*(\S+)$/.exec(head);
+      if (m) { const sha = resolveRef(gd, m[1]); if (sha) return sha; }
+    }
+    const pkg = JSON.parse(readFileSync(join(cliDir, 'package.json'), 'utf-8'));
+    return pkg && pkg.version ? `v${pkg.version}` : null;
+  } catch { return null; }
+}
+
+/** The CLI package this module was loaded from (cli/lib/core -> cli). */
+export const CLI_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');

package/lib/core/client.js

@@ -12,6 +12,7 @@
 import { resolveActing, resolveActingToken } from './actingAs.js';
 import { detectCallerSource } from './callerSource.js';
 import { QuoxApiError, QuoxNetworkError, QuoxAuthError, QuoxTransientAuthError } from './errors.js';
+import { joinServiceUrl, isLocalServiceTarget } from './config.js';
 
 const RETRY_STATUSES = new Set([429, 502, 503]);
 const MAX_RETRIES = 3;
@@ -33,8 +34,9 @@ export function describeNetworkError(service, baseUrl, err) {
   const code = err?.cause?.code || err?.code;
   let msg = `Could not connect to ${service} service at ${baseUrl}: ${err.message}`;
   if (code && TLS_TRUST_CODES.has(code)) {
-    msg += `\n  TLS: certificate not trusted (${code}). For a self-signed dev edge, trust its CA:`
-      + `\n    export NODE_EXTRA_CA_CERTS=~/.config/quox/quox-dev-edge.pem`
+    msg += `\n  TLS: certificate not trusted (${code}). A new QuoxCORE uses its own self-signed certificate; trust that file`
+      + `\n  (on the server, by default ~/quox-install/quox/ssl/quox.crt; copy it here if the server is another machine):`
+      + `\n    export NODE_EXTRA_CA_CERTS=<path to quox.crt>`
       + `\n  Never disable TLS verification (NODE_TLS_REJECT_UNAUTHORIZED=0) instead.`;
   } else if (code === 'ERR_SSL_WRONG_VERSION_NUMBER' || code === 'EPROTO') {
     // quox#532 defect 1: the profile says https:// but the service answered
@@ -113,6 +115,14 @@ export function createClient(config, auth) {
   // never tried again for the rest of its life). A cooldown keeps the
   // don't-hammer-auth property without the death sentence.
   const REFRESH_RETRY_COOLDOWN_MS = 60 * 1000;
+  // quox#1375: a profile with nothing to refresh with (the collector's quox_cli hop writes only the caller's access
+  // token) must surface the route's own 401, not "Session expired... No refresh token", which hid the real cause.
+  // A token-file principal re-mints its own file and a resident re-auths by signed challenge, so both still refresh.
+  const canRefresh = () => {
+    if (process.env.QUOX_TOKEN_FILE) return true;
+    const a = typeof config.getAuth === 'function' ? config.getAuth() : null;
+    return !!(a && (a.refresh_token || a.kind === 'resident'));
+  };
   let refreshFailedAt = 0;
   const correlationId = generateCorrelationId();
 
@@ -128,10 +138,13 @@ export function createClient(config, auth) {
       noAuth = false,
       noActAs = false,
       sensitive = false,
+      // HYPERION #23: an outside-caller request (trigger webhook-fire) also drops the caller labels
+      // (X-Quox-Session / X-Quox-Profile): the receiving route may store every header in an org-readable record.
+      anonymous = false,
     } = options;
 
     const baseUrl = config.getServiceUrl(service);
-    const url = new URL(path, baseUrl);
+    const url = joinServiceUrl(baseUrl, path);
 
     if (query) {
       for (const [key, value] of Object.entries(query)) {
@@ -142,7 +155,7 @@ export function createClient(config, auth) {
     const fetchHeaders = {
       'X-Quox-Correlation': correlationId,
       'X-Quox-Client': 'cli',
-      ...callerContextHeaders(config),
+      ...(anonymous ? {} : callerContextHeaders(config)),
       ...extraHeaders,
     };
 
@@ -177,7 +190,7 @@ export function createClient(config, auth) {
     let usingServiceKey = false;
     // quox#772: opt-in acting identity (--as / QUOX_AS). Replaces the bearer
     // with the agent's attach token; throws (no request sent) if not attached.
-    const acting = !noAuth && !noActAs ? await resolveActing() : { name: null };
+    const acting = !noAuth && !noActAs ? await resolveActing({ explicitProfile: Boolean(config._explicitProfile) }) : { name: null };
     const actingAs = acting.name;
     if (actingAs) {
       const heartbeat = {
@@ -195,7 +208,10 @@ export function createClient(config, auth) {
         usingServiceKey = true;
       } else if (tokens?.access_token) {
         fetchHeaders['Authorization'] = `Bearer ${tokens.access_token}`;
-      } else if (serviceKey) {
+      } else if (serviceKey && isLocalServiceTarget(url.href)) {
+        // QUOXON-Z2H lane R: the implicit fallback is THIS box's key; never
+        // offer it to another host (a remote profile with no login). A caller
+        // that owns a remote key says so with QUOX_FORCE_SERVICE_KEY.
         fetchHeaders['X-Service-Key'] = serviceKey;
         usingServiceKey = true;
       }
@@ -218,6 +234,10 @@ export function createClient(config, auth) {
     }
 
     let lastError;
+    let staleReloaded = false;
+    // REL-424: one refresh per request, on whichever attempt the 401 lands. A token that expires while the
+    // client sleeps between 503 retries gets its 401 on attempt 1+, and gating refresh on attempt 0 surfaced it.
+    let refreshedThisRequest = false;
 
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
@@ -255,10 +275,32 @@ export function createClient(config, auth) {
         // profile over what is really just "wrong token for this route".
         // In that case, skip the refresh and fall through to the normal
         // error handling below so the original 401/403 is surfaced as-is.
-        const looksExpired = typeof auth.isExpired === 'function' ? auth.isExpired() : true;
+        let looksExpired = typeof auth.isExpired === 'function' ? auth.isExpired() : true;
+        // The SERVER saying "invalid or expired token" outranks the local clock. expires_at is
+        // stamped after the refresh response lands, so for a moment the server rejects a token
+        // the client still thinks is good. 2026-10-14 07:32:03: three windows hit that gap
+        // together, skipped the refresh and declared the profile signed out. Refresh is safe
+        // here: a dead refresh token is still judged by auth.refresh() itself.
+        if (res.status === 401 && !looksExpired && !noAuth && !actingAs && !usingServiceKey) {
+          try { looksExpired = (await res.clone().json())?.error === 'invalid_token'; } catch { /* non-JSON body */ }
+        }
+
+        // Stale sign-in: a sibling window or `quox login` may have written a newer token for this profile.
+        // Adopt it and retry this request ONCE before any refresh (which would spend our stale refresh token).
+        if (res.status === 401 && !noAuth && !actingAs && !usingServiceKey && !staleReloaded
+            && typeof config.reloadAuth === 'function' && config.reloadAuth()) {
+          staleReloaded = true;
+          const fresh = auth.getTokens?.();
+          if (fresh?.access_token) {
+            fetchHeaders['Authorization'] = `Bearer ${fresh.access_token}`;
+            attempt--; // this retry is free: it does not spend the caller's retry budget
+            continue;
+          }
+        }
 
         const refreshCoolingDown = refreshFailedAt && (Date.now() - refreshFailedAt < REFRESH_RETRY_COOLDOWN_MS);
-        if (res.status === 401 && !noAuth && !actingAs && attempt === 0 && !refreshCoolingDown && looksExpired) {
+        if (res.status === 401 && !noAuth && !actingAs && !refreshedThisRequest && !refreshCoolingDown && looksExpired && canRefresh()) {
+          refreshedThisRequest = true;
           try {
             if (!refreshing) {
               const serviceUrl = config.getServiceUrl('auth');
@@ -288,16 +330,25 @@ export function createClient(config, auth) {
             if (refreshErr && refreshErr.transient) {
               // Auth is only temporarily unavailable (429 / restart): no
               // cooldown, and keep the type so a listener can back off.
-              throw new QuoxTransientAuthError(`Re-authentication temporarily unavailable. ${refreshErr.message}`, refreshErr.retryAfterMs ?? null);
+              throw new QuoxTransientAuthError(`Quox server is slow or unreachable, retrying. ${refreshErr.message}`, refreshErr.retryAfterMs ?? null);
             }
             refreshFailedAt = Date.now();
             const why = refreshErr?.message ? ` ${refreshErr.message}` : '';
-            throw new QuoxAuthError(`Session expired. Run \`quox login\` to re-authenticate.${why}`);
+            const dead = new QuoxAuthError(`Session expired. Run \`quox login\` to re-authenticate.${why}`);
+            if (refreshErr?.code) dead.code = refreshErr.code;
+            if (refreshErr?.reason) dead.reason = refreshErr.reason;
+            throw dead;
           }
         }
 
         // Retry transient errors
+        // quox#882: the server can say a failure won't clear by itself (a downstream refusing
+        // connections): body retryable:false skips the backoff retries.
+        let noRetry = false;
         if (RETRY_STATUSES.has(res.status) && attempt < retries) {
+          try { noRetry = (await res.clone().json())?.retryable === false; } catch { /* not JSON */ }
+        }
+        if (RETRY_STATUSES.has(res.status) && attempt < retries && !noRetry) {
           const delay = RETRY_DELAYS[attempt] || 9000;
           if (isDebug) {
             console.error(`   Retrying in ${delay}ms (attempt ${attempt + 1}/${retries})...`);
@@ -315,7 +366,8 @@ export function createClient(config, auth) {
           try {
             data = await res.json();
           } catch {
-            data = { error: 'unknown', message: res.statusText };
+            // CLI-ERRORS: a proxy error page, not a Quox body; named so the renderer can say so
+            data = { error: 'non_json_response', message: res.statusText };
           }
           // A permission error while we silently fell back to the SERVICE
           // KEY is almost never a permissions problem: the service key
@@ -327,7 +379,10 @@ export function createClient(config, auth) {
           // theory about who could grant it. He had held instance-admin
           // since March. His session had simply expired and the CLI had
           // quietly downgraded the request to a key with no user attached.
-          let message = data.message || `Request failed with status ${res.status}`;
+          // CLI-ERRORS: a body with only a prose `error` ("Agent not found") leads with that, never
+          // "Request failed with status N" (the real reason used to sit on the dim Status line).
+          const proseError = !data.message && typeof data.error === 'string' && /\s/.test(data.error);
+          let message = data.message || (proseError ? data.error : `Request failed with status ${res.status}`);
           // quox#617: surface the server's machine-readable `reason`. A vault
           // update returns 403 with `reason: 'mfa_required'` for an MFA-enabled
           // owner (a step-up gate) vs `reason: 'role_<r>_lacks_capability_<cap>'`
@@ -344,18 +399,38 @@ export function createClient(config, auth) {
               + `The service key has no user identity, so anything gated on WHO you are will refuse it regardless of your real permissions. `
               + `Run \`quox login\` (or \`quox -p <profile> login\`) and retry before treating this as a permissions problem.`;
           }
+          // #1012: the paid backends (QuoxPlan, QuoxSEO, QLarity, QuoxSignal) are not part of the public
+          // install, so a licensed customer got a bare 502 from the collector proxy. This client cannot
+          // tell "not installed" from "installed but down", so it says both, and exits 1 (not 8).
+          const pluginDown = (res.status === 502 || res.status === 503) && typeof data.error === 'string'
+            && /^(QuoxPlan|QuoxSEO|QLarity|QuoxSignal) service unavailable$/i.exec(data.error);
+          if (pluginDown) {
+            const err = new QuoxApiError(
+              res.status,
+              'PLUGIN_SERVICE_UNAVAILABLE',
+              `${pluginDown[1]} isn't reachable on this server. It isn't part of the public install (it ships separately), `
+                + 'or it is installed but down: run `quox health`. Nothing was changed.',
+              data.detail || data.details,
+              data
+            );
+            err.exitCode = 1;
+            throw err;
+          }
           // LL-3d: carry the WHOLE body, not just message/detail. Endpoints
           // that answer with structured context (the licensing 409's
           // bound_instance_name / bound[] / max_servers, the 402's plugin)
           // had it flattened away here, so command handlers could only print
           // "Request failed with status 409".
-          throw new QuoxApiError(
+          const apiErr = new QuoxApiError(
             res.status,
             data.error || 'api_error',
             message,
             data.detail || data.details,
             data
           );
+          if (proseError) apiErr.reasonFromError = true;
+          if (usingServiceKey && (res.status === 403 || res.status === 401)) apiErr.serviceKeyFallback = true;
+          throw apiErr;
         }
 
         // Handle empty responses (204 No Content)
@@ -431,7 +506,7 @@ export function createClient(config, auth) {
     } = options;
 
     const baseUrl = config.getServiceUrl(service);
-    const url = new URL(path, baseUrl);
+    const url = joinServiceUrl(baseUrl, path);
 
     if (query) {
       for (const [key, value] of Object.entries(query)) {
@@ -449,7 +524,7 @@ export function createClient(config, auth) {
     // Same precedence as request() above, including the QUOX_FORCE_SERVICE_KEY
     // override for daemons that own their key and must not borrow the shared
     // config's stored session.
-    const streamActingR = await resolveActing();
+    const streamActingR = await resolveActing({ explicitProfile: Boolean(config._explicitProfile) });
     const streamActing = streamActingR.name;
     const streamTokens = auth.getTokens();
     let streamServiceKey = null;
@@ -462,7 +537,7 @@ export function createClient(config, auth) {
       fetchHeaders['X-Service-Key'] = streamServiceKey;
     } else if (streamTokens?.access_token) {
       fetchHeaders['Authorization'] = `Bearer ${streamTokens.access_token}`;
-    } else if (process.env.QUOX_SERVICE_KEY) {
+    } else if (process.env.QUOX_SERVICE_KEY && isLocalServiceTarget(url.href)) {
       streamServiceKey = process.env.QUOX_SERVICE_KEY;
       fetchHeaders['X-Service-Key'] = streamServiceKey;
     }
@@ -472,22 +547,61 @@ export function createClient(config, auth) {
       console.error(`-> ${streamBody !== undefined ? 'POST' : 'GET'}(stream) ${url.toString()}`);
     }
 
-    let res;
-    try {
-      res = await fetch(url.toString(), {
-        method: streamBody !== undefined ? 'POST' : 'GET',
-        headers: fetchHeaders,
-        ...(streamBody !== undefined ? { body: JSON.stringify(streamBody) } : {}),
-        signal: externalSignal,
-        // Same redirect protection as the non-streaming path above: never let
-        // a 3xx resend X-Service-Key to a host we did not choose.
-        ...(streamServiceKey ? { redirect: 'manual' } : {}),
-      });
-    } catch (err) {
-      throw new QuoxNetworkError(
-        describeNetworkError(service, baseUrl, err),
-        err
-      );
+    const openStream = async () => {
+      try {
+        return await fetch(url.toString(), {
+          method: streamBody !== undefined ? 'POST' : 'GET',
+          headers: fetchHeaders,
+          ...(streamBody !== undefined ? { body: JSON.stringify(streamBody) } : {}),
+          signal: externalSignal,
+          // Same redirect protection as the non-streaming path above: never let
+          // a 3xx resend X-Service-Key to a host we did not choose.
+          ...(streamServiceKey ? { redirect: 'manual' } : {}),
+        });
+      } catch (err) {
+        throw new QuoxNetworkError(
+          describeNetworkError(service, baseUrl, err),
+          err
+        );
+      }
+    };
+    let res = await openStream();
+
+    // 2026-10-16: request() refreshed an expired session on a 401, the stream (the chat path) did not,
+    // so a chat turn right after the access token expired read "Not signed in" on a signed-in profile.
+    // Same rule as request(): one refresh for a user token that looks expired (locally, or the server
+    // says invalid_token), shared with any refresh already in flight, then one retry.
+    const usesUserToken = !streamActing && !streamServiceKey && !!streamTokens?.access_token;
+    if (res.status === 401 && usesUserToken && typeof config.reloadAuth === 'function' && config.reloadAuth()) {
+      // Stale sign-in: a sibling window or `quox login` wrote a newer token. Adopt it, retry once.
+      const fresh = auth.getTokens?.();
+      if (fresh?.access_token) { fetchHeaders['Authorization'] = `Bearer ${fresh.access_token}`; res = await openStream(); }
+    }
+    if (res.status === 401 && usesUserToken) {
+      let looksExpired = typeof auth.isExpired === 'function' ? auth.isExpired() : true;
+      if (!looksExpired) {
+        try { looksExpired = (await res.clone().json())?.error === 'invalid_token'; } catch { /* non-JSON body */ }
+      }
+      const refreshCoolingDown = refreshFailedAt && (Date.now() - refreshFailedAt < REFRESH_RETRY_COOLDOWN_MS);
+      if (looksExpired && !refreshCoolingDown && canRefresh()) {
+        try {
+          if (!refreshing) {
+            refreshing = auth.refresh(config.getServiceUrl('auth')).finally(() => { refreshing = null; });
+          }
+          await refreshing;
+        } catch (refreshErr) {
+          if (refreshErr && refreshErr.transient) {
+            throw new QuoxTransientAuthError(`Quox server is slow or unreachable, retry shortly. ${refreshErr.message}`, refreshErr.retryAfterMs ?? null);
+          }
+          refreshFailedAt = Date.now();
+          const dead = new QuoxAuthError(`Session expired. Run \`quox login\` to re-authenticate.${refreshErr?.message ? ` ${refreshErr.message}` : ''}`);
+          dead.status = 401;
+          throw dead;
+        }
+        const fresh = auth.getTokens();
+        if (fresh?.access_token) fetchHeaders['Authorization'] = `Bearer ${fresh.access_token}`;
+        res = await openStream();
+      }
     }
 
     if (!res.ok) {
@@ -495,15 +609,18 @@ export function createClient(config, auth) {
       try {
         data = await res.json();
       } catch {
-        data = { error: 'unknown', message: res.statusText };
+        data = { error: 'non_json_response', message: res.statusText };
       }
-      throw new QuoxApiError(
+      const proseError = !data.message && typeof data.error === 'string' && /\s/.test(data.error);
+      const streamErr = new QuoxApiError(
         res.status,
         data.error || 'api_error',
-        data.message || `Stream request failed with status ${res.status}`,
+        data.message || (proseError ? data.error : `Stream request failed with status ${res.status}`),
         data.detail || data.details,
         data
       );
+      if (proseError) streamErr.reasonFromError = true;
+      throw streamErr;
     }
 
     if (!res.body) {