commandmate 0.11.4 → 0.12.0

package/dist/server/src/lib/skills/operation-journal.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Operation journal and idempotency for Skill operations (Issue #1234)
+ *
+ * The journal is the crash-recovery record that lets install/uninstall converge
+ * on one answer after a restart. Its central rule is that the **filesystem
+ * atomic rename is the commit point**: once an operation reaches FS_COMMITTED,
+ * the payload exists and a later DB or index failure must not be reported as a
+ * rollback. Such an operation moves to FAILED_RECONCILABLE and is driven
+ * forward from the receipt, never backwards.
+ *
+ * ```text
+ * PREPARING ──▶ FS_COMMITTED ──▶ INDEXED ──▶ SUCCEEDED
+ *     │              │              │
+ *     └──────────────┴──────────────┴──▶ FAILED_RECONCILABLE ──▶ INDEXED/SUCCEEDED
+ * ```
+ *
+ * The reverse edge out of FAILED_RECONCILABLE is guarded: it is only legal when
+ * the entry recorded a filesystem commit. A failure before the commit point is
+ * genuinely rolled back and stays terminal.
+ *
+ * Idempotency keys are bound to actor, operation, target and plan. Replaying a
+ * request returns the recorded entry instead of writing the payload twice; the
+ * *same* key with a *different* binding is a conflict rather than a silent
+ * substitution of someone else's plan.
+ *
+ * @module lib/skills/operation-journal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_JOURNAL_RETENTION_MS = exports.SkillOperationTransitionError = exports.SKILL_OPERATION_STATES = void 0;
+exports.computeSkillOperationBindingHash = computeSkillOperationBindingHash;
+exports.deriveSkillOperationIdempotencyKey = deriveSkillOperationIdempotencyKey;
+exports.readSkillOperationJournal = readSkillOperationJournal;
+exports.listSkillOperationJournal = listSkillOperationJournal;
+exports.writeSkillOperationJournal = writeSkillOperationJournal;
+exports.deleteSkillOperationJournal = deleteSkillOperationJournal;
+exports.pruneExpiredSkillOperationJournal = pruneExpiredSkillOperationJournal;
+exports.beginSkillOperation = beginSkillOperation;
+exports.transitionSkillOperation = transitionSkillOperation;
+exports.hasSkillFilesystemCommit = hasSkillFilesystemCommit;
+exports.isSkillOperationTerminal = isSkillOperationTerminal;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const operation_store_1 = require("../../lib/skills/operation-store");
+/**
+ * Journal states.
+ *
+ * Local to this module rather than added to the #1228 contract: these describe
+ * CommandMate's internal execution, not the published distribution documents.
+ */
+exports.SKILL_OPERATION_STATES = [
+    'PREPARING',
+    'FS_COMMITTED',
+    'INDEXED',
+    'SUCCEEDED',
+    'FAILED_RECONCILABLE',
+];
+/** Legal forward edges. Anything else is a programming error. */
+const ALLOWED_TRANSITIONS = {
+    PREPARING: ['FS_COMMITTED', 'FAILED_RECONCILABLE'],
+    FS_COMMITTED: ['INDEXED', 'FAILED_RECONCILABLE'],
+    INDEXED: ['SUCCEEDED', 'FAILED_RECONCILABLE'],
+    FAILED_RECONCILABLE: ['INDEXED', 'SUCCEEDED', 'FAILED_RECONCILABLE'],
+    SUCCEEDED: [],
+};
+/** Raised on an illegal state transition. */
+class SkillOperationTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to, reason) {
+        super(`Illegal Skill operation transition ${from} -> ${to}: ${reason}`);
+        this.from = from;
+        this.to = to;
+        this.name = 'SkillOperationTransitionError';
+    }
+}
+exports.SkillOperationTransitionError = SkillOperationTransitionError;
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}
+/**
+ * Digest of everything an idempotency key is bound to.
+ *
+ * Two requests may only share a key when they mean the same thing: same actor,
+ * same operation, same target and same resolved plan.
+ */
+function computeSkillOperationBindingHash(binding) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(canonicalJson({
+        actor: binding.actor,
+        operation: binding.operation,
+        target: binding.target,
+        planHash: binding.planHash,
+    }))
+        .digest('hex');
+}
+/**
+ * Derive an idempotency key when the client did not supply one.
+ * Identical requests then collapse onto one operation by construction.
+ */
+function deriveSkillOperationIdempotencyKey(binding) {
+    return computeSkillOperationBindingHash(binding);
+}
+function getJournalDir(options) {
+    return (0, operation_store_1.ensureSkillStateDir)(operation_store_1.SKILL_JOURNAL_DIRNAME, options);
+}
+/** Journal filename. The key is hashed so a client-supplied string never names a file. */
+function getJournalPath(idempotencyKey, options) {
+    const digest = (0, crypto_1.createHash)('sha256').update(idempotencyKey).digest('hex');
+    return (0, path_1.join)(getJournalDir(options), `${digest}.json`);
+}
+function isJournalEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const entry = value;
+    return (typeof entry.operationId === 'string' &&
+        typeof entry.idempotencyKey === 'string' &&
+        typeof entry.bindingHash === 'string' &&
+        typeof entry.state === 'string' &&
+        exports.SKILL_OPERATION_STATES.includes(entry.state));
+}
+/** Read the entry recorded for an idempotency key. */
+function readSkillOperationJournal(idempotencyKey, options = {}) {
+    const entry = (0, operation_store_1.readSkillStateFile)(getJournalPath(idempotencyKey, options));
+    return isJournalEntry(entry) ? entry : null;
+}
+/** Every entry currently on disk, oldest first. */
+function listSkillOperationJournal(options = {}) {
+    const dir = getJournalDir(options);
+    const entries = [];
+    for (const name of (0, fs_1.readdirSync)(dir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        const parsed = (0, operation_store_1.readSkillStateFile)((0, path_1.join)(dir, name));
+        if (isJournalEntry(parsed))
+            entries.push(parsed);
+    }
+    return entries.sort((a, b) => a.createdAt - b.createdAt);
+}
+/** Persist an entry. */
+function writeSkillOperationJournal(entry, options = {}) {
+    (0, operation_store_1.writeSkillStateFile)(getJournalPath(entry.idempotencyKey, options), entry);
+}
+/** Drop an entry once it is past its retention window. */
+function deleteSkillOperationJournal(idempotencyKey, options = {}) {
+    try {
+        (0, fs_1.unlinkSync)(getJournalPath(idempotencyKey, options));
+    }
+    catch {
+        // Already collected.
+    }
+}
+/**
+ * How long a terminal journal entry is kept before it becomes collectable.
+ *
+ * The journal is the crash-recovery and idempotency record, not the audit trail
+ * (that lives in the append-only `skill_operations` table). A terminal entry is
+ * only still useful for the window during which a client might retry the same
+ * idempotency key; past it, the entry is pure growth. Seven days comfortably
+ * covers realistic retry and support windows while bounding the directory to the
+ * operations of one window rather than of all time (Issue #1428).
+ */
+exports.SKILL_JOURNAL_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Collect terminal journal entries whose retention window has elapsed.
+ *
+ * Only {@link isSkillOperationTerminal} entries are eligible: SUCCEEDED, and a
+ * pre-commit FAILED_RECONCILABLE that rolled back cleanly. A FAILED_RECONCILABLE
+ * that *did* commit to the filesystem is non-terminal — it still owes the
+ * reconciler an index write — and is never pruned, so a genuine
+ * payload-on-disk/no-index inconsistency is not silently discarded. Retention is
+ * measured from `updatedAt`, which for a terminal entry is the moment it reached
+ * its terminal state and never moves again.
+ *
+ * Uniform retention across both terminal outcomes is deliberate (Issue #1428):
+ * a SUCCEEDED entry that were deleted immediately would let a delayed retry of
+ * the *same* idempotency key re-run the install and hit a spurious
+ * DESTINATION_EXISTS, so success and failure expire on the same clock and a key
+ * becomes reusable at a single, predictable time regardless of outcome.
+ *
+ * @returns the idempotency keys of the entries that were pruned.
+ */
+function pruneExpiredSkillOperationJournal(options = {}) {
+    const now = options.now ?? Date.now();
+    const retentionMs = options.retentionMs ?? exports.SKILL_JOURNAL_RETENTION_MS;
+    const pruned = [];
+    for (const entry of listSkillOperationJournal(options)) {
+        if (!isSkillOperationTerminal(entry))
+            continue;
+        if (now - entry.updatedAt <= retentionMs)
+            continue;
+        deleteSkillOperationJournal(entry.idempotencyKey, options);
+        pruned.push(entry.idempotencyKey);
+    }
+    return pruned;
+}
+/**
+ * Open an operation, or return the one this request already started.
+ *
+ * A replay hands back the recorded entry so the caller can answer with the
+ * original outcome instead of writing the payload a second time.
+ */
+function beginSkillOperation(input, options = {}) {
+    const bindingHash = computeSkillOperationBindingHash(input.binding);
+    const idempotencyKey = input.idempotencyKey ?? deriveSkillOperationIdempotencyKey(input.binding);
+    const existing = readSkillOperationJournal(idempotencyKey, options);
+    if (existing !== null) {
+        if (existing.bindingHash !== bindingHash) {
+            return { ok: false, reason: 'IDEMPOTENCY_KEY_CONFLICT', entry: existing };
+        }
+        return { ok: true, entry: existing, replayed: true };
+    }
+    const now = options.now ?? Date.now();
+    const entry = {
+        schemaVersion: 1,
+        operationId: (0, crypto_1.randomUUID)(),
+        idempotencyKey,
+        bindingHash,
+        operation: input.binding.operation,
+        state: 'PREPARING',
+        actor: input.binding.actor,
+        target: input.binding.target,
+        source: input.source ?? null,
+        lockKey: input.lockKey,
+        createdAt: now,
+        updatedAt: now,
+        fsCommittedAt: null,
+        receiptDigest: null,
+        error: null,
+        history: [{ state: 'PREPARING', at: now }],
+    };
+    writeSkillOperationJournal(entry, options);
+    return { ok: true, entry, replayed: false };
+}
+/**
+ * Advance an operation to its next state and persist it.
+ *
+ * @throws SkillOperationTransitionError when the edge is not legal, or when a
+ *   recovery edge is attempted on an operation that never reached the commit
+ *   point (there is no receipt to converge from).
+ */
+function transitionSkillOperation(entry, next, patch = {}, options = {}) {
+    if (!ALLOWED_TRANSITIONS[entry.state].includes(next)) {
+        throw new SkillOperationTransitionError(entry.state, next, 'edge is not defined');
+    }
+    const now = options.now ?? Date.now();
+    const fsCommittedAt = next === 'FS_COMMITTED' ? (entry.fsCommittedAt ?? now) : entry.fsCommittedAt;
+    if ((next === 'INDEXED' || next === 'SUCCEEDED') && fsCommittedAt === null) {
+        throw new SkillOperationTransitionError(entry.state, next, 'no filesystem commit point was recorded');
+    }
+    const updated = {
+        ...entry,
+        state: next,
+        updatedAt: now,
+        fsCommittedAt,
+        source: patch.source !== undefined ? patch.source : entry.source,
+        receiptDigest: patch.receiptDigest !== undefined ? patch.receiptDigest : entry.receiptDigest,
+        error: patch.error !== undefined
+            ? patch.error === null
+                ? null
+                : { code: patch.error.code, message: (0, operation_store_1.redactSkillOperationText)(patch.error.message) }
+            : entry.error,
+        history: [...entry.history, { state: next, at: now }],
+    };
+    writeSkillOperationJournal(updated, options);
+    return updated;
+}
+/** Whether the payload is known to exist, regardless of how the DB side ended. */
+function hasSkillFilesystemCommit(entry) {
+    return entry.fsCommittedAt !== null;
+}
+/** Whether an entry still needs work from the reconciler. */
+function isSkillOperationTerminal(entry) {
+    if (entry.state === 'SUCCEEDED')
+        return true;
+    // A failure before the commit point rolled back cleanly; nothing to converge.
+    return entry.state === 'FAILED_RECONCILABLE' && !hasSkillFilesystemCommit(entry);
+}

package/dist/server/src/lib/skills/operation-lock.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * Cross-process exclusive lock for Skill operations (Issue #1234)
+ *
+ * Extends the O_EXCL pattern of `lib/app-update/update-lock` with the three
+ * properties a Skill operation needs and a self-update does not:
+ *
+ * - **Owner nonce.** Release and renew require the caller to present the nonce
+ *   written at acquisition, so no process can drop a lock it does not hold.
+ * - **Lease heartbeat.** {@link renewSkillOperationLease} can extend a lease so
+ *   a long operation is not reclaimed by age. It is not yet wired into the
+ *   routes, so owner liveness below — not the heartbeat — is what currently
+ *   keeps a live operation safe (Issue #1427).
+ * - **Owner liveness.** A lock whose lease expired is reclaimed only when the
+ *   owning PID is verifiably gone on this host. A live owner that missed a
+ *   heartbeat keeps its lock, including a same-process concurrent operation:
+ *   reclaiming it would let two processes write the same payload.
+ *
+ * The lock key is a digest of the *resolved* worktree path and the validated
+ * Skill ID, so no untrusted name ever reaches a filename.
+ *
+ * @module lib/skills/operation-lock
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_LOCK_FOREIGN_HOST_GRACE_MS = exports.SKILL_LOCK_LEASE_MS = void 0;
+exports.buildSkillOperationLockKey = buildSkillOperationLockKey;
+exports.readSkillOperationLock = readSkillOperationLock;
+exports.describeSkillLockHolder = describeSkillLockHolder;
+exports.evaluateSkillLock = evaluateSkillLock;
+exports.acquireSkillOperationLock = acquireSkillOperationLock;
+exports.renewSkillOperationLease = renewSkillOperationLease;
+exports.releaseSkillOperationLock = releaseSkillOperationLock;
+exports.listSkillOperationLockKeys = listSkillOperationLockKeys;
+exports.releaseOrphanSkillLocks = releaseOrphanSkillLocks;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const operation_store_1 = require("../../lib/skills/operation-store");
+/** Lease length. A holder renews well before this; a crash expires it. */
+exports.SKILL_LOCK_LEASE_MS = 30_000;
+/**
+ * Extra wait before reclaiming a lock owned by another host.
+ * Liveness cannot be checked across hosts, so time is the only evidence there.
+ */
+exports.SKILL_LOCK_FOREIGN_HOST_GRACE_MS = 10 * 60_000;
+/**
+ * Identifies this process across restarts. A PID alone is reusable; combined
+ * with this value a record can be recognised as "written by me".
+ */
+const PROCESS_GENERATION = (0, crypto_1.randomUUID)();
+function defaultIsProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to another user.
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Lock key for a (worktree, skill) pair.
+ *
+ * @param worktreeRealPath - Server-resolved, symlink-free worktree path. Two
+ *   registrations pointing at the same directory must produce the same key, so
+ *   the caller is responsible for having called realpath.
+ * @param skillId - Skill ID already validated against the contract grammar.
+ */
+function buildSkillOperationLockKey(worktreeRealPath, skillId) {
+    return (0, crypto_1.createHash)('sha256').update(`${worktreeRealPath}\x00${skillId}`).digest('hex');
+}
+function getLockDir(options) {
+    return (0, operation_store_1.ensureSkillStateDir)(operation_store_1.SKILL_LOCK_DIRNAME, options);
+}
+function getLockPath(key, options) {
+    return (0, path_1.join)(getLockDir(options), `${key}.lock`);
+}
+function isLockRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    const owner = record.owner;
+    return (typeof record.key === 'string' &&
+        typeof record.operationId === 'string' &&
+        typeof record.leaseExpiresAt === 'number' &&
+        Number.isFinite(record.leaseExpiresAt) &&
+        typeof owner === 'object' &&
+        owner !== null &&
+        typeof owner.nonce === 'string' &&
+        typeof owner.pid === 'number' &&
+        typeof owner.host === 'string');
+}
+/** Read a lock record. Returns null when absent or unparseable. */
+function readSkillOperationLock(key, options = {}) {
+    const record = (0, operation_store_1.readSkillStateFile)(getLockPath(key, options));
+    return isLockRecord(record) ? record : null;
+}
+/** Public, non-sensitive view of a lock record. */
+function describeSkillLockHolder(record) {
+    return {
+        operationId: record.operationId,
+        acquiredAt: record.acquiredAt,
+        leaseExpiresAt: record.leaseExpiresAt,
+    };
+}
+/**
+ * Decide how an observed record may be treated, given the clock and liveness.
+ *
+ * Ordering matters: a valid lease short-circuits every other consideration, so
+ * a live holder is never reclaimed regardless of what its PID looks like. Once
+ * the lease has lapsed on this host, PID liveness is the *only* remaining
+ * evidence — a lock is reclaimed only when its owning process is verifiably gone.
+ *
+ * Same-process locks are deliberately not shortcut to RECLAIMABLE (Issue #1427).
+ * Every Next.js route handler runs in one shared process and none renews its
+ * lease ({@link renewSkillOperationLease} has no production caller), so a lapsed
+ * lease is not evidence that a *concurrent* same-process operation abandoned its
+ * lock. Shortcutting it to reclaimable let a second request steal a live
+ * install's lock ~one lease window in and write the same payload underneath it.
+ * A same-process owner that is still alive now resolves to HELD_BY_LIVE_OWNER
+ * and is left alone.
+ *
+ * Tradeoff: this process can no longer instantly reclaim a lock it truly leaked
+ * (acquired but never released). While the process stays alive such a lock reads
+ * as HELD_BY_LIVE_OWNER; it clears only on an explicit release or after the
+ * process exits — a later process then sees the dead PID and reclaims it. Note
+ * this is stronger than "next acquire waits at most one lease window": with no
+ * heartbeat there is no time-based signal, so within one live process the lock
+ * is held until release/exit, not merely until the lease lapses. In practice the
+ * acquire path always releases in a `finally`, so the only real remnant is a
+ * crash — and crash orphans are unaffected: a new process has a different
+ * generation and finds the old PID gone, so the liveness branch below reclaims
+ * them exactly as before.
+ */
+function evaluateSkillLock(record, options = {}) {
+    if (record === null)
+        return 'FREE';
+    const now = options.now ?? Date.now();
+    if (now < record.leaseExpiresAt)
+        return 'HELD';
+    const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+    if (record.owner.host !== (0, os_1.hostname)()) {
+        const expiredFor = now - record.leaseExpiresAt;
+        return expiredFor > exports.SKILL_LOCK_FOREIGN_HOST_GRACE_MS
+            ? 'RECLAIMABLE'
+            : 'HELD_UNVERIFIABLE_OWNER';
+    }
+    return isAlive(record.owner.pid) ? 'HELD_BY_LIVE_OWNER' : 'RECLAIMABLE';
+}
+function buildRecord(key, operationId, now, leaseMs) {
+    return {
+        schemaVersion: 1,
+        key,
+        operationId,
+        owner: {
+            nonce: (0, crypto_1.randomBytes)(24).toString('hex'),
+            pid: process.pid,
+            host: (0, os_1.hostname)(),
+            processGeneration: PROCESS_GENERATION,
+        },
+        acquiredAt: now,
+        renewedAt: now,
+        leaseExpiresAt: now + leaseMs,
+    };
+}
+/** Create the lock file, failing when it already exists. */
+function tryCreate(lockPath, record) {
+    let fd;
+    try {
+        fd = (0, fs_1.openSync)(lockPath, fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | fs_1.constants.O_WRONLY, operation_store_1.SKILL_STATE_FILE_MODE);
+    }
+    catch {
+        return false;
+    }
+    try {
+        (0, fs_1.writeSync)(fd, JSON.stringify(record));
+        return true;
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Move a reclaimable lock aside atomically, then re-check it.
+ *
+ * The rename is the mutual exclusion: only one reclaimer can move the file, so
+ * a second reclaimer fails and reports RACE_LOST instead of also proceeding.
+ * The post-rename re-check closes the window where the holder renewed its lease
+ * between our read and our rename; in that case the file is put back.
+ */
+function reclaim(lockPath, observed, options) {
+    const stagePath = `${lockPath}.reclaim-${(0, crypto_1.randomBytes)(8).toString('hex')}`;
+    try {
+        (0, fs_1.renameSync)(lockPath, stagePath);
+    }
+    catch {
+        return { ok: false, reason: 'RACE_LOST' };
+    }
+    const staged = (0, operation_store_1.readSkillStateFile)(stagePath);
+    const stagedRecord = isLockRecord(staged) ? staged : null;
+    const stillReclaimable = observed === null
+        ? // The file was unparseable; only proceed if it still is.
+            stagedRecord === null
+        : stagedRecord === null ||
+            (stagedRecord.owner.nonce === observed.owner.nonce &&
+                evaluateSkillLock(stagedRecord, options) === 'RECLAIMABLE');
+    if (!stillReclaimable) {
+        try {
+            (0, fs_1.renameSync)(stagePath, lockPath);
+        }
+        catch {
+            // The holder already re-created its own lock; nothing was lost.
+        }
+        return { ok: false, reason: 'RACE_LOST' };
+    }
+    try {
+        (0, fs_1.unlinkSync)(stagePath);
+    }
+    catch {
+        // Already gone; the lock path is what matters.
+    }
+    return { ok: true };
+}
+/**
+ * Take the exclusive lock for one (worktree, skill) pair.
+ *
+ * @returns the record on success. The caller must keep it: renew and release
+ *   both require the nonce it carries.
+ */
+function acquireSkillOperationLock(input, options = {}) {
+    const now = options.now ?? Date.now();
+    const leaseMs = input.leaseMs ?? exports.SKILL_LOCK_LEASE_MS;
+    const lockPath = getLockPath(input.key, options);
+    const record = buildRecord(input.key, input.operationId, now, leaseMs);
+    if (tryCreate(lockPath, record)) {
+        return { ok: true, lock: record, reclaimed: false };
+    }
+    const observed = readSkillOperationLock(input.key, options);
+    // A file that exists but does not parse can never expire on its own, so it is
+    // reclaimable rather than "free" — free would mean the create below succeeds.
+    const disposition = observed === null
+        ? (0, fs_1.existsSync)(lockPath)
+            ? 'RECLAIMABLE'
+            : 'FREE'
+        : evaluateSkillLock(observed, options);
+    const heldBy = observed ? describeSkillLockHolder(observed) : null;
+    if (disposition === 'HELD' || disposition === 'HELD_BY_LIVE_OWNER') {
+        return { ok: false, reason: disposition, heldBy };
+    }
+    if (disposition === 'HELD_UNVERIFIABLE_OWNER') {
+        return { ok: false, reason: 'HELD_UNVERIFIABLE_OWNER', heldBy };
+    }
+    if (disposition === 'FREE') {
+        // The file vanished between the failed create and the read.
+        return tryCreate(lockPath, record)
+            ? { ok: true, lock: record, reclaimed: false }
+            : { ok: false, reason: 'RACE_LOST', heldBy: null };
+    }
+    // RECLAIMABLE.
+    const reclaimed = reclaim(lockPath, observed, options);
+    if (!reclaimed.ok) {
+        return { ok: false, reason: reclaimed.reason, heldBy };
+    }
+    return tryCreate(lockPath, record)
+        ? { ok: true, lock: record, reclaimed: true }
+        : { ok: false, reason: 'RACE_LOST', heldBy: null };
+}
+/**
+ * Extend the lease. Fails when the caller is not the current owner, which is
+ * how a process that was reclaimed learns it must stop writing.
+ *
+ * @returns the refreshed record, or null when the lock was lost.
+ */
+function renewSkillOperationLease(lock, options = {}) {
+    const current = readSkillOperationLock(lock.key, options);
+    if (current === null || current.owner.nonce !== lock.owner.nonce)
+        return null;
+    const now = options.now ?? Date.now();
+    const leaseMs = lock.leaseExpiresAt - lock.renewedAt;
+    const renewed = {
+        ...current,
+        renewedAt: now,
+        leaseExpiresAt: now + (leaseMs > 0 ? leaseMs : exports.SKILL_LOCK_LEASE_MS),
+    };
+    (0, operation_store_1.writeSkillStateFile)(getLockPath(lock.key, options), renewed);
+    return renewed;
+}
+/**
+ * Drop the lock. Owner-only: presenting a stale or foreign nonce is refused so
+ * no operation can release another operation's resource.
+ */
+function releaseSkillOperationLock(lock, options = {}) {
+    const current = readSkillOperationLock(lock.key, options);
+    if (current === null || current.owner.nonce !== lock.owner.nonce)
+        return false;
+    try {
+        (0, fs_1.unlinkSync)(getLockPath(lock.key, options));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Keys of every lock file currently present. */
+function listSkillOperationLockKeys(options = {}) {
+    return (0, fs_1.readdirSync)(getLockDir(options))
+        .filter((name) => name.endsWith('.lock'))
+        .map((name) => name.slice(0, -'.lock'.length));
+}
+/**
+ * Remove locks whose owner is verifiably gone.
+ *
+ * Used by startup reconciliation. A lock is only removed when
+ * {@link evaluateSkillLock} says RECLAIMABLE, so a live owner — even one whose
+ * lease lapsed — keeps its lock.
+ *
+ * @returns keys of the locks that were removed.
+ */
+function releaseOrphanSkillLocks(options = {}) {
+    const released = [];
+    for (const key of listSkillOperationLockKeys(options)) {
+        const record = readSkillOperationLock(key, options);
+        // A file that exists but does not parse can never expire on its own.
+        const disposition = record === null ? 'RECLAIMABLE' : evaluateSkillLock(record, options);
+        if (disposition !== 'RECLAIMABLE')
+            continue;
+        try {
+            (0, fs_1.unlinkSync)(getLockPath(key, options));
+            released.push(key);
+        }
+        catch {
+            // Someone else cleaned it up first.
+        }
+    }
+    return released;
+}