atris 3.74.9 → 3.74.11

package/lib/gm-phone.js

@@ -13,6 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const zlib = require('zlib');
 
 const CARD_LIMIT = 5;
 const CONFIRM_MS = 5000;
@@ -378,7 +379,7 @@ function appendLog(logPath, row) {
 //   loadView()                    -> view (see loadPhoneView)
 //   runStep(args)                 -> Promise<{ code, last_line }>, one atris command
 //   writeTarget(target)           -> boolean; snapshotTarget() -> restore fn
-//   logPath, now(), page(nonce)   receipts, clock, html
+//   logPath, now(), page(nonce, first)   receipts, clock, html (first: the card on screen now)
 //   makeBetDesk(log)              -> optional bet desk (lib/gm-bet createBetDesk)
 function createPhoneHandler(deps) {
   const now = deps.now || Date.now;
@@ -559,7 +560,7 @@ function createPhoneHandler(deps) {
       'x-frame-options': 'DENY',
       ...extra,
     });
-    res.end(typeof body === 'string' ? body : JSON.stringify(body));
+    res.end(typeof body === 'string' || Buffer.isBuffer(body) ? body : JSON.stringify(body));
   };
 
   async function handle(req, res) {
@@ -570,8 +571,18 @@ function createPhoneHandler(deps) {
     try {
       if (req.method === 'GET' && check.path === '/') {
         const nonce = crypto.randomBytes(16).toString('base64');
-        return send(res, 200, deps.page(nonce), 'text/html; charset=utf-8', {
-          'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`,
+        // the card on screen now goes in the page itself, so its first paint is that card;
+        // a desk that cannot read it right now (starting again) still serves the page, without one, and the page asks
+        let first = null;
+        try { first = bet ? bet.card() : null; } catch { first = null; }
+        const html = deps.page(nonce, first);
+        // packed when the phone takes it (every browser does): about a third of the bytes over a weak wifi
+        const packed = /\bgzip\b/i.test(String(req.headers['accept-encoding'] || ''));
+        return send(res, 200, packed ? zlib.gzipSync(html) : html, 'text/html; charset=utf-8', {
+          vary: 'accept-encoding',
+          ...(packed ? { 'content-encoding': 'gzip' } : {}),
+          // img-src data: only for the page's own inline icon; nothing else loads an image
+          'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; img-src data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`,
         });
       }
       if (req.method === 'GET' && check.path === '/state') return send(res, 200, state());

package/lib/journal.js

@@ -53,7 +53,7 @@ function parseJournalSections(content) {
     if (line.startsWith('## ')) {
       // Save previous section
       if (currentContent.length > 0 || currentSection === '__header__') {
-        sections[currentSection] = currentContent.join('\n');
+        sections[currentSection] = currentContent.concat('').join('\n');
       }
       // Start new section
       currentSection = line.substring(3).trim();

package/lib/noninteractive.js

@@ -69,7 +69,11 @@ function refuseHeadlessUnless(args, { allowYes = true, allowOnce = false, usage
   const lines = [];
   if (usage) lines.push(usage);
   else lines.push('This command needs a terminal, or an explicit proceed flag.');
-  lines.push('Pass --yes to run headless' + (allowOnce ? ', or --once for a single serve op.' : '.'));
+  if (allowYes) {
+    lines.push('Pass --yes to run headless' + (allowOnce ? ', or --once for a single serve op.' : '.'));
+  } else if (allowOnce) {
+    lines.push('Pass --once for a single serve op.');
+  }
   console.error(lines.join('\n'));
   return true;
 }

package/lib/roster-swap.js

@@ -259,6 +259,10 @@ function swapMember(root, memberName, engineWords, modelWords, options = {}) {
 
 // The phone's engine card for one member: what it runs on now, and every
 // model this machine offers that can do the member's work, grouped by tool.
+// A model's last 7 days in the owner's words: the phone's swap card shows it
+// under the model, so it says finished, never the team's own word for it.
+const recordWords = seen => `${seen.landed} of ${seen.runs} finished this week`;
+
 // The current model is on top; models with a record in the last 7 days come
 // next, most landed first; the rest keep --available's order.
 function memberEngineChoices(root, memberName, options = {}) {
@@ -284,7 +288,7 @@ function memberEngineChoices(root, memberName, options = {}) {
         model: id ? name : '',
         label: !name ? 'its own model' : id ? modelText(id) || name : name,
         current: row.engine === curEngine && sameModel(row.engine, id, curModel),
-        record: seen ? `${seen.landed} of ${seen.runs} landed` : null,
+        record: seen ? recordWords(seen) : null,
         landed: seen ? seen.landed : -1,
         runs: seen ? seen.runs : 0,
         index,
@@ -313,7 +317,7 @@ function memberEngineChoices(root, memberName, options = {}) {
   const mark = (option) => {
     const pin = option.model ? pinFor(option.engine, option.model) : '';
     const seen = record(option.engine, pin);
-    return { ...option, current: option.engine === curEngine && sameModel(option.engine, pin, curModel), record: seen ? `${seen.landed} of ${seen.runs} landed` : null };
+    return { ...option, current: option.engine === curEngine && sameModel(option.engine, pin, curModel), record: seen ? recordWords(seen) : null };
   };
   const list = swapList(root, { ...options, offer: { registry, tools, shortlist, shortlistFile } });
   const choices = list.options
@@ -340,7 +344,8 @@ function swapFromCard(root, memberName, engineWords, modelWords, scope, options
   const { resolveEngineForMember } = require('./member-engine');
   const after = resolveEngineForMember(member, root, options);
   const moved = after.engine && after.engine.id === out.engine && sameModel(out.engine, after.model || '', out.model);
-  if (!moved && after.pick_source === 'team') return { ...out, line: `${out.line} ${member} keeps its own line.` };
+  // the owner reads this: the member has its own pick, so it stays on its own model
+  if (!moved && after.pick_source === 'team') return { ...out, line: `${out.line} ${member} keeps its own model.` };
   return out;
 }
 

package/lib/task-decision.js

@@ -23,7 +23,7 @@ function taskTagTokens(task) {
   const fromTags = Array.isArray(task.tags) ? task.tags : [];
   const fromTag = task.tag ? [task.tag] : [];
   const fromMeta = task.metadata && Array.isArray(task.metadata.tags) ? task.metadata.tags : [];
-  const fromTitle = (String(task.title || '').match(/#([a-z0-9-]+)/gi) || []).map((t) => t.slice(1));
+  const fromTitle = (String(task.title || '').match(/#([a-z0-9_-]+)/gi) || []).map((t) => t.slice(1));
   return [...fromTag, ...fromTags, ...fromMeta, ...fromTitle]
     .map(normalizeDecisionTag)
     .filter(Boolean);

package/lib/values.js

@@ -5,20 +5,35 @@ const path = require('node:path');
 
 const PACKAGE_ROOT = path.join(__dirname, '..');
 
-// The bold-lead bullets under `## values` in atris.md, each as its name and
-// its first sentence, so the boot can show them in every new chat instead of
-// leaving them deep in a long file. A workspace made before the values
-// shipped has no such section; the package copy stands in for it.
+// The values in atris.md, each as its name and its first sentence, so the
+// boot can show them in every new chat instead of leaving them deep in a long
+// file. A workspace that writes its own under a `## values` heading gets
+// those, whatever they are called. Otherwise the four that open the operating
+// rules (acceleration, accuracy, ambition, agency) are found by name. A
+// workspace with neither gets the package copy.
+const VALUE_NAMES = ['acceleration', 'accuracy', 'ambition', 'agency'];
+const BULLET = /^- \*\*([^*]+?)\.\*\*\s+([^.]+)\./;
+const asValue = (match) => ({ name: match[1].toLowerCase(), gist: match[2][0].toLowerCase() + match[2].slice(1) });
+
 function extractValues(content) {
   const lines = String(content || '').split(/\r?\n/);
   const start = lines.findIndex((line) => /^## values\s*$/i.test(line));
-  if (start === -1) return [];
-  const values = [];
-  for (let index = start + 1; index < lines.length && !/^##\s+/.test(lines[index]); index += 1) {
-    const match = lines[index].match(/^- \*\*([^*]+?)\.\*\*\s+([^.]+)\./);
-    if (match) values.push({ name: match[1].toLowerCase(), gist: match[2][0].toLowerCase() + match[2].slice(1) });
+  if (start !== -1) {
+    const values = [];
+    for (let index = start + 1; index < lines.length && !/^##\s+/.test(lines[index]); index += 1) {
+      const match = lines[index].match(BULLET);
+      if (match) values.push(asValue(match));
+    }
+    if (values.length) return values;
+  }
+  const found = new Map();
+  for (const line of lines) {
+    const match = line.match(BULLET);
+    if (!match) continue;
+    const value = asValue(match);
+    if (VALUE_NAMES.includes(value.name) && !found.has(value.name)) found.set(value.name, value);
   }
-  return values;
+  return found.size === VALUE_NAMES.length ? VALUE_NAMES.map((name) => found.get(name)) : [];
 }
 
 function readValues(root) {

package/lib/zen-apply.js

@@ -30,6 +30,7 @@ const {
   nextSaveIn,
   sideCopyLines,
   scheduledCopies,
+  runningCopies,
   untrackedFiles,
   ABANDONED_DAYS,
   abandonedDaysFromEnv,
@@ -126,15 +127,21 @@ function putAwaySideCopies(root, cutoff, staleCutoff, tag, teamState) {
   let prune = false;
   let scheduledCount = 0;
   let locked = 0;
+  let running = 0;
   const kept = [];
   const worktrees = listWorktrees(root);
   const scheduled = scheduledCopies(worktrees);
+  const live = runningCopies(worktrees.filter((wt) => path.resolve(wt.path) !== path.resolve(root)));
   for (const wt of worktrees) {
     if (path.resolve(wt.path) === path.resolve(root)) continue;
     if (scheduled.has(path.resolve(wt.path))) {
       scheduledCount += 1;
       continue;
     }
+    if (live.has(path.resolve(wt.path))) {
+      running += 1;
+      continue;
+    }
     if (wt.locked) {
       locked += 1;
       continue;
@@ -181,7 +188,7 @@ function putAwaySideCopies(root, cutoff, staleCutoff, tag, teamState) {
     else busy.push(wt.path);
   }
   if (prune) runGit(['worktree', 'prune'], root);
-  return { removed, busy, inUse, kept, notesKept, scheduled: scheduledCount, locked };
+  return { removed, busy, inUse, kept, notesKept, scheduled: scheduledCount, locked, running };
 }
 
 function clearMergedBranches(root, upstream, main, cutoff) {
@@ -295,6 +302,19 @@ function applyNotes(root, patchFile, files) {
   return { clashed, missed };
 }
 
+// The map files whose code links `atris clean` re-points on every zen run.
+const MAP_FILES = new Set(['atris/MAP.md', 'atris/refs/MAP-NOTES.md']);
+
+// A map edit that only moved `file:line` numbers is the link fixer's own work
+// from an earlier run, and the workspace step redoes it, so it is not news.
+function lineRefsOnly(root, from, p, mine) {
+  if (!MAP_FILES.has(p) || !fs.existsSync(mine)) return false;
+  const was = runGit(['show', `${from}:${p}`], root);
+  if (was.status !== 0) return false;
+  const bare = (text) => String(text).replace(/([\w./-]+\.[A-Za-z]+):\d+(?:-\d+)?/g, '$1:#');
+  return bare(was.stdout) === bare(fs.readFileSync(mine, 'utf8'));
+}
+
 function sameBytes(a, b) {
   try {
     return fs.readFileSync(a).equals(fs.readFileSync(b));
@@ -424,7 +444,7 @@ function moveKeepingNotes(root, args, target, tag, from = 'HEAD') {
     for (const p of clashed) {
       const mine = path.join(dir, 'mine', p);
       if (isJournal(p) && joinJournal(path.join(root, p), mine)) notes.push(`joined your ${p} onto the new one`);
-      else notes.push(`kept the new ${p}; your copy is in ${mine}`);
+      else if (!(fromCommit && lineRefsOnly(root, fromCommit, p, mine))) notes.push(`kept the new ${p}; your copy is in ${mine}`);
     }
     for (const p of missed) {
       const mine = path.join(dir, 'mine', p);
@@ -546,6 +566,7 @@ function applyZen({ cwd = process.cwd(), fetch = true, freshMinutes, abandonedDa
   }
   if (copies.busy.length) left.push(...sideCopyLines(copies.busy, staleDays, nextSaveIn(copies.busy, staleDays, now.getTime())));
   if (copies.scheduled) left.push(`${plural(copies.scheduled, 'side copy is', 'side copies are')} used by a scheduled job, so ${copies.scheduled === 1 ? 'it stays' : 'they stay'}`);
+  if (copies.running) left.push(`${plural(copies.running, 'side copy has', 'side copies have')} a program running in ${copies.running === 1 ? 'it, so it stays' : 'them, so they stay'}`);
   if (copies.locked) left.push(`${plural(copies.locked, 'side copy is', 'side copies are')} locked by ${copies.locked === 1 ? 'its owner, so it stays' : 'their owners, so they stay'}`);
   if (copies.inUse) left.push(`${plural(copies.inUse, 'side copy was', 'side copies were')} used in ${window}, so ${copies.inUse === 1 ? 'it stays' : 'they stay'}`);
 

package/lib/zen.js

@@ -205,6 +205,39 @@ function scheduledCopies(worktrees, text = scheduleText()) {
   return used;
 }
 
+// Folders that programs on this machine are running in right now, read from
+// lsof once per call. A side copy holding one is in use even when its git
+// history looks old: a dev server or a long eval run makes no commits.
+// ATRIS_ZEN_CWDS_FILE points at a file of folders, one per line (tests).
+function programFolders() {
+  const override = process.env.ATRIS_ZEN_CWDS_FILE;
+  if (override) {
+    try {
+      return fs.readFileSync(override, 'utf8').split('\n').filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+  const out = spawnSync('lsof', ['-nP', '-d', 'cwd', '-Fn'], { encoding: 'utf8', timeout: 5000, maxBuffer: 16 * 1024 * 1024 });
+  return (out.stdout || '').split('\n').filter((line) => line.startsWith('n/')).map((line) => line.slice(1));
+}
+
+function runningCopies(worktrees, folders = programFolders()) {
+  const used = new Set();
+  for (const wt of worktrees) {
+    const at = path.resolve(wt.path);
+    let real = at;
+    try {
+      real = fs.realpathSync(at);
+    } catch {
+      // Gone already; compare the path as given.
+    }
+    const inside = (f) => [at, real].some((p) => f === p || f.startsWith(p + path.sep));
+    if (folders.some(inside)) used.add(at);
+  }
+  return used;
+}
+
 const FRESH_MINUTES = 30;
 
 function freshMinutesFromEnv() {
@@ -225,9 +258,31 @@ function changedFiles(checkout) {
   });
 }
 
+// TODO.md is rewritten from the task database by any task command run in a
+// copy (see renderTodoMarkdown in lib/task-db.js). That rewrite is not anyone
+// working there, so it must not keep an idle copy looking fresh forever.
+const REGENERATED_MARK = 'Regenerated from durable Atris task state';
+
+function isRegenerated(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(512);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    return buf.toString('utf8', 0, n).includes(REGENERATED_MARK);
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
 function lastTouched(checkout) {
   let newest = 0;
-  for (const p of changedFiles(checkout)) newest = Math.max(newest, mtime(path.join(checkout, p)));
+  for (const p of changedFiles(checkout)) {
+    const file = path.join(checkout, p);
+    if (!isRegenerated(file)) newest = Math.max(newest, mtime(file));
+  }
   return newest;
 }
 
@@ -413,8 +468,13 @@ function checkZen({ cwd = process.cwd(), fetch = true, freshMinutes = freshMinut
   const locked = [];
   const cutoff = now - freshMinutes * 60000;
   const scheduled = scheduledCopies(others);
+  const running = runningCopies(others);
   for (const wt of others) {
     if (scheduled.has(path.resolve(wt.path))) continue;
+    if (running.has(path.resolve(wt.path))) {
+      inUse.push(wt);
+      continue;
+    }
     if (wt.locked) {
       locked.push(wt);
       continue;
@@ -501,6 +561,24 @@ function shortPlace(p) {
   return p === home || p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p;
 }
 
+// A place too long for a narrow pane keeps as much of its start as fits,
+// then its own folder name, so the line still says where and which. A cut
+// that saves only a few characters hides more than it helps, so it is skipped.
+const PLACE_WIDTH = 100;
+function fitPlace(text, max = PLACE_WIDTH) {
+  if (text.length <= max) return text;
+  const parts = text.split('/');
+  const name = parts.pop();
+  if (parts.length < 2) return text;
+  let head = parts[0];
+  for (const part of parts.slice(1)) {
+    if (`${head}/${part}/…/${name}`.length > max) break;
+    head = `${head}/${part}`;
+  }
+  const cut = `${head}/…/${name}`;
+  return text.length - cut.length >= 10 ? cut : text;
+}
+
 // Side copies left with unsaved work: at most three named, one place per
 // line so a long path still fits a narrow pane, then when zen will take
 // them over and, when known, how long until the first one goes.
@@ -514,11 +592,27 @@ function sideCopyLines(paths, days, waitMs = null) {
     if (!folders.has(dir)) folders.set(dir, []);
     folders.get(dir).push(p);
   }
-  const rows = [];
+  const listed = [];
   for (const [dir, group] of folders) {
-    if (group.length >= 3) rows.push({ text: `${group.length} in ${shortPlace(dir)}/`, count: group.length });
-    else for (const p of group) rows.push({ text: shortPlace(p), count: 1 });
+    if (group.length >= 3) listed.push({ text: `${group.length} in ${shortPlace(dir)}/`, count: group.length });
+    else for (const p of group) listed.push({ text: fitPlace(shortPlace(p)), count: 1, path: p });
+  }
+  // A copy made inside another listed copy goes right under it, named from
+  // there, so a doubly nested path does not run the width of the pane.
+  const parentOf = new Map();
+  for (const row of listed) {
+    const holders = listed.filter((q) => q.path && row.path && row.path.startsWith(q.path + path.sep));
+    if (!holders.length) continue;
+    const holder = holders.reduce((a, b) => (b.path.length > a.path.length ? b : a));
+    parentOf.set(row, holder);
+    row.text = `  inside it: ${path.relative(holder.path, row.path)}`;
   }
+  const rows = [];
+  const place = (row) => {
+    rows.push(row);
+    for (const child of listed) if (parentOf.get(child) === row) place(child);
+  };
+  for (const row of listed) if (!parentOf.has(row)) place(row);
   for (const row of rows.slice(0, 3)) lines.push(`  ${row.text}`);
   const rest = rows.slice(3).reduce((sum, row) => sum + row.count, 0);
   if (rest) lines.push(`  and ${rest} more`);
@@ -551,4 +645,5 @@ module.exports = {
   listWorktrees,
   readTeamState,
   scheduledCopies,
+  runningCopies,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.74.9",
+  "version": "3.74.11",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "mcpName": "io.github.atrislabs/atris",
   "main": "bin/atris.js",

package/utils/auth.js

@@ -318,6 +318,7 @@ function setSessionProfile(profileName) {
     // No terminal session ID — fall back to global switch
     return false;
   }
+  assertSafeLoginWrite(sessionPath);
   fs.writeFileSync(sessionPath, JSON.stringify({
     profile: profileName,
     set_at: new Date().toISOString(),
@@ -370,8 +371,31 @@ function profileNameFromEmail(email) {
   return name || null; // Guard against emails like "@domain.com"
 }
 
+function runningUnderTest() {
+  if (process.env.NODE_TEST_CONTEXT) return true;
+  if ((process.execArgv || []).includes('--test')) return true;
+  return /\.test\.[cm]?js$/.test(path.basename(process.argv[1] || ''));
+}
+
+function realDir(dir) {
+  try { return fs.realpathSync(dir); } catch { return path.resolve(dir); }
+}
+
+// A test that forgets to point HOME at a scratch dir would overwrite the
+// real login (2026-10-23: a mutant test minted a fake token into
+// ~/.atris/credentials.json and logged the owner out). Under a test runner,
+// login files may only be written inside the OS temp dir.
+function assertSafeLoginWrite(targetPath) {
+  if (!runningUnderTest()) return;
+  const target = realDir(path.dirname(targetPath));
+  const tmp = realDir(os.tmpdir());
+  if (target === tmp || target.startsWith(tmp + path.sep)) return;
+  throw new Error(`Refusing to write ${targetPath} during a test: set HOME to a temp dir first`);
+}
+
 function saveProfile(name, credentials) {
   const profilePath = path.join(getProfilesDir(), `${name}.json`);
+  assertSafeLoginWrite(profilePath);
   fs.writeFileSync(profilePath, JSON.stringify(credentials, null, 2));
   restrictToOwner(profilePath);
 }
@@ -452,6 +476,7 @@ function saveCredentials(token, refreshToken, email, userId, provider, extras =
   }
   preserveAgentClientLogin();
   const credentialsPath = getCredentialsPath();
+  assertSafeLoginWrite(credentialsPath);
   const credentials = {
     ...extras,
     token,
@@ -695,7 +720,7 @@ function abortOnAuthFailure(result, printedWake = false, exitFn = (code) => proc
   return true;
 }
 
-async function performTokenRefresh(credentials, apiRequestJson) {
+async function performTokenRefresh(credentials, apiRequestJson, { validate = true } = {}) {
   if (!credentials || !credentials.refresh_token) {
     return { ok: false, error: 'missing_refresh_token' };
   }
@@ -715,13 +740,18 @@ async function performTokenRefresh(credentials, apiRequestJson) {
   const provider = refreshed.data?.provider || credentials.provider;
   const email = refreshUser?.email || credentials.email;
   const userId = refreshUser?.id || credentials.user_id;
+  const refreshedCredentials = { ...credentials };
+  const refreshedExpiry = getTokenExpiryEpochSeconds(accessToken);
+  if (credentials.expires_at != null && refreshedExpiry !== null) {
+    refreshedCredentials.expires_at = new Date(refreshedExpiry * 1000).toISOString();
+  }
 
   // Refreshed tokens must land in the file they were loaded from. Writing a
   // profile's refresh to the global credentials.json leaves the profile token
   // to expire permanently (every ATRIS_PROFILE session then 401s forever).
   const persistRefreshed = () => {
     if (credentials.source_profile) {
-      const { source_profile, source, ...rest } = { ...credentials };
+      const { source_profile, source, ...rest } = refreshedCredentials;
       saveProfile(credentials.source_profile, {
         ...rest,
         token: accessToken,
@@ -732,17 +762,17 @@ async function performTokenRefresh(credentials, apiRequestJson) {
         saved_at: new Date().toISOString(),
       });
     } else {
-      saveCredentials(accessToken, newRefreshToken, email, userId, provider, credentials);
+      saveCredentials(accessToken, newRefreshToken, email, userId, provider, refreshedCredentials);
     }
   };
 
   persistRefreshed();
   let latestCreds = loadCredentials();
 
-  const validation = await validateAccessToken(accessToken, apiRequestJson);
+  const validation = validate ? await validateAccessToken(accessToken, apiRequestJson) : null;
   let finalUser = refreshUser;
 
-  if (validation.ok && validation.data?.valid) {
+  if (validation?.ok && validation.data?.valid) {
     finalUser = validation.data.user || refreshUser || null;
     const updatedEmail = finalUser?.email || latestCreds?.email || email;
     const updatedProvider = finalUser?.provider || latestCreds?.provider || provider;
@@ -755,7 +785,7 @@ async function performTokenRefresh(credentials, apiRequestJson) {
       updatedUserId !== latestCreds.user_id
     ) {
       if (credentials.source_profile) {
-        const { source_profile, source, ...rest } = { ...credentials };
+        const { source_profile, source, ...rest } = refreshedCredentials;
         saveProfile(credentials.source_profile, {
           ...rest,
           token: accessToken,
@@ -766,7 +796,7 @@ async function performTokenRefresh(credentials, apiRequestJson) {
           saved_at: new Date().toISOString(),
         });
       } else {
-        saveCredentials(accessToken, newRefreshToken, updatedEmail, updatedUserId, updatedProvider, credentials);
+        saveCredentials(accessToken, newRefreshToken, updatedEmail, updatedUserId, updatedProvider, refreshedCredentials);
       }
       latestCreds = loadCredentials();
     }
@@ -782,6 +812,31 @@ async function performTokenRefresh(credentials, apiRequestJson) {
   };
 }
 
+// Sync only needs local expiry checks, not a validation request per file.
+async function ensureFreshCredentials(apiRequestJson) {
+  const credentials = loadCredentials();
+  if (!credentials || credentials.source || agentClient.isAgentClientCredential(credentials)) return credentials;
+  const claims = decodeJwtClaims(credentials.token);
+  if (claims?.type === 'agent_access' || !credentials.refresh_token) return credentials;
+
+  const selectedExpiry = expiryTimeMs(credentials.expires_at);
+  const isExpired = () => (selectedExpiry !== null && selectedExpiry <= Date.now())
+    || (typeof claims?.exp === 'number' && claims.exp * 1000 <= Date.now());
+  if (!isExpired() && !shouldRefreshToken(credentials.token)) return credentials;
+
+  try {
+    const refreshed = await performTokenRefresh(credentials, apiRequestJson, { validate: false });
+    if (refreshed.ok) return refreshed.payload.credentials;
+  } catch {
+    // A still-valid token can keep syncing if proactive renewal is unavailable.
+  }
+  if (isExpired()) {
+    console.error('Session expired. Run: atris login');
+    process.exit(1);
+  }
+  return credentials;
+}
+
 async function ensureValidCredentials(apiRequestJson, options = {}) {
   let credentials = await loadCredentials(apiRequestJson);
   if (agentClient.isAgentClientCredential(credentials)) {
@@ -798,6 +853,11 @@ async function ensureValidCredentials(apiRequestJson, options = {}) {
 
   const selectedExpiry = expiryTimeMs(credentials.expires_at);
   if (selectedExpiry !== null && selectedExpiry <= Date.now()) {
+    if (credentials.refresh_token) {
+      const refreshed = await performTokenRefresh(credentials, apiRequestJson);
+      if (refreshed.ok) return refreshed.payload;
+      return { error: 'refresh_failed', detail: refreshed.error };
+    }
     return { error: 'token_invalid', detail: AGENT_TOKEN_EXPIRED_DETAIL };
   }
 
@@ -937,6 +997,7 @@ async function displayAccountSummary(apiRequestJson) {
 }
 
 module.exports = {
+  assertSafeLoginWrite,
   AGENT_TOKEN_EXPIRED_DETAIL,
   decodeJwtClaims,
   getTokenExpiryEpochSeconds,
@@ -954,6 +1015,7 @@ module.exports = {
   validateAccessToken,
   refreshAccessToken,
   performTokenRefresh,
+  ensureFreshCredentials,
   ensureValidCredentials,
   isAuthFailure,
   abortOnAuthFailure,