@timurproko/a1 0.2.7-dev.746 → 0.2.7-dev.767

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/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[]>;

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

@@ -0,0 +1,205 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DraftCheckpointer } from "./draft-checkpoint.js";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+import { PromptJournal } from "./prompt-journal.js";
+import { SettledTurnSynchronizer, synchronizeSessionFile } from "./session-sync.js";
+export class ResidentTabRecovery {
+    #journal;
+    #draft;
+    #synchronizer;
+    #faults;
+    #onDegraded;
+    #active = [];
+    #recovered = { prompts: [], draft: null };
+    constructor(dataDir, options = {}) {
+        const faults = options.faults ?? new ResidentTabFaultInjection();
+        this.#faults = faults;
+        this.#onDegraded = options.onDegraded ?? (() => { });
+        this.#journal = new PromptJournal(join(dataDir, "journal.jsonl"), { faults });
+        this.#draft = new DraftCheckpointer(join(dataDir, "draft.json"), { faults, onDegraded: this.#onDegraded });
+        this.#synchronizer = new SettledTurnSynchronizer(this.#journal, faults);
+    }
+    get recovered() { return this.#recovered; }
+    async initialize(currentSessionFile = null, currentSessionId = null) {
+        await this.#journal.initialize();
+        await adoptHistoricalJournals(dirname(dirname(this.#journal.path)), this.#journal, currentSessionFile, currentSessionId);
+        const records = await this.#journal.read();
+        const sessionFiles = new Set(records.flatMap(record => record.type === "submitted" && record.sessionFile !== null ? [record.sessionFile] : []));
+        if (currentSessionFile !== null)
+            sessionFiles.add(currentSessionFile);
+        const sessionEntries = (await Promise.all([...sessionFiles].map(readSessionJournal))).flat();
+        const [pending, draft] = await Promise.all([
+            this.#journal.pending(sessionEntries),
+            this.#draft.restore(),
+        ]);
+        this.#recovered = { prompts: pending.map(value => value.submitted), draft: draft?.text ?? null };
+        return this.#recovered;
+    }
+    async admit(input, timeoutMs = 2_000) {
+        const fileExisted = input.sessionFile === null ? false : await stat(input.sessionFile).then(() => true, error => {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        });
+        let timer;
+        try {
+            return await Promise.race([
+                this.#journal.submit({ ...input, fileExisted }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("resident prompt journal admission timed out")), timeoutMs);
+                    timer.unref();
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    dispatched() { this.#faults.at("journal-after-dispatch"); }
+    async correlated(submissionId, entryId) {
+        await this.#journal.correlate(submissionId, entryId);
+        this.#active.push({ id: submissionId, entryId });
+    }
+    checkpoint(text) { this.#draft.change(text); }
+    async settled(sessionFile) {
+        const active = this.#active.splice(0);
+        if (active.length === 0 || sessionFile === null)
+            return;
+        await this.#synchronizer.settleMany(sessionFile, active);
+        for (const entry of active)
+            await this.#journal.retire(entry.id);
+        await this.#journal.compactIfRetired();
+    }
+    async gracefulStop(sessionFile) {
+        await this.#draft.flush();
+        if (sessionFile !== null)
+            await synchronizeSessionFile(sessionFile);
+        await this.#synchronizer.flush();
+    }
+}
+const MAX_SESSION_RECONCILE_BYTES = 64 * 1024 * 1024;
+const MAX_ADOPTION_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+async function adoptHistoricalJournals(profileTabsRoot, target, currentSessionFile, currentSessionId) {
+    if (currentSessionFile === null && currentSessionId === null)
+        return;
+    const history = join(profileTabsRoot, "registry-history");
+    const names = await readdir(history).catch(() => []);
+    for (const name of names.filter(value => /^tabset-.+\.json$/.test(value)).sort().reverse()) {
+        const path = join(history, name);
+        const metadata = await stat(path).catch(() => null);
+        if (metadata === null || Date.now() - metadata.mtimeMs > MAX_ADOPTION_AGE_MS)
+            continue;
+        let document;
+        try {
+            document = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const tabs = typeof document === "object" && document !== null && Array.isArray(document.tabs)
+            ? document.tabs : [];
+        for (const value of tabs) {
+            if (typeof value !== "object" || value === null)
+                continue;
+            const tab = value;
+            if (typeof tab.tabId !== "string")
+                continue;
+            const fileMatches = currentSessionFile !== null && typeof tab.sessionFile === "string"
+                && resolve(tab.sessionFile) === resolve(currentSessionFile);
+            const sourcePath = join(profileTabsRoot, tab.tabId, "journal.jsonl");
+            if (resolve(sourcePath) === resolve(target.path))
+                continue;
+            if (!await stat(sourcePath).then(() => true, () => false))
+                continue;
+            const source = new PromptJournal(sourcePath);
+            await source.initialize();
+            const records = await source.read();
+            const submitted = records.filter((record) => record.type === "submitted");
+            const idMatches = currentSessionId !== null && submitted.some(record => record.sessionId === currentSessionId);
+            if (!fileMatches && !idMatches)
+                continue;
+            const pending = await source.pending(currentSessionFile === null ? [] : await readSessionJournal(currentSessionFile));
+            for (const entry of pending) {
+                await target.adopt(entry.submitted);
+                await source.retire(entry.submitted.id);
+            }
+        }
+    }
+}
+/** Reconcile only durable user/assistant ancestry; a torn final JSONL record is not authority. */
+export async function readSessionJournal(path) {
+    let text;
+    try {
+        const metadata = await stat(path);
+        if (metadata.size > MAX_SESSION_RECONCILE_BYTES)
+            throw new Error("resident session exceeds the recovery scan limit");
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const raw = [];
+    const lines = text.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.length === 0)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch (error) {
+            if (index === lines.length - 1 && !text.endsWith("\n"))
+                break;
+            throw error;
+        }
+        if (typeof value !== "object" || value === null)
+            continue;
+        const record = value;
+        const message = typeof record.message === "object" && record.message !== null
+            ? record.message
+            : null;
+        if (record.type !== "message" || typeof record.id !== "string" || message === null
+            || typeof message.role !== "string")
+            continue;
+        const content = message.content;
+        const promptText = typeof content === "string" ? content : Array.isArray(content)
+            ? content.flatMap(part => typeof part === "object" && part !== null
+                && part.type === "text"
+                && typeof part.text === "string"
+                ? [part.text] : []).join("")
+            : "";
+        raw.push({
+            id: record.id,
+            parentId: typeof record.parentId === "string" ? record.parentId : null,
+            role: message.role,
+            text: promptText,
+        });
+    }
+    const byId = new Map(raw.map(record => [record.id, record]));
+    const settled = new Set();
+    for (const record of raw) {
+        if (record.role !== "assistant")
+            continue;
+        let parent = record.parentId;
+        const visited = new Set();
+        while (parent !== null && !visited.has(parent)) {
+            visited.add(parent);
+            const ancestor = byId.get(parent);
+            if (ancestor === undefined)
+                break;
+            if (ancestor.role === "user") {
+                settled.add(ancestor.id);
+                break;
+            }
+            parent = ancestor.parentId;
+        }
+    }
+    return raw
+        .filter(record => record.role === "user")
+        .map(record => ({ entryId: record.id, text: record.text, settled: settled.has(record.id) }));
+}

package/dist/foundation/resident-tabs/session-sync.d.ts

@@ -0,0 +1,14 @@
+import type { PromptJournal } from "./prompt-journal.js";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+export declare function synchronizeSessionFile(path: string, faults?: ResidentTabFaultInjection): Promise<void>;
+/** Serializes settled-turn sync and journal ordering off the input path. */
+export declare class SettledTurnSynchronizer {
+    #private;
+    constructor(journal: PromptJournal, faults?: ResidentTabFaultInjection);
+    settle(sessionFile: string, submissionId: string, entryId: string): Promise<void>;
+    settleMany(sessionFile: string, entries: readonly {
+        readonly id: string;
+        readonly entryId: string;
+    }[]): Promise<void>;
+    flush(): Promise<void>;
+}

package/dist/foundation/resident-tabs/session-sync.js

@@ -0,0 +1,37 @@
+import { open } from "node:fs/promises";
+import { ResidentTabFaultInjection } from "./fault-injection.js";
+export async function synchronizeSessionFile(path, faults = new ResidentTabFaultInjection()) {
+    const handle = await open(path, "r+");
+    try {
+        faults.at("session-before-sync");
+        await handle.sync();
+        faults.at("session-after-sync");
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Serializes settled-turn sync and journal ordering off the input path. */
+export class SettledTurnSynchronizer {
+    #journal;
+    #faults;
+    #queue = Promise.resolve();
+    constructor(journal, faults = new ResidentTabFaultInjection()) {
+        this.#journal = journal;
+        this.#faults = faults;
+    }
+    settle(sessionFile, submissionId, entryId) {
+        return this.settleMany(sessionFile, [{ id: submissionId, entryId }]);
+    }
+    settleMany(sessionFile, entries) {
+        const operation = this.#queue.then(async () => {
+            await synchronizeSessionFile(sessionFile, this.#faults);
+            this.#faults.at("journal-after-settle-sync");
+            for (const entry of entries)
+                await this.#journal.settle(entry.id, entry.entryId);
+        });
+        this.#queue = operation.catch(() => undefined);
+        return operation;
+    }
+    flush() { return this.#queue; }
+}

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

@@ -1,2 +1,9 @@
-/** Read only the routing flag before any UI or extension module is loaded. */
-export declare function readResidentTabsSetting(configDir: string, profileId?: string): Promise<boolean>;
+export interface ResidentTabLaunchSettings {
+    readonly residentTabs: boolean;
+    readonly maxConcurrentStarts: number;
+    readonly unresponsiveRestartSeconds: number;
+    readonly stallNoticeSeconds: number;
+}
+/** Read only resident-launch values before any UI or extension module is loaded. */
+export declare function readResidentTabLaunchSettings(profileDir: string, namespace?: string, legacyConfigDir?: string, profileId?: string): Promise<ResidentTabLaunchSettings>;
+export declare function readResidentTabsSetting(profileDir: string, namespace?: string, legacyConfigDir?: string, profileId?: string): Promise<boolean>;

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

@@ -1,17 +1,65 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { parseOwnedUiSettingsDocument, resolveResidentTabsSetting } from "../../ui/settings/index.js";
+import { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_MIGRATIONS, OWNED_UI_SETTINGS_VERSION, normalizeOwnedUiSettingsValues, parseOwnedUiSettingsDocument, readProfileSettingsNamespace, repairProfileSettingsDocument, resolveOwnedUiSettings, settingValue, } from "../../ui/settings/index.js";
 const MAX_SETTINGS_BYTES = 256 * 1024;
-/** Read only the routing flag before any UI or extension module is loaded. */
-export async function readResidentTabsSetting(configDir, profileId = "a1") {
-    const file = resolve(configDir, "settings", `${profileId}.json`);
+const DEFAULTS = Object.freeze({
+    residentTabs: false,
+    maxConcurrentStarts: 2,
+    unresponsiveRestartSeconds: 120,
+    stallNoticeSeconds: 300,
+});
+/** Read only resident-launch values before any UI or extension module is loaded. */
+export async function readResidentTabLaunchSettings(profileDir, namespace = "a1", legacyConfigDir, profileId = namespace) {
+    const sharedFile = resolve(profileDir, "settings.json");
+    try {
+        repairProfileSettingsDocument(sharedFile);
+    }
+    catch {
+        // Compatibility: recovery is opportunistic; resident launch falls back when bytes stay invalid.
+    }
+    const shared = readProfileSettingsNamespace(sharedFile, namespace);
+    if (shared.status === "invalid")
+        return DEFAULTS;
+    if (shared.status === "available") {
+        const compatibility = normalizeOwnedUiSettingsValues(shared.value);
+        return compatibility.values === null
+            ? DEFAULTS
+            : resolveLaunchValues({ version: OWNED_UI_SETTINGS_VERSION, values: compatibility.values }, []);
+    }
+    const file = resolve(legacyConfigDir ?? profileDir, "settings", `${profileId}.json`);
     try {
         const raw = await readFile(file, "utf8");
         if (Buffer.byteLength(raw, "utf8") > MAX_SETTINGS_BYTES)
-            return false;
-        return resolveResidentTabsSetting(parseOwnedUiSettingsDocument(raw));
+            return DEFAULTS;
+        const document = parseOwnedUiSettingsDocument(raw);
+        return document === null ? DEFAULTS : resolveLaunchValues(document, OWNED_UI_SETTINGS_MIGRATIONS);
     }
     catch {
-        return false;
+        return DEFAULTS;
     }
 }
+export async function readResidentTabsSetting(profileDir, namespace = "a1", legacyConfigDir, profileId = namespace) {
+    return (await readResidentTabLaunchSettings(profileDir, namespace, legacyConfigDir, profileId)).residentTabs;
+}
+function resolveLaunchValues(document, migrations) {
+    const resolution = resolveOwnedUiSettings({
+        declarations: [
+            OWNED_SETTING_DECLARATIONS.residentTabs,
+            OWNED_SETTING_DECLARATIONS.tabsMaxConcurrentStarts,
+            OWNED_SETTING_DECLARATIONS.tabsUnresponsiveRestartSeconds,
+            OWNED_SETTING_DECLARATIONS.tabsStallNoticeSeconds,
+        ],
+        migrations,
+        document,
+        currentVersion: OWNED_UI_SETTINGS_VERSION,
+    });
+    const maximum = settingValue(resolution, "tabsMaxConcurrentStarts");
+    const unresponsive = settingValue(resolution, "tabsUnresponsiveRestartSeconds");
+    const stall = settingValue(resolution, "tabsStallNoticeSeconds");
+    return {
+        residentTabs: settingValue(resolution, "residentTabs") === true,
+        maxConcurrentStarts: typeof maximum === "number" ? maximum : DEFAULTS.maxConcurrentStarts,
+        unresponsiveRestartSeconds: typeof unresponsive === "number" ? unresponsive : DEFAULTS.unresponsiveRestartSeconds,
+        stallNoticeSeconds: typeof stall === "number" ? stall : DEFAULTS.stallNoticeSeconds,
+    };
+}

package/dist/foundation/session-writer-lock/index.d.ts

@@ -0,0 +1,27 @@
+export interface NativeLock {
+    readonly bound: boolean;
+    bindCreated(path: string): void;
+    release(): void;
+}
+export interface LockBackend {
+    acquire(path: string): NativeLock;
+}
+/** Reports that a canonical session identity already has a live writer. */
+export declare class SessionWriterConflict extends Error {
+    readonly path: string;
+    readonly holderKind: string;
+    constructor(path: string, holderKind?: string);
+}
+export interface SessionWriterHandle {
+    readonly path: string;
+    readonly bound: boolean;
+    bind(createdPath?: string): void;
+    release(): void;
+}
+export declare function acquireExisting(path: string): SessionWriterHandle;
+export declare function reserveNew(parent: string, name: string): SessionWriterHandle;
+export declare function acquireSessionWriter(path: string): SessionWriterHandle;
+export declare function bind(handle: SessionWriterHandle, createdPath?: string): void;
+export declare function release(handle: SessionWriterHandle): void;
+/** Test-only backend seam; passing undefined restores native discovery. */
+export declare function setSessionWriterLockBackendForTest(value: LockBackend | undefined): void;