@sema-agent/core 7.5.2 → 7.6.1

package/dist/stores/file/fs-atomic.d.ts

@@ -184,10 +184,11 @@ export declare class FileStoreLockError extends Error {
     ownerPid?: number | undefined);
 }
 /**
- * The coarse boot guard (§2.4): an `O_EXCL` PID file (`root/LOCK` for the whole data dir; one per store
+ * The coarse boot guard (§2.4): an `O_EXCL` owner file (`root/LOCK` for the whole data dir; one per store
  * ledger directory via {@link acquireStoreDirLock}) that forbids two processes sharing it. A second
- * instance fails fast ("another instance owns this data dir"). A STALE lock (the writing PID is dead) is
- * pruned and re-acquired — `proper-lockfile`/CC `concurrentSessions` parity.
+ * instance fails fast ("another instance owns this data dir"). A STALE lock (the process that WROTE it is
+ * gone — see {@link isProcessLive}, which is not the same question as "is that pid free") is pruned and
+ * re-acquired — `proper-lockfile`/CC `concurrentSessions` parity.
  *
  * This is the family's ONE lock MECHANISM (the per-operation CAS stays in-process: one event loop + a
  * per-token async mutex, so there is NO per-operation flock). A holder of one of these fences guarantees
@@ -201,7 +202,7 @@ export declare class BootLock {
     /** The verdict of the ONE release this holding gets, replayed to any later caller (see {@link release}). */
     private spentVerdict;
     constructor(lockPath: string);
-    /** Acquire the lock or throw. Reclaims a lock whose recorded PID is not running (see below). */
+    /** Acquire the lock or throw. Reclaims a lock whose recorded OWNER is gone (see below). */
     acquire(): void;
     /**
      * @param depth how many stale reclaim gates deep we already are (see the gate below). Bounded so a
@@ -240,8 +241,8 @@ export declare class BootLock {
      *
      * ONE-SHOT, and that is load-bearing. This object stops being a holder the moment it is ASKED to release
      * — before the filesystem is touched — and a second call REPEATS the first verdict instead of acting on
-     * it again. A lock file is a bare pid, so two BootLocks over one path in this process are byte-identical
-     * on disk: after a FAILED release the path can legitimately be re-published (a later acquisition here
+     * it again. A lock file names its publishing PROCESS, so two BootLocks over one path in this process are
+     * byte-identical on disk: after a FAILED release the path can legitimately be re-published (a later acquisition here
      * finishing our cleanup), and a stale object that "removed its own lock" a second time would be deleting
      * the SUCCESSOR's fence while both sides believed they held the directory — the double-writer this whole
      * mechanism exists to refuse, minted from bookkeeping instead of from a race. So a second release answers
@@ -320,11 +321,86 @@ export declare function acquireStoreDirLock(dir: string, opts: {
  * stops two processes consolidating the SAME scope at once (the in-process model the file backend assumes —
  * see {@link BootLock} — does not cover a second OS process with its own timer).
  *
- * `acquire(scope)` writes `lockDir/<sanitizedScope>.consolidate.lock` carrying THIS pid (atomic
- * {@link writeThenLink}, so the lock appears with its pid already in it — no empty-window prune race). It
- * returns a `release` callback on success, or `undefined` when a LIVE owner already holds it (the caller
- * treats `undefined` as "busy → skip this pass", a no-op). A STALE lock (recorded pid is dead) is pruned and
- * re-acquired once. The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core
- * only DEFINES the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
+ * `acquire(scope)` takes a {@link BootLock} over `lockDir/<sanitizedScope>.consolidate.lock`. It returns a
+ * `release` callback on success, or `undefined` for EVERY refusal that lock knows how to make — a live
+ * owner (including this process: a second pass here is still a conflict), a takeover in flight, an
+ * unreadable file — because the caller's whole vocabulary is "busy → skip this pass", a no-op that costs
+ * one deferred consolidation. A stale lock is reclaimed by the same protocol as any other, which is the
+ * point of not hand-rolling one: this factory used to prune with a bare `unlink` and re-publish, and two
+ * passes that had both read the same dead owner would then both prune and both publish — one deleting the
+ * other's fresh lock, leaving two processes consolidating the SAME scope, which is exactly what the lock
+ * exists to prevent. The reclaim gate serialises that, the depth cap bounds it, and the identity re-read
+ * makes sure a reclaim prunes the owner it came for. One lock MECHANISM in this family, not two.
+ *
+ * The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core only DEFINES
+ * the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
  */
 export declare function createFileConsolidationLock(lockDir: string): (scope: string) => (() => void) | undefined;
+/**
+ * A process identity that survives PID REUSE: a pid, WHEN that pid's process started, and the host the
+ * observation was made on.
+ *
+ * A pid alone is not an identity. The OS hands the same number out again once its holder exits, so a lock
+ * (or lease, or any other durable "who owns this" record) carrying only a pid says no more than "somebody
+ * with that number" — and after a crash, an unrelated process that inherits the number makes the dead
+ * owner's record read as a LIVE owner for as long as that process lives. Adding the START TIME makes the
+ * record falsifiable: the pid narrows the candidate to one process, the start time decides whether it is
+ * still the SAME one.
+ *
+ * The start time is carried TWICE, against two different clocks, and that is the whole robustness of the
+ * thing. Both numbers come from ONE reading of the process's elapsed time, but one is subtracted from the
+ * WALL clock and the other from the host's UPTIME — and a platform that leaves one of them unmoved when
+ * the wall clock is corrected moves the other. (Where `ps` measures elapsed time against the boot clock, a
+ * corrected wall clock shifts the derived wall-clock start and leaves the uptime-relative one alone; where
+ * it measures against a stored absolute start, it is the other way round.) A comparison that insists on
+ * BOTH before calling a record stale therefore cannot be talked into a reclaim by a clock correction —
+ * which matters because that reclaim would be of a LIVE writer's lock. See {@link isProcessLive}.
+ *
+ * Both are `null` when this host cannot produce a start time (no `ps`, a cut-down `ps` that rejects the
+ * query, a probe too slow for its own reading to be worth anything). That is a plain "unknown" — never a
+ * zero and never a guess — and every consumer treats an unobtainable fingerprint as UNFALSIFIABLE, keeping
+ * the pid-only verdict: the degrade lands on yesterday's behaviour rather than on a wrong reclaim, and
+ * says so out loud once.
+ */
+export interface ProcessFingerprint {
+    /** The process id the rest of the record is about. */
+    readonly pid: number;
+    /** Start of that pid's process against the WALL clock, to the second; `null` when unobtainable here. */
+    readonly startedAtMs: number | null;
+    /** The same start against this host's UPTIME (ms after boot), to the second; `null` likewise. */
+    readonly startedSinceBootMs: number | null;
+    /** The host both were read on — a fingerprint from ANOTHER host is comparable to nothing here. */
+    readonly host: string;
+}
+/**
+ * The fingerprint of a process: this one when called with no pid, any other pid when named.
+ *
+ * ONE derivation for both halves of the mechanism — the record a holder WRITES and the probe a later reader
+ * verifies it with — on purpose. Deriving our own start time from `process.uptime()` instead would be
+ * cheaper, but it measures from Node's own initialisation rather than from the kernel's `exec`, so a busy
+ * machine can put the two derivations seconds apart. A reader comparing across them would then read a
+ * healthy holder as stale and RECLAIM A LIVE LOCK — a strictly worse failure than the pid reuse this fixes.
+ * One derivation makes the tolerance a rounding allowance instead of a guess about bootstrap latency.
+ *
+ * The self case is memoized: our start time cannot change, the probe is a subprocess, and a lock publish is
+ * the only place that needs it — so a process pays for it at most once, whatever it opens.
+ */
+export declare function processFingerprint(pid?: number): ProcessFingerprint;
+/**
+ * Is the process a record names still the one that wrote it? ONE predicate, two terms: the pid is running,
+ * AND the fingerprint has not been falsified.
+ *
+ * "Not falsified" is the load-bearing wording, and it is what every degrade lands on. A record with no
+ * `startedAtMs` (the pre-fingerprint spelling, or a host that cannot produce one), a record written on
+ * ANOTHER host (its start time was measured against a different boot — comparing it here would be
+ * arithmetic on unrelated numbers), and a probe that cannot answer all reach the same verdict: LIVE. The
+ * asymmetry is deliberate and is the whole safety argument — a false "dead" reclaims a directory out from
+ * under a working process (two writers, and the ledger loses whichever rows the loser never loaded), while
+ * a false "live" costs a refusal an operator can act on.
+ */
+export declare function isProcessLive(record: {
+    readonly pid: number;
+    readonly startedAtMs?: number | null;
+    readonly startedSinceBootMs?: number | null;
+    readonly host?: string | null;
+}): boolean;

package/dist/stores/file/fs-atomic.js

@@ -1,7 +1,9 @@
 import { closeSync, constants as FS, existsSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, truncateSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname, uptime } from "node:os";
+import { hrtime } from "node:process";
 import { basename, dirname, join, resolve as resolvePath } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
 const SAFE_COMPONENT = /^[A-Za-z0-9_.-]+$/;
 export function sanitizePathComponent(raw) {
     if (raw === "" || raw === "." || raw === ".." || !SAFE_COMPONENT.test(raw)) {
@@ -270,6 +272,64 @@ export class FileStoreLockError extends Error {
 const MAX_RECLAIM_DEPTH = 8;
 const MAX_ACQUIRE_ATTEMPTS = 4;
 const abandonedLocks = new Set();
+const LOCK_RECORD_VERSION = 2;
+function serializeLockRecord() {
+    const fp = processFingerprint();
+    return JSON.stringify({
+        v: LOCK_RECORD_VERSION,
+        pid: fp.pid,
+        startedAtMs: fp.startedAtMs,
+        startedSinceBootMs: fp.startedSinceBootMs,
+        host: fp.host,
+    });
+}
+function parseLockRecord(raw) {
+    if (/^[1-9][0-9]*$/.test(raw)) {
+        const barePid = Number.parseInt(raw, 10);
+        return Number.isSafeInteger(barePid) && barePid > 0
+            ? { pid: barePid, startedAtMs: null, startedSinceBootMs: null, host: null }
+            : null;
+    }
+    if (!raw.startsWith("{"))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    const rec = parsed;
+    if (typeof rec.pid !== "number" || !Number.isSafeInteger(rec.pid) || rec.pid <= 0)
+        return null;
+    const known = rec.v === LOCK_RECORD_VERSION;
+    const measure = (raw) => (known && typeof raw === "number" && Number.isFinite(raw) ? raw : null);
+    return {
+        pid: rec.pid,
+        startedAtMs: measure(rec.startedAtMs),
+        startedSinceBootMs: measure(rec.startedSinceBootMs),
+        host: known && typeof rec.host === "string" && rec.host !== "" ? rec.host : null,
+    };
+}
+function readLockRecord(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, "utf8").trim();
+    }
+    catch (err) {
+        return err.code === "ENOENT" ? { state: "absent" } : { state: "unreadable" };
+    }
+    const owner = parseLockRecord(raw);
+    return owner === null ? { state: "unreadable" } : { state: "owner", ...owner };
+}
+function sameOwner(a, b) {
+    return (a.pid === b.pid &&
+        a.startedAtMs === b.startedAtMs &&
+        a.startedSinceBootMs === b.startedSinceBootMs &&
+        a.host === b.host);
+}
 export class BootLock {
     lockPath;
     held = false;
@@ -302,7 +362,7 @@ export class BootLock {
                 this.pruneOwnAbandoned();
                 return;
             }
-            if (isProcessRunning(owner.pid)) {
+            if (isProcessLive(owner)) {
                 throw new FileStoreLockError("store.dir_in_use", `file store: another instance (pid ${owner.pid}) owns this data dir (${dirnameOf(this.lockPath)})`, this.lockPath, owner.pid);
             }
             if (depth >= MAX_RECLAIM_DEPTH) {
@@ -322,7 +382,7 @@ export class BootLock {
             }
             try {
                 const under = this.inspectLock();
-                if (under.state === "owner" && under.pid === owner.pid) {
+                if (under.state === "owner" && sameOwner(under, owner)) {
                     try {
                         unlinkSync(this.lockPath);
                     }
@@ -368,23 +428,13 @@ export class BootLock {
         this.publishOrLoseRace();
     }
     writeLock() {
-        writeThenLink(this.lockPath, String(process.pid));
+        writeThenLink(this.lockPath, serializeLockRecord());
     }
     get abandonKey() {
         return resolvePath(this.lockPath);
     }
     inspectLock() {
-        let raw;
-        try {
-            raw = readFileSync(this.lockPath, "utf8").trim();
-        }
-        catch (err) {
-            return err.code === "ENOENT" ? { state: "absent" } : { state: "unreadable" };
-        }
-        if (!/^[1-9][0-9]*$/.test(raw))
-            return { state: "unreadable" };
-        const pid = Number.parseInt(raw, 10);
-        return Number.isInteger(pid) && pid > 0 ? { state: "owner", pid } : { state: "unreadable" };
+        return readLockRecord(this.lockPath);
     }
     release() {
         if (!this.held) {
@@ -500,49 +550,18 @@ export function acquireStoreDirLock(dir, opts) {
 export function createFileConsolidationLock(lockDir) {
     return (scope) => {
         ensureDir(lockDir);
-        const lockPath = join(lockDir, `${sanitizeScope(scope)}.consolidate.lock`);
-        const tryWrite = () => {
-            try {
-                writeThenLink(lockPath, String(process.pid));
-                return true;
-            }
-            catch (err) {
-                if (err.code !== "EEXIST")
-                    throw err;
-                return false;
-            }
-        };
-        const readPid = () => {
-            try {
-                const raw = readFileSync(lockPath, "utf8").trim();
-                if (!/^[1-9][0-9]*$/.test(raw))
-                    return undefined;
-                const pid = Number.parseInt(raw, 10);
-                return Number.isInteger(pid) && pid > 0 ? pid : undefined;
-            }
-            catch {
-                return undefined;
-            }
-        };
-        const release = () => {
-            try {
-                if (readPid() === process.pid)
-                    unlinkSync(lockPath);
-            }
-            catch {
-            }
-        };
-        if (tryWrite())
-            return release;
-        const ownerPid = readPid();
-        if (ownerPid === undefined || isProcessRunning(ownerPid))
-            return undefined;
+        const lock = new BootLock(join(lockDir, `${sanitizeScope(scope)}.consolidate.lock`));
         try {
-            unlinkSync(lockPath);
+            lock.acquire();
         }
-        catch {
+        catch (err) {
+            if (err instanceof FileStoreLockError)
+                return undefined;
+            throw err;
         }
-        return tryWrite() ? release : undefined;
+        return () => {
+            lock.release();
+        };
     };
 }
 function isProcessRunning(pid) {
@@ -554,3 +573,113 @@ function isProcessRunning(pid) {
         return err.code === "EPERM";
     }
 }
+const START_TIME_TOLERANCE_MS = 2_000;
+const START_TIME_PROBE_TIMEOUT_MS = 2_000;
+const START_TIME_PROBE_PRECISION_MS = 250;
+const ETIME_PATTERN = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/;
+let cachedHostname;
+let selfFingerprint;
+let startTimeProbeUnavailable = false;
+function thisHost() {
+    return (cachedHostname ??= hostname());
+}
+function announceStartTimeDegrade(reason) {
+    if (startTimeProbeUnavailable)
+        return;
+    startTimeProbeUnavailable = true;
+    console.warn(`[sema] file store: this host cannot report process start times (${reason}), so a directory lock's owner ` +
+        `is judged by PID ALONE. A lock left behind by a crashed owner whose pid the OS has since handed to an ` +
+        `unrelated process then reads as a LIVE owner, and that directory stays refused until the lock file is ` +
+        `removed by hand.`);
+}
+const START_TIME_PROBE_ATTEMPTS = 3;
+function probeStartTimes(pid) {
+    for (let attempt = 0; attempt < START_TIME_PROBE_ATTEMPTS; attempt++) {
+        const reading = probeStartTimesOnce(pid);
+        if (reading !== "imprecise")
+            return reading;
+    }
+    return null;
+}
+function probeStartTimesOnce(pid) {
+    if (startTimeProbeUnavailable)
+        return null;
+    const knownToExist = pid === process.pid;
+    if (process.platform === "win32") {
+        announceStartTimeDegrade("no ps(1) on win32");
+        return null;
+    }
+    const monotonicBefore = hrtime.bigint();
+    const wallBefore = Date.now();
+    const uptimeBefore = Math.round(uptime() * 1000);
+    let raw;
+    try {
+        raw = execFileSync("ps", ["-p", String(pid), "-o", "etime="], {
+            encoding: "utf8",
+            timeout: START_TIME_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: { ...process.env, LC_ALL: "C", LANG: "C" },
+        });
+    }
+    catch (err) {
+        if (typeof err.status === "number") {
+            if (knownToExist)
+                announceStartTimeDegrade("ps refused a query about this very process");
+            return null;
+        }
+        announceStartTimeDegrade(`ps failed (${err.code ?? "unknown"})`);
+        return null;
+    }
+    const latency = Number(hrtime.bigint() - monotonicBefore) / 1e6;
+    const wallDelta = Date.now() - wallBefore;
+    const trimmed = raw.trim();
+    const parts = ETIME_PATTERN.exec(trimmed);
+    if (parts === null) {
+        if (trimmed !== "" || knownToExist)
+            announceStartTimeDegrade("ps produced no elapsed time");
+        return null;
+    }
+    if (latency > START_TIME_PROBE_PRECISION_MS)
+        return "imprecise";
+    if (Math.abs(wallDelta - latency) > START_TIME_PROBE_PRECISION_MS)
+        return "imprecise";
+    const elapsedMs = (Number(parts[1] ?? "0") * 86_400 + Number(parts[2] ?? "0") * 3_600 + Number(parts[3] ?? "0") * 60 + Number(parts[4] ?? "0")) *
+        1000;
+    return {
+        startedAtMs: Math.round((wallBefore - elapsedMs) / 1000) * 1000,
+        startedSinceBootMs: Math.round((uptimeBefore - elapsedMs) / 1000) * 1000,
+    };
+}
+export function processFingerprint(pid) {
+    const host = thisHost();
+    const of = (id, probed) => ({
+        pid: id,
+        startedAtMs: probed?.startedAtMs ?? null,
+        startedSinceBootMs: probed?.startedSinceBootMs ?? null,
+        host,
+    });
+    if (pid === undefined || pid === process.pid) {
+        if (selfFingerprint === undefined || selfFingerprint.startedAtMs === null) {
+            const answer = of(process.pid, probeStartTimes(process.pid));
+            if (answer.startedAtMs === null)
+                return answer;
+            selfFingerprint = answer;
+        }
+        return selfFingerprint;
+    }
+    if (processFingerprint().startedAtMs === null)
+        return of(pid, null);
+    return of(pid, probeStartTimes(pid));
+}
+export function isProcessLive(record) {
+    if (!isProcessRunning(record.pid))
+        return false;
+    if (record.host !== undefined && record.host !== null && record.host !== thisHost())
+        return true;
+    const observed = processFingerprint(record.pid);
+    const falsified = (was, now) => was !== undefined && was !== null && now !== null && now - was > START_TIME_TOLERANCE_MS;
+    const bootIsOver = (was) => was !== undefined && was !== null && was - Math.round(uptime() * 1000) > START_TIME_TOLERANCE_MS;
+    const wallSaysGone = falsified(record.startedAtMs, observed.startedAtMs);
+    const uptimeSaysGone = falsified(record.startedSinceBootMs, observed.startedSinceBootMs) || bootIsOver(record.startedSinceBootMs);
+    return !(wallSaysGone && uptimeSaysGone);
+}

package/dist/stores/file/index.d.ts

@@ -25,6 +25,7 @@ export { FileStrategyStore, type FileStrategyStoreOptions } from "./strategy-sto
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
+export { processFingerprint, isProcessLive, type ProcessFingerprint } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./adoption/adopt.js";
 /**

package/dist/stores/file/index.js

@@ -27,6 +27,7 @@ export { FileStrategyStore } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { FileStoreLockError } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
+export { processFingerprint, isProcessLive } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./adoption/adopt.js";
 export class FileStorageBackend {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.5.2",
+  "version": "7.6.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -76,7 +76,9 @@
     "gate:wire": "node scripts/wire-changes.mjs",
     "gate:layering": "node scripts/verify-layering.mjs",
     "gate:phase-api": "node scripts/verify-phase-api.mjs",
+    "gate:closed-sets": "node scripts/verify-closed-sets.mjs",
     "gate:agent-returns": "node scripts/verify-agent-returns.mjs",
+    "gate:contract-sentences": "node scripts/verify-contract-sentences.mjs",
     "gate:all": "node scripts/gate-all.mjs"
   },
   "dependencies": {