praxis-agent 0.32.0 → 0.33.0

package/dist/compatibility/claude/session-metadata.js

@@ -0,0 +1,180 @@
+export const CLAUDE_DURABLE_METADATA_TYPES = [
+    'custom-title',
+    'ai-title',
+    'tag',
+    'agent-name',
+    'agent-color',
+    'agent-setting',
+    'permission-mode',
+    'mode',
+    'worktree-state',
+    'pr-link',
+    'last-prompt',
+];
+const DURABLE_METADATA_TYPE_SET = new Set(CLAUDE_DURABLE_METADATA_TYPES);
+export function isClaudeDurableMetadataType(type) {
+    return DURABLE_METADATA_TYPE_SET.has(type);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Reduces Claude's append-only metadata records. Each metadata type is
+ * independently last-wins, while a user-authored custom title always takes
+ * precedence over an AI title regardless of append order.
+ *
+ * Unknown records remain untouched in the transcript but never become
+ * authoritative session state here.
+ */
+export function reduceClaudeSessionMetadata(entries, sessionId) {
+    const latest = new Map();
+    for (const entry of entries) {
+        if (!isClaudeDurableMetadataType(entry.type))
+            continue;
+        if (sessionId !== undefined &&
+            typeof entry.sessionId === 'string' &&
+            entry.sessionId !== sessionId) {
+            continue;
+        }
+        latest.set(entry.type, entry);
+    }
+    const customTitle = nonEmptyString(latest.get('custom-title')?.customTitle);
+    const aiTitle = nonEmptyString(latest.get('ai-title')?.aiTitle);
+    const tag = nonEmptyString(latest.get('tag')?.tag);
+    const agentName = nonEmptyString(latest.get('agent-name')?.agentName);
+    const agentColor = nonEmptyString(latest.get('agent-color')?.agentColor);
+    const agentSetting = nonEmptyString(latest.get('agent-setting')?.agentSetting);
+    const permissionMode = nonEmptyString(latest.get('permission-mode')?.permissionMode);
+    const mode = nonEmptyString(latest.get('mode')?.mode);
+    const worktreeSession = record(latest.get('worktree-state')?.worktreeSession);
+    const pr = latest.get('pr-link');
+    const prNumber = pr?.prNumber;
+    const prUrl = nonEmptyString(pr?.prUrl);
+    const prRepository = nonEmptyString(pr?.prRepository);
+    const prLink = Number.isSafeInteger(prNumber) && Number(prNumber) > 0
+        ? {
+            prNumber: Number(prNumber),
+            ...(prUrl === undefined ? {} : { prUrl }),
+            ...(prRepository === undefined ? {} : { prRepository }),
+        }
+        : undefined;
+    const lastPromptEntry = latest.get('last-prompt');
+    const lastPrompt = nonEmptyString(lastPromptEntry?.lastPrompt);
+    const lastPromptLeafUuid = nonEmptyString(lastPromptEntry?.leafUuid);
+    return {
+        ...(customTitle === undefined ? {} : { customTitle }),
+        ...(aiTitle === undefined ? {} : { aiTitle }),
+        ...(customTitle !== undefined
+            ? { title: customTitle, titleSource: 'custom-title' }
+            : aiTitle !== undefined
+                ? { title: aiTitle, titleSource: 'ai-title' }
+                : {}),
+        ...(tag === undefined ? {} : { tag }),
+        ...(agentName === undefined ? {} : { agentName }),
+        ...(agentColor === undefined ? {} : { agentColor }),
+        ...(agentSetting === undefined ? {} : { agentSetting }),
+        ...(permissionMode === undefined ? {} : { permissionMode }),
+        ...(mode === undefined ? {} : { mode }),
+        ...(worktreeSession === undefined ? {} : { worktreeSession }),
+        ...(prLink === undefined ? {} : { prLink }),
+        ...(lastPrompt === undefined ? {} : { lastPrompt }),
+        ...(lastPromptLeafUuid === undefined ? {} : { lastPromptLeafUuid }),
+    };
+}
+/** Returns one current record per durable metadata type for a tail snapshot. */
+export function createClaudeDurableMetadataSnapshot(entries, sessionId, options = {}) {
+    const latest = new Map();
+    for (const entry of entries) {
+        if (!isClaudeDurableMetadataType(entry.type))
+            continue;
+        if (typeof entry.sessionId === 'string' && entry.sessionId !== sessionId) {
+            continue;
+        }
+        latest.set(entry.type, entry);
+    }
+    // A later AI title must never obscure a user rename in a bounded tail.
+    if (latest.has('custom-title'))
+        latest.delete('ai-title');
+    const lastPrompt = latest.get('last-prompt');
+    if (lastPrompt !== undefined) {
+        const committedLeafUuid = nonEmptyString(lastPrompt.leafUuid);
+        const committedLeaf = entries.find((entry) => entry.isSidechain !== true &&
+            typeof entry.uuid === 'string' &&
+            entry.uuid === committedLeafUuid &&
+            (entry.type === 'assistant' ||
+                (entry.type === 'system' &&
+                    entry.subtype === 'local_command' &&
+                    typeof entry.content === 'string' &&
+                    entry.content.startsWith('<local-command-stdout>'))));
+        const trustedCommittedLeafUuid = committedLeaf?.uuid ??
+            (options.trustLastPromptReference ? committedLeafUuid : undefined);
+        if (trustedCommittedLeafUuid === undefined) {
+            latest.delete('last-prompt');
+        }
+        else {
+            // Metadata-only re-appends never promote a newer assistant: it may be
+            // an abandoned or failed branch. A completed local command is itself a
+            // committed observable result, so it may safely advance the hint when
+            // it descends from the last committed turn.
+            const byUuid = new Map(entries.flatMap((entry) => entry.isSidechain !== true && typeof entry.uuid === 'string'
+                ? [[entry.uuid, entry]]
+                : []));
+            const localCommandLeaf = [...entries].reverse().find((entry) => {
+                if (entry.isSidechain === true ||
+                    entry.type !== 'system' ||
+                    entry.subtype !== 'local_command' ||
+                    typeof entry.uuid !== 'string' ||
+                    typeof entry.content !== 'string' ||
+                    !entry.content.startsWith('<local-command-stdout>')) {
+                    return false;
+                }
+                let parentUuid = typeof entry.parentUuid === 'string' ? entry.parentUuid : null;
+                const seen = new Set();
+                while (parentUuid !== null && !seen.has(parentUuid)) {
+                    if (parentUuid === trustedCommittedLeafUuid)
+                        return true;
+                    seen.add(parentUuid);
+                    const parent = byUuid.get(parentUuid);
+                    if (parent?.type !== 'system' || parent.subtype !== 'local_command') {
+                        return false;
+                    }
+                    parentUuid =
+                        typeof parent?.parentUuid === 'string' ? parent.parentUuid : null;
+                }
+                return false;
+            });
+            if (localCommandLeaf === undefined) {
+                latest.set('last-prompt', lastPrompt);
+            }
+            else {
+                const snapshot = {
+                    ...lastPrompt,
+                    leafUuid: localCommandLeaf.uuid,
+                };
+                delete snapshot.lastPrompt;
+                latest.set('last-prompt', snapshot);
+            }
+        }
+    }
+    return CLAUDE_DURABLE_METADATA_TYPES.flatMap((type) => {
+        const entry = latest.get(type);
+        return entry === undefined ? [] : [{ ...entry, sessionId }];
+    });
+}
+/** Keeps the last known full baseline while overlaying metadata visible in a
+ * newer bounded head/tail observation. Structural entries are included only
+ * to validate or safely advance the committed last-prompt hint. */
+export function mergeClaudeDurableMetadataSnapshot(baseline, observed, sessionId) {
+    return createClaudeDurableMetadataSnapshot([...baseline, ...observed], sessionId, { trustLastPromptReference: true });
+}
+export function createClaudeTagEntry(sessionId, tag) {
+    if (tag.length === 0)
+        throw new Error('Session tag must not be empty');
+    return { type: 'tag', tag, sessionId };
+}
+//# sourceMappingURL=session-metadata.js.map

package/dist/persistence/claude-session-index.d.ts

@@ -0,0 +1,39 @@
+import type { ClaudeSchemaAdapter, ClaudeTranscriptEntry } from '../compatibility/claude/schema.js';
+import type { TranscriptParseIssue } from './claude-transcript-store.js';
+import type { TranscriptTail } from './claude-transcript-store.js';
+export declare const CLAUDE_SESSION_INDEX_HEAD_BYTES: number;
+export declare const CLAUDE_SESSION_INDEX_TAIL_BYTES: number;
+export declare const CLAUDE_SESSION_INDEX_CONCURRENCY = 32;
+export interface ClaudeSessionIndex {
+    entries: ClaudeTranscriptEntry[];
+    tailEntries: ClaudeTranscriptEntry[];
+    issue: TranscriptParseIssue | null;
+    byteLength: number;
+    newlineTerminated: boolean;
+    updatedAt: string;
+    tail: TranscriptTail;
+}
+export interface ClaudeSessionIndexRequest {
+    sessionId: string;
+    path: string;
+}
+export type ClaudeSessionIndexResult = ClaudeSessionIndexRequest & ({
+    index: ClaudeSessionIndex;
+    error?: never;
+} | {
+    index?: never;
+    error: unknown;
+});
+export declare class ClaudeSessionIndexCandidateError extends Error {
+    readonly name = "ClaudeSessionIndexCandidateError";
+}
+/**
+ * Reads only bounded head/tail windows for session discovery. A partial final
+ * line is treated as an in-progress append and ignored. Full JSONL and graph
+ * validation remains the responsibility of inspect/resume.
+ */
+export declare function readClaudeSessionIndex(path: string, schema: ClaudeSchemaAdapter): Promise<ClaudeSessionIndex>;
+/** Reads a discovery set with a fixed worker pool so large projects cannot
+ * exhaust the process file-descriptor limit. Results preserve input order. */
+export declare function readClaudeSessionIndexes(requests: readonly ClaudeSessionIndexRequest[], schema: ClaudeSchemaAdapter, concurrency?: number): Promise<ClaudeSessionIndexResult[]>;
+//# sourceMappingURL=claude-session-index.d.ts.map

package/dist/persistence/claude-session-index.js

@@ -0,0 +1,175 @@
+import { createHash } from 'node:crypto';
+import { lstat, open } from 'node:fs/promises';
+import { TextDecoder } from 'node:util';
+import { isClaudeDurableLastPromptSnapshot } from '../compatibility/claude/history.js';
+export const CLAUDE_SESSION_INDEX_HEAD_BYTES = 64 * 1024;
+export const CLAUDE_SESSION_INDEX_TAIL_BYTES = 128 * 1024;
+export const CLAUDE_SESSION_INDEX_CONCURRENCY = 32;
+const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true });
+function logicalTailUuid(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (!entry)
+            continue;
+        if (entry.type === 'last-prompt' &&
+            isClaudeDurableLastPromptSnapshot(entries, index)) {
+            continue;
+        }
+        if (typeof entry.uuid === 'string')
+            return entry.uuid;
+        if (typeof entry.leafUuid === 'string')
+            return entry.leafUuid;
+    }
+    return null;
+}
+export class ClaudeSessionIndexCandidateError extends Error {
+    name = 'ClaudeSessionIndexCandidateError';
+}
+function completeLines(source, absoluteStart, discardLeadingPartial, discardTrailingPartial, lineNumberStart, tail) {
+    let start = 0;
+    if (discardLeadingPartial) {
+        const newline = source.indexOf(0x0a);
+        if (newline < 0)
+            return [];
+        start = newline + 1;
+    }
+    let end = source.length;
+    if (discardTrailingPartial && source.at(-1) !== 0x0a) {
+        const newline = source.lastIndexOf(0x0a);
+        if (newline < start)
+            return [];
+        end = newline + 1;
+    }
+    const lines = [];
+    let lineStart = start;
+    for (let index = start; index < end; index += 1) {
+        if (source[index] !== 0x0a)
+            continue;
+        if (index > lineStart) {
+            lines.push({
+                source: source.subarray(lineStart, index),
+                byteOffset: absoluteStart + lineStart,
+                lineNumber: lineNumberStart === null ? null : lineNumberStart + lines.length,
+                tail,
+            });
+        }
+        lineStart = index + 1;
+    }
+    if (!discardTrailingPartial && lineStart < end) {
+        lines.push({
+            source: source.subarray(lineStart, end),
+            byteOffset: absoluteStart + lineStart,
+            lineNumber: lineNumberStart === null ? null : lineNumberStart + lines.length,
+            tail,
+        });
+    }
+    return lines;
+}
+async function readWindow(handle, length, position) {
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, position);
+    return buffer.subarray(0, bytesRead);
+}
+/**
+ * Reads only bounded head/tail windows for session discovery. A partial final
+ * line is treated as an in-progress append and ignored. Full JSONL and graph
+ * validation remains the responsibility of inspect/resume.
+ */
+export async function readClaudeSessionIndex(path, schema) {
+    const pathMetadata = await lstat(path);
+    if (!pathMetadata.isFile())
+        throw new ClaudeSessionIndexCandidateError(`Expected a regular file: ${path}`);
+    const handle = await open(path, 'r');
+    try {
+        const metadata = await handle.stat();
+        const byteLength = metadata.size;
+        const wholeFileThreshold = CLAUDE_SESSION_INDEX_HEAD_BYTES + CLAUDE_SESSION_INDEX_TAIL_BYTES;
+        let lines;
+        let newlineTerminated = true;
+        if (byteLength <= wholeFileThreshold) {
+            const source = await readWindow(handle, byteLength, 0);
+            newlineTerminated = source.length === 0 || source.at(-1) === 0x0a;
+            lines = completeLines(source, 0, false, !newlineTerminated, 1, true);
+        }
+        else {
+            const head = await readWindow(handle, CLAUDE_SESSION_INDEX_HEAD_BYTES, 0);
+            const tailStart = byteLength - CLAUDE_SESSION_INDEX_TAIL_BYTES;
+            const tail = await readWindow(handle, CLAUDE_SESSION_INDEX_TAIL_BYTES, tailStart);
+            newlineTerminated = tail.length === 0 || tail.at(-1) === 0x0a;
+            lines = [
+                ...completeLines(head, 0, false, true, 1, false),
+                ...completeLines(tail, tailStart, true, !newlineTerminated, null, true),
+            ];
+        }
+        const entries = [];
+        const tailEntries = [];
+        let issue = null;
+        for (const line of lines) {
+            try {
+                const entry = schema.parse(UTF8_DECODER.decode(line.source));
+                entries.push(entry);
+                if (line.tail)
+                    tailEntries.push(entry);
+            }
+            catch (error) {
+                issue = {
+                    lineNumber: line.lineNumber,
+                    byteOffset: line.byteOffset,
+                    message: error instanceof Error ? error.message : String(error),
+                };
+                break;
+            }
+        }
+        return {
+            entries,
+            tailEntries,
+            issue,
+            byteLength,
+            newlineTerminated,
+            updatedAt: metadata.mtime.toISOString(),
+            tail: {
+                byteLength,
+                lastLineHash: lines.at(-1) === undefined
+                    ? null
+                    : createHash('sha256')
+                        .update(lines.at(-1)?.source ?? Buffer.alloc(0))
+                        .digest('hex'),
+                lastUuid: logicalTailUuid(entries),
+                newlineTerminated,
+            },
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Reads a discovery set with a fixed worker pool so large projects cannot
+ * exhaust the process file-descriptor limit. Results preserve input order. */
+export async function readClaudeSessionIndexes(requests, schema, concurrency = CLAUDE_SESSION_INDEX_CONCURRENCY) {
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+        throw new Error('Claude session index concurrency must be a positive integer');
+    }
+    const results = new Array(requests.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        while (nextIndex < requests.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            const request = requests[index];
+            if (request === undefined)
+                continue;
+            try {
+                results[index] = {
+                    ...request,
+                    index: await readClaudeSessionIndex(request.path, schema),
+                };
+            }
+            catch (error) {
+                results[index] = { ...request, error };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, requests.length) }, async () => worker()));
+    return results;
+}
+//# sourceMappingURL=claude-session-index.js.map

package/dist/persistence/claude-transcript-store.d.ts

@@ -1,17 +1,18 @@
 import type { ClaudeSchemaAdapter, ClaudeTranscriptEntry } from '../compatibility/claude/schema.js';
+import { type ClaudeSessionIndex } from './claude-session-index.js';
 export interface TranscriptTail {
     byteLength: number;
     lastLineHash: string | null;
     lastUuid: string | null;
     newlineTerminated: boolean;
-    branchParentUuid?: string;
+    branchParentUuid?: string | null;
 }
 export interface TranscriptSnapshot {
     entries: ClaudeTranscriptEntry[];
     tail: TranscriptTail;
 }
 export interface TranscriptParseIssue {
-    lineNumber: number;
+    lineNumber: number | null;
     byteOffset: number;
     message: string;
 }
@@ -46,8 +47,10 @@ export type TranscriptReserveResult = {
 };
 export interface ClaudeTranscriptLease {
     load(): Promise<TranscriptSnapshot>;
+    loadIndex?(): Promise<ClaudeSessionIndex>;
     append(expectedTail: TranscriptTail, entry: ClaudeTranscriptEntry): Promise<TranscriptAppendResult>;
     appendMany(expectedTail: TranscriptTail, entries: readonly ClaudeTranscriptEntry[]): Promise<TranscriptAppendResult>;
+    appendMetadataSnapshot(expectedTail: TranscriptTail, entries: readonly ClaudeTranscriptEntry[]): Promise<TranscriptAppendResult>;
 }
 export type TranscriptLeaseResult<T> = {
     status: 'completed';
@@ -80,6 +83,7 @@ export declare class ClaudeTranscriptStore {
     append(expectedTail: TranscriptTail, entry: ClaudeTranscriptEntry): Promise<TranscriptAppendResult>;
     private appendUnderLease;
     private appendManyUnderLease;
+    private appendMetadataSnapshotUnderLease;
     private serializeNewSidechain;
 }
 //# sourceMappingURL=claude-transcript-store.d.ts.map

package/dist/persistence/claude-transcript-store.js

@@ -2,8 +2,11 @@ import { createHash } from 'node:crypto';
 import { mkdir, open, readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { TextDecoder } from 'node:util';
+import { isClaudeDurableLastPromptSnapshot } from '../compatibility/claude/history.js';
+import { isClaudeDurableMetadataType } from '../compatibility/claude/session-metadata.js';
 import { getClaudeContentBlocks, indexClaudeToolLinks, recoverClaudeToolResultLinks, } from '../compatibility/claude/tool-links.js';
 import { ExclusiveFileLease } from '../platform/exclusive-file-lease.js';
+import { readClaudeSessionIndex, } from './claude-session-index.js';
 export class ClaudeTranscriptParseError extends Error {
     lineNumber;
     byteOffset;
@@ -19,6 +22,7 @@ const NON_TAIL_ENTRY_TYPES = new Set([
     'agent-color',
     'agent-name',
     'agent-setting',
+    'ai-title',
     'custom-title',
     'file-history-delta',
     'file-history-snapshot',
@@ -26,6 +30,8 @@ const NON_TAIL_ENTRY_TYPES = new Set([
     'pr-link',
     'queue-operation',
     'relocated',
+    'mode',
+    'tag',
     'worktree-state',
 ]);
 export function classifyTranscriptAppend(written, previousByteLength, encodedLine) {
@@ -63,7 +69,9 @@ function tailsMatch(left, right) {
         left.newlineTerminated === right.newlineTerminated);
 }
 function tailLogicalUuid(tail) {
-    return tail.branchParentUuid ?? tail.lastUuid;
+    return 'branchParentUuid' in tail
+        ? (tail.branchParentUuid ?? null)
+        : tail.lastUuid;
 }
 function getEntryUuid(entry) {
     if (typeof entry.uuid === 'string')
@@ -77,6 +85,10 @@ function findLogicalTailUuid(entries) {
         const entry = entries[index];
         if (!entry)
             continue;
+        if (entry.type === 'last-prompt' &&
+            isClaudeDurableLastPromptSnapshot(entries, index)) {
+            continue;
+        }
         const uuid = getEntryUuid(entry);
         if (uuid)
             return uuid;
@@ -173,7 +185,9 @@ export class ClaudeTranscriptStore {
                     message: error instanceof Error ? error.message : String(error),
                 };
                 if (!recover) {
-                    throw new ClaudeTranscriptParseError(issue.lineNumber, issue.byteOffset, { cause: error });
+                    throw new ClaudeTranscriptParseError(index + 1, byteOffset, {
+                        cause: error,
+                    });
                 }
                 break;
             }
@@ -266,8 +280,10 @@ export class ClaudeTranscriptStore {
         try {
             const value = await operation({
                 load: () => this.load(),
+                loadIndex: () => readClaudeSessionIndex(this.sessionFile, this.schema),
                 append: (expectedTail, entry) => this.appendUnderLease(expectedTail, entry),
                 appendMany: (expectedTail, entries) => this.appendManyUnderLease(expectedTail, entries),
+                appendMetadataSnapshot: (expectedTail, entries) => this.appendMetadataSnapshotUnderLease(expectedTail, entries),
             });
             return { status: 'completed', value };
         }
@@ -314,7 +330,11 @@ export class ClaudeTranscriptStore {
                 }
             }
             else if (entry.type === 'last-prompt') {
-                if (entry.leafUuid !== logicalTailUuid) {
+                const isDurableSnapshot = history.some((candidate) => candidate.type === 'last-prompt' &&
+                    candidate.sessionId === entry.sessionId &&
+                    candidate.leafUuid === entry.leafUuid &&
+                    candidate.lastPrompt === entry.lastPrompt);
+                if (entry.leafUuid !== logicalTailUuid && !isDurableSnapshot) {
                     staleLastPromptLeaf = true;
                     continue;
                 }
@@ -378,6 +398,61 @@ export class ClaudeTranscriptStore {
                 : { ...tail, branchParentUuid },
         };
     }
+    async appendMetadataSnapshotUnderLease(expectedTail, entries) {
+        if (entries.length === 0) {
+            throw new Error('Cannot append an empty Claude metadata snapshot');
+        }
+        if (entries.some((entry) => !isClaudeDurableMetadataType(entry.type))) {
+            throw new Error('Claude metadata snapshot contains a structural entry');
+        }
+        if (new Set(entries.map((entry) => entry.type)).size !== entries.length ||
+            new Set(entries.map((entry) => entry.sessionId)).size !== 1 ||
+            typeof entries[0]?.sessionId !== 'string') {
+            throw new Error('Claude metadata snapshot must contain one session record per type');
+        }
+        const current = await readClaudeSessionIndex(this.sessionFile, this.schema);
+        if (current.issue !== null) {
+            throw new Error('Cannot append metadata to a corrupt Claude transcript');
+        }
+        if (current.byteLength !== expectedTail.byteLength ||
+            current.tail.lastLineHash !== expectedTail.lastLineHash ||
+            current.newlineTerminated !== expectedTail.newlineTerminated) {
+            return { status: 'conflict', reason: 'tail-changed' };
+        }
+        if (!current.newlineTerminated) {
+            throw new Error('Claude transcript is not newline-terminated');
+        }
+        const lines = entries.map((entry) => this.schema.serializeForAppend(entry));
+        const encoded = Buffer.from(`${lines.join('\n')}\n`);
+        const sessionHandle = await open(this.sessionFile, 'a');
+        try {
+            const before = await sessionHandle.stat();
+            if (before.size !== expectedTail.byteLength) {
+                return { status: 'conflict', reason: 'tail-changed' };
+            }
+            await sessionHandle.writeFile(encoded);
+            await sessionHandle.sync();
+            const after = await sessionHandle.stat();
+            if (after.size !== expectedTail.byteLength + encoded.length) {
+                return { status: 'conflict', reason: 'interleaved-write' };
+            }
+        }
+        finally {
+            await sessionHandle.close();
+        }
+        const last = entries.at(-1);
+        return {
+            status: 'appended',
+            tail: {
+                byteLength: expectedTail.byteLength + encoded.length,
+                lastLineHash: hashLine(Buffer.from(lines.at(-1) ?? '')),
+                lastUuid: typeof last?.leafUuid === 'string'
+                    ? last.leafUuid
+                    : expectedTail.lastUuid,
+                newlineTerminated: true,
+            },
+        };
+    }
     serializeNewSidechain(entries) {
         const lines = [];
         const history = [];

package/dist/persistence/in-memory-transcript-store.js

@@ -47,6 +47,7 @@ export class InMemoryTranscriptStore {
                 load: () => this.load(),
                 append: (expectedTail, entry) => this.appendMany(expectedTail, [entry]),
                 appendMany: (expectedTail, entries) => this.appendMany(expectedTail, entries),
+                appendMetadataSnapshot: (expectedTail, entries) => this.appendMany(expectedTail, entries),
             });
             return { status: 'completed', value };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",
@@ -80,6 +80,7 @@
     "test:pr-link-compat": "npm run build && node scripts/verify-pr-link-compatibility.mjs",
     "test:resume-at-compat": "npm run build && node scripts/verify-resume-session-at-compatibility.mjs",
     "test:resume-selector-compat": "npm run build && node scripts/verify-resume-selector-compatibility.mjs",
+    "test:session-metadata-compat": "npm run build && node scripts/verify-session-metadata-compatibility.mjs",
     "test:thinking-compat": "npm run build && node scripts/verify-thinking-controls.mjs",
     "test:memory-import-compat": "npm run build && node scripts/verify-memory-import-compatibility.mjs",
     "test:tui-compat": "npm run build && node scripts/verify-tui-compatibility.mjs",