@sema-agent/core 7.6.0 → 7.6.1

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.6.0",
+  "version": "7.6.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2098,
+  "count": 2102,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -893,6 +893,7 @@
     "PrefixInputClass": "type",
     "ProbeCause": "interface",
     "ProbeCauseOperands": "interface",
+    "ProcessFingerprint": "interface",
     "ProjectMemoryLoad": "interface",
     "PromotedRecord": "interface",
     "PromptArtifactSource": "interface",
@@ -1079,6 +1080,7 @@
     "RunWorkflowToolDeps": "interface",
     "Runner": "class",
     "RunnerDeps": "interface",
+    "RunnerSelfSeat": "interface",
     "RuntimeCaps": "interface",
     "SAFETY_AXIS_VOCABULARY": "variable",
     "SAFETY_MERGE_CONFORMANCE_CORPUS": "variable",
@@ -1736,6 +1738,7 @@
     "isPeerSessionProcessAlive": "function",
     "isPermissionModeClass": "function",
     "isPersonalScope": "function",
+    "isProcessLive": "function",
     "isQuestionUnavailable": "function",
     "isRemoteExecutionEnv": "function",
     "isRetryableRemoteErrorCode": "function",
@@ -1878,6 +1881,7 @@
     "prepareStarterBatch": "function",
     "probeParkRoundTrip": "function",
     "probeSearchBackend": "function",
+    "processFingerprint": "function",
     "projectHumanInput": "function",
     "projectToolManifest": "function",
     "projectionsToWriteBack": "function",
@@ -2993,6 +2997,7 @@
     "PrefixInputClass": "advanced",
     "ProbeCause": "advanced",
     "ProbeCauseOperands": "advanced",
+    "ProcessFingerprint": "advanced",
     "ProjectMemoryLoad": "advanced",
     "PromotedRecord": "advanced",
     "PromptArtifactSource": "advanced",
@@ -3179,6 +3184,7 @@
     "RunWorkflowToolDeps": "advanced",
     "Runner": "stable",
     "RunnerDeps": "stable",
+    "RunnerSelfSeat": "internal",
     "RuntimeCaps": "stable",
     "SAFETY_AXIS_VOCABULARY": "advanced",
     "SAFETY_MERGE_CONFORMANCE_CORPUS": "advanced",
@@ -3836,6 +3842,7 @@
     "isPeerSessionProcessAlive": "advanced",
     "isPermissionModeClass": "advanced",
     "isPersonalScope": "advanced",
+    "isProcessLive": "advanced",
     "isQuestionUnavailable": "advanced",
     "isRemoteExecutionEnv": "advanced",
     "isRetryableRemoteErrorCode": "advanced",
@@ -3978,6 +3985,7 @@
     "prepareStarterBatch": "advanced",
     "probeParkRoundTrip": "stable",
     "probeSearchBackend": "advanced",
+    "processFingerprint": "advanced",
     "projectHumanInput": "advanced",
     "projectToolManifest": "advanced",
     "projectionsToWriteBack": "advanced",