@particle-academy/prism-harness 0.7.0 → 0.9.0

package/dist/session.js

@@ -1,4 +1,5 @@
-import { createHash } from 'node:crypto';
+import { ParticipantRef, SessionAddress } from './address.js';
+import { indexedStore, storeLockRank, StoreAddressIndex } from './address-index.js';
 import { isJsonObject } from './json.js';
 import { StoreTaskSource } from './store-task-source.js';
 import { Thread } from './thread.js';
@@ -18,18 +19,39 @@ import { Thread } from './thread.js';
  *  - the thread and stored capabilities are DURABLE.
  */
 export class Session {
+    address;
+    actor;
+    #addressIndex;
+    #rawDurable;
+    #rawEphemeral;
+    #lockStore;
     scope;
     participant;
     #ephemeral;
     #durable;
     #ttlSeconds;
     #cachedState = null;
+    #resolutionOnly = false;
+    #resolvedMode = null;
     constructor(options) {
-        this.participant = options.participant;
+        if (options.participant instanceof ParticipantRef && options.actor === undefined)
+            throw new Error('Typed participants require an explicit authorization actor.');
+        const strictIdentity = options.agent != null || options.participant instanceof ParticipantRef;
+        this.participant = options.participant instanceof ParticipantRef ? options.participant : (strictIdentity ? Object.freeze({ ...options.participant }) : options.participant);
+        this.address = new SessionAddress(this.participant, options.scope, options.agent ?? null);
+        this.actor = options.actor ?? this.participant;
+        const index = options.addressIndex ?? (this.address.agent !== null || options.participant instanceof ParticipantRef
+            ? new StoreAddressIndex(options.durable, options.maxAddressesPerParticipant ?? null) : undefined);
+        this.#addressIndex = index;
+        this.#rawDurable = options.durable;
+        this.#rawEphemeral = options.ephemeral;
         this.scope = options.scope;
-        this.#ephemeral = options.ephemeral;
-        this.#durable = options.durable;
+        this.#ephemeral = index ? indexedStore(options.ephemeral, index, this.address, 'ephemeral') : options.ephemeral;
+        this.#durable = index ? indexedStore(options.durable, index, this.address, 'durable') : options.durable;
+        this.#lockStore = index && storeLockRank(options.durable) > storeLockRank(options.ephemeral) ? this.#durable : this.#ephemeral;
         this.#ttlSeconds = options.ttlSeconds ?? null;
+        for (const key of strictIdentity ? ['address', 'actor', 'participant', 'scope'] : ['address', 'actor'])
+            Object.defineProperty(this, key, { writable: false, configurable: false });
     }
     /**
      * The address this session is resolved by.
@@ -45,11 +67,14 @@ export class Session {
      * ONE store and resolve the same session.
      */
     key() {
-        const digest = createHash('sha1').update(this.participant.type).digest('hex').slice(0, 12);
-        return `session:${digest}:${String(this.participant.id)}:${this.scope}`;
+        return this.address.agent === null && !(this.participant instanceof ParticipantRef)
+            ? new SessionAddress(this.participant, this.scope).sessionKey() : this.address.sessionKey();
     }
+    get agent() { return this.address.agent; }
     // -- ephemeral half --------------------------------------------------------
     async mode() {
+        if (this.#resolvedMode !== null)
+            return this.#resolvedMode;
         return this.#readString('mode');
     }
     async usingMode(mode) {
@@ -69,10 +94,11 @@ export class Session {
     }
     async state() {
         this.#cachedState ??= (await this.#ephemeral.get(this.#ephemeralKey())) ?? {};
-        return this.#cachedState;
+        return this.#resolutionOnly ? structuredClone(this.#cachedState) : this.#cachedState;
     }
     /** Drop the ephemeral half. THE CONVERSATION IS UNTOUCHED. */
     async forget() {
+        this.#assertWritable();
         await this.#ephemeral.forget(this.#ephemeralKey());
         this.#cachedState = null;
         return this;
@@ -80,7 +106,13 @@ export class Session {
     // -- durable half ----------------------------------------------------------
     /** The stored conversation this session is bound to. */
     thread() {
-        return new Thread(this.#durable, `${this.key()}:thread`);
+        this.#assertWritable();
+        const store = this.#addressIndex ? indexedStore(this.#rawDurable, this.#addressIndex, this.address, 'durable', 'thread') : this.#durable;
+        return new Thread(store, `${this.key()}:thread`);
+    }
+    async findThread() {
+        const thread = this.thread();
+        return await thread.exists() ? thread : null;
     }
     /**
      * The agent task list this session is bound to.
@@ -93,13 +125,15 @@ export class Session {
      * against a store as safe as one reached through here.
      */
     tasks(options = {}) {
-        return new StoreTaskSource(this.#durable, `${this.key()}:tasks`, options);
+        this.#assertWritable();
+        const store = this.#addressIndex ? indexedStore(this.#rawDurable, this.#addressIndex, this.address, 'durable', 'tasks') : this.#durable;
+        return new StoreTaskSource(store, `${this.key()}:tasks`, options);
     }
     async capability(name) {
         const stored = (await this.#durable.get(this.#durableKey())) ?? {};
         const capabilities = isJsonObject(stored.capabilities) ? stored.capabilities : {};
         const capability = capabilities[name];
-        return isJsonObject(capability) ? capability : null;
+        return isJsonObject(capability) ? (this.#resolutionOnly ? structuredClone(capability) : capability) : null;
     }
     async usingCapability(name, state) {
         return this.#writeCapabilities((capabilities) => ({ ...capabilities, [name]: state }));
@@ -149,7 +183,8 @@ export class Session {
      * run inside this, not outside it.
      */
     async lock(callback, ttlSeconds = 10, waitSeconds = 5) {
-        return this.#ephemeral.withLock(this.key(), async () => {
+        this.#assertWritable();
+        return this.#lockStore.withLock(this.key(), async () => {
             // Re-read inside the lock. State written by whoever held it before us
             // is otherwise invisible to this instance, and acting on a stale read
             // is the thing the lock exists to prevent.
@@ -164,17 +199,37 @@ export class Session {
     #durableKey() {
         return `${this.key()}:durable`;
     }
+    /** Refuse explicit logical mutations; ordinary get() retains expired-entry cleanup. */
+    async resolveReadOnly(mode, resolve) {
+        const view = new Session({ participant: this.participant, scope: this.scope, agent: this.agent, actor: this.actor,
+            ephemeral: this.#rawEphemeral, durable: this.#rawDurable, addressIndex: this.#addressIndex, ttlSeconds: this.#ttlSeconds });
+        view.#resolutionOnly = true;
+        view.#resolvedMode = mode;
+        try {
+            return await resolve(view);
+        }
+        finally {
+            view.#resolutionOnly = false;
+            view.#cachedState = null;
+        }
+    }
+    #assertWritable() {
+        if (this.#resolutionOnly)
+            throw new Error('Harness tool resolution is read-only.');
+    }
     async #readString(key) {
         const value = (await this.state())[key];
         return typeof value === 'string' ? value : null;
     }
     async #write(key, value) {
+        this.#assertWritable();
         const state = { ...(await this.state()), [key]: value };
         await this.#ephemeral.put(this.#ephemeralKey(), state, this.#ttlSeconds);
         this.#cachedState = state;
         return this;
     }
     async #writeCapabilities(mutate) {
+        this.#assertWritable();
         const stored = (await this.#durable.get(this.#durableKey())) ?? {};
         const capabilities = isJsonObject(stored.capabilities) ? stored.capabilities : {};
         await this.#durable.put(this.#durableKey(), { ...stored, capabilities: mutate(capabilities) });

package/dist/stores/file-lock-identity.d.ts

@@ -0,0 +1,20 @@
+export interface LockIdentity {
+    readonly platform: 'linux' | 'darwin' | 'win32';
+    readonly boot_id: string;
+    readonly pid_namespace: string | null;
+}
+export interface FileLockIdentityStatus {
+    readonly sampled: boolean;
+    readonly recovery_available: boolean;
+    readonly definitive: boolean;
+    readonly retry_after_ms: number | null;
+    readonly sample_duration_ms: number;
+    readonly code: 'file_lock_identity_unavailable' | null;
+}
+/** Process metadata snapshot only; never runs a query or performs I/O. */
+export declare function fileLockIdentityStatus(): FileLockIdentityStatus;
+/** Definitive metadata is permanent; transient failure is sampled at most once per minute. */
+export declare function nativeLockIdentity(): LockIdentity | null;
+export declare function sameLockIdentity(owner: LockIdentity, local: LockIdentity): boolean;
+/** Read-only signal-zero probe. Permission errors and reused live PIDs remain held. */
+export declare function lockPidIsDead(pid: number): boolean;

package/dist/stores/file-lock-identity.js

@@ -0,0 +1,74 @@
+import { readFileSync, readlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { windowsLockIdentity } from './file-lock-windows-identity.js';
+let sampled = false;
+let established = null;
+let retryAt = 0;
+let definitive = false;
+let durationMs = 0;
+/** Process metadata snapshot only; never runs a query or performs I/O. */
+export function fileLockIdentityStatus() {
+    return Object.freeze({ sampled, recovery_available: established?.pid_namespace != null, definitive,
+        retry_after_ms: !sampled || definitive ? null : Math.max(0, retryAt - performance.now()),
+        sample_duration_ms: durationMs, code: sampled && established?.pid_namespace == null ? 'file_lock_identity_unavailable' : null });
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Definitive metadata is permanent; transient failure is sampled at most once per minute. */
+export function nativeLockIdentity() {
+    if (!sampled || (!definitive && performance.now() >= retryAt)) {
+        const start = performance.now();
+        const identity = readNativeLockIdentity();
+        durationMs = performance.now() - start;
+        established = identity === null ? null : Object.freeze(identity);
+        definitive = identity !== null && (identity.pid_namespace !== null || identity.platform === 'win32');
+        retryAt = performance.now() + 60000;
+        sampled = true;
+    }
+    return established;
+}
+function readNativeLockIdentity() {
+    let identity = null;
+    try {
+        if (process.platform === 'win32')
+            identity = windowsLockIdentity();
+        else if (process.platform === 'linux') {
+            const boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+            if (!UUID.test(boot))
+                return null;
+            let realm = null;
+            try {
+                const value = readlinkSync('/proc/self/ns/pid');
+                if (/^pid:\[[0-9]+\]$/.test(value))
+                    realm = value;
+            }
+            catch { /* unknown */ }
+            identity = { platform: 'linux', boot_id: boot.toLowerCase(), pid_namespace: realm };
+        }
+        else if (process.platform === 'darwin') {
+            const result = spawnSync('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid'], { encoding: 'utf8', timeout: 15000, maxBuffer: 65536 });
+            const boot = result.stdout?.trim();
+            if (result.error || result.status !== 0 || !boot || !UUID.test(boot))
+                return null;
+            identity = { platform: 'darwin', boot_id: boot.toLowerCase(), pid_namespace: 'darwin:kernel' };
+        }
+    }
+    catch {
+        return null;
+    }
+    return identity;
+}
+export function sameLockIdentity(owner, local) {
+    return owner.pid_namespace !== null && local.pid_namespace !== null &&
+        owner.platform === local.platform && owner.boot_id === local.boot_id &&
+        owner.pid_namespace === local.pid_namespace;
+}
+/** Read-only signal-zero probe. Permission errors and reused live PIDs remain held. */
+export function lockPidIsDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}

package/dist/stores/file-lock-windows-identity.d.ts

@@ -0,0 +1,2 @@
+import type { LockIdentity } from './file-lock-identity.js';
+export declare function windowsLockIdentity(): LockIdentity | null;

package/dist/stores/file-lock-windows-identity.js

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process';
+import { win32 } from 'node:path';
+// Master2797: fixed metadata only, no compilation, no value payload or Job state.
+// Resolve the first-party CIM module from PSHOME, never a user module search path.
+const COMMAND = String.raw `
+$ErrorActionPreference = 'Stop'
+$PSModuleAutoloadingPreference = 'None'
+try {
+  Import-Module -Name ($PSHOME + '\Modules\Microsoft.PowerShell.Utility\Microsoft.PowerShell.Utility.psd1') -ErrorAction Stop
+  Import-Module -Name ($PSHOME + '\Modules\CimCmdlets\CimCmdlets.psd1') -ErrorAction Stop
+  $boot = (CimCmdlets\Get-CimInstance -ClassName Win32_OperatingSystem -ErrorAction Stop).LastBootUpTime
+  if ($null -eq $boot) { throw 'Missing boot identity' }
+  $ticks = $boot.ToUniversalTime().Ticks.ToString([Globalization.CultureInfo]::InvariantCulture)
+  $base = [Microsoft.Win32.RegistryKey]::OpenBaseKey([Microsoft.Win32.RegistryHive]::LocalMachine, [Microsoft.Win32.RegistryView]::Registry64)
+  try {
+    $key = $base.OpenSubKey('SYSTEM\CurrentControlSet\Control')
+    if ($null -eq $key) { throw 'Missing registry key' }
+    try { $present = $key.GetValueNames() -contains 'ContainerType' }
+    finally { $key.Dispose() }
+  } finally { $base.Dispose() }
+  [Console]::Out.WriteLine('boot=' + $ticks)
+  if ($present) { [Console]::Out.WriteLine('container=present') }
+  else { [Console]::Out.WriteLine('container=absent') }
+} catch { exit 1 }
+`;
+export function windowsLockIdentity() {
+    const root = process.env.SystemRoot;
+    if (!root || !/^[a-z]:[\\/]/i.test(root) || !win32.isAbsolute(root))
+        return null;
+    const env = { SystemRoot: root, windir: root };
+    for (const key of ['TEMP', 'TMP'])
+        if (process.env[key])
+            env[key] = process.env[key];
+    const binary = win32.join(env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    try {
+        const result = spawnSync(binary, ['-NoProfile', '-NonInteractive', '-NoLogo', '-Command', COMMAND], { env, encoding: 'utf8', timeout: 15000, maxBuffer: 16384, windowsHide: true, shell: false });
+        if (result.error || result.status !== 0 || result.stderr !== '')
+            return null;
+        const match = /^boot=([1-9][0-9]{0,18})\r?\ncontainer=(present|absent)\r?\n$/.exec(result.stdout);
+        if (!match || match[0] !== result.stdout || BigInt(match[1]) > 3155378975999999999n)
+            return null;
+        return { platform: 'win32', boot_id: 'cim-utc-ticks:' + match[1],
+            pid_namespace: match[2] === 'absent' ? 'win32:kernel' : null };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/stores/file-owner-lock.d.ts

@@ -0,0 +1,28 @@
+import type { LockIdentity } from './file-lock-identity.js';
+export interface FileLockOwner {
+    version: 2;
+    pid: number;
+    identity: LockIdentity;
+    nonce: string;
+    released: boolean;
+    expires_at: number;
+}
+interface ReleaseProgress {
+    lockPath: string;
+    owner: FileLockOwner;
+    unlinked: boolean;
+    flushing?: Promise<void>;
+}
+export interface PendingFileLockRelease {
+    readonly key_digest: string;
+    readonly nonce: string;
+}
+/** Snapshot only: no filesystem access, retries, raw keys, paths or PIDs. */
+export declare function pendingFileOwnerReleases(directory: string): readonly PendingFileLockRelease[];
+/** Closed, bounded record; duplicate keys and fractional/exponent number tokens refuse. */
+export declare function parseFileLockOwner(raw: Buffer, filename: string): FileLockOwner | null;
+/** Unlink the observed nonce first. Missing old filename NEVER authorizes rmdir. */
+export declare function cleanFileLockOwner(lockPath: string, owner: FileLockOwner, temporary?: boolean, progress?: ReleaseProgress): Promise<void>;
+/** Decision 0022. Acquisition retry never contains callback execution. */
+export declare function withFileOwnerLock<T>(path: string, key: string, callback: () => T | Promise<T>, ttl: number, wait: number): Promise<T>;
+export {};

package/dist/stores/file-owner-lock.js

@@ -0,0 +1,280 @@
+import { randomBytes } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, rename, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { HarnessError } from '../errors.js';
+import { nativeLockIdentity, sameLockIdentity, lockPidIsDead } from './file-lock-identity.js';
+// Failed release is observable, then retried by this process's next lock call.
+// Key by nonce: old and replacement owners of one path must never overwrite
+// each other's pending state. No background timer keeps an idle worker alive.
+const pendingReleases = new Map();
+/** Snapshot only: no filesystem access, retries, raw keys, paths or PIDs. */
+export function pendingFileOwnerReleases(directory) {
+    const parent = resolve(directory);
+    const rows = [...pendingReleases.values()].filter(progress => dirname(progress.lockPath) === parent)
+        .map(progress => Object.freeze({ key_digest: basename(progress.lockPath, '.json.lock'), nonce: progress.owner.nonce }));
+    rows.sort((a, b) => a.key_digest === b.key_digest ? (a.nonce < b.nonce ? -1 : a.nonce > b.nonce ? 1 : 0) : (a.key_digest < b.key_digest ? -1 : 1));
+    return Object.freeze(rows);
+}
+const OWNER = /^owner-([0-9a-f]{32})\.json$/;
+const HELD = new Set(['EEXIST', 'ENOTEMPTY', 'EISDIR', 'ENOTDIR', 'EPERM', 'EACCES', 'EBUSY']);
+function code(error) { return error?.code; }
+function sleep(ms) { return new Promise(done => { setTimeout(done, ms); }); }
+function object(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+function keys(value, expected) { return Object.keys(value).sort().join(',') === expected.sort().join(','); }
+function bounded(value) { return typeof value === 'string' && value.length > 0 && Buffer.byteLength(value, 'utf8') <= 256 && Buffer.from(value, 'utf8').toString('utf8') === value; }
+/** Closed, bounded record; duplicate keys and fractional/exponent number tokens refuse. */
+export function parseFileLockOwner(raw, filename) {
+    if (raw.length > 4096 || raw.length === 0 || raw.at(-1) !== 10)
+        return null;
+    try {
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw);
+        const value = JSON.parse(text);
+        const tokens = text.match(/"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|[{}\[\]:,]|true|false|null/g) ?? [];
+        const seen = new Set();
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            if (token.startsWith('"') && tokens[i + 1] === ':') {
+                const key = JSON.parse(token);
+                if (seen.has(key))
+                    return null;
+                seen.add(key);
+            }
+            else if (/^-?\d/.test(token) && (!/^-?\d+$/.test(token) || !Number.isSafeInteger(Number(token))))
+                return null;
+        }
+        const match = OWNER.exec(filename);
+        if (!match || !object(value) || !keys(value, ['version', 'pid', 'identity', 'nonce', 'released', 'expires_at']))
+            return null;
+        if (value.version !== 2 || typeof value.pid !== 'number' || !Number.isInteger(value.pid) || value.pid < 1 || value.pid > 4294967295 ||
+            typeof value.released !== 'boolean' || typeof value.expires_at !== 'number' || !Number.isSafeInteger(value.expires_at) || value.nonce !== match[1])
+            return null;
+        const id = value.identity;
+        if (!object(id) || !keys(id, ['platform', 'boot_id', 'pid_namespace']) ||
+            typeof id.platform !== 'string' || !['linux', 'darwin', 'win32'].includes(id.platform) || !bounded(id.boot_id) ||
+            !(id.pid_namespace === null || bounded(id.pid_namespace)))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function filename(owner) { return 'owner-' + owner.nonce + '.json'; }
+function payload(owner) { return JSON.stringify(owner) + '\n'; }
+/** Unlink the observed nonce first. Missing old filename NEVER authorizes rmdir. */
+export async function cleanFileLockOwner(lockPath, owner, temporary = false, progress) {
+    if (temporary)
+        await unlink(join(lockPath, 'owner-' + owner.nonce + '.release.tmp')).catch(error => { if (code(error) !== 'ENOENT')
+            throw error; });
+    if (!progress?.unlinked)
+        for (let attempt = 0;; attempt++) {
+            try {
+                await unlink(join(lockPath, filename(owner)));
+                if (progress)
+                    progress.unlinked = true;
+                break;
+            }
+            catch (error) {
+                if (code(error) === 'ENOENT')
+                    return;
+                if (attempt >= 4 || !HELD.has(code(error) ?? ''))
+                    throw error;
+                await sleep(5);
+            }
+        }
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rmdir(lockPath);
+            return;
+        }
+        catch (error) {
+            // A replacement is populated, or somebody already removed the empty dir.
+            if (['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(code(error) ?? ''))
+                return;
+            if (attempt >= 4 || !HELD.has(code(error) ?? ''))
+                throw error;
+            await sleep(5);
+        }
+    }
+}
+async function inspect(lockPath, local) {
+    let owner, temporary;
+    try {
+        const info = await lstat(lockPath);
+        if (info.isSymbolicLink())
+            return 'held';
+        if (info.isFile())
+            return 'legacy';
+        if (!info.isDirectory())
+            return 'held';
+        const entries = await readdir(lockPath);
+        const names = entries.filter(name => OWNER.test(name));
+        if (names.length !== 1)
+            return 'held';
+        const name = names[0], release = name.replace('.json', '.release.tmp');
+        if (entries.some(entry => entry !== name && entry !== release))
+            return 'held';
+        temporary = entries.includes(release);
+        for (const entry of entries) {
+            const stat = await lstat(join(lockPath, entry));
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096)
+                return 'held';
+        }
+        owner = parseFileLockOwner(await readFile(join(lockPath, name)), name);
+        // Entire established identity must match BEFORE the first liveness probe.
+        if (!owner || !local || !sameLockIdentity(owner.identity, local))
+            return 'held';
+        if (!owner.released && !lockPidIsDead(owner.pid))
+            return 'held';
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return 'retry';
+        if (HELD.has(code(error) ?? ''))
+            return 'held';
+        throw error;
+    }
+    await cleanFileLockOwner(lockPath, owner, temporary);
+    return 'retry';
+}
+async function release(progress) {
+    const { lockPath, owner } = progress;
+    if (progress.unlinked) {
+        await cleanFileLockOwner(lockPath, owner, false, progress);
+        return;
+    }
+    const name = filename(owner);
+    try {
+        const observed = parseFileLockOwner(await readFile(join(lockPath, name)), name);
+        if (!observed || observed.nonce !== owner.nonce)
+            throw new Error('File lock owner changed before release');
+        if (observed.released) {
+            await cleanFileLockOwner(lockPath, owner, true, progress);
+            return;
+        }
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return;
+        throw error;
+    }
+    const temporary = join(lockPath, 'owner-' + owner.nonce + '.release.tmp');
+    // The callback has finished; close the full release record before publishing it.
+    // While this exact live owner is still unreleased, nobody may reclaim it.
+    // Retrying its own known nonce temporary can safely replace a partial write.
+    await writeFile(temporary, payload({ ...owner, released: true }), { encoding: 'utf8', flag: 'w' });
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rename(temporary, join(lockPath, name));
+            break;
+        }
+        catch (error) {
+            if (attempt >= 4 || !HELD.has(code(error) ?? ''))
+                throw error;
+            await sleep(5);
+        }
+    }
+    await cleanFileLockOwner(lockPath, owner, false, progress);
+}
+async function flushPendingReleases() {
+    for (const progress of [...pendingReleases.values()]) {
+        if (pendingReleases.get(progress.owner.nonce) !== progress)
+            continue;
+        if (!progress.flushing)
+            progress.flushing = release(progress);
+        const operation = progress.flushing;
+        try {
+            await operation;
+            if (pendingReleases.get(progress.owner.nonce) === progress)
+                pendingReleases.delete(progress.owner.nonce);
+        }
+        finally {
+            if (progress.flushing === operation)
+                progress.flushing = undefined;
+        }
+    }
+}
+/** Decision 0022. Acquisition retry never contains callback execution. */
+export async function withFileOwnerLock(path, key, callback, ttl, wait) {
+    if (!Number.isFinite(ttl) || !Number.isFinite(wait) || wait < 0 || !Number.isSafeInteger(Math.floor(Date.now() / 1000 + ttl)))
+        throw new RangeError('Invalid file lock duration');
+    await flushPendingReleases();
+    const lockPath = resolve(path);
+    try {
+        if ((await lstat(lockPath)).isFile())
+            throw new HarnessError('session_locked', 'legacy_lock_requires_maintenance: ' + lockPath + '; stop_old_workers_then_inspect_and_archive');
+    }
+    catch (error) {
+        if (code(error) !== 'ENOENT')
+            throw error;
+    }
+    const identity = nativeLockIdentity();
+    const platform = process.platform;
+    if (!identity && platform !== 'win32' && platform !== 'linux' && platform !== 'darwin')
+        throw new HarnessError('session_locked', 'Unsupported file-lock platform');
+    const owner = { version: 2, pid: process.pid, identity: identity ?? { platform: platform, boot_id: 'unknown', pid_namespace: null }, nonce: randomBytes(16).toString('hex'), released: false, expires_at: Math.floor(Date.now() / 1000 + ttl) };
+    if (identity?.pid_namespace == null)
+        process.emitWarning(JSON.stringify({ key_digest: basename(lockPath, '.json.lock'), nonce: owner.nonce }), { code: 'file_lock_identity_unavailable' });
+    const candidate = lockPath + '.candidate-' + owner.nonce;
+    if (dirname(candidate) !== dirname(lockPath) || basename(candidate) === basename(lockPath))
+        throw new Error('Lock publication must stay inside its parent');
+    const deadline = performance.now() + wait * 1000;
+    await mkdir(candidate);
+    let published = false;
+    try {
+        await writeFile(join(candidate, filename(owner)), payload(owner), { encoding: 'utf8', flag: 'wx' });
+        for (;;) {
+            if (pendingReleases.size)
+                await flushPendingReleases();
+            // Node/Windows rename can replace a regular file. Refuse stale legacy
+            // locks before publication; stopping ALL legacy workers is mandatory.
+            try {
+                const existing = await lstat(lockPath);
+                if (existing.isFile())
+                    throw new HarnessError('session_locked', 'legacy_lock_requires_maintenance: ' + lockPath + '; stop_old_workers_then_inspect_and_archive');
+                if (existing.isSymbolicLink() || !existing.isDirectory())
+                    throw HarnessError.sessionLocked(key, wait);
+            }
+            catch (error) {
+                if (code(error) !== 'ENOENT')
+                    throw error;
+            }
+            try {
+                await rename(candidate, lockPath);
+                published = true;
+                break;
+            }
+            catch (error) {
+                if (!HELD.has(code(error) ?? ''))
+                    throw error;
+            }
+            const state = await inspect(lockPath, identity);
+            if (state === 'legacy')
+                throw new HarnessError('session_locked', 'legacy_lock_requires_maintenance: ' + lockPath + '; stop_old_workers_then_inspect_and_archive');
+            if (state === 'retry' && performance.now() < deadline)
+                continue;
+            if (performance.now() >= deadline)
+                throw HarnessError.sessionLocked(key, wait);
+            await sleep(25);
+        }
+    }
+    finally {
+        if (!published)
+            await cleanFileLockOwner(candidate, owner);
+    }
+    // Exactly one execution, with exact original error identity on normal cleanup.
+    try {
+        return await callback();
+    }
+    finally {
+        const progress = { lockPath, owner, unlinked: false };
+        try {
+            await release(progress);
+        }
+        catch (error) {
+            pendingReleases.set(owner.nonce, progress);
+            process.emitWarning(JSON.stringify({ key_digest: basename(lockPath, '.json.lock'), nonce: owner.nonce }), { code: 'file_lock_release_pending' });
+            throw error;
+        }
+    }
+}

package/dist/stores/file-session-store.d.ts

@@ -1,4 +1,6 @@
 import type { JsonObject } from '../json.js';
+import type { FileLockIdentityStatus } from './file-lock-identity.js';
+import type { PendingFileLockRelease } from './file-owner-lock.js';
 import type { AppendLogStore, Durability, SessionStore } from './session-store.js';
 /**
  * State on disk, as one JSON file per key. DURABLE, and it says so.
@@ -16,17 +18,20 @@ import type { AppendLogStore, Durability, SessionStore } from './session-store.j
  * partial write here is a corrupted thread, and a process killed mid-write is
  * ordinary rather than exotic.
  *
- * **The lock is cross-process.** It is an exclusive-create lockfile (`wx`),
- * which is the one primitive that is atomic on every filesystem worth
- * supporting — unlike an "is it there?" check followed by a create, which has a
- * window between the two. Two workers on one machine genuinely exclude each
- * other. Two workers on different machines sharing a network filesystem do NOT
- * reliably, and no file lock can promise that; use a database or Redis there.
+ * **The lock is cross-process.** Decision 0022 uses an atomically published
+ * owner directory. TTL never proves death. Local filesystems on one host only;
+ * SMB/NFS are unsupported. Stop all old workers before upgrading and inspect
+ * legacy timestamp lockfiles explicitly. Use a database or Redis across hosts.
  */
 export declare class FileSessionStore implements SessionStore, AppendLogStore {
     #private;
     constructor(directory: string);
     durability(): Durability;
+    /** Local filesystem on one host; SMB/NFS sharing is unsupported. */
+    sharingScope(): 'host';
+    lockScope(): 'host' | 'process' | 'distributed' | 'unsupported';
+    /** Process discovery snapshot; this observer never starts metadata discovery. */
+    identityStatus(): FileLockIdentityStatus;
     get(key: string): Promise<JsonObject | null>;
     put(key: string, payload: JsonObject, ttlSeconds?: number | null): Promise<void>;
     forget(key: string): Promise<void>;
@@ -42,4 +47,6 @@ export declare class FileSessionStore implements SessionStore, AppendLogStore {
     logLength(key: string): Promise<number | null>;
     clearLog(key: string): Promise<void>;
     withLock<T>(key: string, callback: () => T | Promise<T>, ttlSeconds?: number, waitSeconds?: number): Promise<T>;
+    /** Pending release diagnostics for this directory; length is the pending count. */
+    pendingReleases(): readonly PendingFileLockRelease[];
 }