@1aboveio/skills 1.0.18 → 1.0.19

package/skills/engineering/resolve-issues/scripts/retention-lock.mjs

@@ -0,0 +1,548 @@
+// Interrupted-retention lock for <root>/.retention-lock.
+//
+// A retention apply holds this lock while it snapshots, quarantines, receipts, and
+// removes registered resources. A process killed mid-apply leaves the lock behind, and
+// the lock is never reclaimed by age, so without a recovery path the next daily refuses
+// forever. This module is the whole lock contract:
+//
+//   acquireRetentionLock(root[, options])   -> { root, path, owner, release() }
+//   inspectRetentionLock(root)              -> read-only report; mutates nothing
+//   recoverRetentionLock(root, { apply })   -> clears only a proven-dead local owner
+//
+// `root` is the directory that holds the lock; retention calls it `.resolve-issues`.
+// acquire's options are the recorded identity: `pid` (default this process) and
+// `hostname` (default os.hostname()). acquire fails with code 'locked' when any lock
+// exists, including a provably dead one, so clearing is always an explicit decision.
+//
+// The owner record is a strong schema: format, nonce, pid, hostname, startIdentity and
+// acquiredAt. Recovery requires all of it and a positive answer to one question: is the
+// recorded owner provably dead? That means the hostname is this host and either the pid
+// is gone (kill(pid, 0) => ESRCH) or the pid is alive with a start identity that differs
+// from the recorded one, which proves the pid was reused by a later process. Every other
+// answer is retained and reported, never guessed at: a legacy {pid, at} record (no host,
+// nonce or identity), another host, an empty unreadable or unexpected lock, a symlink or
+// hardlink, a pid that is not a positive integer (never probed), a pid that cannot be
+// probed (EPERM), and a live pid whose start identity cannot be read or was not recorded.
+// Age and idle time are not inputs, so an old lock with an unprovable owner stays.
+//
+// Clearing is atomic and identity-checked: the live lock directory is renamed inside the
+// same parent to `.retention-lock.tombstone-<owner nonce>`, the tombstone is proven to be
+// the same directory (device and inode) with the same owner nonce, and only then are the
+// owner file and the empty tombstone removed. A crash between those steps leaves a
+// tombstone, which is litter rather than a lock, and the next recover finishes it under
+// the same proof. Nothing outside the lock directory is ever touched: receipts,
+// quarantined resources and the cleanup outcome are only observed, so clearing the lock
+// is not a claim that an interrupted apply finished.
+
+import { randomBytes } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import {
+  lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmdirSync,
+  unlinkSync, writeFileSync,
+} from 'node:fs'
+import { hostname as osHostname } from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+export const LOCK_NAME = '.retention-lock'
+export const OWNER_FILE = 'owner.json'
+export const LOCK_FORMAT = 'retention-lock/2'
+export const TOMBSTONE_PREFIX = `${LOCK_NAME}.tombstone-`
+
+const TOMBSTONE_PATTERN = new RegExp(`^${TOMBSTONE_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([0-9a-f]{32})$`)
+const QUARANTINE_PREFIX = '.retention-quarantine-'
+const NONCE_PATTERN = /^[0-9a-f]{32}$/
+const MAX_OWNER_BYTES = 8 * 1024
+const PS_CANDIDATES = ['/bin/ps', '/usr/bin/ps']
+const PROC_BOOT_ID = '/proc/sys/kernel/random/boot_id'
+
+export class RetentionLockError extends Error {
+  constructor(code, message, inspection = null) {
+    super(message)
+    this.name = 'RetentionLockError'
+    this.code = code
+    this.inspection = inspection
+  }
+}
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const lstatOrNull = (path) => {
+  try { return lstatSync(path) } catch (error) { if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null; throw error }
+}
+const boundedText = (value, limit) => (typeof value === 'string' ? value.slice(0, limit) : null)
+const normalizeHost = (value) => (nonEmpty(value) ? value.trim().toLowerCase() : '')
+
+// A root that does not exist has no lock; a root that exists must be a real directory.
+function readRoot(root) {
+  if (!isAbsolute(root ?? '')) throw new RetentionLockError('usage', 'root must be an absolute directory path')
+  let real
+  try {
+    real = realpathSync(root)
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return { root: resolve(root), missing: true }
+    throw new RetentionLockError('root', `cannot resolve ${root}: ${error?.code ?? error?.message}`)
+  }
+  const st = lstatOrNull(real)
+  if (!st || !st.isDirectory()) throw new RetentionLockError('root', `${real} is not a directory`)
+  return { root: real, missing: false }
+}
+
+function mustExistRoot(root) {
+  const read = readRoot(root)
+  if (read.missing) throw new RetentionLockError('root', `canonical root ${read.root} does not exist`)
+  return read.root
+}
+
+// ---- owner identity ----
+
+function readStartIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return null
+  try {
+    if (process.platform === 'linux') {
+      const bootId = readFileSync(PROC_BOOT_ID, 'utf8').trim()
+      if (!bootId) return null
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+      const end = stat.lastIndexOf(')')
+      if (end < 1) return null
+      // Field 22 (starttime) is stable for the life of a process; only that field is read.
+      const started = stat.slice(end + 2).trim().split(' ')[19]
+      if (!started || !/^\d+$/.test(started)) return null
+      return `linux:${bootId}:${started}`
+    }
+    if (process.platform === 'darwin' || process.platform === 'freebsd') {
+      const binary = PS_CANDIDATES.find((candidate) => lstatOrNull(candidate)?.isFile())
+      if (!binary) return null
+      // One pid, start time only: no process listing, no argument or environment text.
+      const out = execFileSync(binary, ['-o', 'lstart=', '-p', String(pid)], {
+        encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
+      })
+      const started = out.replace(/\s+/g, ' ').trim()
+      return started ? `ps-lstart:${started}` : null
+    }
+  } catch { /* an unreadable identity is unknown, and unknown never authorizes a removal */ }
+  return null
+}
+
+// kill(pid, 0) is the only liveness probe used: it signals nothing, and only ESRCH proves
+// death. EPERM (or any other error) means the process may exist, so it is unknown.
+function probeLiveness(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return 'unknown'
+  try {
+    process.kill(pid, 0)
+    return 'alive'
+  } catch (error) {
+    return error?.code === 'ESRCH' ? 'gone' : 'unknown'
+  }
+}
+
+function echoOwner(record) {
+  if (!isObject(record)) return null
+  if (record.format === undefined && record.nonce === undefined && record.hostname === undefined) {
+    return {
+      legacy: true,
+      pid: Number.isSafeInteger(record.pid) ? record.pid : null,
+      at: boundedText(record.at, 64),
+    }
+  }
+  return {
+    legacy: false,
+    format: boundedText(record.format, 64),
+    nonce: boundedText(record.nonce, 64),
+    pid: Number.isSafeInteger(record.pid) ? record.pid : null,
+    hostname: boundedText(record.hostname, 255),
+    startIdentity: boundedText(record.startIdentity, 255),
+    acquiredAt: boundedText(record.acquiredAt, 64),
+  }
+}
+
+function validateOwner(record) {
+  if (record.format !== LOCK_FORMAT) {
+    const legacy = record.nonce === undefined && record.hostname === undefined && record.startIdentity === undefined
+    return legacy
+      ? { ok: false, reason: 'owner-record-legacy', detail: 'the lock was written by an older retention build as {pid, at}; it carries no host, nonce or process identity, so the owner cannot be proven dead. Inspect and remove it by hand' }
+      : { ok: false, reason: 'owner-record-unsupported', detail: `the owner record format is not ${LOCK_FORMAT}` }
+  }
+  if (!nonEmpty(record.nonce) || !NONCE_PATTERN.test(record.nonce)) {
+    return { ok: false, reason: 'owner-record-invalid', detail: 'the owner nonce is missing or malformed' }
+  }
+  if (!Number.isSafeInteger(record.pid) || record.pid < 1) {
+    return { ok: false, reason: 'owner-pid-invalid', detail: 'the owner pid is missing or is not a positive safe integer, so it was not probed' }
+  }
+  if (!nonEmpty(record.hostname)) {
+    return { ok: false, reason: 'owner-record-invalid', detail: 'the owner hostname is missing' }
+  }
+  return { ok: true }
+}
+
+function verdict(verdictName, reason, detail, owner = null) {
+  return {
+    present: true,
+    verdict: verdictName,
+    recoverable: verdictName === 'dead',
+    reason,
+    detail,
+    owner,
+  }
+}
+
+// ---- inspection ----
+
+function inspectDirAt(dirPath, { name }) {
+  const st = lstatOrNull(dirPath)
+  if (!st) {
+    return { name, path: dirPath, result: { present: false, verdict: 'absent', recoverable: false, reason: 'no-lock', detail: `${dirPath} does not exist`, owner: null }, dirIdentity: null, nonce: null }
+  }
+  const dirIdentity = { dev: st.dev, ino: st.ino }
+  const describe = (result) => ({ name, path: dirPath, result: { name, ...result }, dirIdentity, nonce: result.owner?.legacy === false ? result.owner.nonce : null })
+  if (st.isSymbolicLink()) return describe(verdict('unknown', 'lock-is-symlink', `${dirPath} is a symbolic link; it is not followed`))
+  if (!st.isDirectory()) return describe(verdict('unknown', 'lock-not-a-directory', `${dirPath} exists but is not a directory`))
+  let names
+  try { names = readdirSync(dirPath) } catch (error) {
+    return describe(verdict('unknown', 'lock-unreadable', `${dirPath} cannot be listed: ${error?.code ?? error?.message}`))
+  }
+  if (names.length === 0) {
+    return describe(verdict('unknown', 'owner-record-missing', `${dirPath} is empty; no owner can be proven`))
+  }
+  if (names.some((entry) => entry !== OWNER_FILE)) {
+    return describe(verdict('unknown', 'lock-unexpected-contents', `${dirPath} holds entries besides ${OWNER_FILE}, so its contents are not known to be disposable`))
+  }
+  const ownerPath = join(dirPath, OWNER_FILE)
+  const ownerStat = lstatOrNull(ownerPath)
+  if (!ownerStat) {
+    return describe(verdict('unknown', 'owner-record-missing', `${ownerPath} does not exist; the lock directory is the lock`))
+  }
+  if (ownerStat.isSymbolicLink() || !ownerStat.isFile()) {
+    return describe(verdict('unknown', 'owner-file-unsafe', `${ownerPath} is not a regular file; it is not read through`))
+  }
+  if (ownerStat.nlink > 1) {
+    return describe(verdict('unknown', 'owner-file-hardlinked', `${ownerPath} has ${ownerStat.nlink} links, so it is not known to be solely the lock's`))
+  }
+  if (ownerStat.size > MAX_OWNER_BYTES) {
+    return describe(verdict('unknown', 'owner-record-unreadable', `${ownerPath} is larger than ${MAX_OWNER_BYTES} bytes`))
+  }
+  let record
+  try { record = JSON.parse(readFileSync(ownerPath, 'utf8')) } catch (error) {
+    return describe(verdict('unknown', 'owner-record-unreadable', `${ownerPath} cannot be read as JSON: ${error?.code ?? error?.message}`))
+  }
+  if (!isObject(record)) {
+    return describe(verdict('unknown', 'owner-record-unreadable', `${ownerPath} does not hold an owner object`))
+  }
+  const owner = echoOwner(record)
+  const schema = validateOwner(record)
+  if (!schema.ok) return describe(verdict('unknown', schema.reason, schema.detail, owner))
+  if (normalizeHost(record.hostname) !== normalizeHost(osHostname())) {
+    return describe(verdict('unknown', 'owner-other-host', `the owner was recorded on ${owner.hostname}, not on this host; local liveness says nothing about it`, owner))
+  }
+  if (record.pid === process.pid) {
+    // This process is the one the record names, unless its own start identity proves the
+    // record belongs to an earlier process that held the same pid.
+    const selfIdentity = readStartIdentity(process.pid)
+    if (nonEmpty(record.startIdentity) && nonEmpty(selfIdentity) && record.startIdentity !== selfIdentity) {
+      return describe(verdict('dead', 'owner-pid-reused', `owner pid ${record.pid} is this process, which started later than the recorded owner`, owner))
+    }
+    return describe(verdict('live', 'owner-process-alive', `pid ${record.pid} is this process, which holds the lock`, owner))
+  }
+  const liveness = probeLiveness(record.pid)
+  if (liveness === 'gone') {
+    return describe(verdict('dead', 'owner-process-gone', `owner pid ${record.pid} is not running on this host`, owner))
+  }
+  if (liveness === 'unknown') {
+    return describe(verdict('unknown', 'owner-process-unverifiable', `owner pid ${record.pid} exists but cannot be probed, so it may be alive`, owner))
+  }
+  if (!nonEmpty(record.startIdentity)) {
+    return describe(verdict('unknown', 'owner-identity-unrecorded', `owner pid ${record.pid} is alive and the record has no start identity, so a reused pid cannot be excluded`, owner))
+  }
+  const current = readStartIdentity(record.pid)
+  if (!nonEmpty(current)) {
+    return describe(verdict('unknown', 'owner-process-identity-unavailable', `owner pid ${record.pid} is alive and its start identity cannot be read on this host`, owner))
+  }
+  if (current !== record.startIdentity) {
+    return describe(verdict('dead', 'owner-pid-reused', `owner pid ${record.pid} is alive but belongs to a process that started later than the recorded owner`, owner))
+  }
+  return describe(verdict('live', 'owner-process-alive', `the recorded owner is the process now running as pid ${record.pid}`, owner))
+}
+
+function scanTombstones(root) {
+  let entries
+  try { entries = readdirSync(root, { withFileTypes: true }) } catch { return [] }
+  const found = []
+  for (const entry of entries) {
+    const match = TOMBSTONE_PATTERN.exec(entry.name)
+    if (!match) continue
+    const path = join(root, entry.name)
+    const inspected = inspectDirAt(path, { name: entry.name })
+    const expectedNonce = match[1]
+    const result = inspected.result.owner?.legacy === false && inspected.result.owner.nonce !== expectedNonce
+      ? { ...inspected.result, verdict: 'unknown', recoverable: false, reason: 'tombstone-name-mismatch', detail: `the tombstone name carries nonce ${expectedNonce} but its owner record carries another` }
+      : inspected.result
+    found.push({ ...inspected, result })
+  }
+  return found.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+function listQuarantines(root) {
+  try {
+    return readdirSync(root).filter((entry) => entry.startsWith(QUARANTINE_PREFIX)).sort()
+  } catch { return [] }
+}
+
+export function inspectRetentionLock(root) {
+  const read = readRoot(root)
+  const lockPath = join(read.root, LOCK_NAME)
+  if (read.missing) {
+    return {
+      version: 1,
+      root: read.root,
+      lockPath,
+      present: false,
+      verdict: 'absent',
+      recoverable: false,
+      reason: 'root-missing',
+      detail: `${read.root} does not exist, so no retention lock can be held`,
+      owner: null,
+      tombstones: [],
+      quarantines: [],
+    }
+  }
+  const lock = inspectDirAt(lockPath, { name: LOCK_NAME })
+  return {
+    version: 1,
+    root: read.root,
+    lockPath,
+    ...lock.result,
+    tombstones: scanTombstones(read.root).map((tombstone) => tombstone.result),
+    quarantines: listQuarantines(read.root),
+  }
+}
+
+// ---- removal ----
+
+function removeVerifiedDir(dirPath, dirIdentity, expectedNonce) {
+  const st = lstatOrNull(dirPath)
+  if (!st) return { cleared: false, reason: 'lock-vanished' }
+  if (st.isSymbolicLink() || !st.isDirectory() || st.dev !== dirIdentity.dev || st.ino !== dirIdentity.ino) {
+    return { cleared: false, reason: 'identity-changed' }
+  }
+  let names
+  try { names = readdirSync(dirPath) } catch { return { cleared: false, reason: 'lock-unreadable' } }
+  if (names.length !== 1 || names[0] !== OWNER_FILE) {
+    return { cleared: false, reason: 'lock-unexpected-contents' }
+  }
+  const ownerPath = join(dirPath, OWNER_FILE)
+  const ownerStat = lstatOrNull(ownerPath)
+  if (!ownerStat || ownerStat.isSymbolicLink() || !ownerStat.isFile() || ownerStat.nlink > 1) {
+    return { cleared: false, reason: 'identity-changed' }
+  }
+  let record
+  try { record = JSON.parse(readFileSync(ownerPath, 'utf8')) } catch { return { cleared: false, reason: 'identity-changed' } }
+  if (!isObject(record) || record.nonce !== expectedNonce) {
+    return { cleared: false, reason: 'identity-changed' }
+  }
+  try { unlinkSync(ownerPath) } catch (error) {
+    return { cleared: false, reason: 'unlink-failed', detail: error?.code ?? error?.message }
+  }
+  try { rmdirSync(dirPath) } catch (error) {
+    return { cleared: false, reason: 'rmdir-failed', detail: error?.code ?? error?.message }
+  }
+  return { cleared: true }
+}
+
+// The verified removal only unlinks, so a directory that turns out not to be the inspected
+// one is put back at the lock path while that path is still free. A live owner that
+// replaced the lock inside the rename window therefore keeps its lock instead of losing it.
+const RESTORABLE = new Set(['identity-changed', 'lock-unexpected-contents', 'lock-unreadable', 'unlink-failed'])
+function restoreQuarantine(tombstonePath, lockPath) {
+  if (lstatOrNull(lockPath)) return false
+  try {
+    renameSync(tombstonePath, lockPath)
+    return true
+  } catch { return false }
+}
+
+// Atomic quarantine: rename inside the same parent, prove the renamed directory is the
+// inspected one with the same owner nonce, and only then unlink. A failure leaves a
+// tombstone behind, which never blocks a new lock and is finished by the next recover.
+function quarantineAndRemove(lockPath, dirIdentity, nonce) {
+  const tombstonePath = join(dirname(lockPath), `${TOMBSTONE_PREFIX}${nonce}`)
+  try {
+    renameSync(lockPath, tombstonePath)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { cleared: false, reason: 'lock-vanished' }
+    if (error?.code === 'ENOTEMPTY' || error?.code === 'EEXIST') return { cleared: false, reason: 'tombstone-exists' }
+    return { cleared: false, reason: 'rename-failed', detail: error?.code ?? error?.message }
+  }
+  const removed = removeVerifiedDir(tombstonePath, dirIdentity, nonce)
+  if (!removed.cleared && RESTORABLE.has(removed.reason) && restoreQuarantine(tombstonePath, lockPath)) {
+    return { cleared: false, reason: 'identity-changed', detail: 'the lock changed while recovery ran; it was restored to the lock path' }
+  }
+  return { ...removed, tombstonePath }
+}
+
+export function recoverRetentionLock(root, options = {}) {
+  const apply = options?.apply === true
+  const before = inspectRetentionLock(root)
+  const base = {
+    version: 1,
+    root: before.root,
+    lockPath: before.lockPath,
+    apply,
+    dryRun: !apply,
+    before,
+    cleared: { lock: false, tombstones: [] },
+    remaining: { lock: false, tombstones: [] },
+    failures: [],
+    quarantines: before.quarantines,
+  }
+  const tombstoneRoot = before.root
+  const tombstones = before.tombstones.map((entry) => ({ ...entry, path: join(tombstoneRoot, entry.name) }))
+  const clearableTombstones = tombstones.filter((entry) => entry.recoverable)
+  const blockers = tombstones.filter((entry) => !entry.recoverable)
+  let contended = false
+
+  // A tombstone is only a quarantined lock directory. The sweep needs the same proof as
+  // the lock itself, so an unprovable tombstone is reported and left alone.
+  if (apply) {
+    for (const entry of clearableTombstones) {
+      const inspected = inspectDirAt(entry.path, { name: entry.name })
+      const outcome = removeVerifiedDir(entry.path, inspected.dirIdentity, inspected.nonce)
+      if (outcome.cleared) base.cleared.tombstones.push(entry.name)
+      else if (outcome.reason === 'lock-vanished') continue
+      else if (outcome.reason === 'identity-changed') contended = true
+      else base.failures.push({ name: entry.name, reason: outcome.reason, detail: outcome.detail ?? null })
+    }
+  }
+  base.remaining.tombstones = tombstones
+    .filter((entry) => !base.cleared.tombstones.includes(entry.name))
+    .map((entry) => entry.name)
+
+  // The mutation re-inspects immediately before it acts, so a lock replaced by a live
+  // owner between the first report and the rename is retained rather than broken.
+  let outcome = null
+  if (before.present && before.recoverable && apply) {
+    const fresh = inspectDirAt(before.lockPath, { name: LOCK_NAME })
+    if (!fresh.result.present) {
+      outcome = { cleared: false, reason: 'lock-vanished' }
+    } else if (!fresh.result.recoverable) {
+      contended = true
+      outcome = { cleared: false, reason: fresh.result.reason, detail: fresh.result.detail }
+    } else {
+      outcome = quarantineAndRemove(before.lockPath, fresh.dirIdentity, fresh.nonce)
+      if (!outcome.cleared && outcome.reason !== 'lock-vanished') {
+        if (outcome.reason === 'identity-changed' || outcome.reason === 'tombstone-exists') contended = true
+        else base.failures.push({ name: LOCK_NAME, reason: outcome.reason, detail: outcome.detail ?? null })
+      }
+    }
+  }
+  base.cleared.lock = outcome?.cleared === true
+  base.remaining.lock = before.present && !base.cleared.lock && outcome?.reason !== 'lock-vanished'
+
+  const lockStillPresent = before.present && outcome?.reason !== 'lock-vanished'
+  const lockBlocked = lockStillPresent && !before.recoverable
+  const stillRecoverable = (lockStillPresent && before.recoverable && !base.cleared.lock)
+    || tombstones.some((entry) => entry.recoverable && !base.cleared.tombstones.includes(entry.name))
+  const anythingBlocked = lockBlocked || blockers.length > 0
+
+  const status = base.failures.length > 0 ? 'failed'
+    : contended ? 'contended'
+      : base.cleared.lock || base.cleared.tombstones.length > 0 ? 'recovered'
+        : stillRecoverable ? 'recoverable'
+          : anythingBlocked ? 'retained'
+            : 'absent'
+  const action = base.cleared.lock ? 'cleared-lock'
+    : base.cleared.tombstones.length > 0 ? 'cleared-tombstone'
+      : stillRecoverable ? 'would-clear'
+        : 'none'
+
+  const primary = before.present ? before : (clearableTombstones[0] ?? blockers[0] ?? null)
+  const reason = outcome?.cleared === false ? base.failures[0]?.reason ?? outcome.reason : primary?.reason ?? 'no-lock'
+  let detail = primary?.detail ?? `${before.lockPath} does not exist`
+  if (base.cleared.lock) detail = `cleared the lock left by a dead owner (${before.detail})`
+  else if (base.cleared.tombstones.length > 0) detail = `cleared ${base.cleared.tombstones.length} tombstone(s) left by an interrupted recovery`
+  else if (contended) detail = 'the lock now has an owner that is not provably dead; nothing was removed'
+  else if (status === 'retained') detail = `${detail}; it is retained and nothing was changed`
+  else if (status === 'recoverable') detail = `${detail}; the owner is provably dead and recover would clear it`
+  else if (status === 'failed') detail = base.failures.map((failure) => `${failure.name}: ${failure.reason}`).join('; ')
+
+  const after = apply ? inspectRetentionLock(before.root) : null
+  return {
+    ...base,
+    status,
+    action,
+    reason,
+    detail,
+    tombstones,
+    after,
+    note: 'clearing the lock changes no cleanup state: receipts, quarantined resources, and the outcome of an interrupted apply are left exactly as they were',
+  }
+}
+
+// ---- acquire / release ----
+
+function releaseOwnLock(lockPath, nonce) {
+  const st = lstatOrNull(lockPath)
+  if (!st) return { released: false, reason: 'lock-missing' }
+  if (st.isSymbolicLink() || !st.isDirectory()) return { released: false, reason: 'lock-changed' }
+  let names
+  try { names = readdirSync(lockPath) } catch { return { released: false, reason: 'lock-unreadable' } }
+  if (names.length !== 1 || names[0] !== OWNER_FILE) return { released: false, reason: 'lock-unexpected-contents' }
+  let record
+  try { record = JSON.parse(readFileSync(join(lockPath, OWNER_FILE), 'utf8')) } catch {
+    return { released: false, reason: 'owner-record-unreadable' }
+  }
+  if (!isObject(record) || record.nonce !== nonce) return { released: false, reason: 'owner-changed' }
+  try { unlinkSync(join(lockPath, OWNER_FILE)) } catch (error) {
+    return { released: false, reason: 'unlink-failed', detail: error?.code ?? error?.message }
+  }
+  try { rmdirSync(lockPath) } catch (error) {
+    return { released: false, reason: 'rmdir-failed', detail: error?.code ?? error?.message }
+  }
+  return { released: true, reason: 'released' }
+}
+
+export function acquireRetentionLock(root, options = {}) {
+  const canonical = mustExistRoot(root)
+  const pid = options?.pid ?? process.pid
+  const hostname = options?.hostname ?? osHostname()
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new RetentionLockError('usage', 'pid must be a positive safe integer')
+  if (!nonEmpty(hostname)) throw new RetentionLockError('usage', 'hostname must be a non-empty string')
+  const lockPath = join(canonical, LOCK_NAME)
+  try {
+    mkdirSync(lockPath)
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      let inspection = null
+      try { inspection = inspectRetentionLock(canonical) } catch { /* the refusal stands without detail */ }
+      throw new RetentionLockError(
+        'locked',
+        `retention is locked at ${lockPath} (${inspection?.detail ?? 'the lock directory exists'}); acquire never removes an existing lock, so an interrupted owner is cleared explicitly by recover`,
+        inspection,
+      )
+    }
+    throw new RetentionLockError('io', `cannot create ${lockPath}: ${error?.code ?? error?.message}`)
+  }
+  const nonce = randomBytes(16).toString('hex')
+  const owner = {
+    format: LOCK_FORMAT,
+    nonce,
+    pid,
+    hostname,
+    startIdentity: readStartIdentity(pid),
+    acquiredAt: new Date().toISOString(),
+  }
+  try {
+    writeFileSync(join(lockPath, OWNER_FILE), `${JSON.stringify(owner, null, 2)}\n`, { flag: 'wx', mode: 0o600 })
+  } catch (error) {
+    try { rmdirSync(lockPath) } catch { /* an empty lock directory is retained as unknown */ }
+    throw new RetentionLockError('io', `cannot write the lock owner record at ${join(lockPath, OWNER_FILE)}: ${error?.code ?? error?.message}`)
+  }
+  let releaseOutcome = null
+  return {
+    root: canonical,
+    path: lockPath,
+    owner,
+    release() {
+      if (!releaseOutcome) releaseOutcome = releaseOwnLock(lockPath, nonce)
+      return releaseOutcome
+    },
+  }
+}

package/skills/engineering/resolve-issues/scripts/retention-plans.mjs

@@ -0,0 +1,57 @@
+// Canonical plan enumeration, deliberately separate from payload inventory.
+import { lstatSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function retentionPlanFiles(root, { maxPlans = 200, maxEntries = 20000 } = {}) {
+  const paths = new Set()
+  const errors = []
+  let entriesSeen = 0
+  const stat = path => {
+    try { return lstatSync(path) }
+    catch (error) {
+      if (error.code !== 'ENOENT') errors.push(`Cannot inspect ${path}: ${error.code}`)
+      return null
+    }
+  }
+  const planAt = run => {
+    const path = join(run, 'task-plan.json')
+    const info = stat(path)
+    if (!info) return
+    if (!info.isFile() || info.isSymbolicLink()) { errors.push(`Canonical plan is not a regular file: ${path}`); return }
+    if (paths.size >= maxPlans) { errors.push(`Canonical plan count exceeds ${maxPlans}`); return }
+    paths.add(path)
+  }
+  const children = parent => {
+    try {
+      const all = readdirSync(parent, { withFileTypes: true })
+      entriesSeen += all.length
+      if (entriesSeen > maxEntries) { errors.push(`Canonical enumeration exceeds ${maxEntries} entries`); return [] }
+      return all.sort((a, b) => a.name.localeCompare(b.name))
+    } catch (error) {
+      if (error.code !== 'ENOENT') errors.push(`Cannot enumerate ${parent}: ${error.code}`)
+      return []
+    }
+  }
+  const runChildren = container => {
+    for (const entry of children(container)) {
+      const path = join(container, entry.name)
+      if (entry.isSymbolicLink()) { errors.push(`Canonical run location is a symbolic link: ${path}`); continue }
+      if (entry.isDirectory()) planAt(path)
+    }
+  }
+  const rootInfo = stat(root)
+  if (!rootInfo) return { paths: [], complete: errors.length === 0, errors }
+  if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) return { paths: [], complete: false, errors: [`Unsafe retention root: ${root}`] }
+  planAt(root)
+  for (const entry of children(root)) {
+    const path = join(root, entry.name)
+    if (entry.isSymbolicLink()) {
+      errors.push(`Possible canonical run or container is a symbolic link: ${path}`)
+      continue
+    }
+    if (!entry.isDirectory()) continue
+    if (entry.name === 'rush' || entry.name.endsWith('-workspaces')) runChildren(path)
+    else planAt(path)
+  }
+  return { paths: [...paths].sort(), complete: errors.length === 0, errors }
+}