@myagentroam/agent 0.11.33 → 0.11.35

package/dist/session/store/jsonl/history-replacement.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { readdir, rename, rm } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { toolResultResourceFiles } from '../../tool-result-resources.js';
+import { beginSessionStorageTransaction, retiredSessionTrashPath, recoverSessionStorageTransaction } from './transaction-recovery.js';
+import { deriveExecutionState } from '../execution-state.js';
+import { renameIfExists, retainedSessionTitle, stageSessionSegments, stageUnreferencedImages } from './history.js';
+import { generatedImageFileNames } from './images.js';
+import { CONTEXTUAL_WORLD_STATE_FILE } from './open-recovery.js';
+import { resourceFiles } from './resources.js';
+import { syncJsonlDirectory } from './fs-durability.js';
+/** Execute one rollback/clear transaction while its caller holds maintenance. */
+export async function replaceSessionHistory(meta, retained, operation, context) {
+    const targetDirectory = context.targetGeneration === undefined
+        ? context.directory
+        : join(context.sessionDirectory, 'v2', context.targetGeneration);
+    const staged = await stageSessionSegments(targetDirectory, retained);
+    const transactionId = randomUUID();
+    const targetNextSequence = operation.kind === 'clear' ? 2 : (retained.at(-1)?.sequence ?? 0) + 1;
+    const contextualWorldStatePath = join(context.directory, CONTEXTUAL_WORLD_STATE_FILE);
+    const contextualWorldStateBackup = `${contextualWorldStatePath}.${targetNextSequence}.${transactionId}.${operation.kind}-backup`;
+    const originalTransactionId = meta.storageTransactionId;
+    const originalPaths = await context.segmentPaths();
+    const retiredPaths = await retiredSessionPaths(context.sessionDirectory, context.directory, targetDirectory);
+    const backups = originalPaths.map((path) => ({
+        path,
+        backup: `${path}.${transactionId}.${operation.kind}-backup`
+    }));
+    const transaction = {
+        version: 1,
+        id: transactionId,
+        kind: operation.kind,
+        originalSegments: originalPaths.map((path) => basename(path)),
+        stagedSegments: staged.files.map((item) => ({
+            path: basename(item.path),
+            temporary: basename(item.temporaryPath)
+        })),
+        sidecarBackup: basename(contextualWorldStateBackup),
+        retiredPaths,
+        ...(context.targetGeneration === undefined
+            ? {}
+            : { targetGeneration: context.targetGeneration })
+    };
+    let committed = false;
+    let uncertain = false;
+    const recover = (selected) => recoverSessionStorageTransaction(context.directory, selected ? transactionId : originalTransactionId, context.sessionDirectory);
+    try {
+        await beginSessionStorageTransaction(context.directory, transaction);
+        await syncJsonlDirectory(context.directory);
+        await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
+        await stageUnreferencedImages(context.sessionDirectory, 'generated_images', operation.kind === 'rollback' ? new Set(generatedImageFileNames(retained)) : new Set(), transactionId);
+        await stageUnreferencedImages(context.directory, 'resources', operation.kind === 'rollback' ? resourceFiles(retained) : new Set(), transactionId);
+        await stageUnreferencedImages(context.directory, 'tool_results', operation.kind === 'rollback' ? toolResultResourceFiles(retained) : new Set(), transactionId);
+        for (const path of retiredPaths)
+            await renameIfExists(join(context.sessionDirectory, path), retiredSessionTrashPath(context.sessionDirectory, path, transactionId));
+        for (const item of backups)
+            await rename(item.path, item.backup);
+        for (const item of staged.files) {
+            await rename(item.temporaryPath, item.path);
+        }
+        for (const directory of new Set([
+            context.directory,
+            context.sessionDirectory,
+            targetDirectory,
+            join(context.sessionDirectory, 'v2'),
+            join(context.sessionDirectory, 'generated_images'),
+            join(context.directory, 'resources'),
+            join(context.directory, 'tool_results')
+        ])) {
+            try {
+                await syncJsonlDirectory(directory);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        const title = operation.kind === 'rollback' ? retainedSessionTitle(retained, '') : '';
+        const outcome = await context.settleIndex({
+            kind: 'apply',
+            change: {
+                transactionId,
+                nextSequence: targetNextSequence,
+                segments: staged.segments,
+                ...(context.targetGeneration === undefined
+                    ? {}
+                    : { targetGeneration: context.targetGeneration }),
+                ...(operation.kind === 'rollback'
+                    ? {
+                        kind: 'rollback',
+                        state: deriveExecutionState(retained),
+                        ...(title ? { title } : {})
+                    }
+                    : { kind: 'clear', clearedAt: operation.clearedAt })
+            }
+        }, recover);
+        if (outcome.status !== 'committed' || outcome.error !== undefined) {
+            uncertain =
+                outcome.status === 'unknown' ||
+                    (outcome.status === 'committed' && outcome.recoveryRequired === true);
+            return outcome;
+        }
+        committed = true;
+        try {
+            await recover(true);
+            return outcome;
+        }
+        catch (error) {
+            uncertain = true;
+            return { status: 'committed', meta: outcome.meta, error, recoveryRequired: true };
+        }
+    }
+    catch (error) {
+        if (committed) {
+            uncertain = true;
+            return { status: 'unknown', error };
+        }
+        const outcome = await context.settleIndex({ kind: 'recover', transactionId, error }, recover);
+        uncertain =
+            outcome.status === 'unknown' ||
+                (outcome.status === 'committed' && outcome.recoveryRequired === true);
+        return outcome;
+    }
+    finally {
+        if (!uncertain)
+            await Promise.all(staged.files.map((item) => rm(item.temporaryPath, { force: true }))).catch(() => undefined);
+    }
+}
+async function retiredSessionPaths(root, active, target) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const paths = entries
+        .filter((entry) => root !== active &&
+        ((entry.isFile() &&
+            (/^events-\d{6}\.jsonl$/u.test(entry.name) ||
+                entry.name === 'context-world-state.json')) ||
+            (entry.isDirectory() && ['resources', 'tool_results'].includes(entry.name))))
+        .map((entry) => entry.name);
+    const generations = await readdir(join(root, 'v2'), { withFileTypes: true });
+    for (const entry of generations) {
+        if (!entry.isDirectory() || !/^[0-9a-f-]{36}$/u.test(entry.name))
+            continue;
+        const relative = `v2/${entry.name}`;
+        if (join(root, relative) !== active && join(root, relative) !== target)
+            paths.push(relative);
+    }
+    return paths;
+}

package/dist/session/store/jsonl/history.d.ts

@@ -0,0 +1,25 @@
+import type { SessionMeta, SessionRecord } from '../types.js';
+export declare function renameIfExists(from: string, to: string): Promise<boolean>;
+interface StagedSessionSegments {
+    readonly files: readonly {
+        readonly path: string;
+        readonly temporaryPath: string;
+    }[];
+    readonly segments: NonNullable<SessionMeta['segments']>;
+}
+export declare function stageSessionSegments(sessionDirectory: string, records: readonly SessionRecord[], operation?: 'rollback' | 'fork'): Promise<StagedSessionSegments>;
+export declare function stageUnreferencedImages(sessionDirectory: string, directoryName: 'generated_images' | 'tool_results' | 'resources', retained: ReadonlySet<string>, transactionId: string): Promise<Array<{
+    from: string;
+    to: string;
+    trash: string;
+}>>;
+export declare function restoreRenamedFiles(files: readonly {
+    readonly from: string;
+    readonly to: string;
+}[]): Promise<void>;
+export declare function retainedSessionTitle(records: readonly SessionRecord[], fallback: string): string;
+export declare function forkedPayload(type: string, value: unknown, sourceSessionId: string, targetSessionId: string, title: string, identities: ReadonlyMap<string, {
+    recordId: string;
+    sequence: number;
+}>): unknown;
+export {};

package/dist/session/store/jsonl/history.js

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto';
+import { open, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { parseInlineMediaState } from '../../inline-media.js';
+import { MAX_SEGMENT_BYTES } from './records.js';
+export async function renameIfExists(from, to) {
+    try {
+        await rename(from, to);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function stageSessionSegments(sessionDirectory, records, operation = 'rollback') {
+    let group;
+    if (records.length === 0)
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
+    const transactionId = randomUUID();
+    const files = [];
+    const segments = [];
+    const flush = async () => {
+        if (group === undefined)
+            return;
+        const number = segments.length + 1;
+        const path = join(sessionDirectory, `events-${String(number).padStart(6, '0')}.jsonl`);
+        const temporaryPath = `${path}.${transactionId}.${operation}-tmp`;
+        const handle = await open(temporaryPath, 'wx', 0o600);
+        files.push({ path, temporaryPath });
+        try {
+            await handle.writeFile(group.lines.join(''));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        segments.push({
+            number,
+            firstSequence: group.firstSequence,
+            lastSequence: group.lastSequence,
+            bytes: group.bytes
+        });
+        group = undefined;
+    };
+    try {
+        for (const record of records) {
+            const line = `${JSON.stringify(record)}\n`;
+            const bytes = Buffer.byteLength(line);
+            if (group !== undefined && group.bytes > 0 && group.bytes + bytes > MAX_SEGMENT_BYTES)
+                await flush();
+            if (group === undefined) {
+                group = {
+                    lines: [],
+                    bytes: 0,
+                    firstSequence: record.sequence,
+                    lastSequence: record.sequence
+                };
+            }
+            group.lines.push(line);
+            group.bytes += bytes;
+            group.lastSequence = record.sequence;
+        }
+        await flush();
+        return { files, segments };
+    }
+    catch (error) {
+        await Promise.all(files.map((item) => rm(item.temporaryPath, { force: true }))).catch(() => undefined);
+        throw error;
+    }
+}
+export async function stageUnreferencedImages(sessionDirectory, directoryName, retained, transactionId) {
+    const directory = join(sessionDirectory, directoryName);
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const moved = [];
+    try {
+        for (const name of names) {
+            if (retained.has(name))
+                continue;
+            const from = join(directory, name);
+            const trash = join(directory, `.${name}.${transactionId}.rollback-trash`);
+            await rename(from, trash);
+            moved.push({ from: trash, to: from, trash });
+        }
+        return moved;
+    }
+    catch (error) {
+        await restoreRenamedFiles(moved);
+        throw error;
+    }
+}
+export async function restoreRenamedFiles(files) {
+    for (const file of files.toReversed())
+        await rename(file.from, file.to).catch(() => undefined);
+}
+export function retainedSessionTitle(records, fallback) {
+    let title = fallback;
+    for (const record of records) {
+        if ((record.type === 'session.created' || record.type === 'session.title.updated') &&
+            isObject(record.payload) &&
+            typeof record.payload.title === 'string' &&
+            record.payload.title.trim().length > 0)
+            title = record.payload.title;
+    }
+    return title;
+}
+export function forkedPayload(type, value, sourceSessionId, targetSessionId, title, identities) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const payload = { ...value };
+    const remapWindow = (value) => {
+        const state = parseInlineMediaState(value);
+        if (!state)
+            return value;
+        for (const cursor of [state.consideredThrough, state.evictedThrough]) {
+            if (!cursor?.sourceId.startsWith('input:'))
+                continue;
+            const target = identities.get(cursor.sourceId.slice(6));
+            if (!target)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork media reference is missing.');
+            cursor.sourceId = `input:${target.recordId}`;
+        }
+        return state;
+    };
+    if (type === 'resource.window')
+        return remapWindow(payload);
+    if (payload.sessionId === sourceSessionId)
+        payload.sessionId = targetSessionId;
+    const application = (input) => {
+        if (typeof input.inputRef !== 'string') {
+            const recordId = isObject(input.metadata) ? input.metadata.recordId : undefined;
+            const identity = typeof recordId === 'string' ? identities.get(recordId) : undefined;
+            return identity && isObject(input.metadata)
+                ? { ...input, metadata: { ...input.metadata, recordId: identity.recordId } }
+                : input;
+        }
+        const identity = identities.get(input.inputRef);
+        if (!identity)
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork input reference is missing.');
+        return {
+            ...input,
+            inputRef: identity.recordId,
+            ...(isObject(input.metadata)
+                ? { metadata: { ...input.metadata, recordId: identity.recordId } }
+                : {})
+        };
+    };
+    if (type === 'model.context')
+        return application(payload);
+    if (type === 'compact.completed') {
+        if (payload.inlineMediaState)
+            payload.inlineMediaState = remapWindow(payload.inlineMediaState);
+        if (Array.isArray(payload.retainedModelContext))
+            payload.retainedModelContext = payload.retainedModelContext.map((item) => isObject(item) ? application(item) : item);
+        if (Array.isArray(payload.pendingInputs))
+            payload.pendingInputs = payload.pendingInputs.map((record) => {
+                const identity = identities.get(record.recordId);
+                if (!identity)
+                    throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork pending input reference is missing.');
+                return { ...record, ...identity, sessionId: targetSessionId };
+            });
+    }
+    if (type === 'session.title.updated') {
+        payload.title = title;
+        payload.automatic = false;
+    }
+    return payload;
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/session/store/jsonl/images.d.ts

@@ -0,0 +1,19 @@
+import type { SessionRecord } from '../types.js';
+export declare const MAX_INPUT_IMAGES = 5;
+export declare function generatedImageFileNames(records: readonly SessionRecord[]): readonly string[];
+export declare function copyGeneratedImages(sourceSessionDirectory: string, targetSessionDirectory: string, fileNames: readonly string[]): Promise<void>;
+interface InputImageReference {
+    readonly name: string;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly byteSize: number;
+    readonly sha256: string;
+    readonly resourceId?: string;
+    readonly url?: string;
+    readonly urlExpiresAt?: number;
+}
+export declare function inputImageReferences(value: unknown): InputImageReference[];
+export declare function inputImageReference(value: unknown): InputImageReference | undefined;
+export declare function validInputImageFileName(fileName: string): boolean;
+export declare function readInputImageBytes(directory: string, reference: InputImageReference): Promise<Buffer>;
+export {};

package/dist/session/store/jsonl/images.js

@@ -0,0 +1,122 @@
+import { copyFile, mkdir, open, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { isModelImageUrl } from '../../../model/image.js';
+export const MAX_INPUT_IMAGES = 5;
+const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_INPUT_IMAGES_BYTES = 10 * 1024 * 1024;
+const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+export function generatedImageFileNames(records) {
+    const names = new Set();
+    for (const record of records) {
+        if (record.type !== 'tool.completed' || !isObject(record.payload))
+            continue;
+        const artifacts = record.payload.artifacts;
+        if (!Array.isArray(artifacts))
+            continue;
+        for (const artifact of artifacts) {
+            if (!isObject(artifact) ||
+                artifact.kind !== 'image' ||
+                typeof artifact.fileName !== 'string' ||
+                basename(artifact.fileName) !== artifact.fileName ||
+                !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\.png$/u.test(artifact.fileName))
+                continue;
+            names.add(artifact.fileName);
+        }
+    }
+    return [...names];
+}
+export async function copyGeneratedImages(sourceSessionDirectory, targetSessionDirectory, fileNames) {
+    if (fileNames.length === 0)
+        return;
+    const source = join(sourceSessionDirectory, 'generated_images');
+    const target = join(targetSessionDirectory, 'generated_images');
+    await mkdir(target, { recursive: true });
+    for (const fileName of fileNames) {
+        const path = join(target, fileName);
+        await copyFile(join(source, fileName), path);
+        const handle = await open(path, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+export function inputImageReferences(value) {
+    if (!Array.isArray(value))
+        return [];
+    const references = [];
+    let totalBytes = 0;
+    for (const image of value) {
+        const reference = inputImageReference(image);
+        if (reference === undefined)
+            continue;
+        totalBytes += reference.byteSize;
+        if (references.length >= MAX_INPUT_IMAGES || totalBytes > MAX_INPUT_IMAGES_BYTES)
+            throw corruptInputImageReference();
+        references.push(reference);
+    }
+    return references;
+}
+export function inputImageReference(value) {
+    if (!isObject(value) ||
+        (!Object.hasOwn(value, 'fileName') && !Object.hasOwn(value, 'resourceId')))
+        return undefined;
+    const fileName = value.fileName ??
+        (typeof value.resourceId === 'string' ? `${value.resourceId}.bin` : undefined);
+    if (typeof value.name !== 'string' ||
+        typeof value.mimeType !== 'string' ||
+        !INPUT_IMAGE_MIME_TYPES.has(value.mimeType) ||
+        typeof value.byteSize !== 'number' ||
+        !Number.isSafeInteger(value.byteSize) ||
+        value.byteSize <= 0 ||
+        value.byteSize > MAX_INPUT_IMAGE_BYTES ||
+        typeof fileName !== 'string' ||
+        !validInputImageFileName(fileName) ||
+        typeof value.sha256 !== 'string' ||
+        !/^[a-f0-9]{64}$/u.test(value.sha256) ||
+        (value.resourceId !== undefined &&
+            (typeof value.resourceId !== 'string' ||
+                !/^[a-f0-9]{64}$/u.test(value.resourceId) ||
+                fileName !== `${value.resourceId}.bin`)) ||
+        (value.url !== undefined && !isModelImageUrl(value.url)) ||
+        (value.urlExpiresAt !== undefined &&
+            (typeof value.urlExpiresAt !== 'number' ||
+                !Number.isSafeInteger(value.urlExpiresAt) ||
+                value.urlExpiresAt <= 0)) ||
+        (value.urlExpiresAt !== undefined && value.url === undefined))
+        throw corruptInputImageReference();
+    return {
+        name: value.name,
+        fileName,
+        mimeType: value.mimeType,
+        byteSize: value.byteSize,
+        sha256: value.sha256,
+        ...(typeof value.resourceId === 'string' ? { resourceId: value.resourceId } : {}),
+        ...(value.url === undefined ? {} : { url: value.url }),
+        ...(typeof value.urlExpiresAt === 'number' ? { urlExpiresAt: value.urlExpiresAt } : {})
+    };
+}
+export function validInputImageFileName(fileName) {
+    return (basename(fileName) === fileName && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\.bin$/u.test(fileName));
+}
+export async function readInputImageBytes(directory, reference) {
+    try {
+        return await readFile(join(directory, reference.fileName));
+    }
+    catch (cause) {
+        throw new AgentError('MAR_AGENT_IMAGE_UNAVAILABLE', 'Session input image is unavailable.', {
+            cause
+        });
+    }
+}
+function corruptInputImageReference(cause) {
+    return new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session input image is corrupt.', {
+        ...(cause === undefined ? {} : { cause })
+    });
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/session/store/jsonl/index-transaction.d.ts

@@ -0,0 +1,13 @@
+import { AgentError } from '../../../error.js';
+import type { SessionIndex, SessionMeta } from '../types.js';
+export declare class ParentPublicationRejected extends AgentError {
+}
+/** Runs the short disk index transaction; the caller owns its cache. */
+export declare function commitSessionIndex(root: string, snapshot: () => {
+    index: SessionIndex;
+    dirty: ReadonlyMap<string, number>;
+    derivedOnly: ReadonlySet<string>;
+}, committed: (index: SessionIndex, dirty: ReadonlyMap<string, number>, created: ReadonlySet<string>) => void, deletedIds?: string | readonly string[], createdIds?: readonly string[], onPersisted?: () => void, storageSelection?: {
+    readonly before: SessionMeta;
+    readonly generation: string;
+}, deleteExpected?: readonly SessionMeta[]): Promise<void>;

package/dist/session/store/jsonl/index-transaction.js

@@ -0,0 +1,87 @@
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { AgentError } from '../../../error.js';
+import { acquireFileLock } from '../../../storage/file-lock.js';
+import { normalizeSessionSource, persistFormatSelection, prepareSessionIndexCommit, readSessionIndex } from './directory-index.js';
+import { treeDeleteMarker } from './transaction-recovery.js';
+export class ParentPublicationRejected extends AgentError {
+}
+/** Runs the short disk index transaction; the caller owns its cache. */
+export async function commitSessionIndex(root, snapshot, committed, deletedIds, createdIds = [], onPersisted, storageSelection, deleteExpected) {
+    const release = await acquireFileLock(join(root, 'sessions', 'index.lock'));
+    const path = join(root, 'sessions', 'index.json');
+    let failure;
+    try {
+        const disk = await readSessionIndex(path);
+        if (!disk)
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+        for (const id of createdIds) {
+            const created = snapshot().index.sessions.find((entry) => entry.id === id);
+            if (!created)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session publication is missing.');
+            const source = normalizeSessionSource(created.source);
+            if (source.type !== 'subagent')
+                continue;
+            if (!disk.sessions.some((entry) => entry.id === source.parentSessionId))
+                throw new ParentPublicationRejected('MAR_AGENT_SESSION_NOT_FOUND', 'Parent Session was not found.');
+            try {
+                await lstat(treeDeleteMarker(join(root, 'sessions'), source.parentSessionId));
+                throw new ParentPublicationRejected('MAR_AGENT_SESSION_LOCKED', 'Parent Session is under maintenance.');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        if (deleteExpected) {
+            const ids = new Set(deleteExpected.map((entry) => entry.id));
+            for (const expected of deleteExpected) {
+                const current = disk.sessions.find((entry) => entry.id === expected.id);
+                if (!current ||
+                    current.createdAt !== expected.createdAt ||
+                    current.workspace !== expected.workspace ||
+                    !isDeepStrictEqual(current.source, expected.source) ||
+                    !isDeepStrictEqual(current.storage, expected.storage) ||
+                    current.storageTransactionId !== expected.storageTransactionId ||
+                    current.nextSequence !== expected.nextSequence)
+                    throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session tree changed during deletion.');
+            }
+            for (const entry of disk.sessions) {
+                const source = normalizeSessionSource(entry.source);
+                if (source.type === 'subagent' && ids.has(source.parentSessionId) && !ids.has(entry.id))
+                    throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session tree changed during deletion.');
+            }
+        }
+        const local = snapshot();
+        const dirty = local.dirty;
+        const derivedOnly = local.derivedOnly;
+        const created = new Set(createdIds);
+        const updated = prepareSessionIndexCommit(disk, local.index, dirty, derivedOnly, deletedIds, createdIds);
+        if (storageSelection) {
+            const before = storageSelection.before;
+            const selected = disk.sessions.find((item) => item.id === before.id);
+            const replacement = updated.sessions.find((item) => item.id === before.id);
+            if (!selected ||
+                !replacement ||
+                !isDeepStrictEqual(selected.storage, before.storage) ||
+                selected.nextSequence !== before.nextSequence ||
+                selected.storageTransactionId !== before.storageTransactionId)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history changed during replacement.');
+            replacement.storage = { encoding: 2, generation: storageSelection.generation };
+        }
+        await persistFormatSelection(path, updated);
+        onPersisted?.();
+        committed(updated, dirty, created);
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        if (failure !== undefined)
+            await release().catch(() => undefined);
+        else
+            await release();
+    }
+}

package/dist/session/store/jsonl/jsonl-admission.d.ts

@@ -0,0 +1,10 @@
+/** Read-only version admission before any v1 recovery can modify its evidence. */
+export declare function preflightV1Session(directory: string): Promise<void>;
+/** Inspect history only when an existing v2 recovery may replace or remove it. */
+export declare function preflightV2Recovery(directory: string): Promise<void>;
+/** Retired paths may be restored or deleted by the same journal, including other generations. */
+export declare function preflightRetiredRecovery(root: string, journalDirectory: string): Promise<void>;
+/** Check known versioned fields without treating ordinary corruption as a future format. */
+export declare function admitV1RecordVersion(line: string): void;
+export declare function admitWorldStateVersion(value: unknown): void;
+export declare function admitResourceMetadataVersion(value: unknown): void;