@aperant/framework 0.6.2

package/src/cli/install/transforms/cursor.mjs

@@ -0,0 +1,42 @@
+/**
+ * install/transforms/cursor.mjs — Cursor transform.
+ *
+ * Cursor quirks:
+ *   - strip `color` and `skills` from frontmatter.
+ *   - skills land under .cursor/rules/<name>.mdc (Cursor uses .mdc for
+ *     rule files), agents under .cursor/commands/<name>.md.
+ */
+
+import { basename, dirname } from 'node:path'
+import {
+	parseFrontmatter,
+	serializeFrontmatter,
+	stripFields,
+	substituteVersion,
+} from './_shared.mjs'
+
+const STRIP = ['color', 'skills']
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const subbed = substituteVersion(canonicalContent, version)
+	const parsed = parseFrontmatter(subbed)
+	let payload = subbed
+	if (parsed.hasFrontmatter && parsed.fm) {
+		stripFields(parsed.fm, STRIP)
+		payload = serializeFrontmatter(parsed)
+	}
+
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		return [{ outputPath: `rules/${folder}.mdc`, content: payload }]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath, '.md')
+		return [{ outputPath: `commands/${file}.md`, content: payload }]
+	}
+	return []
+}

package/src/cli/install/transforms/gemini.mjs

@@ -0,0 +1,62 @@
+/**
+ * install/transforms/gemini.mjs — Gemini transform.
+ *
+ * Gemini quirks:
+ *   - frontmatter strips `color` (validation error in Gemini's schema) and
+ *     `tools`.
+ *   - body escapes `${var}` → `\${var}` so Gemini's templateString
+ *     interpolation does not fire on prose mentions of shell-style vars.
+ *   - output: .gemini/agents/<name>.md and .gemini/commands/<name>.md.
+ */
+
+import { basename, dirname } from 'node:path'
+import {
+	parseFrontmatter,
+	serializeFrontmatter,
+	stripFields,
+	substituteVersion,
+} from './_shared.mjs'
+
+const STRIP = ['color', 'tools']
+
+/**
+ * Escape ${...} interpolation in body text. Already-escaped (\${) sequences
+ * are left alone so we don't double-escape on re-runs.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function escapeTemplateVars(body) {
+	// Negative lookbehind: only replace ${ that is NOT preceded by a backslash.
+	return body.replace(/(?<!\\)\$\{/g, '\\${')
+}
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const subbed = substituteVersion(canonicalContent, version)
+	const parsed = parseFrontmatter(subbed)
+	let payload
+	if (parsed.hasFrontmatter && parsed.fm) {
+		stripFields(parsed.fm, STRIP)
+		const escapedBody = escapeTemplateVars(parsed.body)
+		payload = serializeFrontmatter({ ...parsed, body: escapedBody })
+	} else {
+		payload = escapeTemplateVars(subbed)
+	}
+
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		return [
+			{ outputPath: `agents/${folder}.md`, content: payload },
+			{ outputPath: `commands/${folder}.md`, content: payload },
+		]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath, '.md')
+		return [{ outputPath: `agents/${file}.md`, content: payload }]
+	}
+	return []
+}

package/src/cli/install/transforms/kilo.mjs

@@ -0,0 +1,30 @@
+/**
+ * install/transforms/kilo.mjs — Kilo transform.
+ *
+ * Same body/frontmatter transform as OpenCode (color → hex, strip the same
+ * agent fields) but writes under .kilo/agent/ + .kilo/command/. We import
+ * the OpenCode transform body and only diverge on output paths.
+ */
+
+import { basename, dirname } from 'node:path'
+import { applyOpencodeTransform } from './opencode.mjs'
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const payload = applyOpencodeTransform(canonicalContent, version)
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		return [
+			{ outputPath: `agent/${folder}.md`, content: payload },
+			{ outputPath: `command/${folder}.md`, content: payload },
+		]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath, '.md')
+		return [{ outputPath: `agent/${file}.md`, content: payload }]
+	}
+	return []
+}

package/src/cli/install/transforms/opencode.mjs

@@ -0,0 +1,65 @@
+/**
+ * install/transforms/opencode.mjs — OpenCode transform.
+ *
+ * OpenCode quirks:
+ *   - color names are converted to hex (`color: cyan` → `color: '#06b6d4'`)
+ *     because OpenCode's UI rejects symbolic names.
+ *   - agents strip `skills`, `memory`, `maxTurns`, `permissionMode`,
+ *     `disallowedTools` (none of these have OpenCode equivalents and they
+ *     trigger validation errors).
+ *   - output: .opencode/agent/<name>.md and .opencode/command/<name>.md
+ *     (note SINGULAR `agent` / `command`, not `agents` / `commands`).
+ */
+
+import { basename, dirname } from 'node:path'
+import {
+	colorNameToHex,
+	parseFrontmatter,
+	serializeFrontmatter,
+	stripFields,
+	substituteVersion,
+} from './_shared.mjs'
+
+const STRIP = ['skills', 'memory', 'maxTurns', 'permissionMode', 'disallowedTools']
+
+/**
+ * Apply the OpenCode body+frontmatter transform. Exported so the kilo
+ * transform (which has the same body invariants but different output paths)
+ * can reuse it.
+ *
+ * @param {string} content
+ * @param {string} version
+ * @returns {string}
+ */
+export function applyOpencodeTransform(content, version) {
+	const subbed = substituteVersion(content, version)
+	const parsed = parseFrontmatter(subbed)
+	if (!parsed.hasFrontmatter || !parsed.fm) return subbed
+	stripFields(parsed.fm, STRIP)
+	if (typeof parsed.fm.color === 'string') {
+		const hex = colorNameToHex(parsed.fm.color)
+		if (hex) parsed.fm.color = hex
+		else delete parsed.fm.color
+	}
+	return serializeFrontmatter(parsed)
+}
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const payload = applyOpencodeTransform(canonicalContent, version)
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		return [
+			{ outputPath: `agent/${folder}.md`, content: payload },
+			{ outputPath: `command/${folder}.md`, content: payload },
+		]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath, '.md')
+		return [{ outputPath: `agent/${file}.md`, content: payload }]
+	}
+	return []
+}

package/src/cli/install/transforms/qwen.mjs

@@ -0,0 +1,14 @@
+/**
+ * install/transforms/qwen.mjs — Qwen transform.
+ *
+ * Quirks (per GSD reference):
+ *   - strips color+skills+tools.
+ *   - output: .qwen/agents/<name>.md + .qwen/commands/<name>.md.
+ */
+
+import { createSimpleTransform } from './_shared.mjs'
+
+export const transform = createSimpleTransform({
+	strip: ['color', 'skills', 'tools'],
+	rewriteCommands: false,
+})

package/src/cli/install/transforms/trae.mjs

@@ -0,0 +1,14 @@
+/**
+ * install/transforms/trae.mjs — Trae transform.
+ *
+ * Quirks:
+ *   - strips color+skills+tools.
+ *   - output: .trae/agents/<name>.md + .trae/commands/<name>.md.
+ */
+
+import { createSimpleTransform } from './_shared.mjs'
+
+export const transform = createSimpleTransform({
+	strip: ['color', 'skills', 'tools'],
+	rewriteCommands: false,
+})

package/src/cli/install/transforms/windsurf.mjs

@@ -0,0 +1,42 @@
+/**
+ * install/transforms/windsurf.mjs — Windsurf transform.
+ *
+ * Windsurf quirks:
+ *   - frontmatter strips color+skills.
+ *   - skills land in .windsurf/rules/<name>.md (Windsurf rule files).
+ *   - agents/invocable land in .windsurf/workflows/<name>.md.
+ */
+
+import { basename, dirname } from 'node:path'
+import {
+	parseFrontmatter,
+	serializeFrontmatter,
+	stripFields,
+	substituteVersion,
+} from './_shared.mjs'
+
+const STRIP = ['color', 'skills']
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const subbed = substituteVersion(canonicalContent, version)
+	const parsed = parseFrontmatter(subbed)
+	let payload = subbed
+	if (parsed.hasFrontmatter && parsed.fm) {
+		stripFields(parsed.fm, STRIP)
+		payload = serializeFrontmatter(parsed)
+	}
+
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		return [{ outputPath: `rules/${folder}.md`, content: payload }]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath, '.md')
+		return [{ outputPath: `workflows/${file}.md`, content: payload }]
+	}
+	return []
+}

package/src/cli/install/update-chips.mjs

@@ -0,0 +1,96 @@
+/**
+ * install/update-chips.mjs — read the SessionStart worker's cache file
+ * and produce the colored statusline chip(s) for it.
+ *
+ * Color scheme (matches GSD precedent):
+ *   - yellow ⬆ /apt:update          when update_available
+ *   - red    ⚠ stale skills — run /apt:update    when stale_files_total > 0
+ *   - yellow ⚠ dev install — re-run installer    when dev_install_ahead
+ *   - dim    ? /apt:update          when not_published
+ *
+ * NO_COLOR is honored upstream (statusline computes the `color` flag).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const ANSI = {
+	yellow: '\x1b[33m',
+	red: '\x1b[31m',
+	dim: '\x1b[2m',
+	reset: '\x1b[0m',
+}
+
+/**
+ * @typedef {Object} UpdateCache
+ * @property {boolean} not_published
+ * @property {boolean} update_available
+ * @property {boolean} dev_install_ahead
+ * @property {number} stale_files_total
+ * @property {string} checked_at
+ * @property {string|null} [lookup_error]  set when npm view threw a non-404 error
+ */
+
+/**
+ * Resolve the cache file location. Honors $HOME (tests inject a tmp HOME)
+ * via os.homedir() which respects the env.
+ *
+ * @returns {string}
+ */
+export function updateCachePath() {
+	return join(homedir(), '.cache', 'aperant', 'apt-update-check.json')
+}
+
+/**
+ * Read the worker's cache file. Returns null when missing or malformed —
+ * statusline shows no chips in that case.
+ *
+ * @returns {UpdateCache|null}
+ */
+export function readUpdateCache() {
+	const path = updateCachePath()
+	if (!existsSync(path)) return null
+	try {
+		const data = JSON.parse(readFileSync(path, 'utf-8'))
+		if (!data || typeof data !== 'object') return null
+		return data
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Build the chip string array for a given cache. Empty array when there
+ * are no chips to show. Order: stale_files first (most urgent), then
+ * update_available, then dev-ahead, then not-published, then lookup_error.
+ *
+ * @param {UpdateCache|null} cache
+ * @param {{ color: boolean }} opts
+ * @returns {string[]}
+ */
+export function formatUpdateChips(cache, { color }) {
+	if (!cache) return []
+	const chips = []
+	const wrap = (ansi, text) => (color ? `${ansi}${text}${ANSI.reset}` : text)
+
+	if (cache.stale_files_total && cache.stale_files_total > 0) {
+		chips.push(wrap(ANSI.red, '⚠ stale skills — run /apt:update'))
+	}
+	if (cache.update_available) {
+		chips.push(wrap(ANSI.yellow, '⬆ /apt:update'))
+	}
+	if (cache.dev_install_ahead) {
+		chips.push(wrap(ANSI.yellow, '⚠ dev install — re-run installer'))
+	}
+	if (cache.not_published) {
+		chips.push(wrap(ANSI.dim, '? /apt:update'))
+	}
+	// Show a dim warning chip when the npm lookup failed with a non-404 error
+	// (network timeout, ENOTFOUND, etc.). This distinguishes "genuinely up to
+	// date" from "we don't know because the check failed".
+	if (cache.lookup_error) {
+		chips.push(wrap(ANSI.dim, '⚠ /apt:update — check failed'))
+	}
+	return chips
+}

package/src/cli/install/version-header.mjs

@@ -0,0 +1,255 @@
+/**
+ * install/version-header.mjs — parse / inject the per-file
+ * `apt-skill-version` and `apt-hook-version` headers regardless of
+ * whether the file is a markdown skill, a markdown agent, a .js hook,
+ * or a .sh hook.
+ *
+ * Used by:
+ *   - check-version: parses installed-file headers to detect drift.
+ *   - pipeline: parses canonical-file headers when computing manifest
+ *     entries (so we record what version the canonical file claimed).
+ *   - The canonical-file injector script (scripts/inject-version-header.mjs)
+ *     for the markdown side; this module exposes the regex helpers it
+ *     uses so both stay in sync.
+ *   - apt-check-update-worker.js (via inspectManifestFiles): shared
+ *     per-file inspection loop so worker and check-version stay in lock-step.
+ *
+ * Note: fs-reading helpers (inspectManifestFiles) are contained in this
+ * module so both the worker and check-version import from a single source
+ * of truth. Pure header helpers remain pure.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { isAbsolute, relative, resolve } from 'node:path'
+
+/**
+ * Compute SHA-256 hex digest of a Buffer or string.
+ *
+ * @param {Buffer|string} buf
+ * @returns {string}
+ */
+export function sha256(buf) {
+	return createHash('sha256').update(buf).digest('hex')
+}
+
+/**
+ * Resolve `entryPath` relative to `installRoot`, asserting containment.
+ * Throws for absolute paths or paths that escape installRoot via '..'.
+ *
+ * @param {string} installRoot  absolute install root directory
+ * @param {string} entryPath    relative path from manifest entry
+ * @returns {string}  resolved absolute path
+ */
+export function safeResolveWithin(installRoot, entryPath) {
+	if (isAbsolute(entryPath)) {
+		throw new Error(`manifest entry has absolute path: ${entryPath}`)
+	}
+	const abs = resolve(installRoot, entryPath)
+	const rel = relative(installRoot, abs)
+	if (rel.startsWith('..') || isAbsolute(rel)) {
+		throw new Error(`manifest entry escapes install root: ${entryPath}`)
+	}
+	return abs
+}
+
+/**
+ * Walk a parsed manifest's file list and return an array of stale-file
+ * records. This is the single source of truth for the per-file inspection
+ * loop; both `check-version` and the SessionStart worker delegate here.
+ *
+ * Each entry in the returned array has:
+ *   `{ path: string, reason: 'missing_file'|'hash_mismatch'|'missing_header'|'header_mismatch'|'invalid_path' }`
+ *
+ * @param {object} manifest        parsed apt-file-manifest.json (files[], framework_version)
+ * @param {string} installRoot     absolute path to the runtime install root
+ * @param {{ installedAtMs?: number }} [opts]
+ *   `installedAtMs` — when provided, files whose mtime <= this value skip the
+ *   hash+header check (fast path: no drift since last install).
+ * @returns {Array<{path: string, reason: string}>}
+ */
+export function inspectManifestFiles(manifest, installRoot, opts = {}) {
+	const { installedAtMs } = opts
+	const stale = []
+	for (const entry of manifest.files) {
+		let abs
+		try {
+			abs = safeResolveWithin(installRoot, entry.path)
+		} catch {
+			stale.push({ path: entry.path, reason: 'invalid_path' })
+			continue
+		}
+		if (!existsSync(abs)) {
+			stale.push({ path: entry.path, reason: 'missing_file' })
+			continue
+		}
+		// mtime short-circuit: if installedAtMs is set and the file's mtime has
+		// not changed since install, skip the expensive read+hash (assume clean).
+		if (installedAtMs !== undefined) {
+			try {
+				const { mtimeMs } = statSync(abs)
+				if (mtimeMs <= installedAtMs) continue
+			} catch {
+				// stat failed — fall through to full check
+			}
+		}
+		const buf = readFileSync(abs)
+		if (sha256(buf) !== entry.installedHash) {
+			stale.push({ path: entry.path, reason: 'hash_mismatch' })
+			continue
+		}
+		const declared = parseVersionHeader(buf.toString('utf-8'))
+		if (declared === null && /\.(md|js|mjs|sh)$/.test(entry.path)) {
+			stale.push({ path: entry.path, reason: 'missing_header' })
+			continue
+		}
+		if (declared !== null && declared !== manifest.framework_version) {
+			stale.push({ path: entry.path, reason: 'header_mismatch' })
+		}
+	}
+	return stale
+}
+
+const SKILL_KEY_RE = /^\s*apt-skill-version\s*:\s*(.+?)\s*$/m
+const SKILL_FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+const JS_HOOK_RE = /^\/\/\s*apt-hook-version\s*:\s*(.+?)\s*$/m
+const SH_HOOK_RE = /^#\s*apt-hook-version\s*:\s*(.+?)\s*$/m
+
+/**
+ * Stable placeholder swapped in for the canonical `{{APT_VERSION}}` token
+ * before any code path parses canonical frontmatter with a YAML library.
+ *
+ * `{{APT_VERSION}}` is valid Mustache but invalid YAML: the outer `{...}`
+ * is read as a flow-map and the inner `{APT_VERSION}` as a flow-map used as
+ * a key, which triggers yaml@2's "Keys with collection values will be
+ * stringified due to JS Object restrictions" warning (one per parse).
+ * Silencing via `logLevel: 'silent'` would hide genuine YAML issues, so
+ * instead we pre-substitute with a syntactically harmless semver-shaped
+ * string before parse. Install-time transforms still replace
+ * `{{APT_VERSION}}` with the real framework version — see
+ * `transforms/_shared.mjs#substituteVersion` — so installed files are
+ * unchanged by this helper.
+ */
+export const APT_VERSION_PARSE_PLACEHOLDER = '0.0.0-apt-placeholder'
+
+/**
+ * Pre-substitute the canonical `{{APT_VERSION}}` Mustache token with a
+ * YAML-safe placeholder so callers can `yaml.parse` canonical
+ * frontmatter without emitting the flow-map-key warning. Pure string
+ * function; idempotent on already-substituted content.
+ *
+ * Use this at every canonical-file parse site that runs BEFORE install
+ * substitution (e.g. `apt-tools check`, schema-validation tests). The
+ * install pipeline itself does NOT need this — it calls `substituteVersion`
+ * with a real version first (see `transforms/_shared.mjs`).
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function sanitizeAptVersionForYamlParse(content) {
+	if (!content) return content
+	return content.split('{{APT_VERSION}}').join(APT_VERSION_PARSE_PLACEHOLDER)
+}
+
+/**
+ * Parse a file's version header. Looks in:
+ *   1. Markdown YAML frontmatter (`apt-skill-version: x.y.z`).
+ *   2. JS/MJS topmost line (`// apt-hook-version: x.y.z`).
+ *   3. SH topmost non-shebang line (`# apt-hook-version: x.y.z`).
+ *
+ * Returns null when no header is found.
+ *
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function parseVersionHeader(content) {
+	if (typeof content !== 'string' || content.length === 0) return null
+
+	// Markdown: only look inside frontmatter so a body mention of
+	// "apt-skill-version" doesn't false-positive.
+	const fmMatch = content.match(SKILL_FRONTMATTER_RE)
+	if (fmMatch) {
+		const fmText = fmMatch[1]
+		const skillMatch = fmText.match(SKILL_KEY_RE)
+		if (skillMatch) return skillMatch[1]
+	}
+
+	const jsMatch = content.match(JS_HOOK_RE)
+	if (jsMatch) return jsMatch[1]
+
+	const shMatch = content.match(SH_HOOK_RE)
+	if (shMatch) return shMatch[1]
+
+	return null
+}
+
+/**
+ * Inject `apt-skill-version: <version>` into a markdown file's frontmatter
+ * if absent. Idempotent. Used by canonical-file injector and by transforms
+ * that need to materialize the header on the fly.
+ *
+ * Insertion point: after `description:` (incl. continuation lines), else
+ * after `name:`, else as the first key.
+ *
+ * @param {string} content
+ * @param {string} version
+ * @returns {string}
+ */
+export function injectMarkdownHeader(content, version) {
+	if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content
+	const eol = /^---\r\n/.test(content) ? '\r\n' : '\n'
+	const lines = content.split(/\r?\n/)
+	let endIdx = -1
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i] === '---') {
+			endIdx = i
+			break
+		}
+	}
+	if (endIdx === -1) return content
+	const fmLines = lines.slice(1, endIdx)
+	for (const l of fmLines) {
+		if (/^apt-skill-version\s*:/.test(l)) {
+			// Already present — only substitute the value.
+			return content.replace(/^(apt-skill-version\s*:\s*).+$/m, `$1${version}`)
+		}
+	}
+	let insertAt = -1
+	for (let i = 0; i < fmLines.length; i++) {
+		if (/^description\s*:/.test(fmLines[i])) {
+			let j = i + 1
+			while (j < fmLines.length && /^\s+\S/.test(fmLines[j])) j++
+			insertAt = j
+			break
+		}
+	}
+	if (insertAt === -1) {
+		for (let i = 0; i < fmLines.length; i++) {
+			if (/^name\s*:/.test(fmLines[i])) {
+				insertAt = i + 1
+				break
+			}
+		}
+	}
+	if (insertAt === -1) insertAt = 0
+	const newFm = [...fmLines]
+	newFm.splice(insertAt, 0, `apt-skill-version: ${version}`)
+	const head = lines.slice(0, 1)
+	const tail = lines.slice(endIdx)
+	return [...head, ...newFm, ...tail].join(eol)
+}
+
+/**
+ * Strip `apt-skill-version` / `apt-hook-version` lines entirely. Used by
+ * tests that need to assert "missing_header" reasons without manually
+ * editing files.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stripVersionHeader(content) {
+	return content
+		.replace(/^\s*apt-skill-version\s*:\s*.+$\r?\n?/m, '')
+		.replace(/^\/\/\s*apt-hook-version\s*:\s*.+$\r?\n?/m, '')
+		.replace(/^#\s*apt-hook-version\s*:\s*.+$\r?\n?/m, '')
+}

package/src/cli/lock/pid.mjs

@@ -0,0 +1,25 @@
+/**
+ * pid.mjs — PID liveness + lock-staleness helpers (C29).
+ */
+
+/**
+ * Check if a PID is alive (Unix only — uses kill(pid, 0) signal check).
+ */
+export function isPidAlive(pid) {
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Check if a lock is stale: heartbeat > 2 min old AND PID is dead.
+ */
+export function isLockStale(lockData) {
+	const heartbeatAge = Date.now() - new Date(lockData.heartbeat).getTime()
+	const ttlMs = (lockData.ttl_seconds || 120) * 1000
+	if (heartbeatAge <= ttlMs) return false
+	return !isPidAlive(lockData.worker_pid)
+}