praxis-agent 0.32.0 → 0.34.0

package/dist/compatibility/claude/schema.js

@@ -18,13 +18,16 @@ const APPENDABLE_ENTRY_TYPES = new Set([
     'assistant',
     'attachment',
     'custom-title',
+    'ai-title',
     'file-history-delta',
     'file-history-snapshot',
     'last-prompt',
+    'mode',
     'permission-mode',
     'pr-link',
     'queue-operation',
     'relocated',
+    'tag',
     'system',
     'user',
     'worktree-state',
@@ -732,6 +735,25 @@ function validateAppendableEntry(entry) {
         }
         return;
     }
+    if (entry.type === 'ai-title') {
+        if (!isNonEmptyString(entry.aiTitle) ||
+            !isNonEmptyString(entry.sessionId)) {
+            throw new Error('Claude ai-title entry has invalid metadata');
+        }
+        return;
+    }
+    if (entry.type === 'tag') {
+        if (!isNonEmptyString(entry.tag) || !isNonEmptyString(entry.sessionId)) {
+            throw new Error('Claude tag entry has invalid metadata');
+        }
+        return;
+    }
+    if (entry.type === 'mode') {
+        if (!isNonEmptyString(entry.mode) || !isNonEmptyString(entry.sessionId)) {
+            throw new Error('Claude mode entry has invalid metadata');
+        }
+        return;
+    }
     if (entry.type === 'agent-color') {
         if (!isAgentColorValue(entry.agentColor) ||
             !isNonEmptyString(entry.sessionId)) {

package/dist/compatibility/claude/session-metadata.d.ts

@@ -0,0 +1,44 @@
+import type { ClaudeTranscriptEntry } from './schema.js';
+export interface ClaudeSessionPrLink {
+    prNumber: number;
+    prUrl?: string;
+    prRepository?: string;
+}
+export interface ClaudeSessionMetadata {
+    title?: string;
+    titleSource?: 'custom-title' | 'ai-title';
+    customTitle?: string;
+    aiTitle?: string;
+    tag?: string;
+    agentName?: string;
+    agentColor?: string;
+    agentSetting?: string;
+    permissionMode?: string;
+    mode?: string;
+    worktreeSession?: Readonly<Record<string, unknown>>;
+    prLink?: ClaudeSessionPrLink;
+    lastPrompt?: string;
+    lastPromptLeafUuid?: string;
+}
+export declare const CLAUDE_DURABLE_METADATA_TYPES: readonly ["custom-title", "ai-title", "tag", "agent-name", "agent-color", "agent-setting", "permission-mode", "mode", "worktree-state", "pr-link", "last-prompt"];
+export type ClaudeDurableMetadataType = (typeof CLAUDE_DURABLE_METADATA_TYPES)[number];
+export declare function isClaudeDurableMetadataType(type: string): type is ClaudeDurableMetadataType;
+/**
+ * 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 declare function reduceClaudeSessionMetadata(entries: readonly ClaudeTranscriptEntry[], sessionId?: string): ClaudeSessionMetadata;
+/** Returns one current record per durable metadata type for a tail snapshot. */
+export declare function createClaudeDurableMetadataSnapshot(entries: readonly ClaudeTranscriptEntry[], sessionId: string, options?: {
+    trustLastPromptReference?: boolean;
+}): ClaudeTranscriptEntry[];
+/** 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 declare function mergeClaudeDurableMetadataSnapshot(baseline: readonly ClaudeTranscriptEntry[], observed: readonly ClaudeTranscriptEntry[], sessionId: string): ClaudeTranscriptEntry[];
+export declare function createClaudeTagEntry(sessionId: string, tag: string): ClaudeTranscriptEntry;
+//# sourceMappingURL=session-metadata.d.ts.map

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/compatibility/claude/sidechain.d.ts

@@ -1,5 +1,7 @@
 import type { ModelUsage } from '../../core/runtime.js';
 import type { ClaudeTranscriptEntry } from './schema.js';
+export declare function isClaudeAgentId(agentId: string): boolean;
+export declare function assertClaudeAgentId(agentId: string): void;
 export interface ClaudeSidechainPaths {
     sessionId: string;
     agentId: string;
@@ -12,6 +14,7 @@ export interface ClaudeSidechainPathOptions {
     subdirectory?: string;
 }
 export interface ClaudeSidechainMetadata {
+    readonly [key: string]: unknown;
     agentType: string;
     description: string;
     toolUseId: string;
@@ -19,6 +22,8 @@ export interface ClaudeSidechainMetadata {
     name?: string;
     permissionMode?: ClaudeSidechainPermissionMode;
     isolation?: 'worktree';
+    parentAgentId?: string;
+    worktreePath?: string;
 }
 export type ClaudeSidechainPermissionMode = 'acceptEdits' | 'auto' | 'bypassPermissions' | 'default' | 'dontAsk' | 'plan';
 export declare function resolveClaudeSidechainPaths(projectRoot: string, sessionId: string, agentId: string, options?: ClaudeSidechainPathOptions): ClaudeSidechainPaths;

package/dist/compatibility/claude/sidechain.js

@@ -1,13 +1,22 @@
 import { resolve } from 'node:path';
 import { isClaudeSessionId } from './paths.js';
-const AGENT_ID_PATTERN = /^a[0-9a-f]{16}$/u;
+/** Claude uses a stable 16-hex suffix and may prefix it with a bounded label.
+ * Keeping the accepted alphabet filename-safe makes path construction a pure
+ * validation boundary rather than a sanitizing rewrite. */
+const CLAUDE_AGENT_ID_PATTERN = /^a(?:[A-Za-z0-9][A-Za-z0-9_-]{0,62}-)?[0-9a-f]{16}$/u;
+export function isClaudeAgentId(agentId) {
+    return CLAUDE_AGENT_ID_PATTERN.test(agentId);
+}
+export function assertClaudeAgentId(agentId) {
+    if (!isClaudeAgentId(agentId)) {
+        throw new Error(`Invalid Claude agent ID: ${agentId}`);
+    }
+}
 export function resolveClaudeSidechainPaths(projectRoot, sessionId, agentId, options = {}) {
     if (!isClaudeSessionId(sessionId)) {
         throw new Error(`Invalid Claude session ID: ${sessionId}`);
     }
-    if (!AGENT_ID_PATTERN.test(agentId)) {
-        throw new Error(`Invalid Claude agent ID: ${agentId}`);
-    }
+    assertClaudeAgentId(agentId);
     const subdirectory = options.subdirectory;
     if (subdirectory !== undefined &&
         (subdirectory.length === 0 ||

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-sidechain-store.js

@@ -1,4 +1,5 @@
 import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import { isClaudeAgentId } from '../compatibility/claude/sidechain.js';
 import { ClaudeTranscriptStore, } from './claude-transcript-store.js';
 export class ClaudeSidechainStore {
     paths;
@@ -72,7 +73,8 @@ export class ClaudeSidechainStore {
         if (typeof record.agentType !== 'string' ||
             typeof record.description !== 'string' ||
             typeof record.toolUseId !== 'string' ||
-            typeof record.spawnDepth !== 'number' ||
+            !Number.isSafeInteger(record.spawnDepth) ||
+            Number(record.spawnDepth) < 1 ||
             (record.name !== undefined && typeof record.name !== 'string') ||
             (record.permissionMode !== undefined &&
                 (typeof record.permissionMode !== 'string' ||
@@ -84,14 +86,22 @@ export class ClaudeSidechainStore {
                         'dontAsk',
                         'plan',
                     ].includes(record.permissionMode))) ||
-            (record.isolation !== undefined && record.isolation !== 'worktree')) {
+            (record.isolation !== undefined && record.isolation !== 'worktree') ||
+            (record.parentAgentId !== undefined &&
+                (typeof record.parentAgentId !== 'string' ||
+                    !isClaudeAgentId(record.parentAgentId))) ||
+            (record.worktreePath !== undefined &&
+                (typeof record.worktreePath !== 'string' ||
+                    record.worktreePath.length === 0 ||
+                    record.worktreePath.includes('\0')))) {
             throw new Error('Claude sidechain metadata is invalid');
         }
         return {
+            ...record,
             agentType: record.agentType,
             description: record.description,
             toolUseId: record.toolUseId,
-            spawnDepth: record.spawnDepth,
+            spawnDepth: Number(record.spawnDepth),
             ...(record.name === undefined ? {} : { name: record.name }),
             ...(record.permissionMode === undefined
                 ? {}
@@ -101,6 +111,12 @@ export class ClaudeSidechainStore {
             ...(record.isolation === undefined
                 ? {}
                 : { isolation: record.isolation }),
+            ...(record.parentAgentId === undefined
+                ? {}
+                : { parentAgentId: record.parentAgentId }),
+            ...(record.worktreePath === undefined
+                ? {}
+                : { worktreePath: record.worktreePath }),
         };
     }
 }

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