quoxcli 0.2.0 → 0.3.1

package/lib/core/askDecision.js

@@ -0,0 +1,60 @@
+/**
+ * quox ask helpers: parse the option list and durations, and wait (bounded long-poll) for a human's answer.
+ * Pure of the CLI framework so the exit codes are unit-testable. Exit codes: 0 answered, 2 expired or denied.
+ */
+
+export const EXIT_ANSWERED = 0;
+export const EXIT_NO_ANSWER = 2;
+
+/** "a: Ship now|b: Wait|c: Drop" -> [{key,label}]. A bare "a|b" gives key=label. Throws with a usable message. */
+export function parseOptions(text) {
+  const parts = String(text || '').split('|').map((s) => s.trim()).filter(Boolean);
+  if (parts.length < 2) throw new Error('--options needs at least two, e.g. "a: Ship now|b: Wait for review|c: Drop it" (or use --yn)');
+  return parts.map((p) => {
+    const m = /^([A-Za-z0-9]{1,8})\s*[:=]\s*(.*)$/.exec(p);
+    if (m) return { key: m[1].toLowerCase(), label: m[2].trim() || m[1] };
+    if (/^[A-Za-z0-9]{1,8}$/.test(p)) return { key: p.toLowerCase(), label: p };
+    throw new Error(`could not read option "${p}": write it as key: label, e.g. "a: Ship now"`);
+  });
+}
+
+export const YN_OPTIONS = [{ key: 'y', label: 'Yes' }, { key: 'n', label: 'No' }];
+
+/** "90s" | "10m" | "2h" | "1d" | bare seconds -> seconds. */
+export function parseDuration(text) {
+  const m = /^(\d+(?:\.\d+)?)\s*([smhd]?)$/i.exec(String(text || '').trim());
+  if (!m) throw new Error(`could not read duration "${text}": use 90s, 10m, 2h or 1d`);
+  const mult = { '': 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2].toLowerCase()];
+  return Math.round(Number(m[1]) * mult);
+}
+
+const fmtLeft = (ms) => { const m = Math.max(0, Math.round(ms / 60000)); return m >= 120 ? `${Math.round(m / 60)}h` : m >= 1 ? `${m}m` : '<1m'; };
+
+/**
+ * Long-poll a decision until it is no longer pending.
+ * @param {{poll:(waitSeconds:number)=>Promise<object>, log:(s:string)=>void, sleep?:Function, now?:()=>number, maxWaitMs?:number|null, pollSeconds?:number}} o
+ * @returns {Promise<{code:number, stdout:string, decision:object|null}>} stdout = chosen option key (+ note line) only when answered.
+ */
+export async function waitForDecision({ poll, log, now = Date.now, maxWaitMs = null, pollSeconds = 25 }) {
+  const start = now();
+  let errors = 0;
+  for (;;) {
+    let d;
+    try { d = (await poll(pollSeconds)).decision; errors = 0; }
+    catch (e) {
+      if (e?.status === 404 || e?.status === 403 || e?.status === 401) throw e; // not a blip: a decision we cannot see
+      if (++errors >= 5) throw e;
+      log(`could not reach the server (${e?.message || 'failed'}), retrying (${errors}/5)`);
+      await new Promise((r) => setTimeout(r, 2000));
+      continue;
+    }
+    if (!d) throw new Error('the server returned no decision');
+    if (d.state === 'answered') return { code: EXIT_ANSWERED, stdout: `${d.answer?.option ?? ''}${d.answer?.note ? `\n${d.answer.note}` : ''}`, decision: d };
+    if (d.state === 'denied') { log(`denied${d.answer?.note ? `: ${d.answer.note}` : ''}`); return { code: EXIT_NO_ANSWER, stdout: '', decision: d }; }
+    if (d.state === 'expired' || d.state === 'cancelled') { log(`${d.state}, no answer${d.default ? ` (default was ${d.default}; not applied)` : ''}`); return { code: EXIT_NO_ANSWER, stdout: '', decision: d }; }
+    const elapsed = now() - start;
+    const left = d.expires_at ? Date.parse(d.expires_at) - now() : null;
+    log(`still waiting for a human (${d.session || 'session'}, ${fmtLeft(elapsed)} elapsed${left != null ? `, ${fmtLeft(left)} left` : ''})`);
+    if (maxWaitMs != null && elapsed >= maxWaitMs) { log('gave up waiting (--timeout); the question is still open: quox ask wait ' + d.id); return { code: EXIT_NO_ANSWER, stdout: '', decision: d }; }
+  }
+}

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)), '..', '..');