@skillsmith/core 0.11.3 → 0.11.5

package/dist/src/config/owned-lock.claim.js

@@ -0,0 +1,310 @@
+/**
+ * Claim parsing and lock-file mechanics (exclusive creation, reclaim,
+ * release) for the owned-lock primitive.
+ * @module @skillsmith/core/config/owned-lock.claim
+ * @see owned-lock.ts for the full soundness argument and the PUBLIC API.
+ * @see owned-lock.acquire.ts for the core acquire loop + `StuckLockError`,
+ * split into a sibling file purely to keep both under the repo's
+ * 500-line-per-file gate.
+ *
+ * INTERNAL module -- not part of the public surface (no `package.json`
+ * subpath export). Co-located tests and the cross-process race-test child
+ * harness import directly from here, by relative path, specifically to
+ * reach `createLockExclusive`'s `linkSyncOverride` test seam -- see
+ * `owned-lock.acquire.ts` for the analogous rationale on the acquire loop's
+ * own destructive test-only options.
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, fstatSync, linkSync, openSync, readSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { hostname } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { HARDLINK_UNAVAILABLE_CODES, LOCK_RETRY_DELAY_MS, MAX_LOCK_BYTES, RECLAIM_LOCK_TIMEOUT_MS, } from './owned-lock.types.js';
+export function randomHex(bytes) {
+    return randomBytes(bytes).toString('hex');
+}
+/**
+ * Synchronously block the calling thread for `ms` milliseconds without
+ * spinning the CPU. `Atomics.wait` on a throwaway `SharedArrayBuffer` is the
+ * standard synchronous-sleep primitive in Node (unlike browsers, Node does
+ * not forbid calling it on the main thread).
+ */
+export function sleepSync(ms) {
+    const view = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(view, 0, 0, ms);
+}
+// ---------------------------------------------------------------------------
+// Claim parsing + bounded, TOCTOU-free read
+// ---------------------------------------------------------------------------
+/**
+ * Parse raw lock-file text into a {@link Claim}. A v1 claim is one line of
+ * canonical JSON; a legacy claim is a bare decimal integer (today's
+ * `acquireConfigLock` format, `String(process.pid)`); anything else --
+ * including valid JSON at a DIFFERENT `v` -- is `unparseable` and therefore
+ * NEVER auto-reclaimed.
+ */
+export function parseClaim(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return { kind: 'unparseable' };
+    if (/^[0-9]+$/.test(trimmed)) {
+        const pid = Number(trimmed);
+        if (Number.isSafeInteger(pid))
+            return { kind: 'legacy', pid };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { kind: 'unparseable' };
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return { kind: 'unparseable' };
+    const p = parsed;
+    if (p['v'] === 1 &&
+        typeof p['pid'] === 'number' &&
+        typeof p['token'] === 'string' &&
+        typeof p['host'] === 'string' &&
+        typeof p['acquiredAt'] === 'number') {
+        return {
+            kind: 'v1',
+            pid: p['pid'],
+            token: p['token'],
+            host: p['host'],
+            acquiredAt: p['acquiredAt'],
+        };
+    }
+    return { kind: 'unparseable' };
+}
+/**
+ * Bounded, TOCTOU-free claim read: open once, `fstat` THAT fd (not the
+ * path), refuse above {@link MAX_LOCK_BYTES}, read from the same fd. Returns
+ * `{ kind: 'absent' }` on `ENOENT` (or any other open failure).
+ */
+export function readClaim(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+    }
+    catch {
+        return { kind: 'absent' };
+    }
+    try {
+        const st = fstatSync(fd);
+        if (st.size > MAX_LOCK_BYTES)
+            return { kind: 'unparseable' };
+        const buf = Buffer.allocUnsafe(MAX_LOCK_BYTES);
+        const n = readSync(fd, buf, 0, MAX_LOCK_BYTES, 0);
+        return parseClaim(buf.subarray(0, n).toString('utf8'));
+    }
+    catch {
+        return { kind: 'unparseable' };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function isAutoReclaimDisabled() {
+    return process.env['SKILLSMITH_LOCK_NO_AUTO_RECLAIM'] === '1';
+}
+/**
+ * Conservative in every ambiguous direction: PID reuse and a not-our-signal
+ * `EPERM` both read as ALIVE (declining to reclaim costs a timeout; an
+ * incorrect reclaim costs a lost caller). `pid <= 0` is rejected WITHOUT
+ * probing -- `kill(0, 0)` signals the process GROUP, which would make the
+ * liveness probe meaningless.
+ */
+export function isOwnerDefinitelyDead(claim, killProbe = process.kill) {
+    if (isAutoReclaimDisabled())
+        return false;
+    if (claim.kind !== 'v1')
+        return false; // legacy | unparseable | absent -- never (D-5/D-6)
+    if (claim.host !== hostname())
+        return false;
+    if (!Number.isInteger(claim.pid) || claim.pid <= 0)
+        return false;
+    try {
+        killProbe(claim.pid, 0);
+        return false; // signalable -> alive
+    }
+    catch (err) {
+        if (err.code === 'ESRCH')
+            return true; // no such process -> dead
+        return false; // EPERM (exists, not ours) or any other errno -> assume alive
+    }
+}
+export function classifyRefusal(claim) {
+    if (isAutoReclaimDisabled())
+        return 'reclaim-disabled';
+    if (claim.kind === 'legacy')
+        return 'legacy';
+    if (claim.kind === 'unparseable' || claim.kind === 'absent')
+        return 'unparseable';
+    return 'held';
+}
+// ---------------------------------------------------------------------------
+// Exclusive creation -- atomic AND content-complete (D-6)
+// ---------------------------------------------------------------------------
+/**
+ * Create the temp file that {@link createLockExclusive} will `linkSync` into
+ * place, EXCLUSIVELY (`wx`) rather than with the default truncating `w`.
+ * `randomHex(8)` collisions are astronomically unlikely, but a `w`-flag
+ * write is a silent last-writer-wins on collision -- including clobbering
+ * another caller's temp file AFTER it has already been `linkSync`'d into a
+ * live lock (the temp file's own content no longer matters to that lock at
+ * that point, but a `w`-flag collision earlier in the window, before the
+ * link, could still corrupt an in-flight sibling attempt). `wx` turns any
+ * collision into a loud `EEXIST` retry with a fresh random suffix instead of
+ * a silent overwrite.
+ */
+function writeTempClaimExclusive(dir, base, recordJson) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const tmp = join(dir, `.${base}.${randomHex(8)}.tmp`);
+        let fd;
+        try {
+            fd = openSync(tmp, 'wx', 0o600);
+        }
+        catch (err) {
+            if (err.code === 'EEXIST')
+                continue; // collision -- retry with a fresh suffix
+            throw err;
+        }
+        try {
+            writeFileSync(fd, recordJson);
+        }
+        finally {
+            closeSync(fd);
+        }
+        chmodSync(tmp, 0o600); // defeat a permissive umask BEFORE the file is reachable as a lock
+        return tmp;
+    }
+    throw new Error(`[skillsmith] could not create a unique temp claim file under ${dir} after 5 attempts`);
+}
+/**
+ * Create `path` exclusively via a temp file + `linkSync` (atomic; `EEXIST`
+ * if `path` exists) so a lock file is NEVER observable without a complete
+ * claim -- closing R2 (a writer could otherwise crash between create and
+ * write, leaving a permanently unreclaimable main lock). On filesystems
+ * without hardlink support this throws rather than falling back to a
+ * non-atomic `openSync('wx')` + separate write -- that two-step sequence
+ * would itself reopen R2 (an observer between the two steps, or a crash in
+ * between, sees an empty/truncated lock that is then PERMANENTLY
+ * unreclaimable, since an `unparseable` claim is never auto-reclaimed by
+ * design). Failing closed on an unsupported filesystem is the sound
+ * resolution the reviewer required; hardlink support is effectively
+ * universal on the filesystems Node actually runs on.
+ *
+ * @param linkSyncOverride - @internal test seam (owned-lock.test.ts item 14)
+ * to exercise the hardlink-unavailable fail-closed path deterministically.
+ * Never set outside that test.
+ */
+export function createLockExclusive(path, recordJson, linkSyncOverride) {
+    const dir = dirname(path);
+    const tmp = writeTempClaimExclusive(dir, basename(path), recordJson);
+    const doLink = linkSyncOverride ?? linkSync;
+    try {
+        doLink(tmp, path);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST')
+            return false;
+        if (code && HARDLINK_UNAVAILABLE_CODES.has(code)) {
+            throw new Error(`[skillsmith] cannot create an owned lock at ${path}: this filesystem does not ` +
+                `support hardlinks (${code}), which the lock's atomic-and-content-complete creation ` +
+                `guarantee depends on. Failing closed rather than falling back to a non-atomic write ` +
+                `(which could leave a permanently unreclaimable lock on a crash mid-write).`);
+        }
+        throw err;
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // Already gone (nlink 2 -> 1 on a successful link), or never created.
+        }
+    }
+}
+/**
+ * Validate and destroy a stale main lock inside a region from which every
+ * other reclaimer is excluded (the reclaim lock). This is the ONLY code path
+ * that may ever unlink `<target>.lock` on the strength of a liveness
+ * inference: a caller's own pre-filter is advisory and discarded; only the
+ * re-read performed HERE, under the reclaim lock, authorizes the unlink.
+ */
+export function tryReclaimUnderLock(lockPath, reclaimPath, opts) {
+    const rToken = randomHex(8);
+    const rRecord = JSON.stringify({
+        v: 1,
+        pid: process.pid,
+        token: rToken,
+        host: hostname(),
+        acquiredAt: Date.now(),
+    }) + '\n';
+    const rDeadline = Date.now() + RECLAIM_LOCK_TIMEOUT_MS;
+    for (;;) {
+        if (createLockExclusive(reclaimPath, rRecord, opts.linkSyncOverride))
+            break;
+        if (Date.now() >= rDeadline)
+            return 'unavailable'; // concurrent reclaimer, or an R1 orphan
+        sleepSync(LOCK_RETRY_DELAY_MS);
+    }
+    try {
+        // ===== RECLAIM CRITICAL SECTION -- mutually exclusive against every other reclaimer =====
+        const claim = readClaim(lockPath); // AUTHORITATIVE re-read
+        if (!opts.unsafeSkipRevalidation) {
+            if (claim.kind === 'absent')
+                return 'gone';
+            if (!isOwnerDefinitelyDead(claim))
+                return 'not-stale';
+        }
+        else if (claim.kind === 'absent') {
+            return 'gone'; // even the negative control cannot unlink something not there
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return 'gone';
+            throw err;
+        }
+        return 'reclaimed';
+    }
+    finally {
+        releaseOwned(reclaimPath, rToken);
+    }
+}
+// ---------------------------------------------------------------------------
+// Release -- ownership-verified, idempotent
+// ---------------------------------------------------------------------------
+export function releaseOwned(path, token) {
+    const claim = readClaim(path);
+    if (claim.kind === 'v1' && claim.token === token) {
+        try {
+            unlinkSync(path);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                console.warn(`[skillsmith] lock_release_unlink_failed: could not remove ${path}: ${err.message}`);
+            }
+        }
+    }
+    else {
+        // We no longer own it -- unlinking would destroy a live holder's lock
+        // (it was reclaimed from us after we appeared dead, or hand-edited).
+        console.warn(`[skillsmith] lock_release_not_owner: ${path} is no longer owned by this process -- not removing it.`);
+    }
+}
+export function makeRelease(lockPath, token) {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        releaseOwned(lockPath, token);
+    };
+}
+//# sourceMappingURL=owned-lock.claim.js.map

package/dist/src/config/owned-lock.claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owned-lock.claim.js","sourceRoot":"","sources":["../../../src/config/owned-lock.claim.ts"],"names":[],"mappings":"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"}

package/dist/src/config/owned-lock.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Two-level owned-lock primitive (SMI-5883 Wave 2, design revision 4).
+ * @module @skillsmith/core/config/owned-lock
+ *
+ * Replaces the single-level, age-based `acquireConfigLock` mechanism (which
+ * `config-atomic-write.ts` now implements as a thin wrapper over
+ * {@link acquireOwnedLock}). The single-level design was found unsound in
+ * round-3 review: it turned "I inspected this path and concluded the holder
+ * is dead" (computed in one region) into an unconditional
+ * `unlinkSync(lockPath)` (performed in another), with no mutual exclusion
+ * between the two. Any process that recreated the path in between had its
+ * LIVE lock destroyed by a contender acting on a stale decision.
+ *
+ * The general defect, stated so the fix can be checked against it: it is
+ * never sound to turn "I inspected this path and concluded X" into an
+ * unconditional destructive operation on that path, unless the interval
+ * between inspection and destruction excludes every actor that could change
+ * what the path holds. This module does not make the destruction
+ * conditional (POSIX offers no delete-if-inode primitive) -- it makes the
+ * interval exclusive, via a SECOND lock file (`<target>.lock.reclaim`,
+ * `owned-lock.claim.ts`'s `tryReclaimUnderLock`) that must be held before
+ * any reclaimer may re-read and then unlink `<target>.lock`. Every
+ * reclaimer therefore validates and destroys inside a region from which
+ * every other reclaimer -- and, by construction, every other mutator of
+ * that path -- is excluded. The authorization to reclaim can no longer go
+ * stale between being computed and being consumed, because nothing that
+ * could invalidate it is permitted to run in between.
+ *
+ * Two files, asymmetric policies:
+ *   - `<target>.lock`         -- the caller's lock. Auto-reclaimed, but ONLY
+ *     from inside the reclaim critical section.
+ *   - `<target>.lock.reclaim` -- serializes reclaim DECISIONS about the lock
+ *     above. Strict, NEVER auto-reclaimed (a staleness heuristic here would
+ *     reintroduce the identical duplicate-delete race one level up).
+ *
+ * This module is a thin wrapper over `owned-lock.acquire.ts`'s
+ * {@link acquireOwnedLockCore} -- it exists specifically so that the two
+ * destructive test-only seams on the core loop's options
+ * (`unsafeSkipReclaimRevalidation`, `linkSyncOverride`) are structurally
+ * unreachable from the public `@skillsmith/core/config/owned-lock` subpath
+ * export: this file's exported {@link AcquireOwnedLockOptions} simply does
+ * not have those fields, and this file never re-exports the internal
+ * `AcquireOwnedLockCoreOptions` type or `acquireOwnedLockCore` function
+ * that do. See owned-lock.acquire.ts's module comment for the full rationale.
+ *
+ * New-race audit (N1-N9) and residual risks (R1-R5) are documented in the
+ * SMI-5883 design doc; the short version: R1 (`SIGKILL` inside the
+ * ~3-syscall reclaim critical section orphans the reclaim lock) is accepted
+ * and loudly diagnosable ({@link StuckLockError} names both files + the
+ * manual unstick procedure below); legacy (pre-v1, bare-decimal-PID) claims
+ * and unparseable claims are NEVER auto-reclaimed (D-5/D-6) because they
+ * carry no `host` field, so "dead on this host" cannot establish "dead" for
+ * a claim that might belong to a process on a different host sharing a
+ * networked `$HOME`.
+ *
+ * Manual unstick (required whenever a `StuckLockError` fires with a reason
+ * other than `held`):
+ *   1. Confirm no skillsmith process is running:
+ *        ps -ax | grep -E '[s]killsmith|[s]klx'
+ *   2. Inspect the claim (read-only, safe):
+ *        cat <lockPath>
+ *        cat <reclaimPath>          # only if the error named it
+ *   3. Remove ONLY the file(s) the error named:
+ *        rm <lockPath>
+ *        rm <reclaimPath>
+ *
+ * Opt-out: `SKILLSMITH_LOCK_NO_AUTO_RECLAIM=1` disables auto-reclaim
+ * entirely (degrades to the strict, no-reclaim design) -- a sound escape
+ * hatch for R5 (an `os.hostname()` collision across two containers with
+ * distinct PID namespaces bind-mounting the same `$HOME`). Registered in
+ * `docs/internal/process/guards-and-opt-outs.md`.
+ */
+import { StuckLockError } from './owned-lock.acquire.js';
+import type { AcquireOwnedLockOptions } from './owned-lock.types.js';
+export type { AcquireOwnedLockOptions, StuckLockReason } from './owned-lock.types.js';
+export { LOCK_ACQUIRE_TIMEOUT_MS, LOCK_RETRY_DELAY_MS, MAX_LOCK_BYTES, RECLAIM_LOCK_TIMEOUT_MS, RECLAIM_PROBE_AFTER_MS, RECLAIM_PROBE_INTERVAL_MS, } from './owned-lock.types.js';
+export { StuckLockError };
+/**
+ * Acquire an exclusive, cross-process, OWNED lock guarding `target`. Unlike
+ * a plain create-exclusive lock, ownership is verified on release (a token,
+ * not just presence) and staleness is verified by PROCESS LIVENESS, not file
+ * age -- and reclaimed only from inside a second, strict-no-auto-reclaim
+ * lock (`<target>.lock.reclaim`) that serializes reclaim decisions. See the
+ * module docstring for the full soundness argument.
+ *
+ * @param target - Path being guarded (NOT the lock file itself -- the lock
+ * file is `${target}.lock`, the reclaim lock `${target}.lock.reclaim`).
+ * @returns A release function. Callers MUST call it exactly once, in a
+ * `finally` block. Idempotent -- a second call is a no-op.
+ *
+ * SMI-5883 code-review round 2: `opts` is destructured field-by-field into a
+ * FRESH object rather than forwarded as-is. TypeScript's excess-property
+ * check only fires on an object LITERAL passed directly at the call site --
+ * a caller passing a variable, a cast, or plain JavaScript (no type checking
+ * at all) is not constrained by `AcquireOwnedLockOptions` omitting the two
+ * unsafe fields, and `acquireOwnedLockCore` reads them by property name at
+ * runtime. Rebuilding the object here means an injected
+ * `unsafeSkipReclaimRevalidation`/`linkSyncOverride` on the caller's `opts`
+ * is structurally dropped before it ever reaches the core loop, regardless
+ * of what extra properties `opts` carries.
+ *
+ * SMI-5883 code-review round 3: the two unsafe fields are ALSO set to
+ * `undefined` explicitly, as OWN properties of the fresh object, rather than
+ * simply omitted. A plain `{ ...safeFields }` object still inherits from
+ * `Object.prototype` -- if that prototype were ever globally polluted (a
+ * distinct, severe vulnerability class in its own right, reachable only by
+ * an attacker who already has arbitrary code execution in this process),
+ * ordinary property access on an object with no OWN `unsafeSkipReclaimRevalidation`/
+ * `linkSyncOverride` would still resolve them via the prototype chain. An
+ * explicit own-property `undefined` shadows any such inherited value.
+ */
+export declare function acquireOwnedLock(target: string, opts?: AcquireOwnedLockOptions): () => void;
+//# sourceMappingURL=owned-lock.d.ts.map

package/dist/src/config/owned-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owned-lock.d.ts","sourceRoot":"","sources":["../../../src/config/owned-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH,OAAO,EAAwB,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC9E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAEpE,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACrF,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,CAAA;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,uBAA4B,GAAG,MAAM,IAAI,CAU/F"}

package/dist/src/config/owned-lock.js

@@ -0,0 +1,121 @@
+/**
+ * Two-level owned-lock primitive (SMI-5883 Wave 2, design revision 4).
+ * @module @skillsmith/core/config/owned-lock
+ *
+ * Replaces the single-level, age-based `acquireConfigLock` mechanism (which
+ * `config-atomic-write.ts` now implements as a thin wrapper over
+ * {@link acquireOwnedLock}). The single-level design was found unsound in
+ * round-3 review: it turned "I inspected this path and concluded the holder
+ * is dead" (computed in one region) into an unconditional
+ * `unlinkSync(lockPath)` (performed in another), with no mutual exclusion
+ * between the two. Any process that recreated the path in between had its
+ * LIVE lock destroyed by a contender acting on a stale decision.
+ *
+ * The general defect, stated so the fix can be checked against it: it is
+ * never sound to turn "I inspected this path and concluded X" into an
+ * unconditional destructive operation on that path, unless the interval
+ * between inspection and destruction excludes every actor that could change
+ * what the path holds. This module does not make the destruction
+ * conditional (POSIX offers no delete-if-inode primitive) -- it makes the
+ * interval exclusive, via a SECOND lock file (`<target>.lock.reclaim`,
+ * `owned-lock.claim.ts`'s `tryReclaimUnderLock`) that must be held before
+ * any reclaimer may re-read and then unlink `<target>.lock`. Every
+ * reclaimer therefore validates and destroys inside a region from which
+ * every other reclaimer -- and, by construction, every other mutator of
+ * that path -- is excluded. The authorization to reclaim can no longer go
+ * stale between being computed and being consumed, because nothing that
+ * could invalidate it is permitted to run in between.
+ *
+ * Two files, asymmetric policies:
+ *   - `<target>.lock`         -- the caller's lock. Auto-reclaimed, but ONLY
+ *     from inside the reclaim critical section.
+ *   - `<target>.lock.reclaim` -- serializes reclaim DECISIONS about the lock
+ *     above. Strict, NEVER auto-reclaimed (a staleness heuristic here would
+ *     reintroduce the identical duplicate-delete race one level up).
+ *
+ * This module is a thin wrapper over `owned-lock.acquire.ts`'s
+ * {@link acquireOwnedLockCore} -- it exists specifically so that the two
+ * destructive test-only seams on the core loop's options
+ * (`unsafeSkipReclaimRevalidation`, `linkSyncOverride`) are structurally
+ * unreachable from the public `@skillsmith/core/config/owned-lock` subpath
+ * export: this file's exported {@link AcquireOwnedLockOptions} simply does
+ * not have those fields, and this file never re-exports the internal
+ * `AcquireOwnedLockCoreOptions` type or `acquireOwnedLockCore` function
+ * that do. See owned-lock.acquire.ts's module comment for the full rationale.
+ *
+ * New-race audit (N1-N9) and residual risks (R1-R5) are documented in the
+ * SMI-5883 design doc; the short version: R1 (`SIGKILL` inside the
+ * ~3-syscall reclaim critical section orphans the reclaim lock) is accepted
+ * and loudly diagnosable ({@link StuckLockError} names both files + the
+ * manual unstick procedure below); legacy (pre-v1, bare-decimal-PID) claims
+ * and unparseable claims are NEVER auto-reclaimed (D-5/D-6) because they
+ * carry no `host` field, so "dead on this host" cannot establish "dead" for
+ * a claim that might belong to a process on a different host sharing a
+ * networked `$HOME`.
+ *
+ * Manual unstick (required whenever a `StuckLockError` fires with a reason
+ * other than `held`):
+ *   1. Confirm no skillsmith process is running:
+ *        ps -ax | grep -E '[s]killsmith|[s]klx'
+ *   2. Inspect the claim (read-only, safe):
+ *        cat <lockPath>
+ *        cat <reclaimPath>          # only if the error named it
+ *   3. Remove ONLY the file(s) the error named:
+ *        rm <lockPath>
+ *        rm <reclaimPath>
+ *
+ * Opt-out: `SKILLSMITH_LOCK_NO_AUTO_RECLAIM=1` disables auto-reclaim
+ * entirely (degrades to the strict, no-reclaim design) -- a sound escape
+ * hatch for R5 (an `os.hostname()` collision across two containers with
+ * distinct PID namespaces bind-mounting the same `$HOME`). Registered in
+ * `docs/internal/process/guards-and-opt-outs.md`.
+ */
+import { acquireOwnedLockCore, StuckLockError } from './owned-lock.acquire.js';
+export { LOCK_ACQUIRE_TIMEOUT_MS, LOCK_RETRY_DELAY_MS, MAX_LOCK_BYTES, RECLAIM_LOCK_TIMEOUT_MS, RECLAIM_PROBE_AFTER_MS, RECLAIM_PROBE_INTERVAL_MS, } from './owned-lock.types.js';
+export { StuckLockError };
+/**
+ * Acquire an exclusive, cross-process, OWNED lock guarding `target`. Unlike
+ * a plain create-exclusive lock, ownership is verified on release (a token,
+ * not just presence) and staleness is verified by PROCESS LIVENESS, not file
+ * age -- and reclaimed only from inside a second, strict-no-auto-reclaim
+ * lock (`<target>.lock.reclaim`) that serializes reclaim decisions. See the
+ * module docstring for the full soundness argument.
+ *
+ * @param target - Path being guarded (NOT the lock file itself -- the lock
+ * file is `${target}.lock`, the reclaim lock `${target}.lock.reclaim`).
+ * @returns A release function. Callers MUST call it exactly once, in a
+ * `finally` block. Idempotent -- a second call is a no-op.
+ *
+ * SMI-5883 code-review round 2: `opts` is destructured field-by-field into a
+ * FRESH object rather than forwarded as-is. TypeScript's excess-property
+ * check only fires on an object LITERAL passed directly at the call site --
+ * a caller passing a variable, a cast, or plain JavaScript (no type checking
+ * at all) is not constrained by `AcquireOwnedLockOptions` omitting the two
+ * unsafe fields, and `acquireOwnedLockCore` reads them by property name at
+ * runtime. Rebuilding the object here means an injected
+ * `unsafeSkipReclaimRevalidation`/`linkSyncOverride` on the caller's `opts`
+ * is structurally dropped before it ever reaches the core loop, regardless
+ * of what extra properties `opts` carries.
+ *
+ * SMI-5883 code-review round 3: the two unsafe fields are ALSO set to
+ * `undefined` explicitly, as OWN properties of the fresh object, rather than
+ * simply omitted. A plain `{ ...safeFields }` object still inherits from
+ * `Object.prototype` -- if that prototype were ever globally polluted (a
+ * distinct, severe vulnerability class in its own right, reachable only by
+ * an attacker who already has arbitrary code execution in this process),
+ * ordinary property access on an object with no OWN `unsafeSkipReclaimRevalidation`/
+ * `linkSyncOverride` would still resolve them via the prototype chain. An
+ * explicit own-property `undefined` shadows any such inherited value.
+ */
+export function acquireOwnedLock(target, opts = {}) {
+    return acquireOwnedLockCore(target, {
+        timeoutMs: opts.timeoutMs,
+        label: opts.label,
+        reclaimProbeAfterMs: opts.reclaimProbeAfterMs,
+        onReclaimBoundary: opts.onReclaimBoundary,
+        onReclaimOutcome: opts.onReclaimOutcome,
+        unsafeSkipReclaimRevalidation: undefined,
+        linkSyncOverride: undefined,
+    });
+}
+//# sourceMappingURL=owned-lock.js.map

package/dist/src/config/owned-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owned-lock.js","sourceRoot":"","sources":["../../../src/config/owned-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAI9E,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,CAAA;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAgC,EAAE;IACjF,OAAO,oBAAoB,CAAC,MAAM,EAAE;QAClC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;QAC7C,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;QACzC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,6BAA6B,EAAE,SAAS;QACxC,gBAAgB,EAAE,SAAS;KAC5B,CAAC,CAAA;AACJ,CAAC"}

package/dist/src/config/owned-lock.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unit tests for the two-level owned-lock primitive (SMI-5883 §8a).
+ * @module @skillsmith/core/config/owned-lock.test
+ *
+ * Single-process tests of `acquireOwnedLock` itself. Cross-process tests
+ * (the reclaim-race proof, the orphaned-reclaim-lock residual, and the
+ * end-to-end lost-update stress test) live in
+ * `packages/core/tests/integration/owned-lock-reclaim-race.test.ts` (§8b/8c)
+ * and `packages/core/tests/integration/owned-lock-lost-update.test.ts` (§8f).
+ */
+export {};
+//# sourceMappingURL=owned-lock.test.d.ts.map

package/dist/src/config/owned-lock.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owned-lock.test.d.ts","sourceRoot":"","sources":["../../../src/config/owned-lock.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}