ticketlens 0.21.7 → 0.21.9

package/README.md

@@ -401,9 +401,11 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Quality loop:** inside a Claude Code session using the jtb skill, a saved note can be silently refined afterward — a generator subagent drafts a more actionable version, a validator subagent checks it against other notes on the same ticket for duplication, up to 3 rounds — and the improved draft overwrites the original via the internal `note patch` command (not typically invoked by hand). This makes zero API calls and costs zero extra tokens beyond your already-running session; it never runs for a bare shell invocation of `note add`, which is skipped silently. Known limitation: a refined draft is not re-synced to your team even if the original was — teammates who already pulled the note keep the earlier draft.
 
-**Team sync:** on a Team plan with Recall enabled for your account (owner-managed, per-tier or per-client), notes also sync to your team's shared pool — `note add` pushes in the background, `recall` pulls the team's notes (cached 4h) before searching. A team manager reviews and verifies incoming notes at `console/admin/recall` before they're marked trusted. Without Team Recall entitlement, everything stays on your machine — no network call.
+**Team sync:** on a Team plan with Recall enabled for your account (owner-managed, per-tier or per-client), notes also sync to your team's shared pool — `note add` pushes in the background, `recall` always pulls the team's notes fresh before searching, so a manager's verify/delete in Console is visible on that very search. (Ticket-brief injection uses a separate, short-timeout 4h-cached pull so it never slows down your everyday `ticketlens PROJ-123` — it doesn't need to be instant the way an explicit search does.) A team manager reviews and verifies incoming notes at `console/admin/recall` before they're marked trusted. Without Team Recall entitlement, everything stays on your machine — no network call.
 
-**Offline resilience:** if a team push fails for a transient reason (network error, timeout, or a 5xx from the backend), the note stays safely in your local vault and is queued for retry — nothing is lost. The queue flushes automatically in the background (at most once every 15 minutes) before every command, not just `recall`/`note add` — a short 4s timeout on that check means it never stalls an unrelated command — or on demand with `ticketlens recall sync`. A session-expired (401) or not-entitled (403) push is never queued — those need you to act (`ticketlens login`, or an owner grant), not a retry. Queued entries expire after 30 days and are capped at 200; switching accounts never flushes a note under the wrong login.
+**Offline resilience:** if a team push fails for a transient reason (network error, timeout, or a 5xx from the backend), the note stays safely in your local vault and is queued for retry — nothing is lost. The queue flushes automatically in the background before every command, not just `recall`/`note add` — a short timeout on that check means it never stalls an unrelated command — or on demand with `ticketlens recall sync`. A session-expired (401) or not-entitled (403) push is never queued — those need you to act (`ticketlens login`, or an owner grant), not a retry. Switching accounts never flushes a note under the wrong login.
+
+**Queue settings:** the retry cooldown (default 15 min), per-request timeout (4s), max queued notes (200), and queued-note expiry (30 days) are set by your team manager at `console/admin/recall` and apply to every member's CLI — solo users get the same platform defaults. `ticketlens recall settings` shows the values currently in effect, fetched live: a manager's change is visible the moment your CLI's next retry decision runs, not on a delay.
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
@@ -684,6 +686,7 @@ ticketlens note delete --id="..." --ticket=CNV1-2  # Remove a note from your loc
 ticketlens recall CNV1-2                      # Search saved notes by ticket key [Pro]
 ticketlens recall "retry backoff"             # Free-text search across all notes [Pro]
 ticketlens recall sync                        # Retry any notes stuck in the local queue [Pro]
+ticketlens recall settings                    # Show effective retry-queue settings, fetched live [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -764,6 +767,7 @@ ticketlens note add --title="..."        # Save a Recall note (body from stdin)
 ticketlens note delete --id="..."        # Remove a note from your local vault
 ticketlens recall <query|TICKET-KEY>     # Search your saved Recall notes
 ticketlens recall sync                   # Retry any notes stuck in the local queue
+ticketlens recall settings               # Show effective retry-queue settings, fetched live
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -70,9 +70,10 @@ checkForUpdate();
 try {
   const cliToken = readCliToken(DEFAULT_CONFIG_DIR);
   if (cliToken) {
-    // Short timeout — this runs before every command, unrelated to Recall or
+    // Timeout defaults to the effective settings' timeout_ms (Console-managed,
+    // 4s by default) — this runs before every command, unrelated to Recall or
     // not, so it must never be the reason an unrelated command feels slow.
-    const result = await maybeAutoFlush({ cliToken, configDir: DEFAULT_CONFIG_DIR, timeoutMs: 4000 });
+    const result = await maybeAutoFlush({ cliToken, configDir: DEFAULT_CONFIG_DIR });
     if (result?.flushed) {
       process.stderr.write(`  ✔ Synced ${result.flushed} pending Recall note${result.flushed === 1 ? '' : 's'}.\n`);
     }
@@ -678,6 +679,16 @@ switch (command) {
       });
       break;
     }
+    if (cmdArgs[0] === 'settings') {
+      const { runRecallSettings } = await import('../skills/jtb/scripts/lib/recall-command.mjs');
+      runRecallSettings(cmdArgs.slice(1)).then(({ ok }) => {
+        if (!ok) process.exitCode = 1;
+      }).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
+      break;
+    }
     const { runRecall } = await import('../skills/jtb/scripts/lib/recall-command.mjs');
     runRecall(cmdArgs).then(({ ok }) => {
       if (!ok) process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.21.7",
+  "version": "0.21.9",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -55,6 +55,7 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb note "gotcha text" --ticket=PROD-1234    # save a Recall note (Pro)
 /jtb recall PROD-1234                  # search saved Recall notes (Pro)
 /jtb recall sync                       # retry any notes stuck in the local queue (Pro)
+/jtb recall settings                   # show effective retry-queue settings, fetched live (Pro)
 ```
 
 ## Prerequisites

package/skills/jtb/scripts/lib/help.mjs

@@ -548,6 +548,7 @@ export function printRecallHelp({ stream = process.stdout } = {}) {
     `  ${s.bold('COMMANDS')}`,
     '',
     `    ${s.brand('sync')}          Manually retry any team-synced notes stuck in the local retry queue ${s.dim('[Pro, requires login]')}`,
+    `    ${s.brand('settings')}      Show effective retry-queue settings (cooldown, timeout, queue limits) ${s.dim('[Pro]')}`,
     '',
     `  ${s.bold('EXAMPLES')}`,
     '',
@@ -556,6 +557,7 @@ export function printRecallHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('$')} ticketlens recall PROD-123 --plain`,
     `    ${s.dim('$')} ticketlens recall PROD-123 --full`,
     `    ${s.dim('$')} ticketlens recall sync`,
+    `    ${s.dim('$')} ticketlens recall settings`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/note-command.mjs

@@ -141,7 +141,7 @@ export async function runNoteAdd(cmdArgs, {
     const payload = { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body };
     const result = await pushNoteFn(payload, { cliToken, configDir, warn });
     if (isRetryableFailureFn(result)) {
-      enqueueNoteFn(payload, { cliToken, configDir, warn });
+      await enqueueNoteFn(payload, { cliToken, configDir, warn });
     }
     await maybeAutoFlushFn({ cliToken, configDir });
   }

package/skills/jtb/scripts/lib/recall-command.mjs

@@ -1,8 +1,12 @@
 /**
  * Implements `tl recall <query|TICKET-KEY>` — a search over saved Recall
- * notes, local-first. When logged in, pulls the team vault down before
- * searching (the user is explicitly waiting on this command, so the full
- * request timeout applies here — unlike the passive brief-fetch pull path).
+ * notes, local-first. When logged in, always pulls the team vault fresh
+ * before searching (ttlMs: 0, bypassing the TTL cache entirely) — the user
+ * is explicitly waiting on this command, so a manager's Console verify/
+ * delete action is visible on this very invocation, not up to 4h later.
+ * The full request timeout applies here — unlike the passive brief-fetch
+ * pull path (fetch-ticket.mjs), which deliberately keeps its short timeout
+ * and TTL cache since it runs on nearly every command, not just this one.
  * A pull failure never blocks the local search from returning results.
  */
 
@@ -13,6 +17,7 @@ import { listNotes } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
 import { pullNotes } from './recall-sync.mjs';
 import { maybeAutoFlush, flushQueue, readQueue } from './recall-queue.mjs';
+import { getEffectiveRecallSettings } from './recall-settings-sync.mjs';
 import { styleRecallResults } from './styled-assembler.mjs';
 
 /**
@@ -42,11 +47,7 @@ export async function runRecall(cmdArgs, {
 
   const cliToken = readCliTokenFn(configDir);
   if (cliToken) {
-    await pullNotesFn({
-      cliToken,
-      configDir,
-      ...(cmdArgs.includes('--no-cache') && { ttlMs: 0 }),
-    });
+    await pullNotesFn({ cliToken, configDir, ttlMs: 0 });
     await maybeAutoFlushFn({ cliToken, configDir });
   }
 
@@ -96,3 +97,38 @@ export async function runRecallSync(cmdArgs, {
   stream.write(`Synced ${flushed} note(s). ${remaining} still pending.\n`);
   return { ok: true };
 }
+
+/**
+ * Implements `tl recall settings` — read-only display of the effective
+ * Recall queue settings (flush cooldown, per-request timeout, max queue
+ * size, max entry age). Management happens in Console (console/admin/recall,
+ * manager-only); this fetches live so it always reflects the manager's
+ * latest saved value, falling back to the last-known cache/platform default
+ * if offline.
+ *
+ * @param {string[]} cmdArgs
+ * @returns {Promise<{ ok: boolean }>}
+ */
+export async function runRecallSettings(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stdout,
+  isLicensedFn = isLicensed,
+  readCliTokenFn = readCliToken,
+  getEffectiveRecallSettingsFn = getEffectiveRecallSettings,
+} = {}) {
+  if (!isLicensedFn('pro', configDir)) {
+    showUpgradePrompt('pro', 'ticketlens recall', { stream });
+    return { ok: false };
+  }
+
+  const cliToken = readCliTokenFn(configDir);
+  const settings = await getEffectiveRecallSettingsFn({ cliToken, configDir });
+  const source = cliToken ? 'your team manager (or platform default if unset)' : 'platform default — log in to pick up a team override';
+
+  stream.write(`  Retry cooldown:      ${settings.flush_cooldown_ms / 60_000} min\n`);
+  stream.write(`  Per-request timeout: ${settings.timeout_ms / 1_000} sec\n`);
+  stream.write(`  Max queued notes:    ${settings.max_queue_size}\n`);
+  stream.write(`  Queued note expiry:  ${settings.max_entry_age_ms / 86_400_000} days\n`);
+  stream.write(`  Source: ${source}\n`);
+  return { ok: true };
+}

package/skills/jtb/scripts/lib/recall-queue.mjs

@@ -29,13 +29,17 @@ import path from 'node:path';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { writeFileAtomically } from './recall-vault.mjs';
 import { pushNote, hashToken } from './recall-sync.mjs';
+import { getEffectiveRecallSettings, DEFAULT_RECALL_SETTINGS } from './recall-settings-sync.mjs';
 
 const QUEUE_FILE = 'recall-pending.json';
 const FLUSH_STATE_FILE = 'recall-flush-state.json';
 
-export const MAX_QUEUE_SIZE = 200;
-export const MAX_ENTRY_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
-export const AUTO_FLUSH_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes
+// Platform defaults — actual effective values now come from
+// getEffectiveRecallSettings(), which is the manager's Console override for
+// their team if one exists (fetched live), else these same numbers.
+export const DEFAULT_MAX_QUEUE_SIZE = DEFAULT_RECALL_SETTINGS.max_queue_size;
+export const DEFAULT_MAX_ENTRY_AGE_MS = DEFAULT_RECALL_SETTINGS.max_entry_age_ms;
+export const DEFAULT_AUTO_FLUSH_INTERVAL_MS = DEFAULT_RECALL_SETTINGS.flush_cooldown_ms;
 
 function queuePath(configDir) {
   return path.join(configDir, QUEUE_FILE);
@@ -62,8 +66,8 @@ function writeQueue(configDir, entries) {
   writeFileAtomically(queuePath(configDir), JSON.stringify(entries));
 }
 
-function purgeExpired(entries, now) {
-  return entries.filter(entry => now - new Date(entry.firstQueuedAt).getTime() <= MAX_ENTRY_AGE_MS);
+function purgeExpired(entries, now, maxEntryAgeMs) {
+  return entries.filter(entry => now - new Date(entry.firstQueuedAt).getTime() <= maxEntryAgeMs);
 }
 
 /**
@@ -84,7 +88,10 @@ export function isRetryableFailure(result) {
 /**
  * Queues a note for later retry after a transient push failure. Purges
  * expired entries first, then evicts the oldest entry (with a single warn)
- * if appending would exceed MAX_QUEUE_SIZE.
+ * if appending would exceed the effective max queue size (Console-managed
+ * per team, fetched live — see recall-settings-sync.mjs). Async: a push just
+ * failed, so one more short network call to get the current cap/expiry
+ * doesn't change this path's performance characteristics.
  *
  * @param {object}   notePayload - exact wire payload passed to pushNote
  * @param {object}   opts
@@ -92,17 +99,20 @@ export function isRetryableFailure(result) {
  * @param {string}   [opts.configDir]
  * @param {() => number} [opts.now]
  * @param {Function} [opts.warn]
+ * @returns {Promise<void>}
  */
-export function enqueueNote(notePayload, {
+export async function enqueueNote(notePayload, {
   cliToken,
   configDir = DEFAULT_CONFIG_DIR,
   now = () => Date.now(),
   warn = (s) => process.stderr.write(s),
+  getEffectiveRecallSettingsFn = getEffectiveRecallSettings,
 } = {}) {
   const nowMs = now();
-  let entries = purgeExpired(readQueue(configDir), nowMs);
+  const settings = await getEffectiveRecallSettingsFn({ cliToken, configDir });
+  let entries = purgeExpired(readQueue(configDir), nowMs, settings.max_entry_age_ms);
 
-  if (entries.length >= MAX_QUEUE_SIZE) {
+  if (entries.length >= settings.max_queue_size) {
     entries = entries.slice(1);
     warn('  Recall queue full — dropped the oldest queued note to make room.\n');
   }
@@ -142,10 +152,22 @@ export async function flushQueue({
   warn = () => {},
   now = () => Date.now(),
   timeoutMs,
+  settings,
+  getEffectiveRecallSettingsFn = getEffectiveRecallSettings,
 } = {}) {
   const nowMs = now();
   const currentHash = hashToken(cliToken);
-  const entries = purgeExpired(readQueue(configDir), nowMs);
+  // Only the age bound comes from settings here — timeoutMs is caller-supplied
+  // or falls through to pushNote's own default. maybeAutoFlush (below) is the
+  // one call site that maps the Console-configured timeout_ms onto this param;
+  // runRecallSync's manual, user-initiated flush deliberately keeps a longer,
+  // uncapped-by-this-setting timeout since the user is actively waiting.
+  // `settings` is an optional already-fetched value — maybeAutoFlush passes
+  // its own fetch through here so a single auto-flush attempt never fetches
+  // settings twice; a direct/manual call (runRecallSync) has none yet, so
+  // this fetches its own.
+  const effectiveSettings = settings ?? await getEffectiveRecallSettingsFn({ cliToken, configDir });
+  const entries = purgeExpired(readQueue(configDir), nowMs, effectiveSettings.max_entry_age_ms);
 
   let flushed = 0;
   const remaining = [];
@@ -199,14 +221,15 @@ function writeLastFlushAttemptAt(configDir, isoTimestamp) {
  * a burst of failures (e.g. a debugging session) would otherwise sit queued
  * until the user happens to run `note add`/`recall` again, or runs
  * `recall sync` by hand. A no-op unless the queue is non-empty AND at least
- * AUTO_FLUSH_INTERVAL_MS has passed since the last attempt — the interval is
- * a single global cooldown, not per-entry, so a burst of failures in one
- * short window still only gets one automatic retry pass, by design: this
- * runs on every command now, so the next opportunity is never far away, and
- * the cooldown exists specifically to stop a down backend from being hit by
- * every single command in the meantime. The attempt timestamp is recorded
- * even on failure, so a down backend can't be hammered once per command
- * within the window.
+ * the effective flush cooldown (Console-managed per team, defaults to 15
+ * minutes — see recall-settings-sync.mjs) has passed since the last attempt.
+ * The interval is a single global cooldown, not per-entry, so a burst of
+ * failures in one short window still only gets one automatic retry pass, by
+ * design: this runs on every command now, so the next opportunity is never
+ * far away, and the cooldown exists specifically to stop a down backend from
+ * being hit by every single command in the meantime. The attempt timestamp is
+ * recorded even on failure, so a down backend can't be hammered once per
+ * command within the window.
  *
  * @param {object}   opts
  * @param {string}   opts.cliToken
@@ -214,9 +237,10 @@ function writeLastFlushAttemptAt(configDir, isoTimestamp) {
  * @param {() => number} [opts.now]
  * @param {Function} [opts.flushQueueFn]
  * @param {number}   [opts.timeoutMs] - per-request timeout, passed through to
- *   pushNote. Callers running this unconditionally on every command (as
- *   opposed to an explicit `recall sync`) should pass something short — this
- *   must feel instant, not stall an unrelated command behind a slow network.
+ *   pushNote. Defaults to the effective settings' timeout_ms (Console-managed,
+ *   defaults to 4s) — short, because this runs unconditionally on every
+ *   command and must feel instant, not stall an unrelated command behind a
+ *   slow network. Pass explicitly to override.
  * @returns {Promise<{flushed: number, remaining: number}|null>} null if skipped
  *   (empty queue or still cooling down) — distinguishes "nothing to report"
  *   from "attempted, flushed 0" for a caller that wants to print a summary.
@@ -227,15 +251,21 @@ export async function maybeAutoFlush({
   now = () => Date.now(),
   flushQueueFn = flushQueue,
   timeoutMs,
+  getEffectiveRecallSettingsFn = getEffectiveRecallSettings,
 } = {}) {
   if (readQueue(configDir).length === 0) return null;
 
+  // Fetched once here (live) and threaded through to flushQueueFn below —
+  // flushQueue also needs max_entry_age_ms but must not fetch a second time
+  // for what is, from the outside, a single "attempt a flush" decision.
+  const settings = await getEffectiveRecallSettingsFn({ cliToken, configDir });
   const lastAttemptAt = readLastFlushAttemptAt(configDir);
   const nowMs = now();
-  if (lastAttemptAt && nowMs - new Date(lastAttemptAt).getTime() < AUTO_FLUSH_INTERVAL_MS) return null;
+  if (lastAttemptAt && nowMs - new Date(lastAttemptAt).getTime() < settings.flush_cooldown_ms) return null;
 
+  const effectiveTimeoutMs = timeoutMs !== undefined ? timeoutMs : settings.timeout_ms;
   try {
-    return await flushQueueFn({ cliToken, configDir, now, ...(timeoutMs !== undefined ? { timeoutMs } : {}) });
+    return await flushQueueFn({ cliToken, configDir, now, timeoutMs: effectiveTimeoutMs, settings });
   } catch {
     // A down backend or a thrown network error must never crash the command
     // that opportunistically triggered this background attempt.

package/skills/jtb/scripts/lib/recall-settings-sync.mjs

@@ -0,0 +1,168 @@
+/**
+ * Effective Recall queue settings (flush cooldown, per-request timeout, max
+ * queue size, max entry age) — manager-controlled per team via the Console
+ * (console/admin/recall).
+ *
+ * getEffectiveRecallSettings() fetches live at the moment a caller actually
+ * needs a decision (queue non-empty, a push just failed, or an explicit `tl
+ * recall settings`) — never on a background timer. Those moments are already
+ * rare (recall-queue.mjs's callers all short-circuit on a local, network-free
+ * read when there's nothing to do), so a manager's Console change is visible
+ * on the very next command that matters, without adding network cost to the
+ * overwhelming majority of commands that never touch this at all.
+ *
+ * A local cache (recall-settings-cache.json) exists only as an offline/
+ * failure fallback — written on every successful fetch, read when a fetch
+ * fails or there's no cliToken. Values from it are never trusted blindly,
+ * even though they came from our own backend: they're re-clamped against the
+ * same bounds the server enforces, so a corrupted cache file or a future
+ * server bug can never push a CLI-side value (e.g. a near-zero cooldown)
+ * outside safe range.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { apiBase } from './api-utils.mjs';
+import { writeFileAtomically } from './recall-vault.mjs';
+import { hashToken } from './recall-sync.mjs';
+
+const SETTINGS_PATH = '/v1/recall/settings';
+const CACHE_FILE = 'recall-settings-cache.json';
+
+// Fixed, not manager-configurable — this timeout gates the fetch of the
+// settings themselves, so it can't depend on a settings value that hasn't
+// been fetched yet. Short: this fires only on already-rare paths, but must
+// still never let a slow/down backend meaningfully stall those commands.
+const FETCH_TIMEOUT_MS = 3_000;
+
+// Platform defaults — must match RecallSettings::DEFAULTS in ticketlens-api.
+export const DEFAULT_RECALL_SETTINGS = {
+  flush_cooldown_ms: 900_000,       // 15 minutes
+  timeout_ms: 4_000,                // 4 seconds
+  max_queue_size: 200,
+  max_entry_age_ms: 2_592_000_000,  // 30 days
+};
+
+// Inclusive [min, max] bounds — must match RecallSettings::BOUNDS in ticketlens-api.
+export const RECALL_SETTINGS_BOUNDS = {
+  flush_cooldown_ms: [60_000, 86_400_000],       // 1m .. 24h
+  timeout_ms: [1_000, 30_000],                   // 1s .. 30s
+  max_queue_size: [10, 2_000],
+  max_entry_age_ms: [3_600_000, 7_776_000_000],  // 1h .. 90d
+};
+
+function cachePath(configDir) {
+  return path.join(configDir, CACHE_FILE);
+}
+
+function clamp(field, value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_RECALL_SETTINGS[field];
+  const [min, max] = RECALL_SETTINGS_BOUNDS[field];
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Local-only, synchronous fallback — used when there's no cliToken, or a live
+ * fetch just failed. Requires cliToken to return a cached override at all: a
+ * cache written under a different (or since-logged-out) account must never
+ * silently apply to this one, so a tokenHash mismatch (or no token) falls
+ * through to platform defaults rather than trusting stale/foreign data.
+ *
+ * @param {string} configDir
+ * @param {object} [opts]
+ * @param {string} [opts.cliToken]
+ * @returns {{flush_cooldown_ms: number, timeout_ms: number, max_queue_size: number, max_entry_age_ms: number}}
+ */
+export function readEffectiveRecallSettings(configDir = DEFAULT_CONFIG_DIR, { cliToken } = {}) {
+  if (!cliToken) return { ...DEFAULT_RECALL_SETTINGS };
+
+  let cached;
+  try {
+    cached = JSON.parse(fs.readFileSync(cachePath(configDir), 'utf8'));
+  } catch {
+    return { ...DEFAULT_RECALL_SETTINGS };
+  }
+  if (!cached || typeof cached.values !== 'object' || cached.tokenHash !== hashToken(cliToken)) {
+    return { ...DEFAULT_RECALL_SETTINGS };
+  }
+
+  const effective = {};
+  for (const field of Object.keys(DEFAULT_RECALL_SETTINGS)) {
+    effective[field] = clamp(field, cached.values[field]);
+  }
+  return effective;
+}
+
+/**
+ * GET /v1/recall/settings. Returns {ok:false} on any network/parse failure —
+ * callers fall back to readEffectiveRecallSettings' cached/default behavior.
+ */
+export async function fetchRecallSettings({
+  cliToken,
+  timeoutMs = FETCH_TIMEOUT_MS,
+  fetcher = globalThis.fetch,
+} = {}) {
+  if (!cliToken) return { ok: false, error: 'no-token' };
+
+  let res;
+  try {
+    res = await fetcher(`${apiBase()}${SETTINGS_PATH}`, {
+      headers: { Authorization: `Bearer ${cliToken}`, Accept: 'application/json' },
+      redirect: 'manual',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    return { ok: false, error: 'network', message: e.message };
+  }
+
+  if (!res.ok) return { ok: false, error: `http-${res.status}` };
+
+  let payload;
+  try {
+    payload = await res.json();
+  } catch {
+    return { ok: false, error: 'parse' };
+  }
+
+  return { ok: true, values: payload, isOverride: payload.is_override === true };
+}
+
+/**
+ * The main entry point — fetches live so a manager's Console change is
+ * visible immediately, falling back to the last-known-good local cache (or
+ * platform defaults) on any failure so a network blip never blocks a retry
+ * decision. Every successful fetch refreshes that fallback cache too, tagged
+ * with a hash of cliToken so a later account switch never serves a stale
+ * team's settings as a "fallback."
+ *
+ * @param {object} opts
+ * @param {string} [opts.cliToken]
+ * @param {string} [opts.configDir]
+ * @param {() => number} [opts.now]
+ * @param {Function} [opts.fetchRecallSettingsFn]
+ * @returns {Promise<{flush_cooldown_ms: number, timeout_ms: number, max_queue_size: number, max_entry_age_ms: number}>}
+ */
+export async function getEffectiveRecallSettings({
+  cliToken,
+  configDir = DEFAULT_CONFIG_DIR,
+  now = () => Date.now(),
+  fetchRecallSettingsFn = fetchRecallSettings,
+} = {}) {
+  if (!cliToken) return readEffectiveRecallSettings(configDir);
+
+  const result = await fetchRecallSettingsFn({ cliToken });
+  if (!result.ok) return readEffectiveRecallSettings(configDir, { cliToken });
+
+  writeFileAtomically(cachePath(configDir), JSON.stringify({
+    values: result.values,
+    tokenHash: hashToken(cliToken),
+    fetchedAt: new Date(now()).toISOString(),
+  }));
+
+  const effective = {};
+  for (const field of Object.keys(DEFAULT_RECALL_SETTINGS)) {
+    effective[field] = clamp(field, result.values[field]);
+  }
+  return effective;
+}