sessionmem 1.5.0 → 1.7.0

package/dist/cli/transcripts/codex.js

@@ -0,0 +1,111 @@
+import { buildFunctionCallEvent } from "../../core/capture/toolEvent.js";
+import { createdAt, object, stableId, unsupported } from "./types.js";
+/** Remove known host context while preserving human text in the same chunk. */
+function humanText(text) {
+    if (/^gAAAAA[A-Za-z0-9_=-]+\s*$/.test(text.trim()))
+        return "";
+    if (/^\s*# AGENTS\.md instructions for\b/.test(text)
+        || /^\s*#{1,3} (?:Skills|Plugins|Plugin catalog(?:ue)?)\s*\n+\s*(?:A skill is|The following (?:skills|plugins)|(?:#{1,3} )?Available (?:skills|plugins))/i.test(text))
+        return "";
+    return text.replace(/<(environment_context|plugin_catalogue|plugin_catalog|available_plugins|available_skills|skills_instructions)>[\s\S]*?<\/\1>/gi, "").trim();
+}
+export function parseCodexTranscript(_path, records) {
+    const result = { host: "codex", sessionId: "", events: [], malformed: false };
+    const occurrences = new Map();
+    for (const { value: record, line } of records) {
+        // agent_message envelopes can hold opaque Fernet strings. Never interpret them.
+        if (record.type === "agent_message")
+            continue;
+        const payload = object(record.payload);
+        if (typeof record.timestamp !== "string" || typeof record.type !== "string" || !payload) {
+            unsupported(result.host, `invalid rollout envelope on line ${line + 1}`);
+        }
+        if (record.type === "session_meta") {
+            if (typeof payload.id !== "string" || !payload.id.trim()
+                || typeof payload.cwd !== "string" || !payload.cwd.trim()) {
+                unsupported(result.host, `session_meta needs id and cwd on line ${line + 1}`);
+            }
+            if (result.sessionId && (result.sessionId !== payload.id || result.cwd !== payload.cwd)) {
+                unsupported(result.host, "conflicting session_meta records");
+            }
+            result.sessionId = payload.id;
+            result.cwd = payload.cwd;
+        }
+        else if (record.type === "response_item") {
+            if (typeof payload.type !== "string")
+                unsupported(result.host, `invalid response_item on line ${line + 1}`);
+            if (payload.type === "message") {
+                if (typeof payload.role !== "string" || !Array.isArray(payload.content)) {
+                    unsupported(result.host, `invalid message on line ${line + 1}`);
+                }
+                if (payload.role !== "user" && payload.role !== "assistant") {
+                    if (payload.role !== "system" && payload.role !== "developer") {
+                        unsupported(result.host, `unrecognized message role on line ${line + 1}`);
+                    }
+                    continue;
+                }
+                const chunks = [];
+                for (const raw of payload.content) {
+                    const chunk = object(raw);
+                    if (!chunk || typeof chunk.type !== "string")
+                        unsupported(result.host, `invalid content on line ${line + 1}`);
+                    if (chunk.type !== "input_text" && chunk.type !== "output_text") {
+                        if (!["input_image", "output_image", "image", "input_audio", "audio"].includes(chunk.type)) {
+                            unsupported(result.host, `unrecognized content type ${chunk.type} on line ${line + 1}`);
+                        }
+                        continue;
+                    }
+                    if (typeof chunk.text !== "string")
+                        unsupported(result.host, `invalid text on line ${line + 1}`);
+                    const text = payload.role === "user" ? humanText(chunk.text)
+                        : /^gAAAAA[A-Za-z0-9_=-]+\s*$/.test(chunk.text.trim()) ? "" : chunk.text.trim();
+                    if (text)
+                        chunks.push(text);
+                }
+                // IDs are absent in some CLI releases. Content plus occurrence preserves
+                // repeated turns and survives added metadata and changed replay timestamps.
+                const identity = stableId(payload.role, JSON.stringify(chunks));
+                const occurrence = occurrences.get(identity) ?? 0;
+                if (!chunks.length)
+                    continue;
+                occurrences.set(identity, occurrence + 1);
+                const key = typeof payload.id === "string" ? payload.id
+                    : typeof record.id === "string" ? record.id : `${identity}-${occurrence}`;
+                for (const [index, text] of chunks.entries())
+                    result.events.push({
+                        id: `message-${key}-${index}`, eventType: `message:${payload.role}`,
+                        createdAt: createdAt(record.timestamp), payloadJson: JSON.stringify({ text: text.slice(0, 4000) }),
+                    });
+            }
+            else if (payload.type === "function_call") {
+                if (typeof payload.name !== "string" || !payload.name.trim()
+                    || typeof payload.call_id !== "string" || !payload.call_id.trim() || typeof payload.arguments !== "string") {
+                    unsupported(result.host, `invalid function_call on line ${line + 1}`);
+                }
+                let input;
+                try {
+                    input = object(JSON.parse(payload.arguments));
+                }
+                catch {
+                    unsupported(result.host, `invalid function_call arguments on line ${line + 1}`);
+                }
+                if (!input)
+                    unsupported(result.host, `function_call arguments must be an object on line ${line + 1}`);
+                result.events.push({
+                    id: `tool-${payload.call_id}`,
+                    ...buildFunctionCallEvent(payload.name, input, payload.call_id, result.cwd), createdAt: createdAt(record.timestamp),
+                });
+            }
+            else if (!["reasoning", "function_call_output", "custom_tool_call", "custom_tool_call_output",
+                "web_search_call", "local_shell_call", "compaction", "agent_message"].includes(payload.type)) {
+                unsupported(result.host, `unrecognized response_item type ${payload.type} on line ${line + 1}`);
+            }
+        }
+        else if (!["event_msg", "turn_context", "compacted"].includes(record.type)) {
+            unsupported(result.host, `unrecognized record type ${record.type} on line ${line + 1}`);
+        }
+    }
+    if (records.length && !result.sessionId)
+        unsupported(result.host, "missing session_meta record");
+    return result;
+}

package/dist/cli/transcripts/cursor.js

@@ -0,0 +1,295 @@
+import BetterSqlite3 from "better-sqlite3";
+import { copyFile, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createdAt, object, unsupported } from "./types.js";
+export function cursorUserDirectory(platform = process.platform) {
+    if (platform === "darwin")
+        return join(homedir(), "Library", "Application Support", "Cursor", "User");
+    if (platform === "win32")
+        return join(process.env.APPDATA || join(homedir(), "AppData", "Roaming"), "Cursor", "User");
+    return join(homedir(), ".config", "Cursor", "User");
+}
+async function fileStamp(path) {
+    try {
+        const info = await stat(path, { bigint: true });
+        return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/** Never give SQLite a connection to the source, including its WAL/SHM files. */
+async function snapshot(path, read) {
+    const temp = await mkdtemp(join(tmpdir(), "sessionmem-cursor-"));
+    try {
+        const target = join(temp, "state.vscdb");
+        // Copy the WAL too: immutable connections to a live database ignore it and
+        // would silently miss recently committed messages. Detect checkpoints and
+        // concurrent writes during the copy, then retry on a later sweep if busy.
+        const suffixes = ["", "-wal", "-journal"];
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const before = await Promise.all(suffixes.map(suffix => fileStamp(path + suffix)));
+            if (!before[0])
+                throw new Error(`Cursor database disappeared: ${path}`);
+            try {
+                for (const [index, suffix] of suffixes.entries()) {
+                    await rm(target + suffix, { force: true });
+                    if (before[index])
+                        await copyFile(path + suffix, target + suffix);
+                }
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            const after = await Promise.all(suffixes.map(suffix => fileStamp(path + suffix)));
+            if (JSON.stringify(before) !== JSON.stringify(after))
+                continue;
+            let db;
+            try {
+                // better-sqlite3 normally compiles with SQLITE_USE_URI=0. Try immutable
+                // only on a copy without sidecars; otherwise use a read-only temp copy
+                // where SQLite can reconstruct its private WAL index safely.
+                if (!before[1] && !before[2]) {
+                    try {
+                        db = new BetterSqlite3(`${pathToFileURL(target).href}?mode=ro&immutable=1`, { readonly: true, fileMustExist: true });
+                    }
+                    catch { /* URI opens are unavailable in the bundled SQLite build. */ }
+                }
+                db ??= new BetterSqlite3(target, { readonly: true, fileMustExist: true, timeout: 0 });
+                return read(db);
+            }
+            finally {
+                db?.close();
+            }
+        }
+        throw new Error("Cursor database changed while copying; will retry");
+    }
+    finally {
+        await rm(temp, { recursive: true, force: true });
+    }
+}
+function json(value, label) {
+    if (Buffer.isBuffer(value))
+        value = value.toString("utf8");
+    if (typeof value !== "string")
+        unsupported("cursor", `${label} is not JSON text`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        unsupported("cursor", `invalid JSON in ${label}`);
+    }
+}
+function requireTable(db, table) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (!["key", "value"].every(name => columns.some(column => column.name === name))) {
+        unsupported("cursor", `missing ${table} table or key/value columns`);
+    }
+}
+function item(db, key) {
+    const row = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get(key);
+    return row ? json(row.value, key) : undefined;
+}
+function workspacePath(value) {
+    const uri = object(value);
+    if (typeof uri?.fsPath === "string" && isAbsolute(uri.fsPath))
+        return uri.fsPath;
+    if (typeof value === "string" && isAbsolute(value))
+        return value;
+    if (typeof value === "string" && value.startsWith("file:")) {
+        try {
+            return fileURLToPath(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // URI components are used in some workspaceIdentifier entries.
+    if (uri?.scheme === "file" && typeof uri.path === "string") {
+        try {
+            return fileURLToPath(`file://${typeof uri.authority === "string" ? uri.authority : ""}${uri.path}`);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function composers(value, key) {
+    const entries = Array.isArray(value) ? value : object(value)?.allComposers;
+    if (!Array.isArray(entries))
+        unsupported("cursor", `${key} needs an array of composers`);
+    return entries.map(entry => {
+        const composer = object(entry);
+        if (!composer || typeof composer.composerId !== "string" || !composer.composerId.trim() || composer.composerId.length > 200) {
+            unsupported("cursor", `invalid composerId in ${key}`);
+        }
+        return composer;
+    });
+}
+/** Resolve a User directory or a global/workspace state.vscdb override. */
+export async function cursorDatabasePath(directory) {
+    try {
+        if ((await stat(directory)).isFile()) {
+            if (basename(dirname(dirname(directory))) === "workspaceStorage") {
+                return join(dirname(dirname(dirname(directory))), "globalStorage", "state.vscdb");
+            }
+            return directory;
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const path = join(directory, "globalStorage", "state.vscdb");
+    return await fileStamp(path) ? path : undefined;
+}
+function parseBubble(value, id) {
+    const bubble = object(json(value, `bubble ${id}`));
+    if (!bubble)
+        unsupported("cursor", `invalid bubble ${id}`);
+    // Cursor uses 1=user and 2=assistant. Tool, system and internal bubbles are
+    // not conversation messages. Never stringify code, tool results or context.
+    const role = bubble.type === 1 || bubble.type === "user" ? "user"
+        : bubble.type === 2 || bubble.type === "assistant" ? "assistant" : undefined;
+    if (!role) {
+        if (bubble.type === undefined)
+            unsupported("cursor", `missing message type in bubble ${id}`);
+        return undefined;
+    }
+    if (bubble.text === undefined || bubble.text === null)
+        return undefined;
+    if (typeof bubble.text !== "string")
+        unsupported("cursor", `invalid text in bubble ${id}`);
+    if (!bubble.text.trim())
+        return undefined;
+    const timestamp = typeof bubble.createdAt === "number" && Number.isFinite(bubble.createdAt)
+        ? new Date(bubble.createdAt).toISOString() : createdAt(bubble.createdAt);
+    return { role, text: bubble.text.slice(0, 4000), timestamp };
+}
+export async function readCursorTranscripts(path) {
+    const global = await snapshot(path, db => {
+        requireTable(db, "cursorDiskKV");
+        // Older layouts only need ItemTable in the workspace databases.
+        const hasHeadersTable = !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'ItemTable'").get();
+        if (hasHeadersTable)
+            requireTable(db, "ItemTable");
+        const headers = hasHeadersTable ? item(db, "composer.composerHeaders") : undefined;
+        // Materialize only the relevant rows, one value at a time. Large tool and
+        // code fields are discarded immediately rather than retained in memory.
+        const metadata = new Map();
+        const bubbles = new Map();
+        for (const row of db.prepare("SELECT key, value FROM cursorDiskKV WHERE key GLOB 'composerData:*' OR key GLOB 'bubbleId:*' ORDER BY key").iterate()) {
+            if (row.key.startsWith("composerData:")) {
+                const data = object(json(row.value, row.key));
+                if (!data)
+                    unsupported("cursor", `invalid ${row.key}`);
+                metadata.set(row.key.slice("composerData:".length), data);
+            }
+            else {
+                const parts = row.key.split(":");
+                if (parts.length !== 3 || !parts[1] || !parts[2])
+                    unsupported("cursor", `invalid bubble key ${row.key}`);
+                const entries = bubbles.get(parts[1]) ?? [];
+                entries.push({ id: parts[2], message: parseBubble(row.value, parts[2]) });
+                bubbles.set(parts[1], entries);
+            }
+        }
+        return { headers, metadata, bubbles };
+    });
+    const index = new Map();
+    const add = (composer, cwd) => {
+        const id = composer.composerId;
+        if (!cwd)
+            unsupported("cursor", `missing workspace path for composer ${id}`);
+        if (index.has(id) && resolve(index.get(id)) !== resolve(cwd))
+            unsupported("cursor", `conflicting workspaces for composer ${id}`);
+        index.set(id, cwd);
+    };
+    let foundIndex = global.headers !== undefined;
+    if (foundIndex) {
+        for (const composer of composers(global.headers, "composer.composerHeaders")) {
+            add(composer, workspacePath(object(composer.workspaceIdentifier)?.uri));
+        }
+    }
+    const workspaces = join(dirname(dirname(path)), "workspaceStorage");
+    let directories;
+    try {
+        directories = await readdir(workspaces, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        directories = [];
+    }
+    for (const entry of directories.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const workspace = join(workspaces, entry.name);
+        const database = join(workspace, "state.vscdb");
+        if (!await fileStamp(database))
+            continue;
+        const legacy = await snapshot(database, db => {
+            requireTable(db, "ItemTable");
+            return item(db, "composer.composerData");
+        });
+        if (legacy === undefined)
+            continue;
+        foundIndex = true;
+        const entries = composers(legacy, "composer.composerData");
+        if (!entries.length)
+            continue;
+        let info;
+        try {
+            info = object(json(await readFile(join(workspace, "workspace.json"), "utf8"), "workspace.json"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                unsupported("cursor", "missing workspace.json for composer index");
+            throw error;
+        }
+        for (const composer of entries) {
+            // Current central headers take precedence over stale workspace indexes.
+            if (!index.has(composer.composerId))
+                add(composer, workspacePath(info?.folder ?? info?.workspace));
+        }
+    }
+    if (!foundIndex)
+        unsupported("cursor", "missing composer.composerHeaders and workspace composer.composerData indexes");
+    const transcripts = [];
+    for (const [sessionId, cwd] of index) {
+        const metadata = global.metadata.get(sessionId);
+        if (!metadata)
+            unsupported("cursor", `missing composerData:${sessionId}`);
+        const headers = metadata.fullConversationHeadersOnly ?? metadata.conversation;
+        if (headers !== undefined && !Array.isArray(headers))
+            unsupported("cursor", `invalid conversation headers for ${sessionId}`);
+        const order = new Map();
+        const entries = global.bubbles.get(sessionId) ?? [];
+        const bubbleIds = new Set(entries.map(bubble => bubble.id));
+        for (const [position, raw] of (Array.isArray(headers) ? headers : []).entries()) {
+            const header = object(raw);
+            if (typeof header?.bubbleId !== "string")
+                unsupported("cursor", `invalid conversation header for ${sessionId}`);
+            order.set(header.bubbleId, position);
+            if (!bubbleIds.has(header.bubbleId)) {
+                unsupported("cursor", `missing bubbleId:${sessionId}:${header.bubbleId}`);
+            }
+        }
+        entries.sort((a, b) => (order.get(a.id) ?? Infinity) - (order.get(b.id) ?? Infinity)
+            || (a.message?.timestamp ?? "").localeCompare(b.message?.timestamp ?? "") || a.id.localeCompare(b.id));
+        transcripts.push({ host: "cursor", cwd, sessionId, malformed: false,
+            events: entries.flatMap(({ id, message }) => message ? [{
+                    id: `bubble-${id}`, eventType: `message:${message.role}`, payloadJson: JSON.stringify({ text: message.text }), createdAt: message.timestamp,
+                }] : []),
+        });
+    }
+    return transcripts;
+}

package/dist/cli/transcripts/index.js

@@ -0,0 +1,118 @@
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { expandTilde } from "../context.js";
+import { isClaudeRecord, parseClaudeTranscript } from "./claudeCode.js";
+import { parseCodexTranscript } from "./codex.js";
+import { cursorDatabasePath, cursorUserDirectory, readCursorTranscripts } from "./cursor.js";
+import { object } from "./types.js";
+export const TRANSCRIPT_HOSTS = ["claude-code", "codex", "cursor"];
+const parsers = { "claude-code": parseClaudeTranscript, codex: parseCodexTranscript };
+export function transcriptDirectory(host) {
+    if (host === "cursor")
+        return cursorUserDirectory();
+    return join(homedir(), host === "codex" ? ".codex" : ".claude", host === "codex" ? "sessions" : "projects");
+}
+export function transcriptSources(options) {
+    const host = options.host;
+    if (host && !TRANSCRIPT_HOSTS.includes(host)) {
+        throw new Error(`Unsupported transcript host: ${host}. Choose ${TRANSCRIPT_HOSTS.join(" or ")}`);
+    }
+    const selected = host;
+    if (options.transcriptsDir)
+        return [{ directory: resolve(expandTilde(options.transcriptsDir)), host: selected }];
+    return (selected ? [selected] : TRANSCRIPT_HOSTS).map(host => ({ directory: transcriptDirectory(host), host }));
+}
+export async function* transcriptFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            yield* transcriptFiles(path);
+        else if (entry.isFile() && entry.name.endsWith(".jsonl"))
+            yield path;
+    }
+}
+/** Recognize Cursor overrides without changing JSONL directory overrides. */
+export async function isCursorSource(directory) {
+    try {
+        if ((await stat(directory)).isFile())
+            return directory.endsWith(".vscdb");
+        return !!await cursorDatabasePath(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function readTranscript(path, claimedHost) {
+    if (claimedHost === "cursor")
+        throw new Error("unsupported format for cursor: expected a User directory or state.vscdb database");
+    const records = [];
+    let malformed = false;
+    const input = createReadStream(path);
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    let lineIndex = 0;
+    try {
+        for await (const line of lines) {
+            const index = lineIndex++;
+            if (!line.trim())
+                continue;
+            let value;
+            try {
+                value = object(JSON.parse(line.replace(/^\uFEFF/, "")));
+            }
+            catch {
+                malformed = true;
+                continue;
+            }
+            if (!value)
+                throw new Error(`unsupported format${claimedHost ? ` for ${claimedHost}` : ""}: record on line ${index + 1} is not an object`);
+            records.push({ value, line: index });
+        }
+    }
+    finally {
+        lines.close();
+        input.destroy();
+    }
+    const host = claimedHost ?? (records.some(({ value }) => value.type === "session_meta") ? "codex"
+        : records.some(({ value }) => isClaudeRecord(value)) ? "claude-code" : undefined);
+    if (!host && records.length)
+        throw new Error("unsupported format: expected Claude Code transcripts or Codex CLI rollouts");
+    const result = parsers[host ?? "claude-code"](path, records);
+    return { ...result, malformed };
+}
+/** Read-only doctor probe: enumerate history and validate one sample per host. */
+export async function inspectTranscriptDiscovery(host) {
+    const directory = transcriptDirectory(host);
+    if (host === "cursor") {
+        const path = await cursorDatabasePath(directory);
+        if (!path)
+            return `No transcripts found (${directory})`;
+        const transcripts = await readCursorTranscripts(path);
+        return `${transcripts.length} composer(s) found (${path}); parsed as cursor`;
+    }
+    let count = 0;
+    let sample;
+    for await (const path of transcriptFiles(directory)) {
+        count++;
+        sample ??= path;
+    }
+    if (!sample)
+        return `No transcripts found (${directory})`;
+    const transcript = await readTranscript(sample, host);
+    if (transcript.malformed)
+        throw new Error(`malformed or incomplete JSONL (${sample})`);
+    return `${count} transcript file(s) found (${directory}); sample parsed as ${host}`;
+}

package/dist/cli/transcripts/types.js

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+export function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
+}
+export function stableId(...parts) {
+    return `transcript-${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+}
+export function createdAt(value) {
+    const timestamp = typeof value === "string" ? Date.parse(value) : NaN;
+    return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : undefined;
+}
+export function unsupported(host, detail) {
+    throw new Error(`unsupported format for ${host}: ${detail}`);
+}

package/dist/cli/watchCheckpoint.js

@@ -0,0 +1,35 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+export const watchCheckpointPath = (dbPath) => join(dirname(resolve(dbPath)), `${basename(dbPath)}.watch-checkpoint.json`);
+export function saveWatchCheckpoint(context, summary, intervalSeconds) {
+    if (context.dbPath === ":memory:")
+        return;
+    const path = watchCheckpointPath(context.dbPath);
+    const checkpoint = {
+        dbPath: resolve(context.dbPath), completedAt: new Date().toISOString(), intervalSeconds,
+        checkpointCount: context.db.prepare("SELECT count(*) AS n FROM transcript_checkpoints").get().n,
+        summary,
+    };
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(checkpoint), { mode: 0o600 });
+    renameSync(temp, path);
+}
+export function inspectWatchCheckpoint(dbPath, now = Date.now()) {
+    const checkpoint = JSON.parse(readFileSync(watchCheckpointPath(dbPath), "utf8"));
+    const age = now - Date.parse(checkpoint.completedAt);
+    if (checkpoint.dbPath !== resolve(dbPath))
+        throw new Error("Watcher checkpoint belongs to a different database");
+    if (!Number.isFinite(checkpoint.intervalSeconds) || checkpoint.intervalSeconds <= 0 || checkpoint.intervalSeconds > 86400)
+        throw new Error("Invalid watcher checkpoint interval");
+    if (!Number.isFinite(age) || age < -60000 || age > Math.max(120000, checkpoint.intervalSeconds * 3000))
+        throw new Error(`Watcher checkpoint is stale or invalid (${checkpoint.completedAt})`);
+    if (!checkpoint.summary || Object.values(checkpoint.summary).length !== 5 || Object.values(checkpoint.summary).some(value => !Number.isInteger(value) || value < 0))
+        throw new Error("Invalid watcher sweep counters");
+    if (checkpoint.summary.errors !== 0)
+        throw new Error(`Last watcher sweep had ${checkpoint.summary.errors} capture error(s)`);
+    if (!Number.isInteger(checkpoint.checkpointCount) || checkpoint.checkpointCount < 0)
+        throw new Error("Invalid transcript checkpoint count");
+    if (checkpoint.summary.filesFound > 0 && checkpoint.checkpointCount === 0)
+        throw new Error("Transcripts found but none checkpointed yet");
+    return `Sweep completed ${Math.max(0, Math.round(age / 1000))}s ago; ${checkpoint.checkpointCount} transcript checkpoint(s); ${checkpoint.summary.filesFound} source file(s)`;
+}

package/dist/cli/watchLog.js

@@ -0,0 +1,23 @@
+import { mkdirSync, openSync, closeSync, writeSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+/** Redirect both streams before opening storage so headless startup failures land
+ * in the same log as per-file capture failures. Never reads stdin or uses a TTY. */
+export function openWatchLog(path) {
+    if (!path)
+        return () => { };
+    const absolute = resolve(path);
+    mkdirSync(dirname(absolute), { recursive: true });
+    const fd = openSync(absolute, "a", 0o600);
+    const stdout = process.stdout.write;
+    const stderr = process.stderr.write;
+    const write = ((chunk, encodingOrCallback, callback) => {
+        const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString();
+        writeSync(fd, `${new Date().toISOString()} ${value}`);
+        const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+        done?.();
+        return true;
+    });
+    process.stdout.write = write;
+    process.stderr.write = write;
+    return () => { process.stdout.write = stdout; process.stderr.write = stderr; closeSync(fd); };
+}

package/dist/core/api/contracts.js

@@ -90,6 +90,9 @@ export const ingestSessionEventSchema = z.object({
 export const ingestSessionEventsRequestSchema = z.object({
     projectId: z.string().min(1),
     sessionId: z.string().min(1).max(200),
+    // Mutable transcript hosts can refresh an existing event without changing
+    // its identity, order or original timestamp. Other callers remain append-only.
+    replaceExisting: z.boolean().optional(),
     events: z.array(ingestSessionEventSchema).min(1).max(MAX_INGEST_EVENTS),
 });
 export const summarizeSessionToMemoryRequestSchema = z.object({