dsh-tower 2.0.4 → 2.1.0

package/lib/doctor.js

@@ -1,10 +1,17 @@
 // Read-only environment contract and health checks for a Tower repository.
-import { execFile } from 'node:child_process'
+import { execFile } from '../adapters/vcs-git.js'
 import { promisify } from 'node:util'
 import path from 'node:path'
-import fsp from 'node:fs/promises'
+import { fsp } from '../adapters/store-fs.js'
 import { git } from './git.js'
 import { readStateLock } from './store.js'
+import { inspectArchive } from './archive.js'
+import { inspectStateVersion } from '../domain/state.js'
+import { SCHEMA_VERSION } from '../domain/mission.js'
+import { DEFAULT_MAX_REPORT_BYTES, completionReportBytes } from '../domain/missions/completion.js'
+import { comparisonMode } from '../domain/scope.js'
+import { assessHostVersion, detectHostVersion, readCompatibility } from './compatibility.js'
+import { profileConfig } from './config.js'
 import { inspectWorkspaceLock } from './workspaceLock.js'
 
 const execFileAsync = promisify(execFile)
@@ -31,22 +38,186 @@ function check(id, status, detail, action) {
   return { id, status, detail, ...(action ? { action } : {}) }
 }
 
+/** Read the on-disk state version without loading, migrating, or locking. */
+async function inspectStateSchema(paths) {
+  try {
+    const text = await fsp.readFile(paths.state, 'utf8')
+    return inspectStateVersion(JSON.parse(text), paths.state)
+  } catch (error) {
+    return {
+      status: 'invalid',
+      currentVersion: null,
+      supportedVersion: SCHEMA_VERSION,
+      migrations: [],
+      message: `tower state could not be inspected: ${String(error?.message ?? error)}`,
+    }
+  }
+}
+
+/**
+ * Report the on-disk schema version and the migration that a write would apply.
+ * Doctor never migrates: a read-only call must leave the file byte-identical.
+ */
+function stateSchemaReport(info) {
+  const stateSchema = {
+    currentVersion: info.currentVersion,
+    supportedVersion: info.supportedVersion,
+    migrations: info.migrations ?? [],
+    status: info.status,
+  }
+  if (info.status === 'current') {
+    return {
+      stateSchema,
+      check: check('state-schema', 'pass', `schemaVersion ${info.currentVersion} is current`),
+    }
+  }
+  if (info.status === 'migratable') {
+    return {
+      stateSchema,
+      check: check(
+        'state-schema',
+        'warn',
+        `schemaVersion ${info.currentVersion} is older than ${info.supportedVersion}; the next locked write migrates it and keeps state.json.v${info.currentVersion}.bak`,
+        'a write tool applies the migration; a read-only tool only migrates in memory',
+      ),
+    }
+  }
+  if (info.status === 'newer') {
+    return {
+      stateSchema,
+      check: check(
+        'state-schema',
+        'fail',
+        `schemaVersion ${info.currentVersion} is newer than this build supports (${info.supportedVersion}); state was written by a newer dsh-tower`,
+        'upgrade dsh-tower; this build refuses to downgrade state.json',
+      ),
+    }
+  }
+  if (info.status === 'unmigratable') {
+    return {
+      stateSchema,
+      check: check(
+        'state-schema',
+        'fail',
+        `schemaVersion ${info.currentVersion} has no migration to ${info.supportedVersion}`,
+        'restore a state.json written by a supported dsh-tower; this build will not guess at an unknown schema',
+      ),
+    }
+  }
+  return {
+    stateSchema,
+    check: check(
+      'state-schema',
+      'fail',
+      info.message ?? 'state schemaVersion is unreadable',
+      'restore a state.json this build can read, or run tower_init for a new repository',
+    ),
+  }
+}
+
 /** Run every read-only diagnostic; never writes state or takes the state lock. */
-export async function runDoctor({ tower, ctx, agent }) {
+export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityFile, loaderRows }) {
   const checks = []
+  let reportsReport = null
   const version = await gitVersion()
   checks.push(version ? check('git', 'pass', version) : check('git', 'fail', 'git is not available', 'install Git and retry'))
 
+  const detectedHost = hostVersion ?? detectHostVersion(ctx)
+  const compatibilityRows = readCompatibility(compatibilityFile)
+  const hostAssessment = assessHostVersion(detectedHost, compatibilityRows)
+  checks.push(
+    check(
+      'host-version',
+      hostAssessment.verdict === 'verified' ? 'pass' : 'warn',
+      detectedHost
+        ? `${detectedHost}: ${hostAssessment.detail}`
+        : `unknown host version; ${hostAssessment.detail}. Include host version + COMPATIBILITY.md row in bug reports.`,
+      'see COMPATIBILITY.md for verified host builds',
+    ),
+  )
+
+  const rows = Array.isArray(loaderRows)
+    ? loaderRows
+    : (() => {
+        try {
+          const loader = ctx?.get?.('loader') ?? ctx?.loader
+          const source = loader?.entries ?? loader?.rows ?? loader?.store?.entries
+          if (Array.isArray(source)) return source
+          if (source && typeof source === 'object') return Object.values(source)
+        } catch {
+          // loader inventory is optional
+        }
+        return null
+      })()
+  if (rows === null) {
+    checks.push(check('loader-conflicts', 'warn', 'loader inventory unavailable; cannot detect co-installed Tower packages'))
+  } else {
+    const towerRows = rows.filter((row) => row && row.name === 'dsh-tower')
+    const foreign = towerRows.filter((row) => row.id !== 'tower')
+    checks.push(
+      towerRows.length > 1 || foreign.length > 0
+        ? check(
+            'loader-conflicts',
+            'fail',
+            `another loader row resolves to "dsh-tower" (${towerRows.map((row) => row.id ?? '?').join(', ')}); uninstall the conflicting dsh-plugins-tower row`,
+            'see README "Known conflicts"',
+          )
+        : check('loader-conflicts', 'pass', 'no conflicting dsh-tower loader rows'),
+    )
+  }
+
   checks.push(check('repository', 'pass', `${tower.root} (common ${tower.commonDir})`))
+  const schemaInfo = await inspectStateSchema(tower.paths)
   let state = null
   try {
     state = await tower.load()
     checks.push(check('state', 'pass', `${tower.paths.state} revision ${state.revision}`))
+    checks.push(
+      state.towerAgentId
+        ? check('tower-owner', 'pass', `bound to ${String(state.towerAgentId)}`)
+        : check('tower-owner', 'warn', 'state has no towerAgentId; write tools will fail closed', 'run tower_init with the restored session to re-claim ownership'),
+    )
   } catch (error) {
     checks.push(check('state', 'fail', String(error?.message ?? error), 'run tower_init or restore the state file'))
   }
+  const schemaReport = stateSchemaReport(schemaInfo)
+  checks.push(schemaReport.check)
+
+  // Scope matching is only as good as the detected filesystem mode (#90).
+  // Doctor never probes: a read-only call must not create files. A legacy state
+  // that has not been re-initialized therefore reports the safe exact default.
+  const caseInsensitive =
+    state && (state.caseInsensitive === true || state.caseInsensitive === false) ? state.caseInsensitive : null
+  const comparison = comparisonMode(caseInsensitive)
+  checks.push(
+    caseInsensitive === null
+      ? check(
+          'case-mode',
+          'warn',
+          `caseInsensitive: not detected; scope matching uses ${comparison} comparison`,
+          'run tower_init on a writable checkout to probe and record the filesystem mode',
+        )
+      : check(
+          'case-mode',
+          'pass',
+          `caseInsensitive: ${caseInsensitive}; scope matching uses ${comparison} comparison`,
+        ),
+  )
 
   const config = tower.config ?? {}
+  const profile = profileConfig()
+  const staleDefaults = []
+  if (profile.review && profile.review.requireReview === undefined) {
+    staleDefaults.push('review.requireReview now defaults to false (2.0.3)')
+  }
+  if (profile.mode && profile.mode.allowAgentControl === undefined) {
+    staleDefaults.push('mode.allowAgentControl now defaults to true (2.0.4)')
+  }
+  checks.push(
+    staleDefaults.length > 0
+      ? check('default-reversals', 'warn', staleDefaults.join('; '), 'pin the key explicitly in the profile if the old posture is required')
+      : check('default-reversals', 'pass', 'profile does not rely on a reversed default'),
+  )
   checks.push(
     check(
       'config',
@@ -98,7 +269,11 @@ export async function runDoctor({ tower, ctx, agent }) {
     }
 
     const live = (state.roster ?? []).filter((entry) => !['retired', 'failed', 'interrupted', 'missing', 'stale', 'inactive'].includes(entry.state))
-    checks.push(live.length > 0 ? check('roster', 'warn', `${live.length} live roster entr${live.length === 1 ? 'y' : 'ies'}`) : check('roster', 'pass', 'no live workers'))
+    checks.push(
+      live.length > 0
+        ? check('roster', 'pass', `${live.length} live roster entr${live.length === 1 ? 'y' : 'ies'}`)
+        : check('roster', 'pass', 'no live workers'),
+    )
 
     let missingWorktrees = 0
     let dirtyWorktrees = 0
@@ -140,6 +315,30 @@ export async function runDoctor({ tower, ctx, agent }) {
     )
     checks.push(check('legacy', 'pass', `${state.legacySnapshots?.length ?? 0} legacy snapshot(s)`))
     checks.push(check('batches', 'pass', `${state.batches?.length ?? 0} batch(es)`))
+
+    // Completion reports are the largest model-supplied strings in state.json;
+    // report the biggest one so growth is visible before it becomes a problem.
+    const reportSizes = (state.missions ?? [])
+      .map((mission) => ({ missionId: mission.id, bytes: completionReportBytes(mission.completionReport) }))
+      .filter((entry) => entry.bytes !== null)
+    const largestReport = reportSizes.reduce(
+      (best, entry) => (best === null || entry.bytes > best.bytes ? entry : best),
+      null,
+    )
+    const reportCap = Number(tower.config?.gates?.maxReportBytes) || DEFAULT_MAX_REPORT_BYTES
+    reportsReport = { count: reportSizes.length, largest: largestReport, capBytes: reportCap }
+    checks.push(
+      largestReport
+        ? check(
+            'reports',
+            largestReport.bytes > reportCap ? 'warn' : 'pass',
+            `${reportSizes.length} completion report(s); largest ${largestReport.bytes} B on ${largestReport.missionId} (cap ${reportCap} B)`,
+            largestReport.bytes > reportCap
+              ? 'existing reports predate the cap; reads are unchanged and no rewrite happens'
+              : undefined,
+          )
+        : check('reports', 'pass', `no completion reports (cap ${reportCap} B)`),
+    )
   }
 
   try {
@@ -158,19 +357,91 @@ export async function runDoctor({ tower, ctx, agent }) {
     )
   }
 
+  try {
+    const text = await fsp.readFile(path.join(tower.paths.dir, 'lock-holds.jsonl'), 'utf8')
+    const samples = text.split('\n').filter(Boolean).slice(-200).map((line) => JSON.parse(line).ms).filter((ms) => Number.isFinite(ms)).sort((a, b) => a - b)
+    if (samples.length === 0) {
+      checks.push(check('lock-holds', 'pass', 'no lock-hold samples yet'))
+    } else {
+      const p = (q) => samples[Math.min(samples.length - 1, Math.floor(q * samples.length))]
+      const p50 = p(0.5)
+      const p95 = p(0.95)
+      checks.push(
+        check(
+          'lock-holds',
+          p95 > 1000 ? 'warn' : 'pass',
+          `${samples.length} sample(s): p50 ${p50}ms, p95 ${p95}ms`,
+          p95 > 1000 ? 'a mutation is holding the state lock across slow work; inspect the activity/lock-holds log' : undefined,
+        ),
+      )
+    }
+  } catch {
+    checks.push(check('lock-holds', 'pass', 'no lock-hold samples yet'))
+  }
+
+  // Archive inventory (#73): size, count and the configured trigger policy.
+  // A missing directory is a healthy empty archive; a corrupt file is a warn.
+  const archiveInventory = await inspectArchive(tower.paths)
+  const stateBytes = await fsp.stat(tower.paths.state).then((stat) => stat.size).catch(() => null)
+  const archivePolicy = config.archive ?? {}
+  const policyText = `afterDays=${archivePolicy.afterDays ?? 30} maxMissions=${archivePolicy.maxMissions ?? 100}${archivePolicy.enabled === false ? ' disabled' : ''}`
+  if (!archiveInventory.exists) {
+    checks.push(check('archive', 'pass', `no archived missions; ${policyText}`))
+  } else if (archiveInventory.unreadable.length > 0) {
+    checks.push(
+      check(
+        'archive',
+        'warn',
+        `${archiveInventory.missions} archived mission(s), ${archiveInventory.bytes} bytes; unreadable: ${archiveInventory.unreadable[0]}`,
+        'inspect <git-common-dir>/dsh-tower/archive/ and repair or move the corrupt file; archiving is paused until it is readable',
+      ),
+    )
+  } else {
+    checks.push(
+      check(
+        'archive',
+        'pass',
+        `${archiveInventory.missions} archived mission(s) in ${archiveInventory.years.length} year file(s), ${archiveInventory.bytes} bytes; ${policyText}`,
+      ),
+    )
+  }
+
   const failed = checks.filter((item) => item.status === 'fail').length
   return {
     ok: failed === 0,
     checks,
+    stateSchema: schemaReport.stateSchema,
+// reports (from #89) and archive (from #73) are both kept
+    reports: reportsReport,
+    archive: {
+      missions: state ? state.missions.length : null,
+      archivedMissions: archiveInventory.missions,
+      stateBytes,
+      archiveBytes: archiveInventory.bytes,
+      dir: archiveInventory.dir,
+      years: archiveInventory.years,
+      files: archiveInventory.files.length,
+      unreadable: archiveInventory.unreadable,
+      policy: {
+        enabled: archivePolicy.enabled !== false,
+        afterDays: archivePolicy.afterDays ?? 30,
+        maxMissions: archivePolicy.maxMissions ?? 100,
+      },
+    },
     environmentContract: {
       platform: process.platform,
       gitVersion: version,
       repoRoot: tower.root,
       commonDir: tower.commonDir,
       stateDir: tower.paths.dir,
+      caseInsensitive,
+      comparisonMode: comparison,
       gitTimeoutMs: Number(tower.config.git?.timeoutMs) || 15000,
       mergeTimeoutMs: Number(tower.config.merge?.timeoutMs) || 900000,
       testsAdmission: tower.config.tests?.admission ?? 'off',
+      hostVersion: detectedHost,
+      hostCompatibility: hostAssessment.verdict,
+      hostCompatibilityDetail: hostAssessment.detail,
     },
     mode: agent ? 'ready' : 'unknown',
   }

package/lib/git.js

@@ -1,17 +1,26 @@
+import { TowerToolError } from '../domain/errors.js'
 // Minimal git port: array arguments only, bounded output, no shell.
-import { execFile } from 'node:child_process'
+import { execFile } from '../adapters/vcs-git.js'
 import path from 'node:path'
 
 const GIT_TIMEOUT_MS = 15000
 const MAX_BUFFER = 16 * 1024 * 1024
 let configuredTimeoutMs = GIT_TIMEOUT_MS
 
+/** @typedef {{ timeoutMs?: number, maxBuffer?: number }} GitOptions */
+/** @typedef {{ path: string, branch?: string, head?: string }} WorktreeEntry */
+
 /** Override the default Git timeout from resolved Tower config. */
 export function setGitTimeout(ms) {
   const value = Number(ms)
   if (Number.isFinite(value) && value >= 1000) configuredTimeoutMs = value
 }
 
+/** Process default retained for manual adapter use; Tower instances pass their own. */
+export function configuredGitTimeout() {
+  return configuredTimeoutMs
+}
+
 const BLOCKED_GIT_ENV = new Set([
   'GIT_DIR',
   'GIT_WORK_TREE',
@@ -29,8 +38,13 @@ const BLOCKED_GIT_ENV = new Set([
   'GIT_QUARANTINE_PATH',
 ])
 
-/** Git must not inherit a repository redirect from the DSH process environment. */
+/**
+ * Git must not inherit a repository redirect from the DSH process environment.
+ * @param {NodeJS.ProcessEnv} [source]
+ * @returns {NodeJS.ProcessEnv}
+ */
 export function gitEnv(source = process.env) {
+  /** @type {NodeJS.ProcessEnv} */
   const env = {}
   for (const [key, value] of Object.entries(source)) {
     if (BLOCKED_GIT_ENV.has(key)) continue
@@ -39,17 +53,16 @@ export function gitEnv(source = process.env) {
   return env
 }
 
-export class GitError extends Error {
-  constructor(args, detail, code, meta = {}) {
-    super(`git ${args.join(' ')} failed: ${detail}`)
-    this.name = 'GitError'
-    this.code = code
-    this.timedOut = meta.timedOut === true
-    this.bufferOverflow = meta.bufferOverflow === true
-    this.stdout = meta.stdout ?? ''
-  }
-}
+import { GitError } from '../domain/errors.js'
+export { GitError }
 
+/**
+ * Run one git command with bounded output and no shell.
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {GitOptions} [options]
+ * @returns {Promise<string>}
+ */
 export function git(cwd, args, options = {}) {
   return new Promise((resolve, reject) => {
     execFile(
@@ -82,6 +95,13 @@ export function git(cwd, args, options = {}) {
   })
 }
 
+/**
+ * Run git when its failure is not an error (existence probes).
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {GitOptions} [options]
+ * @returns {Promise<string | null>}
+ */
 export async function tryGit(cwd, args, options) {
   try {
     return await git(cwd, args, options)
@@ -93,17 +113,29 @@ export async function tryGit(cwd, args, options) {
 /**
  * Resolve an absolute caller path to the repository root, its common git dir
  * (shared by all worktrees), and the current branch of that checkout.
+ * @param {string} repoRoot
+ * @returns {Promise<{ root: string, commonDir: string, branch: string | null }>}
  */
 export async function resolveRepo(repoRoot) {
   if (typeof repoRoot !== 'string' || repoRoot.trim().length === 0) {
-    throw new Error('repoRoot is required')
+    throw new TowerToolError('repo-invalid', 'repoRoot is required')
   }
   if (!path.isAbsolute(repoRoot)) {
-    throw new Error(`repoRoot must be an absolute path: ${repoRoot}`)
+    throw new TowerToolError('repo-invalid', `repoRoot must be an absolute path: ${repoRoot}`)
+  }
+  let top
+  try {
+    top = await git(repoRoot, ['rev-parse', '--show-toplevel'])
+  } catch (error) {
+    throw new TowerToolError('repo-invalid', `not a git repository: ${repoRoot}`, { cause: error })
   }
-  const top = await git(repoRoot, ['rev-parse', '--show-toplevel'])
   const root = path.resolve(top)
-  const commonRaw = await git(root, ['rev-parse', '--git-common-dir'])
+  let commonRaw
+  try {
+    commonRaw = await git(root, ['rev-parse', '--git-common-dir'])
+  } catch (error) {
+    throw new TowerToolError('repo-invalid', `not a git repository: ${root}`, { cause: error })
+  }
   const commonDir = path.isAbsolute(commonRaw)
     ? path.resolve(commonRaw)
     : path.resolve(root, commonRaw)
@@ -115,25 +147,30 @@ export async function resolveRepo(repoRoot) {
   }
 }
 
+/** @param {string} root @returns {Promise<boolean>} */
 export async function hasAnyCommit(root) {
   const out = await tryGit(root, ['rev-list', '-n', '1', '--all'])
   return Boolean(out && out.trim())
 }
 
+/** @param {string} root @param {string} branch @returns {Promise<boolean>} */
 export async function localBranchExists(root, branch) {
   const out = await tryGit(root, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`])
   return out !== null
 }
 
+/** @param {string} cwd @param {string} ref @returns {Promise<string>} */
 export async function revParse(cwd, ref) {
   const out = await git(cwd, ['rev-parse', ref])
   return out.trim()
 }
 
+/** @param {string} cwd @param {string} branch @returns {Promise<boolean>} */
 export async function branchExists(cwd, branch) {
   return (await localBranchExists(cwd, branch)) === true
 }
 
+/** @param {string} cwd @returns {Promise<string | null>} */
 export async function currentBranch(cwd) {
   const out = await tryGit(cwd, ['symbolic-ref', '--short', '-q', 'HEAD'])
   return out && out.trim() ? out.trim() : null
@@ -144,9 +181,12 @@ export async function addWorktree(cwd, { path: worktreePath, branch, commit }) {
   return worktreePath
 }
 
+/** @param {string} cwd @returns {Promise<WorktreeEntry[]>} */
 export async function listWorktrees(cwd) {
   const out = await git(cwd, ['worktree', 'list', '--porcelain'])
+  /** @type {WorktreeEntry[]} */
   const entries = []
+  /** @type {WorktreeEntry | null} */
   let current = null
   for (const line of out.split('\n')) {
     if (line.startsWith('worktree ')) {
@@ -162,22 +202,26 @@ export async function listWorktrees(cwd) {
   return entries
 }
 
+/** @param {string} cwd @returns {Promise<boolean>} */
 export async function isClean(cwd) {
   const out = await git(cwd, ['status', '--porcelain'])
   return out.trim().length === 0
 }
 
+/** @param {string} cwd @returns {Promise<string | null>} */
 export async function currentCommonDir(cwd) {
   const raw = await tryGit(cwd, ['rev-parse', '--git-common-dir'])
   if (raw === null) return null
   return path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(cwd, raw)
 }
 
+/** @param {string} cwd @param {string} fromRef @returns {Promise<number>} */
 export async function countCommits(cwd, fromRef) {
   const out = await git(cwd, ['rev-list', '--count', `${fromRef}..HEAD`])
   return Number(out.trim() || 0)
 }
 
+/** @param {string} cwd @param {string} ancestor @param {string} descendant @returns {Promise<boolean>} */
 export async function isAncestor(cwd, ancestor, descendant) {
   const out = await tryGit(cwd, ['merge-base', '--is-ancestor', ancestor, descendant])
   return out !== null

package/lib/hmr.js

@@ -18,10 +18,11 @@
 //   `restartReason` means the whole process must be restarted.
 // - `runExclusive` rejects nested transactions; a tool call is never inside
 //   one, so a tool-triggered reload is safe.
-import { TowerToolError } from './errors.js'
+import { TowerToolError } from '../domain/errors.js'
 
 /** Entry ids Tower expects to be active after a reconciliation. */
 export const DEFAULT_REQUIRED_IDS = Object.freeze([
+  'tower-bundle',
   'tower',
   'tower-skills',
   'preset-tower-worker',
@@ -94,7 +95,7 @@ function warn(logger, message) {
  * @param {string[]} [options.requiredIds] Entry ids whose inactivity is reported as a failure.
  * @param {number} [options.delayMs] Delay before a scheduled reload runs.
  * @param {{ warn?: Function }} [options.logger] Optional logger for failed scheduled reloads.
- * @returns {{ available: boolean, requiredIds: string[], delayMs: number, status: Function, schedule: Function, runNow: Function }}
+ * @returns {{ available: boolean, requiredIds: string[], delayMs: number, status: Function, schedule: Function, runNow: Function, dispose: Function }}
  */
 export function createHmrBridge(ctx, options = {}) {
   const requiredIds = Object.freeze(normalizeRequiredIds(options.requiredIds))
@@ -186,7 +187,7 @@ export function createHmrBridge(ctx, options = {}) {
     get available() {
       return available()
     },
-    requiredIds,
+    requiredIds: [...requiredIds],
     delayMs,
     status,
     schedule,

package/lib/leases.js

@@ -11,7 +11,7 @@
 // Fail-closed protocol: a held, expired, or token-mismatched lease is reported,
 // never silently taken over. Only the token holder may release a lease, and
 // releasing an expired lease requires an explicit `force: true`.
-import fsp from 'node:fs/promises'
+import { fsp } from '../adapters/store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'
 
@@ -27,7 +27,13 @@ const LOCK_STALE_MS = 10000
 const LOCK_POLL_MS = 20
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
 
+// Exported with the retry loop so a test can assert the budget and the exact
+// transient set instead of copying them (#86).
+export const UNLINK_ATTEMPTS = 12
+export const TRANSIENT_UNLINK_ERRORS = new Set(['EPERM', 'EBUSY', 'EACCES'])
+
 function fail(code, message) {
+  /** @type {Error & {code?: string}} */
   const error = new Error(message)
   error.code = code
   throw error
@@ -56,17 +62,21 @@ export function leasesLockPath(commonDir) {
 /**
  * Windows can reject unlink while an indexer, antivirus, or a concurrent
  * reader still holds the file; retry briefly instead of failing the mutation.
+ *
+ * `options.unlink` and `options.sleep` inject the syscall and the backoff so
+ * both outcomes are testable on any OS (#86); production callers omit them.
  */
-async function unlinkWithRetry(file) {
+export async function unlinkWithRetry(file, options = {}) {
+  const unlink = options.unlink ?? fsp.unlink
+  const wait = options.sleep ?? sleep
   for (let attempt = 0; ; attempt += 1) {
     try {
-      await fsp.unlink(file)
+      await unlink(file)
       return true
     } catch (error) {
       if (error?.code === 'ENOENT') return false
-      const transient = error?.code === 'EPERM' || error?.code === 'EBUSY' || error?.code === 'EACCES'
-      if (!transient || attempt >= 12) throw error
-      await sleep(10 + attempt * 15)
+      if (!TRANSIENT_UNLINK_ERRORS.has(error?.code) || attempt >= UNLINK_ATTEMPTS) throw error
+      await wait(10 + attempt * 15)
     }
   }
 }
@@ -147,7 +157,7 @@ async function lockIsStale(lockFile) {
   } catch {
     at = null
   }
-  const age = Number.isFinite(at) ? Date.now() - at : Date.now() - stat.mtimeMs
+  const age = at !== null && Number.isFinite(at) ? Date.now() - at : Date.now() - stat.mtimeMs
   return age > LOCK_STALE_MS
 }