vibeusage 0.2.8

package/src/commands/status.js

@@ -0,0 +1,155 @@
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+
+const { readJson } = require('../lib/fs');
+const { readCodexNotify, readEveryCodeNotify } = require('../lib/codex-config');
+const { isClaudeHookConfigured, buildClaudeHookCommand } = require('../lib/claude-config');
+const {
+  resolveGeminiConfigDir,
+  resolveGeminiSettingsPath,
+  isGeminiHookConfigured,
+  buildGeminiHookCommand
+} = require('../lib/gemini-config');
+const { resolveOpencodeConfigDir, isOpencodePluginInstalled } = require('../lib/opencode-config');
+const { normalizeState: normalizeUploadState } = require('../lib/upload-throttle');
+const { collectTrackerDiagnostics } = require('../lib/diagnostics');
+const { resolveTrackerPaths } = require('../lib/tracker-paths');
+
+async function cmdStatus(argv = []) {
+  const opts = parseArgs(argv);
+  if (opts.diagnostics) {
+    const diagnostics = await collectTrackerDiagnostics();
+    process.stdout.write(JSON.stringify(diagnostics, null, 2) + '\n');
+    return;
+  }
+
+  const home = os.homedir();
+  const { trackerDir, binDir } = await resolveTrackerPaths({ home, migrate: true });
+  const configPath = path.join(trackerDir, 'config.json');
+  const queuePath = path.join(trackerDir, 'queue.jsonl');
+  const queueStatePath = path.join(trackerDir, 'queue.state.json');
+  const cursorsPath = path.join(trackerDir, 'cursors.json');
+  const notifySignalPath = path.join(trackerDir, 'notify.signal');
+  const throttlePath = path.join(trackerDir, 'sync.throttle');
+  const uploadThrottlePath = path.join(trackerDir, 'upload.throttle.json');
+  const autoRetryPath = path.join(trackerDir, 'auto.retry.json');
+  const codexHome = process.env.CODEX_HOME || path.join(home, '.codex');
+  const codexConfigPath = path.join(codexHome, 'config.toml');
+  const codeHome = process.env.CODE_HOME || path.join(home, '.code');
+  const codeConfigPath = path.join(codeHome, 'config.toml');
+  const claudeSettingsPath = path.join(home, '.claude', 'settings.json');
+  const geminiConfigDir = resolveGeminiConfigDir({ home, env: process.env });
+  const geminiSettingsPath = resolveGeminiSettingsPath({ configDir: geminiConfigDir });
+  const opencodeConfigDir = resolveOpencodeConfigDir({ home, env: process.env });
+  const notifyPath = path.join(binDir, 'notify.cjs');
+  const claudeHookCommand = buildClaudeHookCommand(notifyPath);
+  const geminiHookCommand = buildGeminiHookCommand(notifyPath);
+
+  const config = await readJson(configPath);
+  const cursors = await readJson(cursorsPath);
+  const queueState = (await readJson(queueStatePath)) || { offset: 0 };
+  const uploadThrottle = normalizeUploadState(await readJson(uploadThrottlePath));
+  const autoRetry = await readJson(autoRetryPath);
+
+  const queueSize = await safeStatSize(queuePath);
+  const pendingBytes = Math.max(0, queueSize - (queueState.offset || 0));
+
+  const lastNotify = (await safeReadText(notifySignalPath))?.trim() || null;
+  const lastNotifySpawn = parseEpochMsToIso((await safeReadText(throttlePath))?.trim() || null);
+
+  const codexNotify = await readCodexNotify(codexConfigPath);
+  const notifyConfigured = Array.isArray(codexNotify) && codexNotify.length > 0;
+  const everyCodeNotify = await readEveryCodeNotify(codeConfigPath);
+  const everyCodeConfigured = Array.isArray(everyCodeNotify) && everyCodeNotify.length > 0;
+  const claudeHookConfigured = await isClaudeHookConfigured({
+    settingsPath: claudeSettingsPath,
+    hookCommand: claudeHookCommand
+  });
+  const geminiHookConfigured = await isGeminiHookConfigured({
+    settingsPath: geminiSettingsPath,
+    hookCommand: geminiHookCommand
+  });
+  const opencodePluginConfigured = await isOpencodePluginInstalled({ configDir: opencodeConfigDir });
+
+  const lastUpload = uploadThrottle.lastSuccessMs
+    ? parseEpochMsToIso(uploadThrottle.lastSuccessMs)
+    : typeof queueState.updatedAt === 'string'
+      ? queueState.updatedAt
+      : null;
+  const nextUpload = parseEpochMsToIso(uploadThrottle.nextAllowedAtMs || null);
+  const backoffUntil = parseEpochMsToIso(uploadThrottle.backoffUntilMs || null);
+  const lastUploadError = uploadThrottle.lastError
+    ? `${uploadThrottle.lastErrorAt || 'unknown'} ${uploadThrottle.lastError}`
+    : null;
+  const autoRetryAt = parseEpochMsToIso(autoRetry?.retryAtMs || null);
+  const autoRetryLine = autoRetryAt
+    ? `- Auto retry after: ${autoRetryAt} (${autoRetry?.reason || 'scheduled'}, pending ${Number(
+        autoRetry?.pendingBytes || 0
+      )} bytes)`
+    : null;
+
+  process.stdout.write(
+    [
+      'Status:',
+      `- Base URL: ${config?.baseUrl || 'unset'}`,
+      `- Device token: ${config?.deviceToken ? 'set' : 'unset'}`,
+      `- Queue: ${pendingBytes} bytes pending`,
+      `- Last parse: ${cursors?.updatedAt || 'never'}`,
+      `- Last notify: ${lastNotify || 'never'}`,
+      `- Last notify-triggered sync: ${lastNotifySpawn || 'never'}`,
+      `- Last upload: ${lastUpload || 'never'}`,
+      `- Next upload after: ${nextUpload || 'never'}`,
+      `- Backoff until: ${backoffUntil || 'never'}`,
+      lastUploadError ? `- Last upload error: ${lastUploadError}` : null,
+      autoRetryLine,
+      `- Codex notify: ${notifyConfigured ? JSON.stringify(codexNotify) : 'unset'}`,
+      `- Every Code notify: ${everyCodeConfigured ? JSON.stringify(everyCodeNotify) : 'unset'}`,
+      `- Claude hooks: ${claudeHookConfigured ? 'set' : 'unset'}`,
+      `- Gemini hooks: ${geminiHookConfigured ? 'set' : 'unset'}`,
+      `- Opencode plugin: ${opencodePluginConfigured ? 'set' : 'unset'}`,
+      ''
+    ]
+      .filter(Boolean)
+      .join('\n')
+  );
+}
+
+function parseArgs(argv) {
+  const out = { diagnostics: false };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--diagnostics' || a === '--json') out.diagnostics = true;
+    else throw new Error(`Unknown option: ${a}`);
+  }
+
+  return out;
+}
+
+async function safeStatSize(p) {
+  try {
+    const st = await fs.stat(p);
+    return st.size || 0;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+async function safeReadText(p) {
+  try {
+    return await fs.readFile(p, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+}
+
+function parseEpochMsToIso(v) {
+  const ms = Number(v);
+  if (!Number.isFinite(ms) || ms <= 0) return null;
+  const d = new Date(ms);
+  if (Number.isNaN(d.getTime())) return null;
+  return d.toISOString();
+}
+
+module.exports = { cmdStatus };

package/src/commands/sync.js

@@ -0,0 +1,479 @@
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const cp = require('node:child_process');
+
+const { ensureDir, readJson, writeJson, openLock } = require('../lib/fs');
+const {
+  listRolloutFiles,
+  listClaudeProjectFiles,
+  listGeminiSessionFiles,
+  listOpencodeMessageFiles,
+  parseRolloutIncremental,
+  parseClaudeIncremental,
+  parseGeminiIncremental,
+  parseOpencodeIncremental
+} = require('../lib/rollout');
+const { drainQueueToCloud } = require('../lib/uploader');
+const { createProgress, renderBar, formatNumber, formatBytes } = require('../lib/progress');
+const { syncHeartbeat } = require('../lib/vibescore-api');
+const {
+  DEFAULTS: UPLOAD_DEFAULTS,
+  normalizeState: normalizeUploadState,
+  decideAutoUpload,
+  recordUploadSuccess,
+  recordUploadFailure
+} = require('../lib/upload-throttle');
+const { resolveTrackerPaths } = require('../lib/tracker-paths');
+
+async function cmdSync(argv) {
+  const opts = parseArgs(argv);
+  const home = os.homedir();
+  const { trackerDir } = await resolveTrackerPaths({ home, migrate: true });
+
+  await ensureDir(trackerDir);
+
+  const lockPath = path.join(trackerDir, 'sync.lock');
+  const lock = await openLock(lockPath, { quietIfLocked: opts.auto });
+  if (!lock) return;
+
+  let progress = null;
+  try {
+    progress = !opts.auto ? createProgress({ stream: process.stdout }) : null;
+    const configPath = path.join(trackerDir, 'config.json');
+    const cursorsPath = path.join(trackerDir, 'cursors.json');
+    const queuePath = path.join(trackerDir, 'queue.jsonl');
+    const queueStatePath = path.join(trackerDir, 'queue.state.json');
+    const uploadThrottlePath = path.join(trackerDir, 'upload.throttle.json');
+
+    const config = await readJson(configPath);
+    const cursors = (await readJson(cursorsPath)) || { version: 1, files: {}, updatedAt: null };
+    const uploadThrottle = normalizeUploadState(await readJson(uploadThrottlePath));
+    let uploadThrottleState = uploadThrottle;
+
+    const codexHome = process.env.CODEX_HOME || path.join(home, '.codex');
+    const codeHome = process.env.CODE_HOME || path.join(home, '.code');
+    const claudeProjectsDir = path.join(home, '.claude', 'projects');
+    const geminiHome = process.env.GEMINI_HOME || path.join(home, '.gemini');
+    const geminiTmpDir = path.join(geminiHome, 'tmp');
+    const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+    const opencodeHome = process.env.OPENCODE_HOME || path.join(xdgDataHome, 'opencode');
+    const opencodeStorageDir = path.join(opencodeHome, 'storage');
+
+    const sources = [
+      { source: 'codex', sessionsDir: path.join(codexHome, 'sessions') },
+      { source: 'every-code', sessionsDir: path.join(codeHome, 'sessions') }
+    ];
+
+    const rolloutFiles = [];
+    const seenSessions = new Set();
+    for (const entry of sources) {
+      if (seenSessions.has(entry.sessionsDir)) continue;
+      seenSessions.add(entry.sessionsDir);
+      const files = await listRolloutFiles(entry.sessionsDir);
+      for (const filePath of files) {
+        rolloutFiles.push({ path: filePath, source: entry.source });
+      }
+    }
+
+    if (progress?.enabled) {
+      progress.start(`Parsing ${renderBar(0)} 0/${formatNumber(rolloutFiles.length)} files | buckets 0`);
+    }
+
+    const parseResult = await parseRolloutIncremental({
+      rolloutFiles,
+      cursors,
+      queuePath,
+      onProgress: (p) => {
+        if (!progress?.enabled) return;
+        const pct = p.total > 0 ? p.index / p.total : 1;
+        progress.update(
+          `Parsing ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} files | buckets ${formatNumber(
+            p.bucketsQueued
+          )}`
+        );
+      }
+    });
+
+    const claudeFiles = await listClaudeProjectFiles(claudeProjectsDir);
+    let claudeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    if (claudeFiles.length > 0) {
+      if (progress?.enabled) {
+        progress.start(`Parsing Claude ${renderBar(0)} 0/${formatNumber(claudeFiles.length)} files | buckets 0`);
+      }
+      claudeResult = await parseClaudeIncremental({
+        projectFiles: claudeFiles,
+        cursors,
+        queuePath,
+        onProgress: (p) => {
+          if (!progress?.enabled) return;
+          const pct = p.total > 0 ? p.index / p.total : 1;
+          progress.update(
+            `Parsing Claude ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} files | buckets ${formatNumber(
+              p.bucketsQueued
+            )}`
+          );
+        },
+        source: 'claude'
+      });
+    }
+
+    const geminiFiles = await listGeminiSessionFiles(geminiTmpDir);
+    let geminiResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    if (geminiFiles.length > 0) {
+      if (progress?.enabled) {
+        progress.start(`Parsing Gemini ${renderBar(0)} 0/${formatNumber(geminiFiles.length)} files | buckets 0`);
+      }
+      geminiResult = await parseGeminiIncremental({
+        sessionFiles: geminiFiles,
+        cursors,
+        queuePath,
+        onProgress: (p) => {
+          if (!progress?.enabled) return;
+          const pct = p.total > 0 ? p.index / p.total : 1;
+          progress.update(
+            `Parsing Gemini ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} files | buckets ${formatNumber(
+              p.bucketsQueued
+            )}`
+          );
+        },
+        source: 'gemini'
+      });
+    }
+
+    const opencodeFiles = await listOpencodeMessageFiles(opencodeStorageDir);
+    let opencodeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    if (opencodeFiles.length > 0) {
+      if (progress?.enabled) {
+        progress.start(`Parsing Opencode ${renderBar(0)} 0/${formatNumber(opencodeFiles.length)} files | buckets 0`);
+      }
+      opencodeResult = await parseOpencodeIncremental({
+        messageFiles: opencodeFiles,
+        cursors,
+        queuePath,
+        onProgress: (p) => {
+          if (!progress?.enabled) return;
+          const pct = p.total > 0 ? p.index / p.total : 1;
+          progress.update(
+            `Parsing Opencode ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(
+              p.total
+            )} files | buckets ${formatNumber(p.bucketsQueued)}`
+          );
+        },
+        source: 'opencode'
+      });
+    }
+
+    cursors.updatedAt = new Date().toISOString();
+    await writeJson(cursorsPath, cursors);
+
+    progress?.stop();
+
+    const deviceToken = config?.deviceToken || process.env.VIBEUSAGE_DEVICE_TOKEN || process.env.VIBESCORE_DEVICE_TOKEN || null;
+    const baseUrl = config?.baseUrl ||
+      process.env.VIBEUSAGE_INSFORGE_BASE_URL ||
+      process.env.VIBESCORE_INSFORGE_BASE_URL ||
+      'https://5tmappuk.us-east.insforge.app';
+
+    let uploadResult = null;
+    let uploadAttempted = false;
+    if (deviceToken) {
+      const beforeState = (await readJson(queueStatePath)) || { offset: 0 };
+      const queueSize = await safeStatSize(queuePath);
+      const pendingBytes = Math.max(0, queueSize - Number(beforeState.offset || 0));
+      let maxBatches = opts.auto ? 3 : opts.drain ? 10_000 : 10;
+      let batchSize = UPLOAD_DEFAULTS.batchSize;
+      let allowUpload = pendingBytes > 0;
+      let autoDecision = null;
+
+      if (opts.auto) {
+        autoDecision = decideAutoUpload({
+          nowMs: Date.now(),
+          pendingBytes,
+          state: uploadThrottle
+        });
+        allowUpload = allowUpload && autoDecision.allowed;
+        maxBatches = autoDecision.allowed ? autoDecision.maxBatches : 0;
+        batchSize = autoDecision.batchSize;
+        if (!autoDecision.allowed && pendingBytes > 0 && autoDecision.blockedUntilMs > 0) {
+          const reason = deriveAutoSkipReason({ decision: autoDecision, state: uploadThrottle });
+          await scheduleAutoRetry({
+            trackerDir,
+            retryAtMs: autoDecision.blockedUntilMs,
+            reason,
+            pendingBytes,
+            source: 'auto-throttled'
+          });
+        }
+      }
+
+      if (progress?.enabled && pendingBytes > 0 && allowUpload) {
+        const pct = queueSize > 0 ? Number(beforeState.offset || 0) / queueSize : 0;
+        progress.start(
+          `Uploading ${renderBar(pct)} ${formatBytes(Number(beforeState.offset || 0))}/${formatBytes(queueSize)} | inserted 0 skipped 0`
+        );
+      }
+
+      if (allowUpload && maxBatches > 0) {
+        uploadAttempted = true;
+        try {
+          uploadResult = await drainQueueToCloud({
+            baseUrl,
+            deviceToken,
+            queuePath,
+            queueStatePath,
+            maxBatches,
+            batchSize,
+            onProgress: (u) => {
+              if (!progress?.enabled) return;
+              const pct = u.queueSize > 0 ? u.offset / u.queueSize : 1;
+              progress.update(
+                `Uploading ${renderBar(pct)} ${formatBytes(u.offset)}/${formatBytes(u.queueSize)} | inserted ${formatNumber(
+                  u.inserted
+                )} skipped ${formatNumber(u.skipped)}`
+              );
+            }
+          });
+          if (uploadResult.attempted > 0) {
+            const next = recordUploadSuccess({ nowMs: Date.now(), state: uploadThrottleState });
+            uploadThrottleState = next;
+            await writeJson(uploadThrottlePath, next);
+          }
+        } catch (e) {
+          const next = recordUploadFailure({ nowMs: Date.now(), state: uploadThrottleState, error: e });
+          uploadThrottleState = next;
+          await writeJson(uploadThrottlePath, next);
+          if (opts.auto && pendingBytes > 0) {
+            const retryAtMs = Math.max(next.nextAllowedAtMs || 0, next.backoffUntilMs || 0);
+            if (retryAtMs > 0) {
+              await scheduleAutoRetry({
+                trackerDir,
+                retryAtMs,
+                reason: 'backoff',
+                pendingBytes,
+                source: 'auto-error'
+              });
+            }
+          }
+          throw e;
+        }
+      } else {
+        uploadResult = { inserted: 0, skipped: 0 };
+      }
+
+      progress?.stop();
+    }
+
+    const afterState = (await readJson(queueStatePath)) || { offset: 0 };
+    const queueSize = await safeStatSize(queuePath);
+    const pendingBytes = Math.max(0, queueSize - Number(afterState.offset || 0));
+
+    if (pendingBytes <= 0) {
+      await clearAutoRetry(trackerDir);
+    } else if (opts.auto && uploadAttempted) {
+      const retryAtMs = Number(uploadThrottleState?.nextAllowedAtMs || 0);
+      if (retryAtMs > Date.now()) {
+        await scheduleAutoRetry({
+          trackerDir,
+          retryAtMs,
+          reason: 'backlog',
+          pendingBytes,
+          source: 'auto-backlog'
+        });
+      }
+    }
+
+    await maybeSendHeartbeat({
+      baseUrl,
+      deviceToken,
+      trackerDir,
+      uploadResult,
+      pendingBytes
+    });
+
+    if (!opts.auto) {
+      const totalParsed =
+        parseResult.filesProcessed +
+        claudeResult.filesProcessed +
+        geminiResult.filesProcessed +
+        opencodeResult.filesProcessed;
+      const totalBuckets =
+        parseResult.bucketsQueued +
+        claudeResult.bucketsQueued +
+        geminiResult.bucketsQueued +
+        opencodeResult.bucketsQueued;
+      process.stdout.write(
+        [
+          'Sync finished:',
+          `- Parsed files: ${totalParsed}`,
+          `- New 30-min buckets queued: ${totalBuckets}`,
+          deviceToken
+            ? `- Uploaded: ${uploadResult.inserted} inserted, ${uploadResult.skipped} skipped`
+            : '- Uploaded: skipped (no device token)',
+          deviceToken && pendingBytes > 0 && !opts.drain
+            ? `- Remaining: ${formatBytes(pendingBytes)} pending (run sync again, or use --drain)`
+            : null,
+          ''
+        ]
+          .filter(Boolean)
+          .join('\n')
+      );
+    }
+  } finally {
+    progress?.stop();
+    await lock.release();
+    await fs.unlink(lockPath).catch(() => {});
+  }
+}
+
+function parseArgs(argv) {
+  const out = {
+    auto: false,
+    fromNotify: false,
+    fromRetry: false,
+    drain: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--auto') out.auto = true;
+    else if (a === '--from-notify') out.fromNotify = true;
+    else if (a === '--from-retry') out.fromRetry = true;
+    else if (a === '--drain') out.drain = true;
+    else throw new Error(`Unknown option: ${a}`);
+  }
+  return out;
+}
+
+module.exports = { cmdSync };
+
+async function safeStatSize(p) {
+  try {
+    const st = await fs.stat(p);
+    return st && st.isFile() ? st.size : 0;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+async function maybeSendHeartbeat({ baseUrl, deviceToken, trackerDir, uploadResult, pendingBytes }) {
+  if (!deviceToken || !uploadResult) return;
+  if (pendingBytes > 0) return;
+  if (Number(uploadResult.inserted || 0) !== 0) return;
+
+  const heartbeatPath = path.join(trackerDir, 'sync.heartbeat.json');
+  const heartbeatState = await readJson(heartbeatPath);
+  const lastPingAt = Date.parse(heartbeatState?.lastPingAt || '');
+  const nowMs = Date.now();
+  if (Number.isFinite(lastPingAt) && nowMs - lastPingAt < HEARTBEAT_MIN_INTERVAL_MS) return;
+
+  try {
+    await syncHeartbeat({ baseUrl, deviceToken });
+    await writeJson(heartbeatPath, {
+      lastPingAt: new Date(nowMs).toISOString(),
+      minIntervalMinutes: HEARTBEAT_MIN_INTERVAL_MINUTES
+    });
+  } catch (_e) {
+    // best-effort heartbeat; ignore failures
+  }
+}
+
+function deriveAutoSkipReason({ decision, state }) {
+  if (!decision || decision.reason !== 'throttled') return decision?.reason || 'unknown';
+  const backoffUntilMs = Number(state?.backoffUntilMs || 0);
+  const nextAllowedAtMs = Number(state?.nextAllowedAtMs || 0);
+  if (backoffUntilMs > 0 && backoffUntilMs >= nextAllowedAtMs) return 'backoff';
+  return 'throttled';
+}
+
+async function scheduleAutoRetry({ trackerDir, retryAtMs, reason, pendingBytes, source }) {
+  const retryMs = coerceRetryMs(retryAtMs);
+  if (!retryMs) return { scheduled: false, retryAtMs: 0 };
+
+  const retryPath = path.join(trackerDir, AUTO_RETRY_FILENAME);
+  const nowMs = Date.now();
+  const existing = await readJson(retryPath);
+  const existingMs = coerceRetryMs(existing?.retryAtMs);
+  if (existingMs && existingMs >= retryMs - 1000) {
+    return { scheduled: false, retryAtMs: existingMs };
+  }
+
+  const payload = {
+    version: 1,
+    retryAtMs: retryMs,
+    retryAt: new Date(retryMs).toISOString(),
+    reason: typeof reason === 'string' && reason.length > 0 ? reason : 'throttled',
+    pendingBytes: Math.max(0, Number(pendingBytes || 0)),
+    scheduledAt: new Date(nowMs).toISOString(),
+    source: typeof source === 'string' ? source : 'auto'
+  };
+
+  await writeJson(retryPath, payload);
+
+  const delayMs = Math.min(AUTO_RETRY_MAX_DELAY_MS, Math.max(0, retryMs - nowMs));
+  if (delayMs <= 0) return { scheduled: false, retryAtMs: retryMs };
+  if (process.env.VIBEUSAGE_AUTO_RETRY_NO_SPAWN === '1' || process.env.VIBESCORE_AUTO_RETRY_NO_SPAWN === '1') {
+    return { scheduled: false, retryAtMs: retryMs };
+  }
+
+  spawnAutoRetryProcess({
+    retryPath,
+    trackerBinPath: path.join(trackerDir, 'app', 'bin', 'tracker.js'),
+    fallbackPkg: 'vibeusage',
+    delayMs
+  });
+  return { scheduled: true, retryAtMs: retryMs };
+}
+
+async function clearAutoRetry(trackerDir) {
+  const retryPath = path.join(trackerDir, AUTO_RETRY_FILENAME);
+  await fs.unlink(retryPath).catch(() => {});
+}
+
+function spawnAutoRetryProcess({ retryPath, trackerBinPath, fallbackPkg, delayMs }) {
+  const script = buildAutoRetryScript({ retryPath, trackerBinPath, fallbackPkg, delayMs });
+  try {
+    const child = cp.spawn(process.execPath, ['-e', script], {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env
+    });
+    child.unref();
+  } catch (_e) {}
+}
+
+function buildAutoRetryScript({ retryPath, trackerBinPath, fallbackPkg, delayMs }) {
+  return `'use strict';\n` +
+    `const fs = require('node:fs');\n` +
+    `const cp = require('node:child_process');\n` +
+    `const retryPath = ${JSON.stringify(retryPath)};\n` +
+    `const trackerBinPath = ${JSON.stringify(trackerBinPath)};\n` +
+    `const fallbackPkg = ${JSON.stringify(fallbackPkg)};\n` +
+    `const delayMs = ${Math.max(0, Math.floor(delayMs || 0))};\n` +
+    `setTimeout(() => {\n` +
+    `  let retryAtMs = 0;\n` +
+    `  try {\n` +
+    `    const raw = fs.readFileSync(retryPath, 'utf8');\n` +
+    `    retryAtMs = Number(JSON.parse(raw).retryAtMs || 0);\n` +
+    `  } catch (_) {}\n` +
+    `  if (!retryAtMs || Date.now() + 1000 < retryAtMs) process.exit(0);\n` +
+    `  const argv = ['sync', '--auto', '--from-retry'];\n` +
+    `  const cmd = fs.existsSync(trackerBinPath)\n` +
+    `    ? [process.execPath, trackerBinPath, ...argv]\n` +
+    `    : ['npx', '--yes', fallbackPkg, ...argv];\n` +
+    `  try {\n` +
+    `    const child = cp.spawn(cmd[0], cmd.slice(1), { detached: true, stdio: 'ignore', env: process.env });\n` +
+    `    child.unref();\n` +
+    `  } catch (_) {}\n` +
+    `}, delayMs);\n`;
+}
+
+function coerceRetryMs(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return Math.floor(n);
+}
+
+const HEARTBEAT_MIN_INTERVAL_MINUTES = 30;
+const HEARTBEAT_MIN_INTERVAL_MS = HEARTBEAT_MIN_INTERVAL_MINUTES * 60 * 1000;
+const AUTO_RETRY_FILENAME = 'auto.retry.json';
+const AUTO_RETRY_MAX_DELAY_MS = 2 * 60 * 60 * 1000;