jaitus 0.3.12 → 0.3.14

package/src/agent/tools.js

@@ -746,11 +746,17 @@ export const TOOLS = [
     async run(input) {
       if (input.clear) { todoState.splice(0, todoState.length); return 'Task list cleared.'; }
       if (!Array.isArray(input.todos)) throw new ToolError('Give a todos array (or clear: true).');
-      const cleaned = input.todos.map((t) => ({
-        task: String(t?.task || '').trim(),
-        status: ['pending', 'in_progress', 'completed'].includes(t?.status) ? t.status : 'pending',
-      })).filter((t) => t.task);
-      if (!cleaned.length) throw new ToolError('The list has no usable items.');
+      // Models trained on other agents name the step `content` (or title, text…) and the
+      // status "done" or "in-progress". Only `task` used to count, so a perfectly good
+      // plan was refused as "no usable items" and the list never appeared.
+      const STATUS = { pending: 'pending', todo: 'pending', not_started: 'pending', in_progress: 'in_progress', inprogress: 'in_progress', active: 'in_progress', doing: 'in_progress', started: 'in_progress', completed: 'completed', complete: 'completed', done: 'completed', finished: 'completed' };
+      const cleaned = input.todos.map((t) => {
+        const item = typeof t === 'string' ? { task: t } : (t || {});
+        const text = [item.task, item.content, item.title, item.text, item.description, item.step, item.name].find((v) => typeof v === 'string' && v.trim());
+        const key = String(item.status || '').trim().toLowerCase().replace(/[\s-]+/g, '_');
+        return { task: String(text || '').trim(), status: STATUS[key] || (item.done === true || item.completed === true ? 'completed' : 'pending') };
+      }).filter((t) => t.task);
+      if (!cleaned.length) throw new ToolError('The list has no usable items. Each item is { "task": "one step", "status": "pending" | "in_progress" | "completed" }.');
       todoState.splice(0, todoState.length, ...cleaned);
       return `Task list updated (${cleaned.filter((t) => t.status === 'completed').length}/${cleaned.length} done).`;
     },

package/src/api.js

@@ -4,32 +4,46 @@
 // a JaitusError here, at the edge, so no caller ever has an HTTP body in its hands to
 // print — see errors.js for why that matters.
 
-import { endpoints } from './config.js';
+import { endpoints, version } from './config.js';
 import { signedIn, withAuth } from './session.js';
 import { fromGatewayBody, fromNetwork, JaitusError } from './errors.js';
 
 export class NotSignedIn extends Error {}
 
-// fetch() has no timeout of its own, and the gateway's worst case is minutes of
-// serial failover across provider keys — so a sick window used to pin the CLI on
-// "Working..." forever. Every call below carries its own ceiling: slow becomes a
-// `timeout` JaitusError (retryable by the agent loop, shown with a request id)
-// instead of eternity. The caller's signal (Esc) still wins: it aborts through the
+// fetch() has no timeout of its own, so a request the gateway never answered used to
+// pin the CLI on "Working..." forever. Every call below carries a deadline: slow
+// becomes a `timeout` JaitusError (retryable by the agent loop, shown with a request
+// id) instead of eternity. The caller's signal (Esc) still wins: it aborts through the
 // same controller, and only a genuine user abort reads as one.
-const MESSAGES_TIMEOUT_MS = 10 * 60 * 1000; // streamed turns can legitimately run minutes
+//
+// A turn is bounded by SILENCE, not by its length. Until the reply starts, the gateway
+// may be failing over between provider keys (each gets a 20-45 s budget), so the first
+// byte gets a few minutes. Once it starts, the gateway writes a heartbeat at least every
+// 10 s for as long as the provider is working, so 90 s without a single byte means the
+// connection is dead — while a long, healthy answer streams for as long as it needs.
+// (A fixed 10-minute ceiling on the whole request used to cut long answers off and
+// start them again from nothing.)
+// (Overridable only so the tests can drive a stall in under a second.)
+const FIRST_BYTE_TIMEOUT_MS = Number(process.env.JAITUS_FIRST_BYTE_MS) || 3 * 60 * 1000;
+const STREAM_IDLE_TIMEOUT_MS = Number(process.env.JAITUS_STREAM_IDLE_MS) || 90 * 1000;
 const API_TIMEOUT_MS = 30 * 1000;           // dashboard calls are small JSON
 
-// Combine an optional caller signal with a timeout into one signal.
+// Combine an optional caller signal with a restartable deadline into one signal.
 // Manual combine (not AbortSignal.any): .any needs Node 20.3+, this works everywhere.
 function withTimeout(signal, ms) {
   const ctrl = new AbortController();
   let timedOut = false;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    try { ctrl.abort(new DOMException('Request timed out', 'TimeoutError')); }
-    catch { try { ctrl.abort(); } catch { /* already gone */ } }
-  }, ms);
-  if (timer.unref) timer.unref();
+  let timer = null;
+  const arm = (after) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      timedOut = true;
+      try { ctrl.abort(new DOMException('Request timed out', 'TimeoutError')); }
+      catch { try { ctrl.abort(); } catch { /* already gone */ } }
+    }, after);
+    if (timer.unref) timer.unref();
+  };
+  arm(ms);
   const onAbort = () => {
     clearTimeout(timer);
     try { ctrl.abort(signal.reason); } catch { try { ctrl.abort(); } catch { /* already gone */ } }
@@ -43,10 +57,28 @@ function withTimeout(signal, ms) {
     // True only when OUR timer fired. A user abort also lands here as an AbortError,
     // but signal.aborted is set then — never mistake Esc for a timeout.
     timedOut: () => timedOut && !signal?.aborted,
+    /** Start the deadline again from now (with a new length). */
+    restart: (after) => { if (!ctrl.signal.aborted) arm(after); },
     cleanup: () => { clearTimeout(timer); signal?.removeEventListener?.('abort', onAbort); },
   };
 }
 
+/**
+ * The response with its body watched for silence: every chunk restarts the idle
+ * deadline, and the end of the body (or the reader letting go of it) stops the timer
+ * and drops the caller's abort listener, so nothing outlives the request.
+ */
+function watchedResponse(res, t, idleMs) {
+  if (!res.body) { t.cleanup(); return res; }
+  t.restart(idleMs);
+  const body = res.body.pipeThrough(new TransformStream({
+    transform(chunk, controller) { t.restart(idleMs); controller.enqueue(chunk); },
+    flush() { t.cleanup(); },
+    cancel() { t.cleanup(); },
+  }));
+  return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+}
+
 function timeoutError() {
   return new JaitusError({ code: 'timeout', status: 504, message: 'Jaitus took too long to respond. Try again.' });
 }
@@ -61,7 +93,7 @@ export function createClient() {
 
   // x-jaitus-features: what this build understands, so the gateway can use newer error
   // codes (a used-up usage window) without an older CLI reading them as "went wrong".
-  const base = { 'Content-Type': 'application/json', 'user-agent': 'jaitus-cli', 'x-jaitus-features': 'usage-window' };
+  const base = { 'Content-Type': 'application/json', 'user-agent': `jaitus-cli/${version()}`, 'x-jaitus-features': 'usage-window' };
   const headers = (token) => ({ ...base, authorization: `Bearer ${token}` });
 
   return {
@@ -69,24 +101,26 @@ export function createClient() {
 
     /** POST /v1/messages. Returns the raw Response so the caller can stream it. */
     async messages(body, { signal } = {}) {
-      // The timer is deliberately NOT cleared when headers arrive: a stall can happen
-      // mid-body too (headers fast, tokens never come), and only the stream reader ends
-      // that. Aborting a finished request is harmless; the timer never holds the
-      // process open (unref). 10 minutes: streamed agentic turns legitimately run long.
-      const t = withTimeout(signal, MESSAGES_TIMEOUT_MS);
+      const t = withTimeout(signal, FIRST_BYTE_TIMEOUT_MS);
+      let res;
       try {
-        return await withAuth((token) => fetch(`${baseUrl}/v1/messages`, {
+        res = await withAuth((token) => fetch(`${baseUrl}/v1/messages`, {
           method: 'POST',
           headers: headers(token),
           body: JSON.stringify(body),
           signal: t.signal,
         }));
       } catch (cause) {
+        t.cleanup();
         if (cause?.name === 'JaitusError') throw cause;
         if (t.timedOut()) throw timeoutError();
         if (cause?.name === 'AbortError') throw cause;
         throw fromNetwork(cause);
       }
+      // A mid-body stall (headers fast, then nothing) aborts the body; the reader sees
+      // an AbortError while the caller's signal is NOT aborted, and turns it into a
+      // timeout — keeping whatever already arrived (agent/loop.js).
+      return watchedResponse(res, t, STREAM_IDLE_TIMEOUT_MS);
     },
 
     /** A dashboard API call, returning parsed JSON. */

package/src/commands/update.js

@@ -14,7 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { c, out, ok, info, warn, fail, present, askKey } from '../ui.js';
+import { c, out, ok, info, warn, fail, present } from '../ui.js';
 import { version, HOME } from '../config.js';
 import { RUNNING_FILE } from '../pendingUpdate.js';
 
@@ -89,7 +89,7 @@ export async function updateNotice(opts = {}) {
   const current = opts.current || version();
   const latest = await cachedLatest(opts).catch(() => null);
   if (!latest || !isNewer(latest, current)) return null;
-  return `Jaitus v${latest} is out — you have v${current}. Quit and run \`jaitus update\` to install it.`;
+  return `Jaitus v${latest} is out — you have v${current}. Quit and start jaitus again: it updates itself as it starts.`;
 }
 
 function run(cmd, args, { capture = false } = {}) {
@@ -147,7 +147,14 @@ export async function installMethod({ here = fileURLToPath(import.meta.url), npm
   const norm = (p) => path.resolve(p).toLowerCase();
   if (/[\\/]_npx[\\/]/.test(real)) return 'npx';
   const root = npmRoot ?? (await run('npm', ['root', '-g'], { capture: true })).stdout.trim();
-  if (root && norm(real).startsWith(norm(path.join(root, 'jaitus')) + path.sep.toLowerCase())) return 'npm-global';
+  if (!root) return 'other';
+  // Both sides through their links: with nvm (and similar) npm's global folder is a link
+  // to the active Node's folder, so this file's real path never started with the
+  // reported one, and a perfectly normal npm install was skipped as "not npm".
+  const realRoot = (() => { try { return fs.realpathSync(root); } catch { return root; } })();
+  for (const r of new Set([root, realRoot])) {
+    if (norm(real).startsWith(norm(path.join(r, 'jaitus')) + path.sep.toLowerCase())) return 'npm-global';
+  }
   return 'other';
 }
 
@@ -173,56 +180,70 @@ export function isNewer(a, b) {
 }
 
 /**
- * Update on launch, then reopen: every time `jaitus` starts, the registry is asked
- * (with a short timeout, so a slow network costs at most that); when a newer version is
- * out and this copy is a global npm install, it is installed and the same command is
- * started again on the new version.
+ * Update on launch, then reopen. Every time `jaitus` starts in a terminal, the registry
+ * is asked — always, not from a cache — and when a newer version is out it is installed,
+ * with progress on screen, and the same command is started again on the new version.
  *
- * It never blocks the session on a failure. A failed install (commonly: a system-wide
- * Node on macOS or Linux, where npm -g needs sudo) says so once and is not retried for a
- * day, so a machine that cannot update does not pay for trying on every start.
+ * It used to skip far too often: the registry got 1.5 s (a slower answer meant this
+ * launch went ahead on the old version), one failed install switched updating off for a
+ * day, a copy whose npm folder is reached through a link (nvm and similar) was taken for
+ * "not an npm install" and skipped without a word, and a setting could turn it off. Now:
+ * - the check waits up to `waitMs` (10 s), saying "Checking for updates…" while it does;
+ * - a failed install says why and how to fix it, and is tried again on the next launch;
+ * - a copy that cannot update itself (npx, a linked or vendored copy) says so, every time;
+ * - only CI, scripts/pipes and JAITUS_NO_AUTOUPDATE (for tests and automation) skip it.
  *
- * Off with `jaitus config autoUpdate off`, JAITUS_NO_AUTOUPDATE=1, NO_UPDATE_NOTIFIER or CI.
+ * It never blocks the session on a failure: the user is told, and the app starts.
  * Returns the child's exit code when it relaunched, or null to carry on in this process.
  */
-export async function autoUpdate({ argv = [], settings = {}, env = process.env, current = version(), log = out,
+export async function autoUpdate({ argv = [], env = process.env, current = version(), log = out,
   check = () => checkRegistry(), method = () => installMethod(), install = null,
-  relaunch = defaultRelaunch, now = Date.now(), failFile = path.join(HOME, 'update-failed.json'),
-  cacheFile = CHECK_FILE, waitMs = 1500, write = (s) => process.stdout.write(s),
-  runningFile = RUNNING_FILE } = {}) {
+  relaunch = defaultRelaunch, cacheFile = CHECK_FILE, waitMs = 10_000, write = (s) => process.stdout.write(s),
+  runningFile = RUNNING_FILE, showAfterMs = 300 } = {}) {
   if (env.JAITUS_UPDATED_FROM) return null;                // just relaunched: never loop
-  if (!updateCheckEnabled(env) || env.JAITUS_NO_AUTOUPDATE || settings.autoUpdate === false) return null;
+  if (!updateCheckEnabled(env) || env.JAITUS_NO_AUTOUPDATE) return null;
   if (!process.stdout.isTTY || !process.stdin.isTTY) return null;   // scripts and pipes get a stable version
   const first = argv.find((a) => !a.startsWith('-'));
   if (['update', 'completion', 'help', 'logout'].includes(first) || argv.some((a) => ['--version', '-v', '--help', '-h', '--print', '-p'].includes(a))) return null;
-  try {
-    const failed = JSON.parse(fs.readFileSync(failFile, 'utf8'));
-    if (now - Number(failed.at) < DAY_MS) return null;
-  } catch { /* no recent failure */ }
 
-  // What the last check found. A check that outlived its wait on a slow connection still
-  // finishes and records its answer here, so the NEXT launch updates without waiting —
-  // before this, a network slower than the wait skipped the update on every launch.
   const remember = (latest) => {
     try { fs.mkdirSync(path.dirname(cacheFile), { recursive: true }); fs.writeFileSync(cacheFile, JSON.stringify({ checkedAt: Date.now(), latest: latest || null })); } catch { /* read-only home */ }
   };
-  let latest = null;
-  try {
-    const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
-    if (cached?.latest && isNewer(cached.latest, current) && now - Number(cached.checkedAt) < 6 * 3600e3) latest = cached.latest;
-  } catch { /* no earlier answer */ }
+  // Ask the registry. A quick answer shows nothing; a slow one says what is happening.
+  let shown = false;
+  const showing = setTimeout(() => { shown = true; write(`  ${c.dim('Checking for updates…')}`); }, showAfterMs);
+  // An answer that arrives after the wait is still recorded, for the next launch.
+  const asked = Promise.resolve().then(check).then((r) => { if (r?.version) remember(r.version); return r; }, () => ({ version: null, status: 'unreachable' }));
+  const answer = await Promise.race([
+    asked,
+    new Promise((resolve) => setTimeout(() => resolve({ version: null, status: 'timeout' }), waitMs).unref()),
+  ]);
+  clearTimeout(showing);
+  if (shown) write('\r\x1b[2K');
+  let latest = answer?.version || null;
+  // (an answer is recorded by `asked` itself, on time or late)
   if (!latest) {
-    const asked = Promise.resolve().then(check).then((r) => { if (r?.version) remember(r.version); return r; }, () => ({ version: null }));
-    ({ version: latest } = await Promise.race([
-      asked,
-      // unref: a quick command must not sit waiting for this timer after the answer came.
-      new Promise((resolve) => setTimeout(() => resolve({ version: null }), waitMs).unref()),
-    ]));
+    // No answer this time. A newer version seen earlier is still worth installing.
+    try {
+      const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      if (cached?.latest && isNewer(cached.latest, current)) latest = cached.latest;
+    } catch { /* no earlier answer */ }
+    if (!latest) {
+      if (answer?.status !== 'unpublished') log(`  ${c.dim(`Could not reach npm to check for updates — starting v${current}.`)}`);
+      return null;
+    }
+  }
+  if (!isNewer(latest, current)) return null;
+
+  const how = await method();
+  if (how !== 'npm-global') {
+    log(`  ${c.yellow('!')} ${c.bold(`Jaitus v${latest}`)} ${c.dim(`is out — you have v${current}, and this copy cannot update itself.`)}`);
+    log(`    ${c.dim(how === 'npx' ? 'Start it with' : 'Update it with')} ${c.bold(how === 'npx' ? 'npx jaitus@latest' : 'npm install -g jaitus@latest')}`);
+    return null;
   }
-  if (!latest || !isNewer(latest, current)) return null;
-  if ((await method()) !== 'npm-global') return null;       // the in-app notice covers these
 
   const head = `  ${c.brand('Jaitus')} ${c.dim(`v${current} →`)} ${c.bold(`v${latest}`)}`;
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
   write(`${head} ${c.dim('— updating…')}`);
   // Ctrl+C now leaves npm to finish on its own (it is detached) — say so rather than
   // leaving someone to wonder whether they broke the install. Runs before the bin's own
@@ -232,7 +253,7 @@ export async function autoUpdate({ argv = [], settings = {}, env = process.env,
   };
   process.prependListener('SIGINT', onInterrupt);
   const doInstall = install || ((v) => installGlobal(v, {
-    onTick: (s) => write(`\r${head} ${c.dim(`— updating… ${s}s (this takes about a minute)`)}`),
+    onTick: (s) => write(`\r\x1b[2K${head} ${c.brand(frames[s % frames.length])} ${c.dim(`updating… ${s}s — this usually takes under a minute`)}`),
     // Left behind only if this process is gone before npm is — the next launch waits on it.
     onStart: (pid) => { try { fs.mkdirSync(path.dirname(runningFile), { recursive: true }); fs.writeFileSync(runningFile, JSON.stringify({ pid, at: Date.now(), version: v })); } catch { /* best effort */ } },
   }));
@@ -243,14 +264,15 @@ export async function autoUpdate({ argv = [], settings = {}, env = process.env,
   }
   write('\n');
   if (result.code !== 0) {
-    try { fs.mkdirSync(path.dirname(failFile), { recursive: true }); fs.writeFileSync(failFile, JSON.stringify({ at: now, version: latest })); } catch { /* best effort */ }
     const needsSudo = /EACCES|permission denied/i.test(result.stderr || '');
-    log(`  ${c.yellow('!')} ${c.dim('Could not update automatically — continuing on')} v${current}${c.dim('. To update:')} ${c.bold(process.platform !== 'win32' && needsSudo ? 'sudo npm install -g jaitus@latest' : 'npm install -g jaitus@latest')}`);
+    const busy = /EBUSY|EPERM|resource busy|operation not permitted/i.test(result.stderr || '');
+    log(`  ${c.yellow('!')} ${c.dim('The update to')} v${latest} ${c.dim('did not install — starting')} v${current}${c.dim('. It is tried again next time you start jaitus.')}`);
+    if (busy) log(`    ${c.dim('Another jaitus window may be holding its files: close every jaitus window, then start it again.')}`);
+    log(`    ${c.dim('To install it by hand:')} ${c.bold(process.platform !== 'win32' && needsSudo ? 'sudo npm install -g jaitus@latest' : 'npm install -g jaitus@latest')}`);
     const reason = (result.stderr || '').split('\n').map((l) => l.trim()).filter(Boolean).find((l) => /ERR|EACCES|EPERM|EBUSY|ENOTEMPTY/i.test(l));
-    if (reason) log(`  ${c.dim(reason.slice(0, 200))}`);
+    if (reason) log(`    ${c.dim(reason.slice(0, 200))}`);
     return null;
   }
-  remember(latest);
   log(`  ${c.accent('✓')} ${c.dim(`Updated to v${latest} — reopening`)}`);
   return relaunch({ ...env, JAITUS_UPDATED_FROM: current });
 }
@@ -303,16 +325,20 @@ export default async function update(argv = [], { json = false, interactive = tr
     manual();
     return 0;
   }
-  const yes = argv.includes('--yes') || argv.includes('-y');
-  if (!yes) {
-    if (!process.stdin.isTTY) { manual(); return 0; }
-    const answer = await askKey(`  Install v${latest} now? ${c.dim('[Y/n]')} `, ['y', 'n', '\r', '\n']);
-    if (answer === 'n') { manual(); return 0; }
-  }
-  out(`  ${c.dim('running')} npm install -g jaitus@${latest}`);
-  const { code } = await run('npm', ['install', '-g', `jaitus@${latest}`]);
+  // Asking for the update IS the yes: it installs straight away, with the same progress
+  // line as an update on launch.
+  const tty = process.stdout.isTTY;
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  const line = `  ${c.dim('installing')} v${latest}`;
+  if (tty) process.stdout.write(`${line}…`); else out(`${line} (npm install -g jaitus@${latest})`);
+  const { code, stderr } = await installGlobal(latest, {
+    onTick: (s) => { if (tty) process.stdout.write(`\r\x1b[2K${line} ${c.brand(frames[s % frames.length])} ${c.dim(`${s}s — this usually takes under a minute`)}`); },
+  });
+  if (tty) process.stdout.write('\n');
   if (code !== 0) {
     fail(`npm could not install it (exit ${code}). Try it yourself — on macOS or Linux it may need sudo, or a Node version manager:`);
+    const reason = (stderr || '').split('\n').map((l) => l.trim()).filter(Boolean).find((l) => /ERR|EACCES|EPERM|EBUSY|ENOTEMPTY/i.test(l));
+    if (reason) info(reason.slice(0, 200));
     manual();
     return 1;
   }

package/src/errors.js

@@ -1,106 +1,120 @@
-// ─── What the CLI says when something fails ─────────────────────────────────────
-//
-// The gateway answers every failure with a `jaitus_*` code from one catalog. This file
-// is the CLI's half of that contract: a code maps to a title and a hint written here,
-// and anything WITHOUT a known code — an HTML page from a proxy, a body in some other
-// shape, a code this build has never heard of — becomes "something went wrong in
-// Jaitus" plus the request id. The CLI never prints an error body it does not
-// recognise, because the only text that is safe to show is text we wrote.
-
-const CATALOG = {
-  auth_required: { title: 'Not signed in', hint: 'Type /login to sign in (or run `jaitus login`).' },
-  session_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
-  account_suspended: { title: 'Account suspended', hint: 'Contact support if you think this is a mistake.' },
-  email_unverified: { title: 'Email not verified', hint: 'Open the verification link in your inbox, then retry.' },
-  free_limit_reached: { title: 'Free prompts used up', hint: 'Subscribe on the website, then retry this turn.' },
-  free_request_too_large: { title: 'Too large for the free plan', hint: 'Run /compact or start a new session, or subscribe.' },
-  plan_limit_reached: { title: 'Monthly allowance used', hint: 'It resets at the start of your next period, or upgrade on the website. /usage shows where you are.' },
-  rate_limited: { title: 'Slow down', hint: 'Wait a moment, then retry.' },
-  context_too_long: { title: 'Conversation too long', hint: 'Run /compact, or start a new session.' },
-  request_too_large: { title: 'Request too large', hint: 'Usually images: remove some, or run /compact to drop old ones. Images over 3.5 MB are shrunk automatically.' },
-  daily_limit_reached: { title: 'Usage limit reached', hint: 'It refills automatically. /usage shows where you are.' },
-  window_limit_reached: { title: 'This usage window is used up', hint: 'It refills when the window ends — the rest of your month is still there. /usage shows when.' },
-  token_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
-  refresh_race: { title: 'Sign-in was being renewed', hint: 'Try again.' },
-  content_blocked: { title: 'Request refused', hint: 'Rephrase the request and try again.' },
-  bad_request: { title: 'Request not accepted', hint: 'Try again; if it repeats, run /debug and contact support.' },
-  model_unavailable: { title: 'Model unavailable', hint: 'Run /model to pick another.' },
-  busy: { title: 'Jaitus is busy', hint: 'Try again in a minute.' },
-  unavailable: { title: 'Jaitus is unavailable', hint: 'Try again shortly. `jaitus doctor` checks your side.' },
-  maintenance: { title: 'Down for maintenance', hint: 'Try again shortly.' },
-  timeout: { title: 'Timed out', hint: 'Try again.' },
-  interrupted: { title: 'Response interrupted', hint: 'Try again.' },
-  internal: { title: 'Something went wrong', hint: 'Try again; if it keeps happening, contact support with the request id.' },
-};
-
-const GENERIC = 'Something went wrong in Jaitus.';
-
-export class JaitusError extends Error {
-  constructor({ code = 'internal', message, status = 0, requestId = '', retryAfter = null } = {}) {
-    const known = Object.prototype.hasOwnProperty.call(CATALOG, code) ? code : 'internal';
-    super(message || GENERIC);
-    this.name = 'JaitusError';
-    this.code = known;
-    this.status = status;
-    this.requestId = requestId;
-    this.retryAfter = retryAfter;
-    this.title = CATALOG[known].title;
-    this.hint = CATALOG[known].hint;
-  }
-}
-
-/**
- * An error body from the gateway → a JaitusError.
- *
- * The gateway's message is shown ONLY when the body carries a recognised `jaitus_`
- * code, because only then is it guaranteed to be our wording (it may carry specifics,
- * like how many free prompts there were). Otherwise the message is ours, generic.
- */
-export function fromGatewayBody(status, body, { requestId = '', retryAfter = null } = {}) {
-  let parsed = body;
-  if (typeof body === 'string') {
-    try { parsed = JSON.parse(body); } catch { parsed = null; }
-  }
-  const err = parsed?.error || null;
-  const rawCode = String(err?.code || '');
-  const code = rawCode.startsWith('jaitus_') ? rawCode.slice(7) : '';
-  const known = code && Object.prototype.hasOwnProperty.call(CATALOG, code);
-  const id = String(parsed?.request_id || requestId || '');
-  return new JaitusError({
-    code: known ? code : 'internal',
-    message: known && typeof err?.message === 'string' && err.message.trim() ? err.message.trim() : GENERIC,
-    status,
-    requestId: id,
-    retryAfter,
-  });
-}
-
-/** A failed fetch Response → a JaitusError, reading the body once. */
-export async function fromResponse(res) {
-  const text = await res.text().catch(() => '');
-  const requestId = res.headers?.get?.('x-request-id') || '';
-  const retryAfter = Number(res.headers?.get?.('retry-after')) || null;
-  return fromGatewayBody(res.status, text, { requestId, retryAfter });
-}
-
-/**
- * fetch() threw before any response — the network, not the service. This is the one
- * failure where the true cause is on the user's side and worth naming plainly.
- */
-export function fromNetwork(cause) {
-  if (cause?.name === 'AbortError') return cause;
-  const error = new JaitusError({
-    code: 'unavailable',
-    message: 'Could not reach Jaitus. Check your internet connection.',
-  });
-  error.title = 'Cannot reach Jaitus';
-  error.hint = 'Check your connection, then run `jaitus doctor`.';
-  error.cause = cause;
-  return error;
-}
-
-export function isJaitusError(e) {
-  return e instanceof JaitusError || e?.name === 'JaitusError';
-}
-
-export const ERROR_CODES = Object.freeze(Object.keys(CATALOG));
+// ─── What the CLI says when something fails ─────────────────────────────────────
+//
+// The gateway answers every failure with a `jaitus_*` code from one catalog. This file
+// is the CLI's half of that contract: a code maps to a title and a hint written here,
+// and anything WITHOUT a known code — an HTML page from a proxy, a body in some other
+// shape, a code this build has never heard of — becomes "something went wrong in
+// Jaitus" plus the request id. The CLI never prints an error body it does not
+// recognise, because the only text that is safe to show is text we wrote.
+
+const CATALOG = {
+  auth_required: { title: 'Not signed in', hint: 'Type /login to sign in (or run `jaitus login`).' },
+  session_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
+  account_suspended: { title: 'Account suspended', hint: 'Contact support if you think this is a mistake.' },
+  email_unverified: { title: 'Email not verified', hint: 'Open the verification link in your inbox, then retry.' },
+  free_limit_reached: { title: 'Free prompts used up', hint: 'Subscribe on the website, then retry this turn.' },
+  free_request_too_large: { title: 'Too large for the free plan', hint: 'Run /compact or start a new session, or subscribe.' },
+  plan_limit_reached: { title: 'Monthly allowance used', hint: 'It resets at the start of your next period, or upgrade on the website. /usage shows where you are.' },
+  rate_limited: { title: 'Slow down', hint: 'Wait a moment, then retry.' },
+  context_too_long: { title: 'Conversation too long', hint: 'Run /compact, or start a new session.' },
+  request_too_large: { title: 'Request too large', hint: 'Usually images: remove some, or run /compact to drop old ones. Images over 3.5 MB are shrunk automatically.' },
+  daily_limit_reached: { title: 'Usage limit reached', hint: 'It refills automatically. /usage shows where you are.' },
+  window_limit_reached: { title: 'This usage window is used up', hint: 'It refills when the window ends — the rest of your month is still there. /usage shows when.' },
+  token_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
+  refresh_race: { title: 'Sign-in was being renewed', hint: 'Try again.' },
+  content_blocked: { title: 'Request refused', hint: 'Rephrase the request and try again.' },
+  bad_request: { title: 'Request not accepted', hint: 'Try again; if it repeats, run /debug and contact support.' },
+  model_unavailable: { title: 'Model unavailable', hint: 'Run /model to pick another.' },
+  busy: { title: 'Jaitus is busy', hint: 'Try again in a minute.' },
+  unavailable: { title: 'Jaitus is unavailable', hint: 'Try again shortly. `jaitus doctor` checks your side.' },
+  maintenance: { title: 'Down for maintenance', hint: 'Try again shortly.' },
+  timeout: { title: 'Timed out', hint: 'Try again.' },
+  interrupted: { title: 'Response interrupted', hint: 'Try again.' },
+  internal: { title: 'Something went wrong', hint: 'Try again; if it keeps happening, contact support with the request id.' },
+};
+
+const GENERIC = 'Something went wrong in Jaitus.';
+
+export class JaitusError extends Error {
+  constructor({ code = 'internal', message, status = 0, requestId = '', retryAfter = null } = {}) {
+    const known = Object.prototype.hasOwnProperty.call(CATALOG, code) ? code : 'internal';
+    super(message || GENERIC);
+    this.name = 'JaitusError';
+    this.code = known;
+    this.status = status;
+    this.requestId = requestId;
+    this.retryAfter = retryAfter;
+    this.title = CATALOG[known].title;
+    this.hint = CATALOG[known].hint;
+  }
+}
+
+/**
+ * An error body from the gateway → a JaitusError.
+ *
+ * The gateway's message is shown ONLY when the body carries a recognised `jaitus_`
+ * code, because only then is it guaranteed to be our wording (it may carry specifics,
+ * like how many free prompts there were). Otherwise the message is ours, generic.
+ */
+export function fromGatewayBody(status, body, { requestId = '', retryAfter = null } = {}) {
+  let parsed = body;
+  if (typeof body === 'string') {
+    try { parsed = JSON.parse(body); } catch { parsed = null; }
+  }
+  const err = parsed?.error || null;
+  const rawCode = String(err?.code || '');
+  const code = rawCode.startsWith('jaitus_') ? rawCode.slice(7) : '';
+  const known = code && Object.prototype.hasOwnProperty.call(CATALOG, code);
+  const id = String(parsed?.request_id || requestId || '');
+  // No Jaitus code on a gateway-class status: the answer came from the proxy in front of
+  // the gateway (its timeout page, a 502 while a deploy restarts the server), not from
+  // the gateway. Those are "not right now" — said plainly and retried — never the
+  // dead-end "Something went wrong" they used to read as.
+  if (!known && (status === 504 || status === 524)) {
+    return new JaitusError({ code: 'timeout', status, requestId: id, retryAfter, message: 'Jaitus took too long to answer and the connection was closed on the way. Try again.' });
+  }
+  if (!known && (status === 502 || status === 503 || (status >= 520 && status <= 530))) {
+    return new JaitusError({ code: 'unavailable', status, requestId: id, retryAfter, message: 'Jaitus could not be reached just now. Try again in a moment.' });
+  }
+  return new JaitusError({
+    code: known ? code : 'internal',
+    message: known && typeof err?.message === 'string' && err.message.trim() ? err.message.trim() : GENERIC,
+    status,
+    requestId: id,
+    retryAfter,
+  });
+}
+
+/** A failed fetch Response → a JaitusError, reading the body once. */
+export async function fromResponse(res) {
+  const text = await res.text().catch(() => '');
+  const requestId = res.headers?.get?.('x-request-id') || '';
+  const retryAfter = Number(res.headers?.get?.('retry-after')) || null;
+  const error = fromGatewayBody(res.status, text, { requestId, retryAfter });
+  // The gateway says trying again cannot help yet (e.g. no provider is switched on):
+  // report it at once instead of retrying behind "Working…".
+  if (res.headers?.get?.('x-jaitus-retry') === 'no') error.noRetry = true;
+  return error;
+}
+
+/**
+ * fetch() threw before any response — the network, not the service. This is the one
+ * failure where the true cause is on the user's side and worth naming plainly.
+ */
+export function fromNetwork(cause) {
+  if (cause?.name === 'AbortError') return cause;
+  const error = new JaitusError({
+    code: 'unavailable',
+    message: 'Could not reach Jaitus. Check your internet connection.',
+  });
+  error.title = 'Cannot reach Jaitus';
+  error.hint = 'Check your connection, then run `jaitus doctor`.';
+  error.cause = cause;
+  return error;
+}
+
+export function isJaitusError(e) {
+  return e instanceof JaitusError || e?.name === 'JaitusError';
+}
+
+export const ERROR_CODES = Object.freeze(Object.keys(CATALOG));