acuvo-code 0.2.0 → 0.3.0

package/bin/acuvo.mjs

@@ -1109,7 +1109,61 @@ ${formatBoard(listed)}
     let raw = life.loginToken;
     if (raw === null) {
       if (process.stdin.isTTY) {
-        die('paste the key on stdin: `acuvo --login < key.txt`, or pass it directly with `acuvo --login <key>`.', EXIT_USAGE);
+        /**
+         * ── ⭐⭐⭐ NO KEY AND A REAL PERSON: LOG THEM IN (2026-08-22) ─────────
+         *
+         * This branch used to `die()` with instructions to go and find a key.
+         * That was the five-step path — sign in, find Settings, create a key,
+         * copy it, come back — where Claude Code has one step.
+         *
+         * ⭐ Roman: *"like how I pay and I can type claude and it works, but it
+         * probably works for anyone, but they have to log in."* This is that.
+         */
+        const { requestDeviceCode, pollForKey, openBrowser } = await import('../lib/device-login.mjs');
+        const { spawn } = await import('node:child_process');
+        const gateway = process.env.ACUVO_GATEWAY_URL || DEFAULT_GATEWAY_URL;
+
+        let start;
+        try {
+          start = await requestDeviceCode(gateway);
+        } catch (e) {
+          die(e?.message ?? 'could not start a login.', EXIT_USAGE);
+        }
+
+        const url = start.verification_uri_complete || start.verification_uri;
+        /**
+         * ⚠️ THE URL AND CODE ARE PRINTED WHETHER OR NOT THE BROWSER OPENS.
+         * This runs over SSH, in containers and in terminals with no desktop
+         * session, where opening a browser is impossible — a flow that assumes
+         * it worked strands every remote user.
+         */
+        process.stderr.write(`\nYour code:  ${start.user_code}\n\n`);
+        const opened = openBrowser(url, { spawn });
+        process.stderr.write(
+          opened
+            ? `Opened your browser to approve it. If nothing appeared:\n  ${url}\n\n`
+            : `Open this to approve it:\n  ${url}\n\n`,
+        );
+        process.stderr.write('Waiting for approval… (Ctrl-C to cancel)\n');
+
+        let granted;
+        try {
+          granted = await pollForKey(gateway, start.device_code, {
+            intervalMs: (start.interval ?? 2) * 1000,
+            expiresInMs: (start.expires_in ?? 600) * 1000,
+          });
+        } catch (e) {
+          die(e?.message ?? 'login failed.', EXIT_USAGE);
+        }
+
+        const saved = writeAccount({ token: granted.api_key, gatewayUrl: gateway });
+        const { maskToken: mask } = await import('../lib/login.mjs');
+        process.stderr.write(`\nSigned in. Key ${mask(granted.api_key)} saved.\n`);
+        if (saved && saved.restricted === false) {
+          process.stderr.write('⚠️  Could not restrict permissions on the credentials file — check it yourself.\n');
+        }
+        process.stderr.write('Run `acuvo` to start.\n');
+        process.exit(0);
       }
       const chunks = [];
       for await (const c of process.stdin) chunks.push(c);
@@ -3096,8 +3150,47 @@ ${formatBoard(listed)}
   return verdictExit(outcome);
 }
 
+/**
+ * ── ⭐⭐⭐ THE UPDATE CHECK RUNS AT EXIT, NEVER AT STARTUP ────────────────────
+ *
+ * Roman, 2026-08-22: *"how do we do self updates so all users get updates as
+ * soon as we do it… like Claude."*
+ *
+ * ⚠️ AT EXIT BECAUSE STARTUP LATENCY IS THE ONE THING A CLI CANNOT SPEND. The
+ * user has their answer by the time this runs, so the worst case — a 3-second
+ * timeout against an unreachable registry — costs them nothing they were
+ * waiting on. At startup the same code would delay the first token of every
+ * single run to serve a check that matters once a day.
+ *
+ * ⚠️ AND IT CANNOT FAIL THE RUN. Every path is caught and the exit code is the
+ * one `main()` decided. An update mechanism that can turn a successful task into
+ * a failure has inverted its own purpose.
+ */
+async function noticeUpdateQuietly() {
+  try {
+    const { updatesEnabled, checkForUpdate, applyUpdate, updateNotice } = await import('../lib/self-update.mjs');
+    if (!updatesEnabled()) return;
+    // A machine-readable run must stay machine-readable — a friendly line on
+    // stderr is still a surprise to something parsing this.
+    if (process.env.ACUVO_JSON === '1') return;
+
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const { latest, isNewer } = await checkForUpdate({ current: pkg.version });
+    if (!isNewer) return;
+
+    const { spawn } = await import('node:child_process');
+    const started = applyUpdate({ spawn });
+    process.stderr.write(updateNotice(pkg.version, latest, started));
+  } catch {
+    // Deliberately total. Nothing about staying current is worth a stack trace.
+  }
+}
+
 main().then(
-  (code) => process.exit(code),
+  async (code) => {
+    await noticeUpdateQuietly();
+    process.exit(code);
+  },
   (err) => {
     // Nothing should reach here — every expected failure is a returned value.
     // A stack trace escaping to the user is therefore a BUG in this package,

package/lib/device-login.mjs

@@ -0,0 +1,151 @@
+/**
+ * ── ⭐⭐⭐ `acuvo` LOGS ITSELF IN ────────────────────────────────────────────
+ *
+ * Roman, 2026-08-22: *"paying users should be able to type acuvo into a terminal
+ * and then it works... like how I pay and I can type claude and it works, but it
+ * probably works for anyone, but they have to log in."*
+ *
+ * RFC 8628 device-authorization grant, client half. Replaces the five-step
+ * manual path (sign in → find Settings → create key → copy → `acuvo --login
+ * xxi_live_…`) with: run `acuvo`, approve in the browser, done.
+ *
+ * ⚠️ EVERY PIECE OF IO IS INJECTED — `fetchImpl`, `openBrowser`, `sleep`, `now`.
+ * Not for purity's sake: this module's whole job is a timing loop against a
+ * remote service, and a version that can only be tested by actually waiting two
+ * seconds a tick against production is a version nobody tests. The CLI's success
+ * path had zero coverage once before, for exactly this reason.
+ */
+
+import { DEFAULT_GATEWAY_URL } from './account.mjs';
+
+/**
+ * The gateway constant points at the completions endpoint; the device endpoints
+ * are siblings of it. Derived rather than duplicated so a self-hosted or staging
+ * gateway moves all three together.
+ */
+export function deviceEndpoints(gatewayUrl = DEFAULT_GATEWAY_URL) {
+  const base = String(gatewayUrl).replace(/\/api\/cli\/v1\/chat\/completions\/?$/, '');
+  return {
+    code: `${base}/api/cli/v1/device/code`,
+    token: `${base}/api/cli/v1/device/token`,
+  };
+}
+
+/** Ask for a device code. Returns the server's payload, or throws a readable error. */
+export async function requestDeviceCode(gatewayUrl = DEFAULT_GATEWAY_URL, { fetchImpl = fetch, timeoutMs = 15000 } = {}) {
+  const { code } = deviceEndpoints(gatewayUrl);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetchImpl(code, { method: 'POST', signal: controller.signal });
+  } catch (e) {
+    throw new Error(`could not reach Acuvo to start a login (${e?.message ?? e}). Check your connection.`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  /**
+   * ⚠️ A NON-JSON BODY IS THE SYMPTOM THAT MATTERS HERE. If the middleware ever
+   * stops exempting this path, the response is a 307 to an HTML login page —
+   * and "unexpected token < in JSON" tells the user nothing they can act on.
+   * That exact failure has shipped on this path before.
+   */
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(
+      `Acuvo returned a ${res.status} that was not JSON — the login endpoint is not reachable. ` +
+      `This is a server-side problem, not something you can fix locally.`,
+    );
+  }
+  if (!res.ok) throw new Error(json?.error ? `login could not start: ${json.error}` : `login could not start (HTTP ${res.status})`);
+  if (!json?.device_code || !json?.user_code) throw new Error('Acuvo did not return a login code.');
+  return json;
+}
+
+/** RFC 8628 statuses that mean "keep waiting" rather than "stop". */
+const PENDING = new Set(['authorization_pending', 'slow_down']);
+
+/**
+ * Poll until the human approves, denies, or the code expires.
+ *
+ * @returns {Promise<{api_key: string, tenant_id: string|null}>}
+ */
+export async function pollForKey(
+  gatewayUrl,
+  deviceCode,
+  {
+    intervalMs = 2000,
+    expiresInMs = 600000,
+    fetchImpl = fetch,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = () => Date.now(),
+    onTick = () => {},
+  } = {},
+) {
+  const { token } = deviceEndpoints(gatewayUrl);
+  const deadline = now() + expiresInMs;
+  let wait = intervalMs;
+
+  while (now() < deadline) {
+    await sleep(wait);
+    onTick();
+
+    let res;
+    let json = {};
+    try {
+      res = await fetchImpl(token, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ device_code: deviceCode }),
+      });
+      json = await res.json().catch(() => ({}));
+    } catch {
+      /**
+       * ⚠️ A DROPPED POLL IS NOT A FAILED LOGIN. Wifi blips mid-approval are
+       * ordinary; aborting here would throw away an approval the user already
+       * gave. Keep waiting until the code itself expires.
+       */
+      continue;
+    }
+
+    if (res.ok && json.api_key) return { api_key: json.api_key, tenant_id: json.tenant_id ?? null };
+
+    const err = String(json.error ?? '');
+    if (err === 'access_denied') throw new Error('login was denied in the browser.');
+    if (err === 'expired_token') throw new Error('the login code expired. Run `acuvo --login` again.');
+    if (err === 'already_claimed') throw new Error('that login code was already used. Run `acuvo --login` again.');
+    if (err === 'invalid_grant') throw new Error('that login code is not recognised. Run `acuvo --login` again.');
+
+    // `slow_down` is the server asking for room; honouring it is the difference
+    // between a polite client and one that gets rate-limited mid-login.
+    if (err === 'slow_down') wait = Math.min(wait * 2, 10000);
+    else if (!PENDING.has(err) && !res.ok && res.status >= 500) wait = Math.min(wait * 2, 10000);
+  }
+
+  throw new Error('the login code expired before it was approved. Run `acuvo --login` again.');
+}
+
+/**
+ * Best-effort browser open. NEVER throws and never blocks the flow.
+ *
+ * ⚠️ THE URL IS ALWAYS PRINTED TOO, and that is not redundancy — this runs over
+ * SSH, in containers, and in terminals with no desktop session, where opening a
+ * browser is impossible by definition. A flow that depends on the open
+ * succeeding is a flow that strands every remote user.
+ */
+export function openBrowser(url, { platform = process.platform, spawn } = {}) {
+  if (!spawn) return false;
+  const cmd = platform === 'win32' ? 'cmd' : platform === 'darwin' ? 'open' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/model.mjs

@@ -91,6 +91,26 @@ export const DEEPSEEK_DIRECT_MODELS = Object.freeze({
  * @returns {{ url: string, apiKey: string, model: string } | null}
  */
 export function directDeepSeek(model, env = process.env) {
+  /**
+   * ── ⭐⭐⭐ OFF UNLESS EXPLICITLY ASKED FOR (Roman, 2026-08-22) ──────────────
+   *
+   * *"no direct deepseek api, we can just use the rest of it for testing."*
+   *
+   * ⚠️ A KEY BEING PRESENT IS NOT A REQUEST TO USE IT. Before this line, merely
+   * exporting `DEEPSEEK_API_KEY` silently re-routed every build onto the direct
+   * endpoint — which is 3.7x dearer on OUTPUT ($0.66/M vs OpenRouter's $0.18/M)
+   * and doubles for 7 hours a day under DeepSeek's peak billing (01:00-04:00 and
+   * 06:00-10:00 UTC = 11am-2pm / 4pm-8pm AEST). Measured over 95M tokens that is
+   * 62.3% margin against 85.6%.
+   *
+   * ⭐ Direct's cache READ is genuinely cheaper ($0.007/M vs $0.0154/M) and that
+   * is why it once led. It cannot pay for the cache MISSES (2.9x dearer) or the
+   * output (3.7x dearer), and output is ~60% of the bill.
+   *
+   * Mirrors `deepSeekDirectEnabled()` in `console/lib/llm.ts` — the builder and
+   * the CLI must not disagree about which vendor serves a build.
+   */
+  if (String(env?.ACUVO_DEEPSEEK_DIRECT ?? '') !== '1') return null;
   const key = String(env?.DEEPSEEK_API_KEY ?? '').trim();
   if (!key) return null;
   const mapped = DEEPSEEK_DIRECT_MODELS[String(model ?? '')];
@@ -325,17 +345,42 @@ export function readModelConfig(env = process.env) {
  * is stuck: it needs no key, runs offline, and every line it prints names the
  * variable that fixes it.
  */
+/**
+ * ── ⭐⭐⭐ THE GATEWAY SHIPPED, SO THIS MESSAGE CHANGED WITH IT (2026-08-22) ──
+ *
+ * The note above promised exactly that: *"When the gateway ships, this message
+ * changes with it."* It shipped — `acuvo --login` lands an Acuvo key, and the
+ * metered path recorded its first real usage row today after never once having
+ * worked.
+ *
+ * ⚠️⚠️ AND UNTIL THIS EDIT THE FRONT DOOR SOLD THE COMPETITION. The first thing
+ * a brand-new user saw was "create your own OpenRouter key" — BYOK, which Roman
+ * has ruled out twice, printed as step 1 of onboarding on a package anyone can
+ * now `npm i -g`. `--help` did list `--login`; the message people actually hit
+ * did not. Every stranger who installed this brought their own key, so we
+ * metered nothing and earned nothing.
+ *
+ * ⭐ BOTH PATHS STAY, ORDER REVERSED. BYOK is not removed — it is honest, it
+ * works, and hiding it would make the tool look locked. It is simply no longer
+ * the default answer to "how do I start".
+ *
+ * ⚠️ IT STILL PROMISES NOTHING THAT DOES NOT EXIST. No pricing, no "sign up
+ * free", no plan names — self-serve signup has never been walked end to end
+ * (every tenant today is operated · unmetered). It names the two commands that
+ * are real and stops there.
+ */
 export const MISSING_KEY_MESSAGE = [
   'Acuvo Code — a terminal coding agent that tells you the price before it runs,',
   'stops at the number you set, and can re-check every claim it ever made.',
   '',
-  'It needs a model key to think. Today that is your own OpenRouter key:',
+  'It needs a key. Two ways — then run the same command again:',
+  '',
+  '  A) Your Acuvo account, billed to your Acuvo credits:',
+  '       acuvo --login        (paste the key from Settings → API keys)',
   '',
-  '  1. Create one (free, about a minute):  https://openrouter.ai/keys',
-  '  2. Set it:',
+  '  B) Your own key, billed to you — https://openrouter.ai/keys',
   '       export OPENROUTER_API_KEY=sk-or-v1-...        (bash / zsh)',
   '       $env:OPENROUTER_API_KEY = "sk-or-v1-..."      (PowerShell)',
-  '  3. Run the same command again.',
   '',
   'A typical task costs $0.001-$0.003. The ceiling is $0.02 a run unless you',
   'raise it, so a mistake costs two cents to find.',

package/lib/self-update.mjs

@@ -0,0 +1,174 @@
+/**
+ * ── ⭐⭐⭐ USERS GET UPDATES WITHOUT BEING ASKED TO ──────────────────────────
+ *
+ * Roman, 2026-08-22: *"how do we do self updates so all users get updates as
+ * soon as we do it, and we just advertise the new npm version instead of having
+ * users constantly download new versions, like Claude."*
+ *
+ * npm is IMMUTABLE — a published version can never be changed — so shipping a
+ * fix means publishing a new version, and without this module every user sits on
+ * whatever they first installed, forever. A bug we fixed in an hour would live
+ * on their machine for months.
+ *
+ * ── ⚠️⚠️ WHAT THIS MUST NEVER DO, WHICH IS MOST OF THE DESIGN ───────────────
+ *
+ * It must never block a run, never throw, never slow the first token, and never
+ * swap files underneath a session that is already executing. An update mechanism
+ * that can break the tool is worse than no update mechanism: the failure lands
+ * on someone who was in the middle of real work and did not ask for any of it.
+ *
+ * So: the check is THROTTLED to once a day against a cache, the install runs
+ * DETACHED after the decision, and the new version applies on the NEXT run —
+ * never the current one.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { accountDir } from './account.mjs';
+
+export const PACKAGE_NAME = 'acuvo-code';
+
+/** How long between registry checks. A day is plenty and keeps npm quiet. */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Compare two semver-ish strings.
+ *
+ * ⚠️ NUMERIC PER SEGMENT, NOT LEXICOGRAPHIC. `'0.10.0' > '0.9.0'` is TRUE
+ * numerically and FALSE as strings — so a string compare stops offering updates
+ * exactly when the minor version reaches 10, and does it silently.
+ *
+ * @returns 1 if a > b, -1 if a < b, 0 if equal
+ */
+export function compareVersions(a, b) {
+  const parse = (v) =>
+    String(v ?? '')
+      .trim()
+      .replace(/^v/, '')
+      // A prerelease suffix (`1.0.0-beta.1`) is dropped rather than ranked. We
+      // do not publish them, and inventing an ordering for something that does
+      // not exist is how you offer people a "newer" version that is older.
+      .split('-')[0]
+      .split('.')
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i += 1) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+export function updateCachePath(env = process.env) {
+  return join(accountDir(env), 'update-check.json');
+}
+
+function readCache(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value), 'utf8');
+  } catch {
+    // A read-only home is not a reason to fail a run. Worst case we check again
+    // next time, which costs one HTTP request.
+  }
+}
+
+/**
+ * Is there a newer published version?
+ *
+ * @returns {Promise<{latest: string, isNewer: boolean, checked: boolean}>}
+ */
+export async function checkForUpdate({
+  current,
+  fetchImpl = fetch,
+  now = () => Date.now(),
+  cachePath = updateCachePath(),
+  intervalMs = CHECK_INTERVAL_MS,
+  timeoutMs = 3000,
+  force = false,
+} = {}) {
+  const cached = readCache(cachePath);
+  if (!force && cached && now() - (cached.at ?? 0) < intervalMs) {
+    return { latest: cached.latest ?? current, isNewer: compareVersions(cached.latest, current) > 0, checked: false };
+  }
+
+  let latest = current;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    /**
+     * ⚠️ THE `latest` ENDPOINT, NOT THE FULL PACKUMENT. The full document for
+     * this package is megabytes of version history; this one is a few hundred
+     * bytes. On a slow connection that difference is the whole reason the check
+     * finishes inside its timeout instead of being abandoned every run.
+     */
+    const res = await fetchImpl(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    clearTimeout(timer);
+    const json = await res.json();
+    if (typeof json?.version === 'string') latest = json.version;
+  } catch {
+    // Offline, DNS down, npm having a moment. None of these are the user's
+    // problem and none should surface.
+    return { latest: current, isNewer: false, checked: false };
+  }
+
+  writeCache(cachePath, { at: now(), latest });
+  return { latest, isNewer: compareVersions(latest, current) > 0, checked: true };
+}
+
+/**
+ * Install the newer version, DETACHED, so it applies to the next run.
+ *
+ * ⚠️⚠️ NEVER IN-PROCESS AND NEVER AWAITED. Rewriting `lib/*.mjs` underneath a
+ * session that is mid-task is how an update becomes a crash in someone else's
+ * work — and the person it lands on never asked for the update at all.
+ *
+ * @returns {boolean} whether the install was successfully STARTED (not finished)
+ */
+export function applyUpdate({ spawn, version = 'latest' } = {}) {
+  if (!spawn) return false;
+  try {
+    const child = spawn(
+      process.platform === 'win32' ? 'npm.cmd' : 'npm',
+      ['install', '-g', `${PACKAGE_NAME}@${version}`],
+      { stdio: 'ignore', detached: true },
+    );
+    child.unref?.();
+    return true;
+  } catch {
+    // A global install can fail on permissions (a root-owned prefix is common).
+    // Silently — the notice below still tells them the command to run.
+    return false;
+  }
+}
+
+/** The one line a user sees. Deliberately small; nobody wants a changelog here. */
+export function updateNotice(current, latest, applied) {
+  return applied
+    ? `\nacuvo ${latest} is available (you have ${current}) — installing in the background, it will apply next run.\n`
+    : `\nacuvo ${latest} is available (you have ${current}) — update with:  npm i -g ${PACKAGE_NAME}@latest\n`;
+}
+
+/**
+ * Whether we should look at all.
+ *
+ * ⚠️ OFF FOR CI AND FOR ANYONE WHO SAYS SO. A build machine that silently
+ * upgrades its own toolchain mid-pipeline produces results nobody can reproduce,
+ * which is precisely the thing CI exists to prevent.
+ */
+export function updatesEnabled(env = process.env) {
+  if (String(env.ACUVO_NO_UPDATE ?? '') === '1') return false;
+  if (String(env.CI ?? '').toLowerCase() === 'true' || env.CI === '1') return false;
+  return true;
+}

package/lib/turn.mjs

@@ -49,7 +49,7 @@ import { budgetedAsker } from './ask-user.mjs';
 import { normalizeRelativePath } from './workspace.mjs';
 import { stringifyForModel } from './model-json.mjs';
 import { callModel, DEFAULT_MAX_TOKENS, DEFAULT_TIMEOUT_MS, pinOutcome, providerOrderFor } from './model.mjs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 /**
  * The pure prefix instrument. See the prefix-stability block in the round loop.
  * It was written, tested, and imported by nothing until 2026-08-20 —
@@ -71,8 +71,42 @@ import { detectDrift, driftNudge, reanchorDecision, reconcile, formatReconciliat
  * key OpenRouter groups by — and a resumed session passes its own id anyway,
  * which is exactly where the two need to agree and do.
  */
-function defaultStickyKey() {
-  return `acuvo-${randomUUID()}`;
+/**
+ * ── 💰⭐⭐⭐ DERIVED FROM THE WORKSPACE, NOT RANDOM (2026-08-22) ──────────────
+ *
+ * This returned `acuvo-${randomUUID()}` and the note below already recorded the
+ * damage without naming it as a bug: *"each cold process rolled the dice
+ * afresh"*, measured as a **65 / 98 / 31 / 98** cache alternation across runs.
+ *
+ * ⭐ THAT ALTERNATION *IS* THE MISSING CACHE. `session_id` is what OpenRouter
+ * groups by when choosing an upstream, and `deepseek-v4-flash-0731` has 28 of
+ * them. A fresh id every process means a fresh upstream every process — and a
+ * cold prompt cache each time, because a cache lives on ONE provider. Only
+ * resumed sessions escaped it, and the common case (`acuvo "do the thing"` in a
+ * project, over and over) never resumes.
+ *
+ * ⭐ THE WORKSPACE IS THE RIGHT ANCHOR. The same project returns to the same
+ * upstream every run, so its prefix stays warm across processes, across days,
+ * and across several terminals open on the same repo — which now SHARE a cache
+ * instead of each warming their own.
+ *
+ * ⚠️ IT IS A PREFERENCE, NOT A PIN. OpenRouter still falls back when that
+ * upstream is unhealthy, so this trades no availability for the cache.
+ *
+ * ⚠️ AND IT MUST NOT BE THE PATH ITSELF. The key goes over the wire to a third
+ * party; `C:/Projects/clients/<name>` would leak a customer list into request
+ * metadata. Hashed, so it is stable and says nothing.
+ */
+export function defaultStickyKey() {
+  let root;
+  try {
+    root = process.cwd();
+  } catch {
+    // A deleted cwd throws here. Falling back to a random id is correct — an
+    // unidentifiable workspace should not collide with a real one's cache.
+    return `acuvo-${randomUUID()}`;
+  }
+  return `acuvo-${createHash('sha256').update(root).digest('hex').slice(0, 32)}`;
 }
 /**
  * ⭐ THE DEFAULT IS THE CHAIN, NOT THE SINGLE CALL. `callModel` is still

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {