mixdog 1.0.11 → 1.1.0

package/src/runtime/shared/provider-accounts.mjs

@@ -134,7 +134,7 @@ export function changeProviderAccounts(provider, change) {
     !change ||
     typeof change !== 'object' ||
     Array.isArray(change) ||
-    Object.keys(change).some((key) => !['selectedId', 'order', 'auto', 'rename'].includes(key))
+    Object.keys(change).some((key) => !['selectedId', 'order', 'auto', 'useCredits', 'rename'].includes(key))
   ) {
     throw new TypeError('Invalid provider account change.');
   }
@@ -175,6 +175,10 @@ export function changeProviderAccounts(provider, change) {
       if (typeof change.auto !== 'boolean') throw new TypeError('Automatic account switching must be boolean.');
       pool.auto = change.auto;
     }
+    if (change.useCredits !== undefined) {
+      if (typeof change.useCredits !== 'boolean') throw new TypeError('Credit use must be boolean.');
+      pool.useCredits = change.useCredits;
+    }
   });
 }
 
@@ -217,7 +221,9 @@ const MAX_BLOCK_MS = 6 * 60 * 60_000;
 // account-wide, as before. `source` records whether the server scheduled the
 // window or we inferred it, which decides whether re-measuring the account
 // early can tell us anything.
-export function blockProviderAccount(provider, id, until, model = '', source = 'inferred') {
+// `options.quota` records that the block came from a typed quota refusal or an
+// exhausted usage window, so later sends still count it as quota evidence.
+export function blockProviderAccount(provider, id, until, model = '', source = 'inferred', options = {}) {
   return update(provider, (pool) => {
     const row = pool.accounts.find((entry) => entry.id === id);
     if (!row) return;
@@ -227,6 +233,8 @@ export function blockProviderAccount(provider, id, until, model = '', source = '
     else delete row.blockedModel;
     if (source === 'retry-after') row.blockedSource = source;
     else delete row.blockedSource;
+    if (options.quota === true) row.blockedQuota = true;
+    else delete row.blockedQuota;
   });
 }
 
@@ -248,6 +256,7 @@ function clearAccountBlock(row) {
   delete row.blockedUntil;
   delete row.blockedModel;
   delete row.blockedSource;
+  delete row.blockedQuota;
 }
 
 // Single-token weekly labels ("7D Fable", "7D Opus") belong to that Claude
@@ -256,7 +265,7 @@ function clearAccountBlock(row) {
 // model.
 const FAMILY_QUOTA_WINDOW = /^7D\s+([A-Za-z][A-Za-z0-9]*)$/i;
 
-function quotaWindowAppliesToModel(window, model) {
+export function quotaWindowAppliesToModel(window, model) {
   const match = FAMILY_QUOTA_WINDOW.exec(String(window?.label || '').trim());
   if (!match) return true;
   const family = match[1].toLowerCase();
@@ -280,8 +289,36 @@ function blockAppliesToModel(row, model) {
   return scoped.some((window) => quotaWindowAppliesToModel(window, scope) && quotaWindowAppliesToModel(window, model));
 }
 
-export function providerAccountExhausted(row, now = Date.now(), model = '') {
+// Earliest moment any of the given exhausted accounts can serve `model` again,
+// or null when unknown. Per account the LATEST blocking reset counts (every
+// blocking window must clear); across accounts the EARLIEST account does. A
+// server-scheduled block (`retry-after`) is a known time; an inferred block or
+// a full window without a reset time leaves that account's reset unknown.
+export function providerAccountsResetAt(rows, now = Date.now(), model = '', options = {}) {
+  const known = [];
+  for (const row of rows || []) {
+    if (!providerAccountExhausted(row, now, model, options)) continue;
+    const times = [];
+    let unknown = false;
+    if (row.blockedUntil > now && blockAppliesToModel(row, model)) {
+      if (row.blockedSource === 'retry-after') times.push(row.blockedUntil);
+      else unknown = true;
+    }
+    if (options.useCredits !== true) {
+      for (const window of row.usage?.windows || []) {
+        if (!(window.usedPct >= 100) || !quotaWindowAppliesToModel(window, model)) continue;
+        if (window.resetAt > now) times.push(window.resetAt);
+        else if (!window.resetAt && now - row.usage.checkedAt < 60_000) unknown = true;
+      }
+    }
+    if (!unknown && times.length) known.push(Math.max(...times));
+  }
+  return known.length ? Math.min(...known) : null;
+}
+
+export function providerAccountExhausted(row, now = Date.now(), model = '', options = {}) {
   if (row?.blockedUntil > now && blockAppliesToModel(row, model)) return true;
+  if (options.useCredits === true) return false;
   return (row?.usage?.windows || []).some(
     (window) =>
       window.usedPct >= 100 &&
@@ -309,9 +346,13 @@ function accountHeadroom(row, now, model) {
 }
 
 export function chooseProviderAccount(pool, excluded = new Set(), now = Date.now(), model = '') {
-  const usable = (row) => row && !excluded.has(row.id) && !providerAccountExhausted(row, now, model);
+  const options = { useCredits: pool.useCredits === true };
+  const usable = (row) => row && !excluded.has(row.id) && !providerAccountExhausted(row, now, model, options);
   const selected = pool.accounts.find((row) => row.id === pool.selectedId);
-  if (pool.auto === false) return excluded.has(selected?.id) ? null : selected || null;
+  if (pool.auto === false) {
+    if (excluded.has(selected?.id)) return null;
+    return options.useCredits || usable(selected) ? selected || null : null;
+  }
   if (usable(selected)) return selected;
   // Falling back in roster order is blind: the account after the one that just
   // refused may itself be nearly spent, so the request pays a second switch to

package/src/runtime/shared/quota-resume-store.mjs

@@ -0,0 +1,255 @@
+/**
+ * quota-resume-store.mjs — the daemon's durable queue of Lead turns waiting
+ * for their provider quota to reset, plus the global auto-resume setting.
+ *
+ * One process (the daemon) owns the file; every session runtime it hosts and
+ * its resume scheduler read and mutate this same in-memory copy, and every
+ * mutation is written through synchronously so a restart finds the queue
+ * exactly as the last mutation left it. Mutations are synchronous on purpose:
+ * a cancel and a fire can never interleave inside one, and each entry carries
+ * a generation so a stale holder can neither fire nor defer a replaced entry.
+ *
+ * Entry: { sessionId, turnKey, provider, model, resetAt, attempts, generation,
+ *          routeProvider, routeModel }
+ *   resetAt  — when the scheduler next takes a usage reading (the provider's
+ *              reset time, or the later re-check after a still-exhausted one).
+ * Suspension: { sessionId, turnKey, goalId } — the Goal one quota failure
+ *   moved from active to usage_limited, the only Goal a resume may revive.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolvePluginData } from './plugin-paths.mjs';
+import { writeJsonAtomicSync } from './atomic-file.mjs';
+import { readSection, updateSection } from './config.mjs';
+
+export const QUOTA_RESUME_FILE = 'quota-resume.json';
+const FILE_VERSION = 1;
+const SETTING_SECTION = 'quotaResume';
+
+let state = null;
+const listeners = new Set();
+// Frozen public snapshots keyed by the immutable entry object they describe,
+// so an unchanged entry publishes the same value identity on every read.
+const publicSnapshots = new WeakMap();
+
+const text = (value) => (typeof value === 'string' ? value.trim() : '');
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+
+function normalizeEntry(value) {
+  const entry = {
+    sessionId: text(value?.sessionId),
+    turnKey: text(value?.turnKey),
+    provider: text(value?.provider),
+    model: typeof value?.model === 'string' ? value.model : '',
+    resetAt: value?.resetAt,
+    attempts: Number.isSafeInteger(value?.attempts) && value.attempts >= 0 ? value.attempts : 0,
+    generation: value?.generation,
+    // The session's own route when the resume was queued; a fire on any
+    // other route is not the resume of this failure.
+    routeProvider: typeof value?.routeProvider === 'string' ? value.routeProvider : '',
+    routeModel: typeof value?.routeModel === 'string' ? value.routeModel : '',
+  };
+  if (!entry.sessionId || !entry.turnKey || !entry.provider || !finite(entry.resetAt)) return null;
+  if (!Number.isSafeInteger(entry.generation) || entry.generation < 1) return null;
+  return Object.freeze(entry);
+}
+
+function normalizeSuspension(value) {
+  const suspension = {
+    sessionId: text(value?.sessionId),
+    turnKey: text(value?.turnKey),
+    goalId: text(value?.goalId),
+  };
+  return suspension.sessionId && suspension.turnKey && suspension.goalId ? Object.freeze(suspension) : null;
+}
+
+function storePath() {
+  return join(resolvePluginData(), QUOTA_RESUME_FILE);
+}
+
+function load() {
+  const path = storePath();
+  if (state?.path === path) return state;
+  let raw = null;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    // A missing or torn file is an empty queue; an unreadable one is not.
+    if (error?.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+  }
+  const entries = new Map();
+  for (const value of Array.isArray(raw?.entries) ? raw.entries : []) {
+    const entry = normalizeEntry(value);
+    if (entry) entries.set(entry.sessionId, entry);
+  }
+  const suspensions = new Map();
+  for (const value of Array.isArray(raw?.suspensions) ? raw.suspensions : []) {
+    const suspension = normalizeSuspension(value);
+    if (suspension) suspensions.set(suspension.sessionId, suspension);
+  }
+  const generations = [Number.isSafeInteger(raw?.generation) ? raw.generation : 0];
+  for (const entry of entries.values()) generations.push(entry.generation);
+  state = { path, generation: Math.max(...generations), entries, suspensions };
+  return state;
+}
+
+function persist(current) {
+  writeJsonAtomicSync(
+    current.path,
+    {
+      version: FILE_VERSION,
+      generation: current.generation,
+      entries: [...current.entries.values()],
+      suspensions: [...current.suspensions.values()],
+    },
+    { fsyncDir: true }
+  );
+}
+
+function notify(sessionId) {
+  for (const listener of [...listeners]) {
+    try {
+      listener(sessionId);
+    } catch {
+      // The mutation is already persisted; one failing listener must neither
+      // undo it nor keep the others from hearing about it.
+    }
+  }
+}
+
+/** Listener receives the changed sessionId, or null when every entry changed. */
+export function subscribeQuotaResume(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function quotaResumeEntry(sessionId) {
+  return load().entries.get(text(sessionId)) || null;
+}
+
+export function listQuotaResumeEntries() {
+  return [...load().entries.values()];
+}
+
+/** The session snapshot's `quotaResume` value for an entry (or null). */
+export function publicQuotaResume(entry) {
+  if (!entry) return null;
+  let snapshot = publicSnapshots.get(entry);
+  if (!snapshot) {
+    snapshot = Object.freeze({
+      state: 'waiting',
+      turnKey: entry.turnKey,
+      provider: entry.provider,
+      model: entry.model,
+      resetAt: entry.resetAt,
+      attempts: entry.attempts,
+    });
+    publicSnapshots.set(entry, snapshot);
+  }
+  return snapshot;
+}
+
+/** Queue (or replace) the session's resume under a fresh generation. */
+export function scheduleQuotaResumeEntry({
+  sessionId,
+  turnKey,
+  provider,
+  model = '',
+  resetAt,
+  routeProvider = '',
+  routeModel = '',
+} = {}) {
+  const current = load();
+  const entry = normalizeEntry({
+    sessionId,
+    turnKey,
+    provider,
+    model,
+    resetAt,
+    routeProvider,
+    routeModel,
+    attempts: 0,
+    generation: current.generation + 1,
+  });
+  if (!entry) throw new TypeError('quota resume needs a session, turn, provider and reset time');
+  current.generation = entry.generation;
+  current.entries.set(entry.sessionId, entry);
+  persist(current);
+  notify(entry.sessionId);
+  return entry;
+}
+
+/** Remove the session's entry; with `generation`, only that exact entry. */
+export function cancelQuotaResumeEntry(sessionId, { generation = null } = {}) {
+  const current = load();
+  const entry = current.entries.get(text(sessionId));
+  if (!entry || (generation !== null && entry.generation !== generation)) return false;
+  current.entries.delete(entry.sessionId);
+  persist(current);
+  notify(entry.sessionId);
+  return true;
+}
+
+/** Move the exact entry to a later reading, keeping its generation. */
+export function deferQuotaResumeEntry(sessionId, generation, { resetAt, attempts }) {
+  const current = load();
+  const entry = current.entries.get(text(sessionId));
+  if (!entry || entry.generation !== generation) return null;
+  const next = normalizeEntry({ ...entry, resetAt, attempts });
+  if (!next) throw new TypeError('quota resume deferral needs a reset time');
+  current.entries.set(next.sessionId, next);
+  persist(current);
+  notify(next.sessionId);
+  return next;
+}
+
+export function cancelAllQuotaResumeEntries() {
+  const current = load();
+  const count = current.entries.size;
+  if (count === 0) return 0;
+  current.entries.clear();
+  persist(current);
+  notify(null);
+  return count;
+}
+
+/** Record the Goal this quota failure suspended (replaces any earlier note). */
+export function noteQuotaSuspendedGoal(sessionId, turnKey, goalId) {
+  const suspension = normalizeSuspension({ sessionId, turnKey, goalId });
+  if (!suspension) return false;
+  const current = load();
+  current.suspensions.set(suspension.sessionId, suspension);
+  persist(current);
+  return true;
+}
+
+/** The Goal the failure `turnKey` suspended, or '' when it suspended none. */
+export function quotaSuspendedGoal(sessionId, turnKey) {
+  const suspension = load().suspensions.get(text(sessionId));
+  return suspension && suspension.turnKey === text(turnKey) ? suspension.goalId : '';
+}
+
+export function forgetQuotaSuspendedGoal(sessionId) {
+  const current = load();
+  if (!current.suspensions.delete(text(sessionId))) return false;
+  persist(current);
+  return true;
+}
+
+/** Global setting, default on. */
+export function quotaAutoResumeEnabled() {
+  return readSection(SETTING_SECTION)?.autoResume !== false;
+}
+
+/** Persist the setting; turning it off cancels every pending resume. */
+export function setQuotaAutoResumeEnabled(enabled) {
+  const next = enabled !== false;
+  updateSection(SETTING_SECTION, (section) => ({ ...(section || {}), autoResume: next }));
+  if (!next) cancelAllQuotaResumeEntries();
+  return next;
+}
+
+/** Drop the in-memory copy so the next read loads from disk (a daemon restart). */
+export function reloadQuotaResumeStore() {
+  state = null;
+}

package/src/runtime/shared/shipped-definitions.mjs

@@ -0,0 +1,275 @@
+// Shipped definitions live in code; the data dir should hold only copies the
+// user actually changed. This module holds the pieces shared by the startup
+// migration (seeds.mjs), the editors, and scripts/build-shipped-history.mjs:
+// content normalisation + hashing (so the generator and the runtime compare
+// exactly the same thing), the shipped-history file, and the backup mover.
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { readMarkdownDocument } from './markdown-frontmatter.mjs';
+
+export const SHIPPED_HISTORY_FILE = ['defaults', 'shipped-history.json'];
+export const EMPTY_HISTORY = Object.freeze({ agents: {}, workflows: {}, outputStyles: {}, skills: {} });
+
+// Leftovers from hand edits or editors that never belong to a definition.
+const IGNORABLE_STRAY = /(\.(bak|orig|tmp)|~)$/i;
+export const isIgnorableStray = (name) => IGNORABLE_STRAY.test(name);
+
+const digest = (text) => createHash('sha256').update(text).digest('hex').slice(0, 32);
+
+/** CRLF -> LF, trailing whitespace stripped per line and at the end. */
+export function normalizeText(value) {
+  return (Buffer.isBuffer(value) ? value.toString('utf8') : String(value ?? ''))
+    .replace(/\r\n/g, '\n')
+    .replace(/[^\S\n]+$/gm, '')
+    .trimEnd();
+}
+
+export const hashText = (value) => digest(normalizeText(value));
+
+const oneLine = (value) =>
+  String(value || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/**
+ * Editable surface of an agent/workflow pack. `read(name)` returns the text of
+ * a file in the pack or null. agent.json wins over frontmatter for
+ * name/description, matching the loaders.
+ */
+export function packDefinitionFrom(read, entry, id = '') {
+  let manifest = {};
+  try {
+    const parsed = JSON.parse(read('agent.json') || '{}');
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) manifest = parsed;
+  } catch {
+    manifest = {};
+  }
+  const doc = readMarkdownDocument(read(oneLine(manifest.entry) || entry) || '');
+  const body = normalizeText(doc.body);
+  if (!body) return null;
+  // Every other loader-visible field (frontmatter flags such as permission or
+  // hidden, model/tool fields, manifest keys). An `id` equal to the directory
+  // id and the default `entry` are what the loaders assume anyway, so they are
+  // not differences.
+  const sameId = (value) =>
+    String(value ?? '')
+      .trim()
+      .toLowerCase() === String(id).toLowerCase();
+  const fields = {};
+  for (const [key, value] of Object.entries(doc.frontmatter)) {
+    if (key === 'name' || key === 'description' || (key === 'id' && sameId(value))) continue;
+    fields[`frontmatter.${key}`] = String(value).trim();
+  }
+  for (const [key, value] of Object.entries(manifest)) {
+    if (key === 'name' || key === 'description' || (key === 'id' && sameId(value))) continue;
+    if (key === 'entry' && (oneLine(value) === entry || !oneLine(value))) continue;
+    fields[`manifest.${key}`] = JSON.stringify(value);
+  }
+  return {
+    name: oneLine(manifest.name || doc.frontmatter.name),
+    description: oneLine(manifest.description || doc.frontmatter.description),
+    body,
+    fields,
+  };
+}
+
+const fieldsKey = (fields) => {
+  const source = fields || {};
+  return JSON.stringify(
+    Object.keys(source)
+      .sort()
+      .map((key) => [key, source[key]])
+  );
+};
+
+/** surfaceOnly: name/description/body, what the editors can express. */
+export const hashDefinition = ({ name, description, body, fields }, { surfaceOnly = false } = {}) =>
+  digest(
+    JSON.stringify([oneLine(name), oneLine(description), normalizeText(body), surfaceOnly ? '' : fieldsKey(fields)])
+  );
+
+export function packDefinitionFromDir(dir, entry, id = '') {
+  return packDefinitionFrom(
+    (name) => {
+      try {
+        return readFileSync(join(dir, name), 'utf8');
+      } catch {
+        return null;
+      }
+    },
+    entry,
+    id
+  );
+}
+
+export function packHashFromDir(dir, entry, id = '') {
+  const definition = packDefinitionFromDir(dir, entry, id);
+  return definition ? hashDefinition(definition) : null;
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+// Anything that is not valid UTF-8 text hashes byte-for-byte.
+const isBinary = (content) => {
+  if (!Buffer.isBuffer(content)) return false;
+  if (content.includes(0)) return true;
+  try {
+    utf8.decode(content);
+    return false;
+  } catch {
+    return true;
+  }
+};
+
+/**
+ * files: [relative '/' path, Buffer|string][]; stray files are ignored. Text
+ * files are normalised (CRLF/trailing space); binary files hash byte-for-byte.
+ */
+export function hashTree(files) {
+  const lines = files
+    .filter(([rel]) => !isIgnorableStray(rel.split('/').pop()))
+    .map(([rel, content]) => `${rel}\0${isBinary(content) ? `b${digest(content)}` : hashText(content)}`)
+    .sort();
+  return digest(lines.join('\n'));
+}
+
+export function readTreeFiles(dir, prefix = '') {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...readTreeFiles(join(dir, entry.name), rel));
+    else if (entry.isFile()) files.push([rel, readFileSync(join(dir, entry.name))]);
+  }
+  return files;
+}
+
+export function treeHashFromDir(dir) {
+  try {
+    return hashTree(readTreeFiles(dir));
+  } catch {
+    return null;
+  }
+}
+
+export function fileHash(file) {
+  try {
+    return hashText(readFileSync(file));
+  } catch {
+    return null;
+  }
+}
+
+export function loadShippedHistory(rootDir) {
+  try {
+    return { ...EMPTY_HISTORY, ...JSON.parse(readFileSync(join(rootDir, ...SHIPPED_HISTORY_FILE), 'utf8')) };
+  } catch {
+    return EMPTY_HISTORY;
+  }
+}
+
+/** The copy must hold the entry file and nothing but editor files and ignorable strays. */
+export function holdsOnlyEditorFiles(dir, allowed, entry) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  return (
+    entries.some((e) => e.isFile() && e.name === entry) &&
+    entries.every((e) => e.isFile() && (allowed.includes(e.name) || isIgnorableStray(e.name)))
+  );
+}
+
+/**
+ * Editor save of a pack whose definition equals the shipped one: no user copy
+ * should exist, so the item keeps following the shipped version. An existing
+ * copy (only editor files, a tombstone, strays) moves into a backup. Returns
+ * true when the save was absorbed; false means the caller writes the copy.
+ */
+export function absorbSaveEqualToShipped({ rootDir, dataDir, dir, id, entry, files, definition }) {
+  // The editor only expresses name/description/body; the shipped fields it
+  // cannot see keep applying because no copy is written.
+  const shipped = packDefinitionFromDir(join(rootDir, dir, id), entry, id);
+  if (
+    !shipped ||
+    hashDefinition(definition, { surfaceOnly: true }) !== hashDefinition(shipped, { surfaceOnly: true })
+  ) {
+    return false;
+  }
+  const copy = join(dataDir, dir, id);
+  if (!existsSync(copy)) return true;
+  const allowed = [...files, '.deleted'];
+  const clean = readdirSync(copy, { withFileTypes: true }).every(
+    (e) => e.isFile() && (allowed.includes(e.name) || isIgnorableStray(e.name))
+  );
+  if (!clean) return false;
+  // A real existing definition must match the shipped hidden fields exactly
+  // (an empty set included); a tombstone-only state has no definition to compare.
+  const existing = packDefinitionFromDir(copy, entry, id);
+  if (existing && fieldsKey(existing.fields || {}) !== fieldsKey(shipped.fields)) return false;
+  return makeBackup(dataDir).move(copy);
+}
+
+// Bump to re-run the history-based retirement for every install.
+export const SEPARATION_VERSION = 1;
+export const HISTORY_MARKER_FILE = '.shipped-history-retired';
+
+/** Identity of the history retirement: separation version + history content. */
+export const historyStamp = (rootDir) => `${SEPARATION_VERSION}:${digest(JSON.stringify(loadShippedHistory(rootDir)))}`;
+
+/**
+ * Lazily-created `<dataDir>/backups/defaults-separation-<timestamp>` folder.
+ * Moved entries keep their data-dir-relative path; nothing is deleted.
+ */
+export function makeBackup(dataDir) {
+  let root = null;
+  let failures = 0;
+  // Atomic create: an existing backup folder is never reused.
+  const claimRoot = () => {
+    const base = join(dataDir, 'backups', `defaults-separation-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+    mkdirSync(join(dataDir, 'backups'), { recursive: true });
+    for (let n = 1; ; n += 1) {
+      const candidate = n === 1 ? base : `${base}-${n}`;
+      try {
+        mkdirSync(candidate);
+        return candidate;
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+      }
+    }
+  };
+  const freeDest = (wanted) => {
+    let dest = wanted;
+    for (let n = 2; existsSync(dest); n += 1) dest = `${wanted}.${n}`;
+    return dest;
+  };
+  return {
+    get root() {
+      return root;
+    },
+    get failures() {
+      return failures;
+    },
+    /** Moves `target` into the backup; returns false if it could not be moved. */
+    move(target) {
+      if (!existsSync(target)) return true;
+      try {
+        root ??= claimRoot();
+        const dest = freeDest(join(root, relative(dataDir, target)));
+        mkdirSync(dirname(dest), { recursive: true });
+        try {
+          renameSync(target, dest);
+        } catch {
+          cpSync(target, dest, { recursive: true, force: false, errorOnExist: true });
+          rmSync(target, { recursive: true, force: true });
+        }
+        return true;
+      } catch {
+        // best-effort; a stuck copy simply keeps shadowing until moved by hand
+        failures += 1;
+        return false;
+      }
+    },
+  };
+}