@ai-agent-forge/agent-forge 0.86.7 → 0.87.0

package/dist/core/session-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-storage.d.ts","sourceRoot":"","sources":["../../src/core/session-storage.ts"],"names":[],"mappings":"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","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"]}
+{"version":3,"file":"session-storage.d.ts","sourceRoot":"","sources":["../../src/core/session-storage.ts"],"names":[],"mappings":"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","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 { t } from \"./i18n/index.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(\n\t\t\t\t\tt(\"session guard lock timeout after {timeoutMs} ms: {lockPath}\", { timeoutMs: lockTimeoutMs, lockPath }),\n\t\t\t\t);\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\tt(\n\t\t\t\t\t\t\t\"Session file is owned by another live process (pid {pid}): {sessionFile}. Close that process first; concurrent writers would silently fork the session history.\",\n\t\t\t\t\t\t\t{ pid: current.pid, sessionFile },\n\t\t\t\t\t\t),\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/session-storage.js

@@ -26,6 +26,7 @@ import { dirname, join } from "path";
 import { StringDecoder } from "string_decoder";
 import { normalizePath } from "../utils/paths.js";
 import { sleepSync } from "../utils/sync-sleep.js";
+import { t } from "./i18n/index.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. */
@@ -155,7 +156,7 @@ function acquireGuardLock(lockPath, lockTimeoutMs, staleLockMs) {
                 continue;
             }
             if (Date.now() >= deadline) {
-                throw new Error(`session guard lock timeout after ${lockTimeoutMs} ms: ${lockPath}`);
+                throw new Error(t("session guard lock timeout after {timeoutMs} ms: {lockPath}", { timeoutMs: lockTimeoutMs, lockPath }));
             }
             sleepSync(GUARD_LOCK_POLL_INTERVAL_MS);
         }
@@ -362,8 +363,7 @@ export class FileSessionStorageProvider {
             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.");
+                    throw new Error(t("Session file is owned by another live process (pid {pid}): {sessionFile}. Close that process first; concurrent writers would silently fork the session history.", { pid: current.pid, sessionFile }));
                 }
             }
             // Free, dead owner, or same-process writer: take (or refresh) ownership.

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

@@ -1 +1 @@
-{"version":3,"file":"session-storage.js","sourceRoot":"","sources":["../../src/core/session-storage.ts"],"names":[],"mappings":"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","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"]}
+{"version":3,"file":"session-storage.js","sourceRoot":"","sources":["../../src/core/session-storage.ts"],"names":[],"mappings":"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","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 { t } from \"./i18n/index.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(\n\t\t\t\t\tt(\"session guard lock timeout after {timeoutMs} ms: {lockPath}\", { timeoutMs: lockTimeoutMs, lockPath }),\n\t\t\t\t);\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\tt(\n\t\t\t\t\t\t\t\"Session file is owned by another live process (pid {pid}): {sessionFile}. Close that process first; concurrent writers would silently fork the session history.\",\n\t\t\t\t\t\t\t{ pid: current.pid, sessionFile },\n\t\t\t\t\t\t),\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-manager.d.ts

@@ -1,6 +1,7 @@
 import type { ThinkingLevel } from "@agent-forge/agent-core";
 import { type Model, type Transport } from "@agent-forge/ai";
 import type { TuiMode as RendererTuiMode, ScrollViewScrollbar, TerminalCapabilities, WheelScrollLines } from "@agent-forge/tui";
+import { type I18nLanguage } from "./i18n/index.ts";
 export interface CompactionModelOverride {
     reserveTokens?: number;
     keepRecentTokens?: number;
@@ -31,6 +32,13 @@ export interface RetrySettings {
 }
 export type TuiMode = RendererTuiMode;
 export type FullscreenExitOutput = "transcript" | "resume-hint";
+/**
+ * 界面语言（docs/design/国际化与本地化.md）：`ui.language` 持久配置面。
+ * env `AGENT_FORGE_I18N_LANG` 是更高优先的临时覆盖。
+ */
+export interface UiSettings {
+    language?: I18nLanguage;
+}
 export interface TerminalSettings {
     showImages?: boolean;
     imageWidthCells?: number;
@@ -131,6 +139,7 @@ export interface Settings {
     steeringMode?: "all" | "one-at-a-time";
     followUpMode?: "all" | "one-at-a-time";
     theme?: string;
+    ui?: UiSettings;
     compaction?: CompactionSettings;
     branchSummary?: BranchSummarySettings;
     retry?: RetrySettings;
@@ -404,6 +413,8 @@ export declare class SettingsManager {
     getDefaultTools(): string[] | undefined;
     setEnabledModels(patterns: string[] | undefined): void;
     getDoubleEscapeAction(): "fork" | "tree" | "none";
+    getUiLanguage(): I18nLanguage;
+    setUiLanguage(language: I18nLanguage): void;
     setDoubleEscapeAction(action: "fork" | "tree" | "none"): void;
     getTreeFilterMode(): "default" | "no-tools" | "user-only" | "labeled-only" | "all";
     setTreeFilterMode(mode: "default" | "no-tools" | "user-only" | "labeled-only" | "all"): void;