@ipv9/tokentracker-cli 0.39.0

package/src/lib/diagnostics.js

@@ -0,0 +1,272 @@
+const os = require("node:os");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+
+const { readJson } = require("./fs");
+const { readCodexNotify, readEveryCodeNotify } = require("./codex-config");
+const { isClaudeHookConfigured, buildClaudeHookCommand } = require("./claude-config");
+const {
+  resolveGeminiConfigDir,
+  resolveGeminiSettingsPath,
+  buildGeminiHookCommand,
+  isGeminiHookConfigured,
+} = require("./gemini-config");
+const { resolveOpencodeConfigDir, isOpencodePluginInstalled } = require("./opencode-config");
+const { normalizeState: normalizeUploadState } = require("./upload-throttle");
+const { probeOpenclawHookState } = require("./openclaw-hook");
+const { probeOpenclawSessionPluginState } = require("./openclaw-session-plugin");
+const { probeGrokHookState } = require("./grok-hook");
+const { resolveTrackerPaths } = require("./tracker-paths");
+// TASK-011: Kiro CLI DB path inlined here to avoid pulling the ~4000-line
+// rollout module on every `tokentracker status` / `diagnostics` call.
+// rollout.js still exports resolveKiroCliDbPath for external callers.
+function resolveKiroCliDbPathInline(env, home) {
+  if (env.KIRO_CLI_DB_PATH) return env.KIRO_CLI_DB_PATH;
+  const effectiveHome = env.HOME || home;
+  return path.join(
+    effectiveHome,
+    "Library",
+    "Application Support",
+    "kiro-cli",
+    "data.sqlite3",
+  );
+}
+
+async function collectTrackerDiagnostics({
+  home = os.homedir(),
+  codexHome = process.env.CODEX_HOME || path.join(home, ".codex"),
+  codeHome = process.env.CODE_HOME || path.join(home, ".code"),
+} = {}) {
+  const { trackerDir, binDir } = await resolveTrackerPaths({ home });
+  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 openclawSignalPath = path.join(trackerDir, "openclaw.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 codexConfigPath = path.join(codexHome, "config.toml");
+  const codeConfigPath = path.join(codeHome, "config.toml");
+  const claudeConfigPath = 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 grokHome =
+    process.env.TOKENTRACKER_GROK_HOME ||
+    process.env.GROK_HOME ||
+    path.join(home, ".grok");
+
+  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 offsetBytes = Number(queueState.offset || 0);
+  const pendingBytes = Math.max(0, queueSize - offsetBytes);
+
+  const lastNotify = (await safeReadText(notifySignalPath))?.trim() || null;
+  const lastOpenclawSync = (await safeReadText(openclawSignalPath))?.trim() || null;
+  const lastNotifySpawn = parseEpochMsToIso((await safeReadText(throttlePath))?.trim() || null);
+
+  const codexNotifyRaw = await readCodexNotify(codexConfigPath);
+  const notifyConfigured = Array.isArray(codexNotifyRaw) && codexNotifyRaw.length > 0;
+  const codexNotify = notifyConfigured ? codexNotifyRaw.map((v) => redactValue(v, home)) : null;
+  const everyCodeNotifyRaw = await readEveryCodeNotify(codeConfigPath);
+  const everyCodeConfigured = Array.isArray(everyCodeNotifyRaw) && everyCodeNotifyRaw.length > 0;
+  const everyCodeNotify = everyCodeConfigured
+    ? everyCodeNotifyRaw.map((v) => redactValue(v, home))
+    : null;
+  const claudeHookCommand = buildClaudeHookCommand(path.join(binDir, "notify.cjs"));
+  const claudeHookConfigured = await isClaudeHookConfigured({
+    settingsPath: claudeConfigPath,
+    hookCommand: claudeHookCommand,
+  });
+  const geminiHookCommand = buildGeminiHookCommand(path.join(binDir, "notify.cjs"));
+  const geminiHookConfigured = await isGeminiHookConfigured({
+    settingsPath: geminiSettingsPath,
+    hookCommand: geminiHookCommand,
+  });
+  const opencodePluginConfigured = await isOpencodePluginInstalled({
+    configDir: opencodeConfigDir,
+  });
+  const openclawSessionPluginState = await probeOpenclawSessionPluginState({
+    home,
+    trackerDir,
+    env: process.env,
+  });
+  const openclawHookState = await probeOpenclawHookState({ home, trackerDir, env: process.env });
+  const grokHookState = await probeGrokHookState({ home, trackerDir, env: process.env });
+
+  // Kiro IDE and Kiro CLI sub-path presence — merged under one "kiro" source
+  // at token/cost aggregation level; operators need visibility of both
+  // sub-paths here for debugging.
+  const kiroIdeDevDataDir = path.join(
+    home,
+    "Library",
+    "Application Support",
+    "Kiro",
+    "User",
+    "globalStorage",
+    "kiro.kiroagent",
+    "dev_data",
+  );
+  const kiroIdePresent =
+    (await safeStatSize(path.join(kiroIdeDevDataDir, "devdata.sqlite"))) > 0 ||
+    (await safeStatSize(path.join(kiroIdeDevDataDir, "tokens_generated.jsonl"))) > 0;
+  const kiroCliDbPath = resolveKiroCliDbPathInline(process.env, home);
+  const kiroCliPresent = require("node:fs").existsSync(kiroCliDbPath);
+
+  const lastSuccessAt = uploadThrottle.lastSuccessMs
+    ? new Date(uploadThrottle.lastSuccessMs).toISOString()
+    : null;
+  const autoRetryAt = parseEpochMsToIso(autoRetry?.retryAtMs);
+
+  return {
+    ok: true,
+    version: 1,
+    generated_at: new Date().toISOString(),
+    env: {
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+    },
+    paths: {
+      tracker_dir: redactValue(trackerDir, home),
+      codex_home: redactValue(codexHome, home),
+      codex_config: redactValue(codexConfigPath, home),
+      code_home: redactValue(codeHome, home),
+      code_config: redactValue(codeConfigPath, home),
+      claude_config: redactValue(claudeConfigPath, home),
+      gemini_config: redactValue(geminiSettingsPath, home),
+      opencode_config: redactValue(opencodeConfigDir, home),
+      grok_home: redactValue(grokHome, home),
+      grok_hooks: redactValue(grokHookState?.grokHooksDir, home),
+      grok_handler: redactValue(grokHookState?.handlerPath, home),
+      kiro_ide_dev_data: redactValue(kiroIdeDevDataDir, home),
+      kiro_cli_db: redactValue(kiroCliDbPath, home),
+    },
+    kiro: {
+      ide_present: kiroIdePresent,
+      cli_present: kiroCliPresent,
+      cli_approximation:
+        "Kiro CLI does not persist explicit token counts (billing is credit-based on Bedrock). Tokens are approximated at 4 chars/token from user prompt chars and assistant response chars. Source rows that came through this path have model='kiro-cli-agent' when the underlying model is unknown (auto-routing); known Bedrock ARNs canonicalize to their short name (e.g. claude-sonnet-4).",
+      merge_policy:
+        "Kiro IDE and Kiro CLI both emit source='kiro' in queue.jsonl so token, cost, heatmap, and leaderboard aggregations merge transparently. Use this block to distinguish sub-path contributions.",
+    },
+    config: {
+      base_url: typeof config?.baseUrl === "string" ? config.baseUrl : null,
+      device_token: config?.deviceToken ? "set" : "unset",
+      device_id: maskId(config?.deviceId),
+      installed_at: typeof config?.installedAt === "string" ? config.installedAt : null,
+    },
+    parse: {
+      updated_at: typeof cursors?.updatedAt === "string" ? cursors.updatedAt : null,
+      file_count:
+        cursors?.files && typeof cursors.files === "object"
+          ? Object.keys(cursors.files).length
+          : null,
+    },
+    queue: {
+      size_bytes: queueSize,
+      offset_bytes: offsetBytes,
+      pending_bytes: pendingBytes,
+      updated_at: typeof queueState.updatedAt === "string" ? queueState.updatedAt : null,
+    },
+    notify: {
+      last_notify: lastNotify,
+      last_openclaw_triggered_sync: lastOpenclawSync,
+      last_notify_triggered_sync: lastNotifySpawn,
+      codex_notify_configured: notifyConfigured,
+      codex_notify: codexNotify,
+      every_code_notify_configured: everyCodeConfigured,
+      every_code_notify: everyCodeNotify,
+      claude_hook_configured: claudeHookConfigured,
+      gemini_hook_configured: geminiHookConfigured,
+      opencode_plugin_configured: opencodePluginConfigured,
+      openclaw_session_plugin_configured: Boolean(openclawSessionPluginState?.configured),
+      openclaw_session_plugin_linked: Boolean(openclawSessionPluginState?.linked),
+      openclaw_session_plugin_enabled: Boolean(openclawSessionPluginState?.enabled),
+      openclaw_hook_configured: Boolean(openclawHookState?.configured),
+      openclaw_hook_linked: Boolean(openclawHookState?.linked),
+      openclaw_hook_enabled: Boolean(openclawHookState?.enabled),
+      grok_hook_configured: Boolean(grokHookState?.configured),
+      grok_hook_exists: Boolean(grokHookState?.hookExists),
+      grok_hook_handler_exists: Boolean(grokHookState?.handlerExists),
+      grok_sessions_dir: redactValue(grokHookState?.sessionsDir, home),
+    },
+    upload: {
+      last_success_at: lastSuccessAt,
+      next_allowed_after: parseEpochMsToIso(uploadThrottle.nextAllowedAtMs || null),
+      backoff_until: parseEpochMsToIso(uploadThrottle.backoffUntilMs || null),
+      last_error: uploadThrottle.lastError
+        ? {
+            at: uploadThrottle.lastErrorAt || null,
+            message: redactError(String(uploadThrottle.lastError), home),
+          }
+        : null,
+    },
+    auto_retry: autoRetryAt
+      ? {
+          next_retry_at: autoRetryAt,
+          reason: typeof autoRetry?.reason === "string" ? autoRetry.reason : null,
+          pending_bytes: Number.isFinite(Number(autoRetry?.pendingBytes))
+            ? Math.max(0, Number(autoRetry.pendingBytes))
+            : null,
+          scheduled_at: typeof autoRetry?.scheduledAt === "string" ? autoRetry.scheduledAt : null,
+          source: typeof autoRetry?.source === "string" ? autoRetry.source : null,
+        }
+      : null,
+  };
+}
+
+function maskId(v) {
+  if (typeof v !== "string") return null;
+  const s = v.trim();
+  if (s.length < 12) return null;
+  return `${s.slice(0, 8)}…${s.slice(-4)}`;
+}
+
+function redactValue(value, home) {
+  if (typeof value !== "string") return value;
+  if (typeof home !== "string" || home.length === 0) return value;
+  const homeNorm = home.endsWith(path.sep) ? home.slice(0, -1) : home;
+  return value.startsWith(homeNorm) ? `~${value.slice(homeNorm.length)}` : value;
+}
+
+function redactError(message, home) {
+  if (typeof message !== "string") return message;
+  if (typeof home !== "string" || home.length === 0) return message;
+  const homeNorm = home.endsWith(path.sep) ? home.slice(0, -1) : home;
+  return message.split(homeNorm).join("~");
+}
+
+async function safeStatSize(p) {
+  try {
+    const st = await fs.stat(p);
+    return st && st.isFile() ? 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 = { collectTrackerDiagnostics };

package/src/lib/doctor.js

@@ -0,0 +1,338 @@
+const fs = require("node:fs/promises");
+const { constants } = require("node:fs");
+
+const { readJsonStrict } = require("./fs");
+
+async function buildDoctorReport({
+  runtime = {},
+  diagnostics = null,
+  fetch = globalThis.fetch,
+  now = () => new Date(),
+  paths = {},
+} = {}) {
+  const checks = [];
+
+  checks.push(...buildRuntimeChecks(runtime));
+
+  if (paths.trackerDir) {
+    checks.push(await checkTrackerDir(paths.trackerDir));
+  }
+  if (paths.configPath) {
+    checks.push(await checkConfigJson(paths.configPath));
+  }
+  if (paths.cliPath) {
+    checks.push(await checkCliEntrypoint(paths.cliPath));
+  }
+
+  checks.push(await checkNetwork({ baseUrl: runtime?.baseUrl || null, fetch }));
+
+  if (diagnostics) {
+    checks.push(...buildDiagnosticsChecks(diagnostics));
+  }
+
+  const summary = summarizeChecks(checks);
+
+  return {
+    version: 1,
+    generated_at: now().toISOString(),
+    ok: summary.critical === 0,
+    summary,
+    checks,
+    diagnostics,
+  };
+}
+
+function buildRuntimeChecks(runtime = {}) {
+  const checks = [];
+  const baseUrl =
+    typeof runtime.baseUrl === "string" && runtime.baseUrl.trim() ? runtime.baseUrl.trim() : null;
+  const deviceToken =
+    typeof runtime.deviceToken === "string" && runtime.deviceToken.trim() ? "set" : "unset";
+  const dashboardUrl =
+    typeof runtime.dashboardUrl === "string" && runtime.dashboardUrl.trim()
+      ? runtime.dashboardUrl.trim()
+      : null;
+  const httpTimeoutMs = Number.isFinite(Number(runtime.httpTimeoutMs))
+    ? Number(runtime.httpTimeoutMs)
+    : null;
+  const debug = Boolean(runtime.debug);
+  const autoRetryNoSpawn = Boolean(runtime.autoRetryNoSpawn);
+
+  checks.push({
+    id: "runtime.base_url",
+    status: baseUrl ? "ok" : "fail",
+    detail: baseUrl ? "base_url set" : "base_url missing",
+    critical: false,
+    meta: {
+      base_url: baseUrl,
+      source: runtime?.sources?.baseUrl || null,
+    },
+  });
+
+  checks.push({
+    id: "runtime.device_token",
+    status: deviceToken === "set" ? "ok" : "warn",
+    detail: deviceToken === "set" ? "device token set" : "device token missing",
+    critical: false,
+    meta: {
+      device_token: deviceToken,
+      source: runtime?.sources?.deviceToken || null,
+    },
+  });
+
+  checks.push({
+    id: "runtime.dashboard_url",
+    status: "ok",
+    detail: dashboardUrl ? "dashboard_url set" : "dashboard_url unset",
+    critical: false,
+    meta: {
+      dashboard_url: dashboardUrl,
+      source: runtime?.sources?.dashboardUrl || null,
+    },
+  });
+
+  checks.push({
+    id: "runtime.http_timeout_ms",
+    status: "ok",
+    detail: "http timeout resolved",
+    critical: false,
+    meta: {
+      http_timeout_ms: httpTimeoutMs,
+      source: runtime?.sources?.httpTimeoutMs || null,
+    },
+  });
+
+  checks.push({
+    id: "runtime.debug",
+    status: "ok",
+    detail: debug ? "debug enabled" : "debug disabled",
+    critical: false,
+    meta: {
+      debug,
+      source: runtime?.sources?.debug || null,
+    },
+  });
+
+  checks.push({
+    id: "runtime.auto_retry_no_spawn",
+    status: "ok",
+    detail: autoRetryNoSpawn ? "auto retry spawn disabled" : "auto retry spawn enabled",
+    critical: false,
+    meta: {
+      auto_retry_no_spawn: autoRetryNoSpawn,
+      source: runtime?.sources?.autoRetryNoSpawn || null,
+    },
+  });
+
+  return checks;
+}
+
+async function checkTrackerDir(trackerDir) {
+  try {
+    const st = await fs.stat(trackerDir);
+    if (!st.isDirectory()) {
+      return {
+        id: "fs.tracker_dir",
+        status: "fail",
+        detail: "tracker dir is not a directory",
+        critical: true,
+        meta: { path: trackerDir },
+      };
+    }
+    await fs.access(trackerDir, constants.R_OK);
+    return {
+      id: "fs.tracker_dir",
+      status: "ok",
+      detail: "tracker dir readable",
+      critical: false,
+      meta: { path: trackerDir },
+    };
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      return {
+        id: "fs.tracker_dir",
+        status: "warn",
+        detail: "tracker dir missing",
+        critical: false,
+        meta: { path: trackerDir },
+      };
+    }
+    if (err && (err.code === "EACCES" || err.code === "EPERM")) {
+      return {
+        id: "fs.tracker_dir",
+        status: "fail",
+        detail: "tracker dir permission denied",
+        critical: true,
+        meta: { path: trackerDir, code: err.code },
+      };
+    }
+    return {
+      id: "fs.tracker_dir",
+      status: "fail",
+      detail: "tracker dir error",
+      critical: true,
+      meta: { path: trackerDir, code: err?.code || "error" },
+    };
+  }
+}
+
+async function checkConfigJson(configPath) {
+  const res = await readJsonStrict(configPath);
+  if (res.status === "ok") {
+    return {
+      id: "fs.config_json",
+      status: "ok",
+      detail: "config.json readable",
+      critical: false,
+      meta: { path: configPath },
+    };
+  }
+  if (res.status === "missing") {
+    return {
+      id: "fs.config_json",
+      status: "warn",
+      detail: "config.json missing",
+      critical: false,
+      meta: { path: configPath },
+    };
+  }
+  if (res.status === "invalid") {
+    return {
+      id: "fs.config_json",
+      status: "fail",
+      detail: "config.json invalid",
+      critical: true,
+      meta: { path: configPath },
+    };
+  }
+  return {
+    id: "fs.config_json",
+    status: "fail",
+    detail: "config.json read error",
+    critical: true,
+    meta: { path: configPath },
+  };
+}
+
+async function checkCliEntrypoint(cliPath) {
+  try {
+    const st = await fs.stat(cliPath);
+    if (!st.isFile()) {
+      return {
+        id: "cli.entrypoint",
+        status: "fail",
+        detail: "cli entrypoint is not a file",
+        critical: false,
+        meta: { path: cliPath },
+      };
+    }
+    await fs.access(cliPath, constants.R_OK);
+    if (process.platform !== "win32") {
+      await fs.access(cliPath, constants.X_OK);
+    }
+    return {
+      id: "cli.entrypoint",
+      status: "ok",
+      detail: "cli entrypoint readable",
+      critical: false,
+      meta: { path: cliPath },
+    };
+  } catch (err) {
+    return {
+      id: "cli.entrypoint",
+      status: "fail",
+      detail: "cli entrypoint not accessible",
+      critical: false,
+      meta: { path: cliPath, code: err?.code || "error" },
+    };
+  }
+}
+
+async function checkNetwork({ baseUrl, fetch }) {
+  if (!baseUrl) {
+    return {
+      id: "network.base_url",
+      status: "warn",
+      detail: "base_url missing (skipped)",
+      critical: false,
+      meta: { base_url: null },
+    };
+  }
+
+  const start = Date.now();
+  try {
+    if (typeof fetch !== "function") throw new Error("Missing fetch");
+    const res = await fetch(baseUrl, { method: "GET" });
+    const latency = Date.now() - start;
+    return {
+      id: "network.base_url",
+      status: "ok",
+      detail: `HTTP ${res.status} (reachable)`,
+      critical: false,
+      meta: {
+        status_code: res.status,
+        latency_ms: latency,
+        base_url: baseUrl,
+      },
+    };
+  } catch (err) {
+    const latency = Date.now() - start;
+    return {
+      id: "network.base_url",
+      status: "fail",
+      detail: "Network error",
+      critical: false,
+      meta: {
+        error: err?.message || String(err),
+        latency_ms: latency,
+        base_url: baseUrl,
+      },
+    };
+  }
+}
+
+function buildDiagnosticsChecks(diagnostics) {
+  const checks = [];
+  const notify = diagnostics?.notify || {};
+  const notifyConfigured = Boolean(
+    notify.codex_notify_configured ||
+    notify.every_code_notify_configured ||
+    notify.claude_hook_configured ||
+    notify.gemini_hook_configured ||
+    notify.opencode_plugin_configured ||
+    notify.openclaw_hook_configured,
+  );
+
+  checks.push({
+    id: "notify.configured",
+    status: notifyConfigured ? "ok" : "warn",
+    detail: notifyConfigured ? "notify configured" : "notify not configured",
+    critical: false,
+    meta: { configured: notifyConfigured },
+  });
+
+  const uploadError = diagnostics?.upload?.last_error || null;
+  checks.push({
+    id: "upload.last_error",
+    status: uploadError ? "warn" : "ok",
+    detail: uploadError ? "last upload error present" : "no upload errors",
+    critical: false,
+    meta: { last_error: uploadError ? uploadError.message || null : null },
+  });
+
+  return checks;
+}
+
+function summarizeChecks(checks = []) {
+  const summary = { ok: 0, warn: 0, fail: 0, critical: 0 };
+  for (const check of checks) {
+    if (!check || typeof check.status !== "string") continue;
+    if (check.status === "ok") summary.ok += 1;
+    else if (check.status === "warn") summary.warn += 1;
+    else if (check.status === "fail") summary.fail += 1;
+    if (check.status === "fail" && check.critical) summary.critical += 1;
+  }
+  return summary;
+}
+
+module.exports = { buildDoctorReport };

package/src/lib/fs.js

@@ -0,0 +1,91 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+async function writeFileAtomic(filePath, content) {
+  const dir = path.dirname(filePath);
+  await ensureDir(dir);
+  const tmp = `${filePath}.tmp.${Date.now()}`;
+  await fs.writeFile(tmp, content, { encoding: "utf8" });
+  await fs.rename(tmp, filePath);
+}
+
+async function readJson(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (_e) {
+    return null;
+  }
+}
+
+async function readJsonStrict(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return { status: "ok", value: JSON.parse(raw), error: null };
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      return { status: "missing", value: null, error: err };
+    }
+    if (err && err.name === "SyntaxError") {
+      return { status: "invalid", value: null, error: err };
+    }
+    return { status: "error", value: null, error: err };
+  }
+}
+
+async function writeJson(filePath, obj) {
+  await writeFileAtomic(filePath, JSON.stringify(obj, null, 2) + "\n");
+}
+
+async function chmod600IfPossible(filePath) {
+  try {
+    await fs.chmod(filePath, 0o600);
+  } catch (_e) {}
+}
+
+const LOCK_STALE_MS = 5 * 60 * 1000; // 5 minutes
+
+async function openLock(lockPath, { quietIfLocked }) {
+  try {
+    const handle = await fs.open(lockPath, "wx");
+    return {
+      async release() {
+        await handle.close().catch(() => {});
+        await fs.unlink(lockPath).catch(() => {});
+      },
+    };
+  } catch (e) {
+    if (e && e.code === "EEXIST") {
+      // Check if lock is stale
+      try {
+        const stat = await fs.stat(lockPath);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+          await fs.unlink(lockPath).catch(() => {});
+          return openLock(lockPath, { quietIfLocked });
+        }
+      } catch (_statErr) {
+        // Lock file disappeared between checks, retry
+        return openLock(lockPath, { quietIfLocked });
+      }
+      if (!quietIfLocked) {
+        process.stdout.write("Another sync is already running.\n");
+      }
+      return null;
+    }
+    throw e;
+  }
+}
+
+module.exports = {
+  ensureDir,
+  writeFileAtomic,
+  readJson,
+  readJsonStrict,
+  writeJson,
+  chmod600IfPossible,
+  openLock,
+};