@ai-agent-forge/agent-forge 0.85.0

package/dist/core/session-storage.js

@@ -0,0 +1,386 @@
+/**
+ * Storage seam for process sessions (D-067 phase 1).
+ *
+ * `SessionManager` owns the session tree, index, and context logic; a
+ * `SessionStorageProvider` owns only physical record storage for one session
+ * location. The default implementation is the current local JSONL file
+ * protocol, byte-identical to the pre-seam behavior; alternative providers
+ * (in-memory for tests, remote backends later) implement the same contract.
+ *
+ * Scope line: discovery/enrichment reads used by `SessionManager.list` /
+ * `listAll` (async streamed `SessionInfo` construction) stay on the fs path
+ * for now; they move behind this seam in a later phase.
+ *
+ * Cross-process write arbitration (D-067 phase 2 S5): providers may expose an
+ * optional {@link SessionWriteGuardV1}. The default file provider implements
+ * it as a `<sessionFile>.guard` sibling token ({ writerId, hostId, pid }): a
+ * write fails explicitly while another LIVE process on the same host owns the
+ * session, a dead owner (closed/crashed process) is taken over silently, and
+ * same-process writers are never conflicted (in-process sequencing is the
+ * caller's concern, unchanged). Cross-host guards are treated as live
+ * foreign owners (conservative: no false takeover over shared filesystems).
+ */
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, statSync, truncateSync, unlinkSync, writeFileSync, writeSync, } from "fs";
+import { hostname } from "os";
+import { dirname, join } from "path";
+import { StringDecoder } from "string_decoder";
+import { normalizePath } from "../utils/paths.js";
+import { sleepSync } from "../utils/sync-sleep.js";
+const SESSION_READ_BUFFER_SIZE = 1024 * 1024;
+const SESSION_HEADER_READ_BUFFER_SIZE = 4096;
+/** Bound synchronous header discovery while allowing large cwd and custom metadata fields. */
+const MAX_SESSION_HEADER_SCAN_BYTES = 1024 * 1024;
+/**
+ * Thrown by `readHeader` when the header scan exceeds the bounded limit.
+ * `SessionManager.open` treats it as a discovery optimization miss and falls
+ * back to a full load; discovery callers swallow it.
+ */
+export class SessionHeaderScanLimitError extends Error {
+    constructor(filePath) {
+        super(`Session header exceeds ${MAX_SESSION_HEADER_SCAN_BYTES}-byte scan limit: ${filePath}`);
+        this.name = "SessionHeaderScanLimitError";
+    }
+}
+function parseSessionEntryLine(line) {
+    if (!line.trim())
+        return null;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        // Skip malformed lines
+        return null;
+    }
+}
+/** Serialize one entry as a protocol line (JSON body plus terminating newline). */
+function serializeEntryLine(entry) {
+    return `${JSON.stringify(entry)}\n`;
+}
+function parseSessionHeaderCandidate(line) {
+    if (!line.trim())
+        return undefined;
+    const entry = parseSessionEntryLine(line);
+    if (!entry)
+        return undefined;
+    if (entry.type !== "session" || typeof entry.id !== "string")
+        return null;
+    return entry;
+}
+/** Suffix of the session write-guard sibling file (`<sessionFile>.guard`). */
+const GUARD_FILE_SUFFIX = ".guard";
+/** Wall-clock wait between guard-lock acquisition attempts (ledger protocol value). */
+const GUARD_LOCK_POLL_INTERVAL_MS = 25;
+/** Default ceiling on waiting for a competing guard-lock holder. */
+const GUARD_LOCK_TIMEOUT_MS = 5000;
+/** Default age at which a guard-lock counts as abandoned and is stolen. */
+const GUARD_STALE_LOCK_MS = 60_000;
+function defaultPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but is owned by another user — alive.
+        return error.code === "EPERM";
+    }
+}
+/** Writes every byte of `data` to the fd, looping over partial writeSync results. */
+function writeAllSync(fd, data) {
+    const buffer = Buffer.from(data, "utf8");
+    let written = 0;
+    while (written < buffer.length) {
+        written += writeSync(fd, buffer, written, buffer.length - written);
+    }
+}
+/**
+ * Takes the guard's cross-process lock (same protocol as the memory ledger's
+ * and the durable store's persist locks — exclusive create, poll, mtime
+ * stale-lock stealing, token-guarded release; the three implementations stay
+ * behaviorally identical by precedent, deliberately without module coupling).
+ */
+function acquireGuardLock(lockPath, lockTimeoutMs, staleLockMs) {
+    const deadline = Date.now() + lockTimeoutMs;
+    for (;;) {
+        mkdirSync(dirname(lockPath), { recursive: true });
+        const token = `${process.pid}:${Date.now()}`;
+        try {
+            const fd = openSync(lockPath, "wx");
+            try {
+                writeFileSync(fd, token);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return token;
+        }
+        catch (error) {
+            const code = error.code;
+            // POSIX maps a lost create race to EEXIST; Windows/libuv maps the
+            // same concurrent-create sharing violation to EPERM. For EPERM a
+            // vanished lock retries, a persistent permission failure propagates.
+            if (code === "EPERM") {
+                let vanished = false;
+                try {
+                    statSync(lockPath);
+                }
+                catch (statError) {
+                    if (statError.code !== "ENOENT")
+                        throw error;
+                    vanished = true;
+                }
+                if (vanished) {
+                    if (Date.now() >= deadline)
+                        throw error;
+                    sleepSync(GUARD_LOCK_POLL_INTERVAL_MS);
+                    continue;
+                }
+            }
+            else if (code !== "EEXIST") {
+                throw error;
+            }
+            let stale = false;
+            try {
+                stale = Date.now() - statSync(lockPath).mtimeMs > staleLockMs;
+            }
+            catch {
+                // The holder released between the failed open and the stat.
+            }
+            if (stale) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    // Already stolen — retry.
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`session guard lock timeout after ${lockTimeoutMs} ms: ${lockPath}`);
+            }
+            sleepSync(GUARD_LOCK_POLL_INTERVAL_MS);
+        }
+    }
+}
+/** Releases the guard lock, but only if our own token still owns it. */
+function releaseGuardLock(lockPath, token) {
+    try {
+        if (readFileSync(lockPath, "utf8") === token)
+            unlinkSync(lockPath);
+    }
+    catch {
+        // Already gone (or unreadable) — nothing to release.
+    }
+}
+/**
+ * The default provider: the local JSONL file protocol, moved verbatim from
+ * `SessionManager`. Stateless beyond the injectable guard identity options,
+ * so a shared module-level instance is the default for every session manager
+ * that does not inject its own provider.
+ */
+export class FileSessionStorageProvider {
+    /** Shared stateless instance used as the default provider. */
+    static instance = new FileSessionStorageProvider();
+    hostId;
+    ownPid;
+    pidAlive;
+    constructor(options = {}) {
+        this.hostId = options.hostId ?? hostname();
+        this.ownPid = options.ownPid ?? process.pid;
+        this.pidAlive = options.pidAlive ?? defaultPidAlive;
+    }
+    ensureDir(dir) {
+        mkdirSync(dir, { recursive: true });
+    }
+    exists(path) {
+        return existsSync(path);
+    }
+    size(path) {
+        return statSync(path).size;
+    }
+    loadEntries(path) {
+        const resolvedFilePath = normalizePath(path);
+        if (!existsSync(resolvedFilePath))
+            return [];
+        const entries = [];
+        let pending = "";
+        const fd = openSync(resolvedFilePath, "r");
+        try {
+            const decoder = new StringDecoder("utf8");
+            const buffer = Buffer.allocUnsafe(SESSION_READ_BUFFER_SIZE);
+            while (true) {
+                const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
+                if (bytesRead === 0)
+                    break;
+                pending += decoder.write(buffer.subarray(0, bytesRead));
+                let lineStart = 0;
+                let newlineIndex = pending.indexOf("\n", lineStart);
+                while (newlineIndex !== -1) {
+                    const entry = parseSessionEntryLine(pending.slice(lineStart, newlineIndex));
+                    if (entry)
+                        entries.push(entry);
+                    lineStart = newlineIndex + 1;
+                    newlineIndex = pending.indexOf("\n", lineStart);
+                }
+                pending = pending.slice(lineStart);
+            }
+            pending += decoder.end();
+            const finalEntry = parseSessionEntryLine(pending);
+            if (finalEntry)
+                entries.push(finalEntry);
+        }
+        finally {
+            closeSync(fd);
+        }
+        // Validate session header before repairing the file.
+        if (entries.length === 0)
+            return entries;
+        const header = entries[0];
+        if (header.type !== "session" || typeof header.id !== "string") {
+            return [];
+        }
+        if (pending)
+            appendFileSync(resolvedFilePath, "\n");
+        return entries;
+    }
+    readHeader(path) {
+        if (!existsSync(path))
+            return null;
+        const fd = openSync(path, "r");
+        try {
+            const decoder = new StringDecoder("utf8");
+            const buffer = Buffer.allocUnsafe(SESSION_HEADER_READ_BUFFER_SIZE);
+            const lineChunks = [];
+            let scannedBytes = 0;
+            while (scannedBytes < MAX_SESSION_HEADER_SCAN_BYTES) {
+                const readLength = Math.min(buffer.length, MAX_SESSION_HEADER_SCAN_BYTES - scannedBytes);
+                const bytesRead = readSync(fd, buffer, 0, readLength, null);
+                if (bytesRead === 0) {
+                    lineChunks.push(decoder.end());
+                    return parseSessionHeaderCandidate(lineChunks.join("")) ?? null;
+                }
+                scannedBytes += bytesRead;
+                const chunk = decoder.write(buffer.subarray(0, bytesRead));
+                let lineStart = 0;
+                let newlineIndex = chunk.indexOf("\n", lineStart);
+                while (newlineIndex !== -1) {
+                    lineChunks.push(chunk.slice(lineStart, newlineIndex));
+                    const header = parseSessionHeaderCandidate(lineChunks.join(""));
+                    if (header !== undefined)
+                        return header;
+                    lineChunks.length = 0;
+                    lineStart = newlineIndex + 1;
+                    newlineIndex = chunk.indexOf("\n", lineStart);
+                }
+                lineChunks.push(chunk.slice(lineStart));
+            }
+            // Probe for EOF so a final header without a newline is allowed when it ends
+            // exactly at the scan limit. Any additional byte exceeds the bounded scan.
+            const probe = Buffer.allocUnsafe(1);
+            if (readSync(fd, probe, 0, probe.length, null) === 0) {
+                lineChunks.push(decoder.end());
+                return parseSessionHeaderCandidate(lineChunks.join("")) ?? null;
+            }
+            throw new SessionHeaderScanLimitError(path);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    rewrite(path, entries) {
+        const fd = openSync(path, "w");
+        try {
+            for (const entry of entries) {
+                writeFileSync(fd, serializeEntryLine(entry));
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    createExclusive(path, entries) {
+        const fd = openSync(path, "wx");
+        try {
+            for (const entry of entries) {
+                writeFileSync(fd, serializeEntryLine(entry));
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    append(path, entry) {
+        appendFileSync(path, serializeEntryLine(entry));
+    }
+    truncate(path, size) {
+        truncateSync(path, size);
+    }
+    remove(path) {
+        unlinkSync(path);
+    }
+    listSessionFiles(dir) {
+        const resolvedDir = normalizePath(dir);
+        return readdirSync(resolvedDir)
+            .filter((f) => f.endsWith(".jsonl"))
+            .map((f) => join(resolvedDir, f));
+    }
+    modifiedTime(path) {
+        return statSync(path).mtime;
+    }
+    /**
+     * Cross-process write guard (D-067 phase 2 S5): `<sessionFile>.guard`
+     * carries `{ writerId, hostId, pid }`. A write conflicts only while the
+     * recorded owner is a live process on this host; a dead owner (closed or
+     * crashed process) and same-process writers never conflict, and cross-host
+     * guards are treated as live foreign owners (conservative over shared
+     * filesystems). Check-and-take-ownership is atomic under the guard lock.
+     */
+    guard = {
+        ensureWritable: (sessionFile, writerId) => {
+            const guardPath = `${sessionFile}${GUARD_FILE_SUFFIX}`;
+            const readToken = () => {
+                try {
+                    const value = JSON.parse(readFileSync(guardPath, "utf8"));
+                    if (typeof value !== "object" || value === null || Array.isArray(value))
+                        return undefined;
+                    const record = value;
+                    if (typeof record.writerId !== "string" || record.writerId.length === 0)
+                        return undefined;
+                    if (typeof record.hostId !== "string" || record.hostId.length === 0)
+                        return undefined;
+                    if (typeof record.pid !== "number" || !Number.isInteger(record.pid))
+                        return undefined;
+                    return { writerId: record.writerId, hostId: record.hostId, pid: record.pid };
+                }
+                catch {
+                    return undefined;
+                }
+            };
+            const current = readToken();
+            // Fast path: already ours (most appends), or no owner.
+            if (current !== undefined && current.writerId === writerId)
+                return;
+            if (current !== undefined) {
+                const foreignLive = current.hostId === this.hostId && current.pid !== this.ownPid && this.pidAlive(current.pid);
+                if (foreignLive) {
+                    throw new Error(`Session file is owned by another live process (pid ${current.pid}): ${sessionFile}. ` +
+                        "Close that process first; concurrent writers would silently fork the session history.");
+                }
+            }
+            // Free, dead owner, or same-process writer: take (or refresh) ownership.
+            const token = acquireGuardLock(`${guardPath}.lock`, GUARD_LOCK_TIMEOUT_MS, GUARD_STALE_LOCK_MS);
+            try {
+                const fd = openSync(guardPath, "w");
+                try {
+                    writeAllSync(fd, JSON.stringify({ writerId, hostId: this.hostId, pid: this.ownPid }));
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            finally {
+                releaseGuardLock(`${guardPath}.lock`, token);
+            }
+        },
+    };
+}
+//# sourceMappingURL=session-storage.js.map

package/dist/core/session-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.js","sourceRoot":"","sources":["../../src/core/session-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACN,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,aAAa,EACb,SAAS,GACT,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,MAAM,wBAAwB,GAAG,IAAI,GAAG,IAAI,CAAC;AAC7C,MAAM,+BAA+B,GAAG,IAAI,CAAC;AAC7C,8FAA8F;AAC9F,MAAM,6BAA6B,GAAG,IAAI,GAAG,IAAI,CAAC;AAElD;;;;GAIG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACrD,YAAY,QAAgB,EAAE;QAC7B,KAAK,CAAC,0BAA0B,6BAA6B,qBAAqB,QAAQ,EAAE,CAAC,CAAC;QAC9F,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAAA,CAC1C;CACD;AA4DD,SAAS,qBAAqB,CAAC,IAAY,EAAoB;IAC9D,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAc,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACR,uBAAuB;QACvB,OAAO,IAAI,CAAC;IACb,CAAC;AAAA,CACD;AAED,mFAAmF;AACnF,SAAS,kBAAkB,CAAC,KAAgB,EAAU;IACrD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;AAAA,CACpC;AAED,SAAS,2BAA2B,CAAC,IAAY,EAAoC;IACpF,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IACnC,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,OAAQ,KAA0B,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAChG,OAAO,KAAK,CAAC;AAAA,CACb;AAED,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AACnC,uFAAuF;AACvF,MAAM,2BAA2B,GAAG,EAAE,CAAC;AACvC,oEAAoE;AACpE,MAAM,qBAAqB,GAAG,IAAI,CAAC;AACnC,2EAA2E;AAC3E,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAQnC,SAAS,eAAe,CAAC,GAAW,EAAW;IAC9C,IAAI,CAAC;QACJ,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,yEAAuE;QACvE,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAC1D,CAAC;AAAA,CACD;AAED,qFAAqF;AACrF,SAAS,YAAY,CAAC,EAAU,EAAE,IAAY,EAAQ;IACrD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAChC,OAAO,IAAI,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;IACpE,CAAC;AAAA,CACD;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,QAAgB,EAAE,aAAqB,EAAE,WAAmB,EAAU;IAC/F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC;IAC5C,SAAS,CAAC;QACT,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC;YACJ,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC;gBACJ,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YAC1B,CAAC;oBAAS,CAAC;gBACV,SAAS,CAAC,EAAE,CAAC,CAAC;YACf,CAAC;YACD,OAAO,KAAK,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;YACnD,kEAAkE;YAClE,iEAAiE;YACjE,qEAAqE;YACrE,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACtB,IAAI,QAAQ,GAAG,KAAK,CAAC;gBACrB,IAAI,CAAC;oBACJ,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBACpB,CAAC;gBAAC,OAAO,SAAS,EAAE,CAAC;oBACpB,IAAK,SAAmC,CAAC,IAAI,KAAK,QAAQ;wBAAE,MAAM,KAAK,CAAC;oBACxE,QAAQ,GAAG,IAAI,CAAC;gBACjB,CAAC;gBACD,IAAI,QAAQ,EAAE,CAAC;oBACd,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;wBAAE,MAAM,KAAK,CAAC;oBACxC,SAAS,CAAC,2BAA2B,CAAC,CAAC;oBACvC,SAAS;gBACV,CAAC;YACF,CAAC;iBAAM,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,KAAK,CAAC;YACb,CAAC;YACD,IAAI,KAAK,GAAG,KAAK,CAAC;YAClB,IAAI,CAAC;gBACJ,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,GAAG,WAAW,CAAC;YAC/D,CAAC;YAAC,MAAM,CAAC;gBACR,4DAA4D;YAC7D,CAAC;YACD,IAAI,KAAK,EAAE,CAAC;gBACX,IAAI,CAAC;oBACJ,UAAU,CAAC,QAAQ,CAAC,CAAC;gBACtB,CAAC;gBAAC,MAAM,CAAC;oBACR,4BAA0B;gBAC3B,CAAC;gBACD,SAAS;YACV,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,oCAAoC,aAAa,QAAQ,QAAQ,EAAE,CAAC,CAAC;YACtF,CAAC;YACD,SAAS,CAAC,2BAA2B,CAAC,CAAC;QACxC,CAAC;IACF,CAAC;AAAA,CACD;AAED,wEAAwE;AACxE,SAAS,gBAAgB,CAAC,QAAgB,EAAE,KAAa,EAAQ;IAChE,IAAI,CAAC;QACJ,IAAI,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,KAAK;YAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACR,uDAAqD;IACtD,CAAC;AAAA,CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,0BAA0B;IACtC,8DAA8D;IAC9D,MAAM,CAAU,QAAQ,GAA+B,IAAI,0BAA0B,EAAE,CAAC;IAEvE,MAAM,CAAS;IACf,MAAM,CAAS;IACf,QAAQ,CAA2B;IAEpD,YACC,OAAO,GAOH,EAAE,EACL;QACD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IAAA,CACpD;IAED,SAAS,CAAC,GAAW,EAAQ;QAC5B,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAAA,CACpC;IAED,MAAM,CAAC,IAAY,EAAW;QAC7B,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAAA,CACxB;IAED,IAAI,CAAC,IAAY,EAAU;QAC1B,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IAAA,CAC3B;IAED,WAAW,CAAC,IAAY,EAAe;QACtC,MAAM,gBAAgB,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC;YAAE,OAAO,EAAE,CAAC;QAE7C,MAAM,OAAO,GAAgB,EAAE,CAAC;QAChC,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,MAAM,EAAE,GAAG,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;YAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAAC;YAE5D,OAAO,IAAI,EAAE,CAAC;gBACb,MAAM,SAAS,GAAG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAC/D,IAAI,SAAS,KAAK,CAAC;oBAAE,MAAM;gBAE3B,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;gBACxD,IAAI,SAAS,GAAG,CAAC,CAAC;gBAClB,IAAI,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBACpD,OAAO,YAAY,KAAK,CAAC,CAAC,EAAE,CAAC;oBAC5B,MAAM,KAAK,GAAG,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;oBAC5E,IAAI,KAAK;wBAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBAC/B,SAAS,GAAG,YAAY,GAAG,CAAC,CAAC;oBAC7B,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBACjD,CAAC;gBACD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACpC,CAAC;YAED,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;YAClD,IAAI,UAAU;gBAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1C,CAAC;gBAAS,CAAC;YACV,SAAS,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;QAED,qDAAqD;QACrD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,OAAQ,MAA2B,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YACtF,OAAO,EAAE,CAAC;QACX,CAAC;QAED,IAAI,OAAO;YAAE,cAAc,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC;IAAA,CACf;IAED,UAAU,CAAC,IAAY,EAAwB;QAC9C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;YAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,+BAA+B,CAAC,CAAC;YACnE,MAAM,UAAU,GAAa,EAAE,CAAC;YAChC,IAAI,YAAY,GAAG,CAAC,CAAC;YAErB,OAAO,YAAY,GAAG,6BAA6B,EAAE,CAAC;gBACrD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,6BAA6B,GAAG,YAAY,CAAC,CAAC;gBACzF,MAAM,SAAS,GAAG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;gBAC5D,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;oBACrB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;oBAC/B,OAAO,2BAA2B,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC;gBACjE,CAAC;gBACD,YAAY,IAAI,SAAS,CAAC;gBAE1B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;gBAC3D,IAAI,SAAS,GAAG,CAAC,CAAC;gBAClB,IAAI,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBAClD,OAAO,YAAY,KAAK,CAAC,CAAC,EAAE,CAAC;oBAC5B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;oBACtD,MAAM,MAAM,GAAG,2BAA2B,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;oBAChE,IAAI,MAAM,KAAK,SAAS;wBAAE,OAAO,MAAM,CAAC;oBACxC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;oBACtB,SAAS,GAAG,YAAY,GAAG,CAAC,CAAC;oBAC7B,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBAC/C,CAAC;gBACD,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YACzC,CAAC;YAED,4EAA4E;YAC5E,2EAA2E;YAC3E,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACpC,IAAI,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACtD,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;gBAC/B,OAAO,2BAA2B,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC;YACjE,CAAC;YACD,MAAM,IAAI,2BAA2B,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACV,SAAS,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;IAAA,CACD;IAED,OAAO,CAAC,IAAY,EAAE,OAA6B,EAAQ;QAC1D,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC;YACJ,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC7B,aAAa,CAAC,EAAE,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9C,CAAC;QACF,CAAC;gBAAS,CAAC;YACV,SAAS,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;IAAA,CACD;IAED,eAAe,CAAC,IAAY,EAAE,OAA6B,EAAQ;QAClE,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC;YACJ,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC7B,aAAa,CAAC,EAAE,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9C,CAAC;QACF,CAAC;gBAAS,CAAC;YACV,SAAS,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;IAAA,CACD;IAED,MAAM,CAAC,IAAY,EAAE,KAAgB,EAAQ;QAC5C,cAAc,CAAC,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;IAAA,CAChD;IAED,QAAQ,CAAC,IAAY,EAAE,IAAY,EAAQ;QAC1C,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAAA,CACzB;IAED,MAAM,CAAC,IAAY,EAAQ;QAC1B,UAAU,CAAC,IAAI,CAAC,CAAC;IAAA,CACjB;IAED,gBAAgB,CAAC,GAAW,EAAY;QACvC,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QACvC,OAAO,WAAW,CAAC,WAAW,CAAC;aAC7B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;aACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;IAAA,CACnC;IAED,YAAY,CAAC,IAAY,EAAQ;QAChC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;IAAA,CAC5B;IAED;;;;;;;OAOG;IACM,KAAK,GAAwB;QACrC,cAAc,EAAE,CAAC,WAAmB,EAAE,QAAgB,EAAQ,EAAE,CAAC;YAChE,MAAM,SAAS,GAAG,GAAG,WAAW,GAAG,iBAAiB,EAAE,CAAC;YACvD,MAAM,SAAS,GAAG,GAAoC,EAAE,CAAC;gBACxD,IAAI,CAAC;oBACJ,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;oBACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;wBAAE,OAAO,SAAS,CAAC;oBAC1F,MAAM,MAAM,GAAG,KAAgE,CAAC;oBAChF,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;wBAAE,OAAO,SAAS,CAAC;oBAC1F,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;wBAAE,OAAO,SAAS,CAAC;oBACtF,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC;wBAAE,OAAO,SAAS,CAAC;oBACtF,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;gBAC9E,CAAC;gBAAC,MAAM,CAAC;oBACR,OAAO,SAAS,CAAC;gBAClB,CAAC;YAAA,CACD,CAAC;YAEF,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;YAC5B,uDAAuD;YACvD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;gBAAE,OAAO;YACnE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,WAAW,GAChB,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC7F,IAAI,WAAW,EAAE,CAAC;oBACjB,MAAM,IAAI,KAAK,CACd,sDAAsD,OAAO,CAAC,GAAG,MAAM,WAAW,IAAI;wBACrF,uFAAuF,CACxF,CAAC;gBACH,CAAC;YACF,CAAC;YACD,yEAAyE;YACzE,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,SAAS,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,CAAC,CAAC;YAChG,IAAI,CAAC;gBACJ,MAAM,EAAE,GAAG,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;gBACpC,IAAI,CAAC;oBACJ,YAAY,CACX,EAAE,EACF,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAgC,CAAC,CACjG,CAAC;gBACH,CAAC;wBAAS,CAAC;oBACV,SAAS,CAAC,EAAE,CAAC,CAAC;gBACf,CAAC;YACF,CAAC;oBAAS,CAAC;gBACV,gBAAgB,CAAC,GAAG,SAAS,OAAO,EAAE,KAAK,CAAC,CAAC;YAC9C,CAAC;QAAA,CACD;KACD,CAAC;CACF","sourcesContent":["/**\n * Storage seam for process sessions (D-067 phase 1).\n *\n * `SessionManager` owns the session tree, index, and context logic; a\n * `SessionStorageProvider` owns only physical record storage for one session\n * location. The default implementation is the current local JSONL file\n * protocol, byte-identical to the pre-seam behavior; alternative providers\n * (in-memory for tests, remote backends later) implement the same contract.\n *\n * Scope line: discovery/enrichment reads used by `SessionManager.list` /\n * `listAll` (async streamed `SessionInfo` construction) stay on the fs path\n * for now; they move behind this seam in a later phase.\n *\n * Cross-process write arbitration (D-067 phase 2 S5): providers may expose an\n * optional {@link SessionWriteGuardV1}. The default file provider implements\n * it as a `<sessionFile>.guard` sibling token ({ writerId, hostId, pid }): a\n * write fails explicitly while another LIVE process on the same host owns the\n * session, a dead owner (closed/crashed process) is taken over silently, and\n * same-process writers are never conflicted (in-process sequencing is the\n * caller's concern, unchanged). Cross-host guards are treated as live\n * foreign owners (conservative: no false takeover over shared filesystems).\n */\n\nimport {\n\tappendFileSync,\n\tcloseSync,\n\texistsSync,\n\tmkdirSync,\n\topenSync,\n\treaddirSync,\n\treadFileSync,\n\treadSync,\n\tstatSync,\n\ttruncateSync,\n\tunlinkSync,\n\twriteFileSync,\n\twriteSync,\n} from \"fs\";\nimport { hostname } from \"os\";\nimport { dirname, join } from \"path\";\nimport { StringDecoder } from \"string_decoder\";\nimport { normalizePath } from \"../utils/paths.ts\";\nimport { sleepSync } from \"../utils/sync-sleep.ts\";\nimport type { FileEntry, SessionHeader } from \"./session-manager.ts\";\n\nconst SESSION_READ_BUFFER_SIZE = 1024 * 1024;\nconst SESSION_HEADER_READ_BUFFER_SIZE = 4096;\n/** Bound synchronous header discovery while allowing large cwd and custom metadata fields. */\nconst MAX_SESSION_HEADER_SCAN_BYTES = 1024 * 1024;\n\n/**\n * Thrown by `readHeader` when the header scan exceeds the bounded limit.\n * `SessionManager.open` treats it as a discovery optimization miss and falls\n * back to a full load; discovery callers swallow it.\n */\nexport class SessionHeaderScanLimitError extends Error {\n\tconstructor(filePath: string) {\n\t\tsuper(`Session header exceeds ${MAX_SESSION_HEADER_SCAN_BYTES}-byte scan limit: ${filePath}`);\n\t\tthis.name = \"SessionHeaderScanLimitError\";\n\t}\n}\n\n/**\n * Record-level storage contract for sessions, keyed by location path. All\n * methods are synchronous and reflect the append-only JSONL protocol\n * semantics; implementations for other media map the same operations onto\n * their own storage model.\n */\nexport interface SessionStorageProvider {\n\t/** Ensure the storage location for a session directory exists. */\n\tensureDir(dir: string): void;\n\t/** True when the given session location exists. */\n\texists(path: string): boolean;\n\t/** Current byte size of a session location (rollback baseline). Missing locations throw. */\n\tsize(path: string): number;\n\t/**\n\t * Load all entries (header first). A missing location yields `[]`. When the\n\t * stored content ends with an unterminated final line, implementations\n\t * repair it by terminating it (the file protocol appends a `\\n`).\n\t */\n\tloadEntries(path: string): FileEntry[];\n\t/** Bounded header scan used for discovery and cwd resolution. Missing or header-less locations yield `null`. */\n\treadHeader(path: string): SessionHeader | null;\n\t/** Replace the whole stored content (header included). */\n\trewrite(path: string, entries: readonly FileEntry[]): void;\n\t/** Write initial content; fails when the location already exists (\"wx\" semantics). */\n\tcreateExclusive(path: string, entries: readonly FileEntry[]): void;\n\t/** Append one entry after the existing content. */\n\tappend(path: string, entry: FileEntry): void;\n\t/** Roll back to a previous byte size after a failed append. */\n\ttruncate(path: string, size: number): void;\n\t/** Remove a session location (used when a failed append created it). */\n\tremove(path: string): void;\n\t/** Enumerate session locations inside a directory. Missing directories throw. */\n\tlistSessionFiles(dir: string): string[];\n\t/** Modification time of a session location, used for recent-session ordering. */\n\tmodifiedTime(path: string): Date;\n\t/**\n\t * Optional cross-process write guard (D-067 phase 2 S5). When present,\n\t * `SessionManager` calls `ensureWritable` before every record write and a\n\t * conflicting live foreign owner fails the write explicitly; absent, no\n\t * arbitration happens (the pre-S5 behavior).\n\t */\n\treadonly guard?: SessionWriteGuardV1;\n}\n\n/**\n * Cross-process write guard for one session location (D-067 phase 2 S5).\n * Implementations must make \"check and take ownership\" atomic against other\n * processes, and must throw a descriptive error when another live process\n * owns the session instead of letting two writers interleave entries.\n */\nexport interface SessionWriteGuardV1 {\n\t/**\n\t * Verifies the caller may write the session and records (or refreshes) its\n\t * ownership. Throws when another live process owns the session.\n\t */\n\tensureWritable(sessionFile: string, writerId: string): void;\n}\n\nfunction parseSessionEntryLine(line: string): FileEntry | null {\n\tif (!line.trim()) return null;\n\ttry {\n\t\treturn JSON.parse(line) as FileEntry;\n\t} catch {\n\t\t// Skip malformed lines\n\t\treturn null;\n\t}\n}\n\n/** Serialize one entry as a protocol line (JSON body plus terminating newline). */\nfunction serializeEntryLine(entry: FileEntry): string {\n\treturn `${JSON.stringify(entry)}\\n`;\n}\n\nfunction parseSessionHeaderCandidate(line: string): SessionHeader | null | undefined {\n\tif (!line.trim()) return undefined;\n\tconst entry = parseSessionEntryLine(line);\n\tif (!entry) return undefined;\n\tif (entry.type !== \"session\" || typeof (entry as { id?: unknown }).id !== \"string\") return null;\n\treturn entry;\n}\n\n/** Suffix of the session write-guard sibling file (`<sessionFile>.guard`). */\nconst GUARD_FILE_SUFFIX = \".guard\";\n/** Wall-clock wait between guard-lock acquisition attempts (ledger protocol value). */\nconst GUARD_LOCK_POLL_INTERVAL_MS = 25;\n/** Default ceiling on waiting for a competing guard-lock holder. */\nconst GUARD_LOCK_TIMEOUT_MS = 5000;\n/** Default age at which a guard-lock counts as abandoned and is stolen. */\nconst GUARD_STALE_LOCK_MS = 60_000;\n\ninterface SessionGuardTokenV1 {\n\treadonly writerId: string;\n\treadonly hostId: string;\n\treadonly pid: number;\n}\n\nfunction defaultPidAlive(pid: number): boolean {\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn true;\n\t} catch (error) {\n\t\t// EPERM means the process exists but is owned by another user — alive.\n\t\treturn (error as NodeJS.ErrnoException).code === \"EPERM\";\n\t}\n}\n\n/** Writes every byte of `data` to the fd, looping over partial writeSync results. */\nfunction writeAllSync(fd: number, data: string): void {\n\tconst buffer = Buffer.from(data, \"utf8\");\n\tlet written = 0;\n\twhile (written < buffer.length) {\n\t\twritten += writeSync(fd, buffer, written, buffer.length - written);\n\t}\n}\n\n/**\n * Takes the guard's cross-process lock (same protocol as the memory ledger's\n * and the durable store's persist locks — exclusive create, poll, mtime\n * stale-lock stealing, token-guarded release; the three implementations stay\n * behaviorally identical by precedent, deliberately without module coupling).\n */\nfunction acquireGuardLock(lockPath: string, lockTimeoutMs: number, staleLockMs: number): string {\n\tconst deadline = Date.now() + lockTimeoutMs;\n\tfor (;;) {\n\t\tmkdirSync(dirname(lockPath), { recursive: true });\n\t\tconst token = `${process.pid}:${Date.now()}`;\n\t\ttry {\n\t\t\tconst fd = openSync(lockPath, \"wx\");\n\t\t\ttry {\n\t\t\t\twriteFileSync(fd, token);\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t\treturn token;\n\t\t} catch (error) {\n\t\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\t\t// POSIX maps a lost create race to EEXIST; Windows/libuv maps the\n\t\t\t// same concurrent-create sharing violation to EPERM. For EPERM a\n\t\t\t// vanished lock retries, a persistent permission failure propagates.\n\t\t\tif (code === \"EPERM\") {\n\t\t\t\tlet vanished = false;\n\t\t\t\ttry {\n\t\t\t\t\tstatSync(lockPath);\n\t\t\t\t} catch (statError) {\n\t\t\t\t\tif ((statError as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n\t\t\t\t\tvanished = true;\n\t\t\t\t}\n\t\t\t\tif (vanished) {\n\t\t\t\t\tif (Date.now() >= deadline) throw error;\n\t\t\t\t\tsleepSync(GUARD_LOCK_POLL_INTERVAL_MS);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t} else if (code !== \"EEXIST\") {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tlet stale = false;\n\t\t\ttry {\n\t\t\t\tstale = Date.now() - statSync(lockPath).mtimeMs > staleLockMs;\n\t\t\t} catch {\n\t\t\t\t// The holder released between the failed open and the stat.\n\t\t\t}\n\t\t\tif (stale) {\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(lockPath);\n\t\t\t\t} catch {\n\t\t\t\t\t// Already stolen — retry.\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (Date.now() >= deadline) {\n\t\t\t\tthrow new Error(`session guard lock timeout after ${lockTimeoutMs} ms: ${lockPath}`);\n\t\t\t}\n\t\t\tsleepSync(GUARD_LOCK_POLL_INTERVAL_MS);\n\t\t}\n\t}\n}\n\n/** Releases the guard lock, but only if our own token still owns it. */\nfunction releaseGuardLock(lockPath: string, token: string): void {\n\ttry {\n\t\tif (readFileSync(lockPath, \"utf8\") === token) unlinkSync(lockPath);\n\t} catch {\n\t\t// Already gone (or unreadable) — nothing to release.\n\t}\n}\n\n/**\n * The default provider: the local JSONL file protocol, moved verbatim from\n * `SessionManager`. Stateless beyond the injectable guard identity options,\n * so a shared module-level instance is the default for every session manager\n * that does not inject its own provider.\n */\nexport class FileSessionStorageProvider implements SessionStorageProvider {\n\t/** Shared stateless instance used as the default provider. */\n\tstatic readonly instance: FileSessionStorageProvider = new FileSessionStorageProvider();\n\n\tprivate readonly hostId: string;\n\tprivate readonly ownPid: number;\n\tprivate readonly pidAlive: (pid: number) => boolean;\n\n\tconstructor(\n\t\toptions: {\n\t\t\t/** Host identity written into guard tokens; defaults to `os.hostname()`. */\n\t\t\treadonly hostId?: string;\n\t\t\t/** Process identity written into guard tokens; defaults to `process.pid`. */\n\t\t\treadonly ownPid?: number;\n\t\t\t/** Injectable liveness check for deterministic tests; defaults to `process.kill(pid, 0)`. */\n\t\t\treadonly pidAlive?: (pid: number) => boolean;\n\t\t} = {},\n\t) {\n\t\tthis.hostId = options.hostId ?? hostname();\n\t\tthis.ownPid = options.ownPid ?? process.pid;\n\t\tthis.pidAlive = options.pidAlive ?? defaultPidAlive;\n\t}\n\n\tensureDir(dir: string): void {\n\t\tmkdirSync(dir, { recursive: true });\n\t}\n\n\texists(path: string): boolean {\n\t\treturn existsSync(path);\n\t}\n\n\tsize(path: string): number {\n\t\treturn statSync(path).size;\n\t}\n\n\tloadEntries(path: string): FileEntry[] {\n\t\tconst resolvedFilePath = normalizePath(path);\n\t\tif (!existsSync(resolvedFilePath)) return [];\n\n\t\tconst entries: FileEntry[] = [];\n\t\tlet pending = \"\";\n\t\tconst fd = openSync(resolvedFilePath, \"r\");\n\t\ttry {\n\t\t\tconst decoder = new StringDecoder(\"utf8\");\n\t\t\tconst buffer = Buffer.allocUnsafe(SESSION_READ_BUFFER_SIZE);\n\n\t\t\twhile (true) {\n\t\t\t\tconst bytesRead = readSync(fd, buffer, 0, buffer.length, null);\n\t\t\t\tif (bytesRead === 0) break;\n\n\t\t\t\tpending += decoder.write(buffer.subarray(0, bytesRead));\n\t\t\t\tlet lineStart = 0;\n\t\t\t\tlet newlineIndex = pending.indexOf(\"\\n\", lineStart);\n\t\t\t\twhile (newlineIndex !== -1) {\n\t\t\t\t\tconst entry = parseSessionEntryLine(pending.slice(lineStart, newlineIndex));\n\t\t\t\t\tif (entry) entries.push(entry);\n\t\t\t\t\tlineStart = newlineIndex + 1;\n\t\t\t\t\tnewlineIndex = pending.indexOf(\"\\n\", lineStart);\n\t\t\t\t}\n\t\t\t\tpending = pending.slice(lineStart);\n\t\t\t}\n\n\t\t\tpending += decoder.end();\n\t\t\tconst finalEntry = parseSessionEntryLine(pending);\n\t\t\tif (finalEntry) entries.push(finalEntry);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\n\t\t// Validate session header before repairing the file.\n\t\tif (entries.length === 0) return entries;\n\t\tconst header = entries[0];\n\t\tif (header.type !== \"session\" || typeof (header as { id?: unknown }).id !== \"string\") {\n\t\t\treturn [];\n\t\t}\n\n\t\tif (pending) appendFileSync(resolvedFilePath, \"\\n\");\n\t\treturn entries;\n\t}\n\n\treadHeader(path: string): SessionHeader | null {\n\t\tif (!existsSync(path)) return null;\n\t\tconst fd = openSync(path, \"r\");\n\t\ttry {\n\t\t\tconst decoder = new StringDecoder(\"utf8\");\n\t\t\tconst buffer = Buffer.allocUnsafe(SESSION_HEADER_READ_BUFFER_SIZE);\n\t\t\tconst lineChunks: string[] = [];\n\t\t\tlet scannedBytes = 0;\n\n\t\t\twhile (scannedBytes < MAX_SESSION_HEADER_SCAN_BYTES) {\n\t\t\t\tconst readLength = Math.min(buffer.length, MAX_SESSION_HEADER_SCAN_BYTES - scannedBytes);\n\t\t\t\tconst bytesRead = readSync(fd, buffer, 0, readLength, null);\n\t\t\t\tif (bytesRead === 0) {\n\t\t\t\t\tlineChunks.push(decoder.end());\n\t\t\t\t\treturn parseSessionHeaderCandidate(lineChunks.join(\"\")) ?? null;\n\t\t\t\t}\n\t\t\t\tscannedBytes += bytesRead;\n\n\t\t\t\tconst chunk = decoder.write(buffer.subarray(0, bytesRead));\n\t\t\t\tlet lineStart = 0;\n\t\t\t\tlet newlineIndex = chunk.indexOf(\"\\n\", lineStart);\n\t\t\t\twhile (newlineIndex !== -1) {\n\t\t\t\t\tlineChunks.push(chunk.slice(lineStart, newlineIndex));\n\t\t\t\t\tconst header = parseSessionHeaderCandidate(lineChunks.join(\"\"));\n\t\t\t\t\tif (header !== undefined) return header;\n\t\t\t\t\tlineChunks.length = 0;\n\t\t\t\t\tlineStart = newlineIndex + 1;\n\t\t\t\t\tnewlineIndex = chunk.indexOf(\"\\n\", lineStart);\n\t\t\t\t}\n\t\t\t\tlineChunks.push(chunk.slice(lineStart));\n\t\t\t}\n\n\t\t\t// Probe for EOF so a final header without a newline is allowed when it ends\n\t\t\t// exactly at the scan limit. Any additional byte exceeds the bounded scan.\n\t\t\tconst probe = Buffer.allocUnsafe(1);\n\t\t\tif (readSync(fd, probe, 0, probe.length, null) === 0) {\n\t\t\t\tlineChunks.push(decoder.end());\n\t\t\t\treturn parseSessionHeaderCandidate(lineChunks.join(\"\")) ?? null;\n\t\t\t}\n\t\t\tthrow new SessionHeaderScanLimitError(path);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t}\n\n\trewrite(path: string, entries: readonly FileEntry[]): void {\n\t\tconst fd = openSync(path, \"w\");\n\t\ttry {\n\t\t\tfor (const entry of entries) {\n\t\t\t\twriteFileSync(fd, serializeEntryLine(entry));\n\t\t\t}\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t}\n\n\tcreateExclusive(path: string, entries: readonly FileEntry[]): void {\n\t\tconst fd = openSync(path, \"wx\");\n\t\ttry {\n\t\t\tfor (const entry of entries) {\n\t\t\t\twriteFileSync(fd, serializeEntryLine(entry));\n\t\t\t}\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t}\n\n\tappend(path: string, entry: FileEntry): void {\n\t\tappendFileSync(path, serializeEntryLine(entry));\n\t}\n\n\ttruncate(path: string, size: number): void {\n\t\ttruncateSync(path, size);\n\t}\n\n\tremove(path: string): void {\n\t\tunlinkSync(path);\n\t}\n\n\tlistSessionFiles(dir: string): string[] {\n\t\tconst resolvedDir = normalizePath(dir);\n\t\treturn readdirSync(resolvedDir)\n\t\t\t.filter((f) => f.endsWith(\".jsonl\"))\n\t\t\t.map((f) => join(resolvedDir, f));\n\t}\n\n\tmodifiedTime(path: string): Date {\n\t\treturn statSync(path).mtime;\n\t}\n\n\t/**\n\t * Cross-process write guard (D-067 phase 2 S5): `<sessionFile>.guard`\n\t * carries `{ writerId, hostId, pid }`. A write conflicts only while the\n\t * recorded owner is a live process on this host; a dead owner (closed or\n\t * crashed process) and same-process writers never conflict, and cross-host\n\t * guards are treated as live foreign owners (conservative over shared\n\t * filesystems). Check-and-take-ownership is atomic under the guard lock.\n\t */\n\treadonly guard: SessionWriteGuardV1 = {\n\t\tensureWritable: (sessionFile: string, writerId: string): void => {\n\t\t\tconst guardPath = `${sessionFile}${GUARD_FILE_SUFFIX}`;\n\t\t\tconst readToken = (): SessionGuardTokenV1 | undefined => {\n\t\t\t\ttry {\n\t\t\t\t\tconst value: unknown = JSON.parse(readFileSync(guardPath, \"utf8\"));\n\t\t\t\t\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return undefined;\n\t\t\t\t\tconst record = value as { writerId?: unknown; hostId?: unknown; pid?: unknown };\n\t\t\t\t\tif (typeof record.writerId !== \"string\" || record.writerId.length === 0) return undefined;\n\t\t\t\t\tif (typeof record.hostId !== \"string\" || record.hostId.length === 0) return undefined;\n\t\t\t\t\tif (typeof record.pid !== \"number\" || !Number.isInteger(record.pid)) return undefined;\n\t\t\t\t\treturn { writerId: record.writerId, hostId: record.hostId, pid: record.pid };\n\t\t\t\t} catch {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\t\t\t};\n\n\t\t\tconst current = readToken();\n\t\t\t// Fast path: already ours (most appends), or no owner.\n\t\t\tif (current !== undefined && current.writerId === writerId) return;\n\t\t\tif (current !== undefined) {\n\t\t\t\tconst foreignLive =\n\t\t\t\t\tcurrent.hostId === this.hostId && current.pid !== this.ownPid && this.pidAlive(current.pid);\n\t\t\t\tif (foreignLive) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`Session file is owned by another live process (pid ${current.pid}): ${sessionFile}. ` +\n\t\t\t\t\t\t\t\"Close that process first; concurrent writers would silently fork the session history.\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Free, dead owner, or same-process writer: take (or refresh) ownership.\n\t\t\tconst token = acquireGuardLock(`${guardPath}.lock`, GUARD_LOCK_TIMEOUT_MS, GUARD_STALE_LOCK_MS);\n\t\t\ttry {\n\t\t\t\tconst fd = openSync(guardPath, \"w\");\n\t\t\t\ttry {\n\t\t\t\t\twriteAllSync(\n\t\t\t\t\t\tfd,\n\t\t\t\t\t\tJSON.stringify({ writerId, hostId: this.hostId, pid: this.ownPid } satisfies SessionGuardTokenV1),\n\t\t\t\t\t);\n\t\t\t\t} finally {\n\t\t\t\t\tcloseSync(fd);\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\treleaseGuardLock(`${guardPath}.lock`, token);\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/core/settings-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { AgentSessionRuntimeDiagnostic } from "./agent-session-services.ts";
+import type { SettingsManager } from "./settings-manager.ts";
+export declare function collectSettingsDiagnostics(settingsManager: SettingsManager): AgentSessionRuntimeDiagnostic[];
+/**
+ * Remove duplicate type/message diagnostics while preserving their first occurrence.
+ * Startup and runtime settings managers can report the same file error.
+ */
+export declare function deduplicateDiagnostics(diagnostics: readonly AgentSessionRuntimeDiagnostic[]): AgentSessionRuntimeDiagnostic[];
+//# sourceMappingURL=settings-diagnostics.d.ts.map

package/dist/core/settings-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-diagnostics.d.ts","sourceRoot":"","sources":["../../src/core/settings-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,wBAAgB,0BAA0B,CAAC,eAAe,EAAE,eAAe,GAAG,6BAA6B,EAAE,CAK5G;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,SAAS,6BAA6B,EAAE,GACnD,6BAA6B,EAAE,CAQjC","sourcesContent":["import type { AgentSessionRuntimeDiagnostic } from \"./agent-session-services.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\n\nexport function collectSettingsDiagnostics(settingsManager: SettingsManager): AgentSessionRuntimeDiagnostic[] {\n\treturn settingsManager.drainErrors().map(({ scope, path, error }) => ({\n\t\ttype: \"warning\",\n\t\tmessage: path ? `Invalid settings file ${path}: ${error.message}` : `Invalid ${scope} settings: ${error.message}`,\n\t}));\n}\n\n/**\n * Remove duplicate type/message diagnostics while preserving their first occurrence.\n * Startup and runtime settings managers can report the same file error.\n */\nexport function deduplicateDiagnostics(\n\tdiagnostics: readonly AgentSessionRuntimeDiagnostic[],\n): AgentSessionRuntimeDiagnostic[] {\n\tconst seen = new Set<string>();\n\treturn diagnostics.filter((diagnostic) => {\n\t\tconst key = `${diagnostic.type}\\0${diagnostic.message}`;\n\t\tif (seen.has(key)) return false;\n\t\tseen.add(key);\n\t\treturn true;\n\t});\n}\n"]}

package/dist/core/settings-diagnostics.js

@@ -0,0 +1,21 @@
+export function collectSettingsDiagnostics(settingsManager) {
+    return settingsManager.drainErrors().map(({ scope, path, error }) => ({
+        type: "warning",
+        message: path ? `Invalid settings file ${path}: ${error.message}` : `Invalid ${scope} settings: ${error.message}`,
+    }));
+}
+/**
+ * Remove duplicate type/message diagnostics while preserving their first occurrence.
+ * Startup and runtime settings managers can report the same file error.
+ */
+export function deduplicateDiagnostics(diagnostics) {
+    const seen = new Set();
+    return diagnostics.filter((diagnostic) => {
+        const key = `${diagnostic.type}\0${diagnostic.message}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+//# sourceMappingURL=settings-diagnostics.js.map

package/dist/core/settings-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-diagnostics.js","sourceRoot":"","sources":["../../src/core/settings-diagnostics.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,0BAA0B,CAAC,eAAgC,EAAmC;IAC7G,OAAO,eAAe,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACrE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,yBAAyB,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,cAAc,KAAK,CAAC,OAAO,EAAE;KACjH,CAAC,CAAC,CAAC;AAAA,CACJ;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACrC,WAAqD,EACnB;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;QACxD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IAAA,CACZ,CAAC,CAAC;AAAA,CACH","sourcesContent":["import type { AgentSessionRuntimeDiagnostic } from \"./agent-session-services.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\n\nexport function collectSettingsDiagnostics(settingsManager: SettingsManager): AgentSessionRuntimeDiagnostic[] {\n\treturn settingsManager.drainErrors().map(({ scope, path, error }) => ({\n\t\ttype: \"warning\",\n\t\tmessage: path ? `Invalid settings file ${path}: ${error.message}` : `Invalid ${scope} settings: ${error.message}`,\n\t}));\n}\n\n/**\n * Remove duplicate type/message diagnostics while preserving their first occurrence.\n * Startup and runtime settings managers can report the same file error.\n */\nexport function deduplicateDiagnostics(\n\tdiagnostics: readonly AgentSessionRuntimeDiagnostic[],\n): AgentSessionRuntimeDiagnostic[] {\n\tconst seen = new Set<string>();\n\treturn diagnostics.filter((diagnostic) => {\n\t\tconst key = `${diagnostic.type}\\0${diagnostic.message}`;\n\t\tif (seen.has(key)) return false;\n\t\tseen.add(key);\n\t\treturn true;\n\t});\n}\n"]}