@timurproko/a1 0.2.7-dev.754 → 0.2.7-dev.772

package/dist/foundation/resident-tabs/maintenance.js

@@ -0,0 +1,78 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { runBoundedHostCommand } from "./bounded-host-command.js";
+import { resolveTerminalHostPath } from "./ensure-terminal-host.js";
+import { verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
+const INCOMPATIBLE_EXIT = 4;
+/**
+ * Runs one maintenance form through a verified terminal host. When the running host speaks
+ * another protocol generation, it retries once with the binary from the release that host
+ * recorded, after verifying that release's manifest; it never runs an unverified binary.
+ */
+export async function runTerminalHostMaintenance(options) {
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    const executable = await firstVerifiedHost(options, options.releaseRoots, platform, architecture);
+    if (executable === undefined)
+        return unavailable(options.action, "no verified terminal host is installed");
+    const report = await invoke(options, executable);
+    if (report.exitCode !== INCOMPATIBLE_EXIT || typeof report.releaseRoot !== "string")
+        return report;
+    const cohort = await firstVerifiedHost({ ...options, environment: {} }, [report.releaseRoot], platform, architecture);
+    if (cohort === undefined || cohort === executable) {
+        return { ...report, message: "the running tabs use another version whose terminal host cannot be verified" };
+    }
+    return await invoke(options, cohort);
+}
+function arguments_(options) {
+    const command = options.action === "stop" ? ["stop", options.tabId ?? ""] : [options.action];
+    return ["tabs", ...command, "--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
+}
+async function invoke(options, executable) {
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    try {
+        const result = await (options.run ?? runHost)(executable, arguments_(options), timeoutMs);
+        const line = result.stdout.trim().split(/\r?\n/u).at(-1) ?? "";
+        const parsed = JSON.parse(line);
+        if (parsed.schema !== "a1-tabs-maintenance-v1" || typeof parsed.host !== "string")
+            throw new Error("malformed maintenance report");
+        return { ...parsed, exitCode: result.code };
+    }
+    catch (error) {
+        return unavailable(options.action, `terminal host maintenance failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function firstVerifiedHost(options, roots, platform, architecture) {
+    const override = options.environment[PRODUCT_IDENTITY.environment.developmentInstanceId]
+        ? options.environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim()
+        : undefined;
+    if (override) {
+        try {
+            await access(override, constants.R_OK | (platform === "win32" ? 0 : constants.X_OK));
+            return override;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    for (const root of roots) {
+        const candidate = resolveTerminalHostPath(root, {}, platform, architecture);
+        try {
+            await (options.verify ?? verifyTerminalHostArtifact)(candidate, platform, architecture);
+            return candidate;
+        }
+        catch {
+            // Rationale: an older retained release may predate the packaged host; try the next one.
+        }
+    }
+    return undefined;
+}
+function unavailable(action, message) {
+    return { schema: "a1-tabs-maintenance-v1", command: action, host: "unavailable", message, exitCode: 3 };
+}
+/** The largest maintenance report accepted from the terminal host. */
+export const MAX_MAINTENANCE_REPORT_BYTES = 4 * 1024 * 1024;
+async function runHost(executable, arguments_, timeoutMs) {
+    return await runBoundedHostCommand(executable, arguments_, { maxStdoutBytes: MAX_MAINTENANCE_REPORT_BYTES, timeoutMs, label: "terminal host maintenance" });
+}

package/dist/foundation/resident-tabs/prompt-journal.d.ts

@@ -0,0 +1,65 @@
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+export interface SubmittedPromptRecord {
+    readonly type: "submitted";
+    readonly id: string;
+    readonly sessionId: string;
+    readonly sessionFile: string | null;
+    readonly incarnation: number;
+    readonly fileExisted: boolean;
+    readonly kind: "prompt" | "steer" | "follow-up";
+    readonly text: string;
+    readonly images?: readonly unknown[];
+    readonly at: string;
+}
+export interface CorrelatedPromptRecord {
+    readonly type: "correlated";
+    readonly id: string;
+    readonly entryId: string;
+}
+export interface SettledPromptRecord {
+    readonly type: "settled";
+    readonly id: string;
+    readonly entryId: string;
+}
+export interface RetiredPromptRecord {
+    readonly type: "retired";
+    readonly id: string;
+}
+export type PromptJournalRecord = SubmittedPromptRecord | CorrelatedPromptRecord | SettledPromptRecord | RetiredPromptRecord;
+export interface PromptSubmission {
+    readonly sessionId: string;
+    readonly sessionFile: string | null;
+    readonly incarnation: number;
+    readonly fileExisted: boolean;
+    readonly kind: SubmittedPromptRecord["kind"];
+    readonly text: string;
+    readonly images?: readonly unknown[];
+}
+export interface SessionJournalEntry {
+    readonly entryId: string;
+    readonly text: string;
+    readonly settled: boolean;
+}
+export interface PendingPrompt {
+    readonly submitted: SubmittedPromptRecord;
+    readonly correlatedEntryId?: string;
+}
+export declare class PromptJournal {
+    #private;
+    readonly path: string;
+    constructor(path: string, options?: {
+        readonly faults?: ResidentTabFaultInjection;
+        readonly maximumBytes?: number;
+    });
+    initialize(): Promise<void>;
+    submit(submission: PromptSubmission): Promise<SubmittedPromptRecord>;
+    adopt(record: SubmittedPromptRecord): Promise<boolean>;
+    correlate(id: string, entryId: string): Promise<void>;
+    settle(id: string, entryId: string): Promise<void>;
+    retire(id: string): Promise<void>;
+    read(): Promise<readonly PromptJournalRecord[]>;
+    pending(sessionEntries?: readonly SessionJournalEntry[]): Promise<readonly PendingPrompt[]>;
+    compactIfRetired(): Promise<boolean>;
+}
+export declare function classifyMissingSession(record: SubmittedPromptRecord, sessionExists: boolean): "available" | "first-turn" | "missing-transcript";
+export declare function removeJournalTemporary(path: string): Promise<void>;

package/dist/foundation/resident-tabs/prompt-journal.js

@@ -0,0 +1,214 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+const MAX_JOURNAL_BYTES = 8 * 1024 * 1024;
+const MAX_RECORD_BYTES = 2 * 1024 * 1024;
+export class PromptJournal {
+    path;
+    #faults;
+    #maximumBytes;
+    #operation = Promise.resolve();
+    #retired = new Set();
+    constructor(path, options = {}) {
+        this.path = path;
+        this.#faults = options.faults ?? new ResidentTabFaultInjection();
+        this.#maximumBytes = options.maximumBytes ?? MAX_JOURNAL_BYTES;
+    }
+    async initialize() {
+        await secureDirectory(dirname(this.path));
+        const handle = await open(this.path, "a", 0o600);
+        await handle.close();
+        if (process.platform !== "win32")
+            await chmod(this.path, 0o600);
+        for (const record of await this.read())
+            if (record.type === "retired")
+                this.#retired.add(record.id);
+    }
+    async submit(submission) {
+        const record = {
+            type: "submitted",
+            id: randomUUID(),
+            ...submission,
+            ...(submission.images === undefined ? {} : { images: submission.images }),
+            at: new Date().toISOString(),
+        };
+        await this.#append(record, "journal-before-append", "journal-after-append", "journal-after-sync");
+        return record;
+    }
+    async adopt(record) {
+        if ((await this.read()).some(existing => existing.type === "submitted" && existing.id === record.id))
+            return false;
+        await this.#append(record, "journal-before-append", "journal-after-append", "journal-after-sync");
+        return true;
+    }
+    async correlate(id, entryId) {
+        await this.#append({ type: "correlated", id, entryId }, "journal-before-correlation", "journal-after-correlation");
+    }
+    async settle(id, entryId) {
+        await this.#append({ type: "settled", id, entryId }, "journal-before-settled-record", "journal-after-settled-record");
+    }
+    async retire(id) {
+        if (this.#retired.has(id))
+            return;
+        await this.#append({ type: "retired", id }, "journal-during-retirement");
+        this.#retired.add(id);
+    }
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const records = [];
+        const lines = text.split("\n");
+        for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index];
+            if (!line)
+                continue;
+            try {
+                const value = JSON.parse(line);
+                records.push(decodeRecord(value));
+            }
+            catch (error) {
+                if (index === lines.length - 1 && !text.endsWith("\n"))
+                    break;
+                throw error;
+            }
+        }
+        return records;
+    }
+    async pending(sessionEntries = []) {
+        const states = new Map();
+        const settled = new Set();
+        const retired = new Set();
+        for (const record of await this.read()) {
+            if (record.type === "submitted")
+                states.set(record.id, { submitted: record });
+            else if (record.type === "correlated") {
+                const state = states.get(record.id);
+                if (state !== undefined)
+                    states.set(record.id, { ...state, correlatedEntryId: record.entryId });
+            }
+            else if (record.type === "settled")
+                settled.add(record.id);
+            else
+                retired.add(record.id);
+        }
+        const byId = new Map(sessionEntries.map(entry => [entry.entryId, entry]));
+        const pending = [];
+        const claimedEntries = new Set();
+        for (const [id, state] of states) {
+            if (retired.has(id) || settled.has(id)) {
+                await this.retire(id);
+                continue;
+            }
+            const correlated = state.correlatedEntryId === undefined ? undefined : byId.get(state.correlatedEntryId);
+            const textMatch = correlated ?? sessionEntries.find(entry => entry.text === state.submitted.text && !claimedEntries.has(entry.entryId));
+            if (textMatch !== undefined)
+                claimedEntries.add(textMatch.entryId);
+            if (textMatch?.settled === true)
+                await this.retire(id);
+            else
+                pending.push(state);
+        }
+        return pending;
+    }
+    async compactIfRetired() {
+        if ((await this.pending()).length !== 0)
+            return false;
+        await this.#serialize(async () => {
+            this.#faults.at("journal-during-compaction");
+            const temporary = `${this.path}.tmp-${process.pid}-${randomUUID()}`;
+            const handle = await open(temporary, "wx", 0o600);
+            try {
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(temporary, this.path);
+            await syncDirectory(dirname(this.path));
+        });
+        return true;
+    }
+    async #append(record, ...points) {
+        const line = `${JSON.stringify(record)}\n`;
+        const bytes = Buffer.byteLength(line);
+        if (bytes > MAX_RECORD_BYTES)
+            throw new Error("resident prompt journal record exceeds its size limit");
+        await this.#serialize(async () => {
+            for (const point of points.slice(0, 1))
+                this.#faults.at(point);
+            const current = await stat(this.path).then(value => value.size, error => error.code === "ENOENT" ? 0 : Promise.reject(error));
+            if (current + bytes > this.#maximumBytes)
+                throw new Error("resident prompt journal is full");
+            const handle = await open(this.path, "a", 0o600);
+            try {
+                await handle.write(line, undefined, "utf8");
+                if (points[1] !== undefined)
+                    this.#faults.at(points[1]);
+                await handle.sync();
+                if (points[2] !== undefined)
+                    this.#faults.at(points[2]);
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    async #serialize(operation) {
+        const next = this.#operation.then(operation, operation);
+        this.#operation = next.catch(() => undefined);
+        await next;
+    }
+}
+export function classifyMissingSession(record, sessionExists) {
+    if (sessionExists)
+        return "available";
+    return record.fileExisted ? "missing-transcript" : "first-turn";
+}
+function decodeRecord(value) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("invalid resident prompt journal record");
+    const record = value;
+    if (typeof record.id !== "string" || record.id.length === 0)
+        throw new Error("invalid resident prompt journal id");
+    if (record.type === "submitted") {
+        if (typeof record.sessionId !== "string" || !(typeof record.sessionFile === "string" || record.sessionFile === null)
+            || typeof record.incarnation !== "number" || typeof record.fileExisted !== "boolean"
+            || !["prompt", "steer", "follow-up"].includes(String(record.kind)) || typeof record.text !== "string" || typeof record.at !== "string") {
+            throw new Error("invalid submitted prompt journal record");
+        }
+        return record;
+    }
+    if ((record.type === "correlated" || record.type === "settled") && typeof record.entryId === "string")
+        return record;
+    if (record.type === "retired")
+        return record;
+    throw new Error("invalid resident prompt journal record type");
+}
+async function secureDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await chmod(path, 0o700);
+}
+async function syncDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function removeJournalTemporary(path) {
+    await unlink(path).catch(error => { if (error.code !== "ENOENT")
+        throw error; });
+}

package/dist/foundation/resident-tabs/protocol.d.ts

@@ -0,0 +1,12 @@
+export interface ResidentEnvelope<T = Readonly<Record<string, unknown>>> {
+    readonly type: string;
+    readonly requestId?: number;
+    readonly body: T;
+}
+/** Generation-1 MessagePack named-map codec. It intentionally supports only bridge-safe values. */
+export declare function encodeResidentFrame(value: ResidentEnvelope): Buffer;
+export declare function decodeResidentPayload(payload: Uint8Array): ResidentEnvelope;
+export declare class ResidentFrameDecoder {
+    #private;
+    push(chunk: Uint8Array): readonly ResidentEnvelope[];
+}

package/dist/foundation/resident-tabs/protocol.js

@@ -0,0 +1,195 @@
+const MAX_FRAME_BYTES = 2 * 1024 * 1024;
+const MAX_DEPTH = 64;
+/** Generation-1 MessagePack named-map codec. It intentionally supports only bridge-safe values. */
+export function encodeResidentFrame(value) {
+    const payload = Buffer.from(encodeValue(value, 0));
+    if (payload.length > MAX_FRAME_BYTES)
+        throw new Error("resident frame exceeds 2 MiB");
+    const frame = Buffer.allocUnsafe(payload.length + 4);
+    frame.writeUInt32LE(payload.length, 0);
+    payload.copy(frame, 4);
+    return frame;
+}
+export function decodeResidentPayload(payload) {
+    if (payload.byteLength > MAX_FRAME_BYTES)
+        throw new Error("resident frame exceeds 2 MiB");
+    const state = { bytes: payload, offset: 0 };
+    const value = decodeValue(state, 0);
+    if (state.offset !== payload.byteLength || !isRecord(value) || typeof value.type !== "string" || !isRecord(value.body)) {
+        throw new Error("invalid resident envelope");
+    }
+    return value;
+}
+export class ResidentFrameDecoder {
+    #buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        const messages = [];
+        while (this.#buffer.length >= 4) {
+            const length = this.#buffer.readUInt32LE(0);
+            if (length > MAX_FRAME_BYTES)
+                throw new Error("resident frame exceeds 2 MiB");
+            if (this.#buffer.length < length + 4)
+                break;
+            messages.push(decodeResidentPayload(this.#buffer.subarray(4, length + 4)));
+            this.#buffer = this.#buffer.subarray(length + 4);
+        }
+        return messages;
+    }
+}
+function encodeValue(value, depth) {
+    if (depth > MAX_DEPTH)
+        throw new Error("resident value exceeds nesting limit");
+    if (value === null)
+        return [0xc0];
+    if (value === false)
+        return [0xc2];
+    if (value === true)
+        return [0xc3];
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return encodeInteger(value);
+    if (typeof value === "string") {
+        const bytes = [...Buffer.from(value, "utf8")];
+        if (bytes.length < 32)
+            return [0xa0 | bytes.length, ...bytes];
+        if (bytes.length <= 0xff)
+            return [0xd9, bytes.length, ...bytes];
+        if (bytes.length <= 0xffff)
+            return [0xda, bytes.length >>> 8, bytes.length & 0xff, ...bytes];
+        return [0xdb, ...u32(bytes.length), ...bytes];
+    }
+    if (value instanceof Uint8Array) {
+        const bytes = [...value];
+        if (bytes.length <= 0xff)
+            return [0xc4, bytes.length, ...bytes];
+        if (bytes.length <= 0xffff)
+            return [0xc5, bytes.length >>> 8, bytes.length & 0xff, ...bytes];
+        return [0xc6, ...u32(bytes.length), ...bytes];
+    }
+    if (Array.isArray(value)) {
+        const head = value.length < 16 ? [0x90 | value.length] : value.length <= 0xffff ? [0xdc, value.length >>> 8, value.length & 0xff] : [0xdd, ...u32(value.length)];
+        return [...head, ...value.flatMap(entry => encodeValue(entry, depth + 1))];
+    }
+    if (isRecord(value)) {
+        const entries = Object.entries(value).filter(([, child]) => child !== undefined);
+        const head = entries.length < 16 ? [0x80 | entries.length] : entries.length <= 0xffff ? [0xde, entries.length >>> 8, entries.length & 0xff] : [0xdf, ...u32(entries.length)];
+        return [...head, ...entries.flatMap(([key, child]) => [...encodeValue(key, depth + 1), ...encodeValue(child, depth + 1)])];
+    }
+    throw new Error(`unsupported resident value: ${typeof value}`);
+}
+function encodeInteger(value) {
+    if (value >= 0 && value <= 0x7f)
+        return [value];
+    if (value < 0 && value >= -32)
+        return [0x100 + value];
+    if (value >= 0 && value <= 0xff)
+        return [0xcc, value];
+    if (value >= 0 && value <= 0xffff)
+        return [0xcd, value >>> 8, value & 0xff];
+    if (value >= -0x80 && value < 0)
+        return [0xd0, value & 0xff];
+    if (value >= -0x8000 && value < 0)
+        return [0xd1, (value >>> 8) & 0xff, value & 0xff];
+    if (value >= 0 && value <= 0xffffffff)
+        return [0xce, ...u32(value)];
+    return [0xd3, ...i64(value)];
+}
+function decodeValue(state, depth) {
+    if (depth > MAX_DEPTH)
+        throw new Error("resident value exceeds nesting limit");
+    const marker = byte(state);
+    if (marker <= 0x7f)
+        return marker;
+    if (marker >= 0xe0)
+        return marker - 0x100;
+    if ((marker & 0xe0) === 0xa0)
+        return string(state, marker & 0x1f);
+    if ((marker & 0xf0) === 0x90)
+        return array(state, marker & 0x0f, depth);
+    if ((marker & 0xf0) === 0x80)
+        return map(state, marker & 0x0f, depth);
+    switch (marker) {
+        case 0xc0: return null;
+        case 0xc2: return false;
+        case 0xc3: return true;
+        case 0xc4: return binary(state, uint(state, 1));
+        case 0xc5: return binary(state, uint(state, 2));
+        case 0xc6: return binary(state, uint(state, 4));
+        case 0xcc: return uint(state, 1);
+        case 0xcd: return uint(state, 2);
+        case 0xce: return uint(state, 4);
+        case 0xcf: return safeInteger(state, false);
+        case 0xd0: return signed(state, 1);
+        case 0xd1: return signed(state, 2);
+        case 0xd2: return signed(state, 4);
+        case 0xd3: return safeInteger(state, true);
+        case 0xd9: return string(state, uint(state, 1));
+        case 0xda: return string(state, uint(state, 2));
+        case 0xdb: return string(state, uint(state, 4));
+        case 0xdc: return array(state, uint(state, 2), depth);
+        case 0xdd: return array(state, uint(state, 4), depth);
+        case 0xde: return map(state, uint(state, 2), depth);
+        case 0xdf: return map(state, uint(state, 4), depth);
+        default: throw new Error(`unsupported resident MessagePack marker 0x${marker.toString(16)}`);
+    }
+}
+function byte(state) {
+    const value = state.bytes[state.offset++];
+    if (value === undefined)
+        throw new Error("incomplete resident value");
+    return value;
+}
+function uint(state, width) {
+    let value = 0;
+    for (let index = 0; index < width; index++)
+        value = value * 256 + byte(state);
+    return value;
+}
+function signed(state, width) {
+    const value = uint(state, width);
+    return value >= 2 ** (width * 8 - 1) ? value - 2 ** (width * 8) : value;
+}
+function safeInteger(state, signedValue) {
+    const high = uint(state, 4);
+    const low = uint(state, 4);
+    const value = high * 0x1_0000_0000 + low;
+    const resolved = signedValue && high >= 0x80000000 ? value - 0x1_0000_0000_0000_0000 : value;
+    if (!Number.isSafeInteger(resolved))
+        throw new Error("resident integer exceeds JavaScript safe range");
+    return resolved;
+}
+function string(state, length) {
+    return Buffer.from(binary(state, length)).toString("utf8");
+}
+function binary(state, length) {
+    const end = state.offset + length;
+    if (end > state.bytes.byteLength)
+        throw new Error("incomplete resident value");
+    const value = state.bytes.slice(state.offset, end);
+    state.offset = end;
+    return value;
+}
+function array(state, length, depth) {
+    if (length > 65_536)
+        throw new Error("resident collection exceeds limit");
+    return Array.from({ length }, () => decodeValue(state, depth + 1));
+}
+function map(state, length, depth) {
+    if (length > 65_536)
+        throw new Error("resident collection exceeds limit");
+    const value = {};
+    for (let index = 0; index < length; index++) {
+        const key = decodeValue(state, depth + 1);
+        if (typeof key !== "string" || Object.hasOwn(value, key))
+            throw new Error("invalid resident map key");
+        value[key] = decodeValue(state, depth + 1);
+    }
+    return value;
+}
+function u32(value) { return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff]; }
+function i64(value) {
+    const integer = BigInt(value);
+    const encoded = integer < 0 ? (1n << 64n) + integer : integer;
+    return Array.from({ length: 8 }, (_, index) => Number((encoded >> BigInt((7 - index) * 8)) & 0xffn));
+}
+function isRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/dist/foundation/resident-tabs/recovery.d.ts

@@ -0,0 +1,26 @@
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+import { type PromptSubmission, type SessionJournalEntry, type SubmittedPromptRecord } from "./prompt-journal.js";
+export interface ResidentTabRecoveredInput {
+    readonly prompts: readonly SubmittedPromptRecord[];
+    readonly draft: string | null;
+}
+export interface ResidentTabAdmission extends Omit<PromptSubmission, "fileExisted" | "incarnation"> {
+    readonly incarnation: number;
+}
+export declare class ResidentTabRecovery {
+    #private;
+    constructor(dataDir: string, options?: {
+        readonly faults?: ResidentTabFaultInjection;
+        readonly onDegraded?: (degraded: boolean) => void;
+    });
+    get recovered(): ResidentTabRecoveredInput;
+    initialize(currentSessionFile?: string | null, currentSessionId?: string | null): Promise<ResidentTabRecoveredInput>;
+    admit(input: ResidentTabAdmission, timeoutMs?: number): Promise<SubmittedPromptRecord>;
+    dispatched(): void;
+    correlated(submissionId: string, entryId: string): Promise<void>;
+    checkpoint(text: string): void;
+    settled(sessionFile: string | null): Promise<void>;
+    gracefulStop(sessionFile: string | null): Promise<void>;
+}
+/** Reconcile only durable user/assistant ancestry; a torn final JSONL record is not authority. */
+export declare function readSessionJournal(path: string): Promise<readonly SessionJournalEntry[]>;