praxis-agent 0.32.0 → 0.34.0

package/dist/application/session-service.js

@@ -1,31 +1,36 @@
 import { randomUUID } from 'node:crypto';
 import { appendFile, copyFile, link, lstat, mkdir, readdir, realpath, stat, unlink, } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, extname, isAbsolute, join, relative, resolve, } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, } from 'node:path';
 import { isPathWithin } from '../platform/path-containment.js';
 import { AGENT_COLOR_DEFAULT, agentColorMessage, getClaudeEffectiveAgentColor, } from '../compatibility/claude/agent-color.js';
 import { createClaudeCompactEntries, formatClaudeCompactSummary, getCumulativeDroppedTokens, } from '../compatibility/claude/compaction.js';
 import { discoverClaudeProjectRoot, isClaudeSessionId, resolveClaudePaths, resolveClaudeScheduledTaskFile, } from '../compatibility/claude/paths.js';
+import { isClaudeAgentId } from '../compatibility/claude/sidechain.js';
 import { resolveDataPlanePaths, resolveScheduledTaskFile, } from '../persistence/data-plane.js';
 import { downloadClaudeFileResources, } from '../compatibility/claude/file-resources.js';
 import { createClaudeNativeFork } from '../compatibility/claude/fork.js';
-import { selectClaudeActiveTranscript, selectClaudeTranscriptAtMessage, } from '../compatibility/claude/history.js';
+import { selectClaudeActiveTranscript, selectClaudeTranscriptAtMessage, selectClaudeTranscriptFromNewestLeaf, } from '../compatibility/claude/history.js';
 import { ClaudeFileHistory } from '../compatibility/claude/file-history.js';
-import { getClaudePrLink } from '../compatibility/claude/pr-links.js';
-import { getClaudeAgentSetting, getClaudeLastPrompt, projectClaudeDisplayTranscript, projectClaudeModelMessages, } from '../compatibility/claude/projection.js';
+import { getClaudeAgentSetting, projectClaudeDisplayTranscript, projectClaudeModelMessages, } from '../compatibility/claude/projection.js';
 import { selectClaudeSchemaAdapter, } from '../compatibility/claude/schema.js';
+import { createClaudeDurableMetadataSnapshot, createClaudeTagEntry, mergeClaudeDurableMetadataSnapshot, reduceClaudeSessionMetadata, } from '../compatibility/claude/session-metadata.js';
+import { classifyClaudeInterruption, } from '../compatibility/claude/interruption.js';
 import { findUnresolvedClaudeToolCalls, getClaudeContentBlocks, } from '../compatibility/claude/tool-links.js';
 import { createClaudeAgentSettingEntry, createClaudeHookAttachmentEntries, createClaudeLastPromptEntry, createClaudeRuleAttachmentEntry, translateProviderEvents, } from '../compatibility/claude/translation.js';
 import { AgentRunCancelledError, AgentRuntime, ModelProviderError, } from '../core/runtime.js';
 import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
 import { BackgroundTaskRuntime, } from './background-task-runtime.js';
+import { backgroundAgentNotificationMarkers, } from './background-agent-manager.js';
 import { usageCostUsd } from '../core/usage.js';
 import { ContextBudget, ContextRecoveryPlanner, contextRecoveryMadeProgress, estimateModelRequestTokens, isPromptTooLongError, } from '../core/context-budget.js';
 import { injectFirstUserMessageContext, } from '../core/context.js';
 import { ClaudeHookToolCoordinator } from '../hooks/claude-hook-tools.js';
 import { ClaudeFileChangeWatcher } from '../hooks/claude-file-change-watcher.js';
 import { ClaudeTranscriptStore, } from '../persistence/claude-transcript-store.js';
+import { ClaudeSessionIndexCandidateError, readClaudeSessionIndexes, } from '../persistence/claude-session-index.js';
 import { InMemoryTranscriptStore } from '../persistence/in-memory-transcript-store.js';
+import { SubagentLifecycleStore } from '../persistence/subagent-lifecycle-store.js';
 import { ModelCompactor } from './model-compactor.js';
 import { agentMemoryPrompt, ClaudeSubagentExecutor, StructuredOutputRegistry, } from './subagent-service.js';
 import { ScheduledPromptManager, } from './scheduled-prompt-manager.js';
@@ -49,6 +54,15 @@ function agentToolName(rule) {
     const opening = rule.indexOf('(');
     return (opening < 0 ? rule : rule.slice(0, opening)).trim();
 }
+function transcriptContainsBackgroundAgentNotification(entries, notification) {
+    const markers = backgroundAgentNotificationMarkers(notification);
+    return entries.some((entry) => {
+        if (entry.type !== 'user')
+            return false;
+        const source = JSON.stringify(entry.message);
+        return markers.every((marker) => source.includes(marker));
+    });
+}
 function mainAgentToolNames(tools, agent) {
     const requested = agent.tools ? new Set(agent.tools.map(agentToolName)) : null;
     if (requested && agent.memory) {
@@ -630,10 +644,18 @@ export class ClaudeSessionService {
     worktreeManager;
     sessionCwds = new Map();
     discoveredProjectRoots = new Map();
+    explicitSessionFiles = new Map();
+    explicitResumeLeafUuids = new Map();
     sessionPermissionUpdates = new Map();
     hostedSubagents = new Set();
+    subagentExecutors = new Set();
     hostedSubagentsByRegistry = new WeakMap();
+    subagentExecutorSessions = new WeakMap();
+    hostedSubagentNotificationPumps = new WeakMap();
+    hostedSubagentPumpPromises = new Set();
+    hostedSubagentNotificationReservations = new WeakSet();
     backgroundNotificationWrites = new Map();
+    closing = false;
     downloadedFileResourceSessions = new Set();
     detachedHookRuns = new Map();
     activeProvider;
@@ -641,6 +663,9 @@ export class ClaudeSessionService {
     sessionCostTrackers = new Map();
     activeCostSessionId;
     closeCostSavePromise;
+    closeMetadataSavePromise;
+    durableMetadataSessions = new Set();
+    durableMetadataSnapshots = new Map();
     sessionMemoryControllers = new Map();
     resolvedSessionMemoryProvider;
     hookLifecycle;
@@ -788,6 +813,56 @@ export class ClaudeSessionService {
     stopTask(sessionId, taskId) {
         return this.backgroundTasks.stop(sessionId, taskId);
     }
+    backgroundForegroundTask(sessionId) {
+        return this.backgroundTasks.backgroundForeground(sessionId);
+    }
+    sendOwnedBackgroundAgent(sessionId, agentId, message, summary, toolUseId) {
+        const sent = this.backgroundTasks.sendAgentWithOwner(sessionId, agentId, message, summary, toolUseId);
+        if (!sent)
+            return null;
+        const hosted = [...this.hostedSubagents].find((executor) => executor === sent.owner);
+        if (hosted)
+            this.startHostedSubagentNotificationPump(sessionId, hosted);
+        return sent.content;
+    }
+    sessionSubagentExecutors(sessionId, includeHosted = false) {
+        return [...this.subagentExecutors].filter((executor) => this.subagentExecutorSessions.get(executor) === sessionId &&
+            (includeHosted ||
+                (!this.hostedSubagentNotificationPumps.has(executor) &&
+                    !this.hostedSubagentNotificationReservations.has(executor))));
+    }
+    async collectSubagentNotifications(sessionId, waitForExecutor) {
+        const executors = this.sessionSubagentExecutors(sessionId);
+        if (executors.length === 0)
+            return null;
+        const poll = () => Promise.all(executors.map((executor) => executor.notifications(false, false)));
+        let batches = await poll();
+        if (batches.every(({ messages }) => messages.length === 0)) {
+            if (waitForExecutor &&
+                executors.includes(waitForExecutor) &&
+                waitForExecutor.notificationClaimAgentIds().length > 0) {
+                await waitForExecutor.notifications(true, false);
+                batches = await poll();
+            }
+        }
+        const durationSeen = batches.some(({ durationApiMs, durationApiWithoutRetriesMs }) => durationApiMs !== undefined ||
+            durationApiWithoutRetriesMs !== undefined);
+        const modelUsage = mergeSessionRawModelUsage(...batches.map((batch) => batch.modelUsage));
+        return {
+            messages: batches.flatMap(({ messages }) => messages),
+            usage: batches.reduce((total, { usage }) => mergeUsage(total, usage), {
+                inputTokens: 0,
+                outputTokens: 0,
+            }),
+            ...(modelUsage ? { modelUsage } : {}),
+            ...(durationSeen
+                ? {
+                    durationApiMs: batches.reduce((total, batch) => addApiDuration(batch.durationApiMs, total, 'durationApiMs'), 0),
+                    durationApiWithoutRetriesMs: batches.reduce((total, batch) => addApiDuration(batch.durationApiWithoutRetriesMs ?? batch.durationApiMs, total, 'durationApiWithoutRetriesMs'), 0),
+                }
+                : {}),
+        };
+    }
     async applyPermissionUpdates(sessionId, updates) {
         if (updates.length === 0)
             return;
@@ -801,20 +876,25 @@ export class ClaudeSessionService {
         }
     }
     async close() {
+        this.closing = true;
         await this.fileChangeWatcher?.close(5_000);
         await this.hookLifecycle.close();
         await this.drainDetachedHookRuns(5_000);
         await this.options.hooks?.drainAsync(5_000);
         this.scheduledPrompts?.close();
         await this.options.projectMemoryExtraction?.close(5_000);
-        await Promise.all([...this.hostedSubagents].map((executor) => executor.close()));
+        await Promise.all([...this.subagentExecutors].map((executor) => executor.close()));
+        await Promise.allSettled([...this.hostedSubagentPumpPromises]);
         await Promise.resolve();
         await Promise.all([...this.backgroundNotificationWrites.values()]);
         this.hostedSubagents.clear();
+        this.subagentExecutors.clear();
         this.backgroundTasks.clear();
         await Promise.all([...this.sessionMemoryControllers.values()].map((controller) => controller.close()));
         this.sessionMemoryControllers.clear();
         await this.workflowManager?.close();
+        this.closeMetadataSavePromise ??= Promise.all([...this.durableMetadataSessions].map((sessionId) => this.reappendDurableMetadata(sessionId))).then(() => undefined);
+        await this.closeMetadataSavePromise;
         this.closeCostSavePromise ??= this.persistActiveSessionCost();
         await this.closeCostSavePromise;
         this.mcpClosePromise ??= this.options.mcp?.close?.() ?? Promise.resolve();
@@ -1041,11 +1121,15 @@ export class ClaudeSessionService {
                         backgroundTaskNotifications: (waitForRunning) => taskTools.notifications(waitForRunning),
                     }
                     : {}),
+                stopOwnedBackgroundAgent: (ownerSessionId, agentId) => this.backgroundTasks.stopAgent(ownerSessionId, agentId),
+                outputOwnedBackgroundAgent: (ownerSessionId, agentId, options) => this.backgroundTasks.outputAgent(ownerSessionId, agentId, options),
+                sendOwnedBackgroundAgent: (ownerSessionId, agentId, message, summary, toolUseId) => this.sendOwnedBackgroundAgent(ownerSessionId, agentId, message, summary, toolUseId),
             })
             : null;
-        if (subagentExecutor)
-            this.hostedSubagents.add(subagentExecutor);
         if (subagentExecutor) {
+            this.hostedSubagents.add(subagentExecutor);
+            this.subagentExecutors.add(subagentExecutor);
+            this.subagentExecutorSessions.set(subagentExecutor, sessionId);
             this.backgroundTasks.registerAgents(sessionId, subagentExecutor);
         }
         const agentTools = subagentExecutor
@@ -1248,6 +1332,9 @@ export class ClaudeSessionService {
             .join('-')
             .slice(0, 64) || 'side-question';
         const registry = this.createHostedToolRegistry(sessionId);
+        const executor = this.hostedSubagentsByRegistry.get(registry);
+        if (executor)
+            this.hostedSubagentNotificationReservations.add(executor);
         const call = {
             id: randomUUID(),
             name: 'Agent',
@@ -1263,26 +1350,69 @@ export class ClaudeSessionService {
             cwd: this.activeCwd(),
             ...(signal ? { signal } : {}),
         };
-        const prepared = await registry.prepare(call, context);
-        const result = await registry.execute(prepared, context);
-        const agentId = result.nativeToolUseResult?.agentId;
-        if (result.isError || typeof agentId !== 'string') {
-            throw new Error(result.content || 'Could not fork side question');
+        try {
+            const prepared = await registry.prepare(call, context);
+            const result = await registry.execute(prepared, context);
+            const agentId = result.nativeToolUseResult?.agentId;
+            if (result.isError || typeof agentId !== 'string') {
+                throw new Error(result.content || 'Could not fork side question');
+            }
+            await this.appendSystemLocalCommand(sessionId, 'btw', prompt, `⑂ forked ${name} (${agentId.slice(-4)})`);
+            if (executor) {
+                this.startHostedSubagentNotificationPump(sessionId, executor);
+            }
+            return { agentId, name };
         }
-        await this.appendSystemLocalCommand(sessionId, 'btw', prompt, `⑂ forked ${name} (${agentId.slice(-4)})`);
-        const executor = this.hostedSubagentsByRegistry.get(registry);
-        if (executor) {
-            void executor
-                .notifications(true)
-                .then(({ messages }) => this.enqueueBackgroundNotifications(sessionId, messages))
-                .catch((error) => this.options.eventSink?.({
-                type: 'warning',
-                message: error instanceof Error
-                    ? error.message
-                    : `Could not persist background notification: ${String(error)}`,
-            }));
+        catch (error) {
+            if (executor) {
+                this.hostedSubagentNotificationReservations.delete(executor);
+            }
+            throw error;
         }
-        return { agentId, name };
+    }
+    startHostedSubagentNotificationPump(sessionId, executor) {
+        this.hostedSubagentNotificationReservations.delete(executor);
+        if (this.hostedSubagentNotificationPumps.has(executor))
+            return;
+        const pump = (async () => {
+            while (!this.closing) {
+                const reconciled = await this.turnStore(sessionId).withLease(async (lease) => {
+                    const snapshot = await lease.load();
+                    await executor.reconcileDetachedNotifications((notification) => transcriptContainsBackgroundAgentNotification(snapshot.entries, notification));
+                });
+                if (reconciled.status !== 'completed') {
+                    await new Promise((resolve) => setTimeout(resolve, 25));
+                    continue;
+                }
+                const { messages } = await executor.notifications(true, false);
+                if (messages.length === 0)
+                    return;
+                await executor.prepareNotificationsDetached(messages);
+                if (!(await this.enqueueBackgroundNotifications(sessionId, messages, async (message) => {
+                    await executor.confirmNotificationsDetached([message]);
+                    await executor.acknowledgeNotifications([message]);
+                }))) {
+                    return;
+                }
+                if (executor.notificationClaimAgentIds().length === 0)
+                    return;
+            }
+        })()
+            .catch((error) => this.options.eventSink?.({
+            type: 'warning',
+            message: error instanceof Error
+                ? error.message
+                : `Could not persist background notification: ${String(error)}`,
+        }))
+            .finally(() => {
+            if (this.hostedSubagentNotificationPumps.get(executor) === pump) {
+                this.hostedSubagentNotificationPumps.delete(executor);
+            }
+            this.hostedSubagentPumpPromises.delete(pump);
+        });
+        this.hostedSubagentNotificationPumps.set(executor, pump);
+        this.hostedSubagentPumpPromises.add(pump);
+        void pump;
     }
     async promptSuggestion(sessionId, signal) {
         const loaded = this.options.sessionPersistence === false
@@ -1364,10 +1494,12 @@ export class ClaudeSessionService {
         return validSessionName(metrics.text);
     }
     async sessions() {
-        const discoveredRoot = await discoverClaudeProjectRoot({
-            configRoot: this.options.configRoot,
-            cwd: this.activeCwd(),
-        });
+        const discoveredRoot = this.options.dataPlane === 'native'
+            ? undefined
+            : await discoverClaudeProjectRoot({
+                configRoot: this.options.configRoot,
+                cwd: this.activeCwd(),
+            });
         const projectRoot = discoveredRoot ?? this.paths(randomUUID()).projectRoot;
         let names;
         try {
@@ -1378,33 +1510,55 @@ export class ClaudeSessionService {
                 return [];
             throw error;
         }
-        const sessionIds = names
+        const discoveredSessionIds = names
             .filter((name) => extname(name) === '.jsonl')
             .map((name) => basename(name, '.jsonl'))
             .filter((sessionId) => isClaudeSessionId(sessionId));
+        const sessionIds = [
+            ...new Set([
+                ...discoveredSessionIds,
+                ...this.explicitSessionFiles.keys(),
+            ]),
+        ];
         if (discoveredRoot !== undefined) {
-            for (const sessionId of sessionIds) {
+            for (const sessionId of discoveredSessionIds) {
                 this.discoveredProjectRoots.set(sessionId, projectRoot);
             }
         }
-        const summaries = await Promise.all(sessionIds.map(async (sessionId) => {
-            const sessionFile = join(projectRoot, `${sessionId}.jsonl`);
+        const indexResults = await readClaudeSessionIndexes(sessionIds.map((sessionId) => ({
+            sessionId,
+            path: this.explicitSessionFiles.get(sessionId) ??
+                join(projectRoot, `${sessionId}.jsonl`),
+        })), this.schema);
+        const summaries = indexResults.map((result) => {
             try {
-                const metadata = await lstat(sessionFile);
-                if (!metadata.isFile())
-                    return null;
-                const recovery = await this.store(sessionId).loadReadOnly();
-                if (!(await lstat(sessionFile)).isFile())
-                    return null;
-                const name = this.sessionName(recovery.entries);
-                const prLink = getClaudePrLink(recovery.entries, sessionId);
+                if ('error' in result)
+                    throw result.error;
+                const { sessionId, index } = result;
+                const metadata = reduceClaudeSessionMetadata(index.entries, sessionId);
+                const name = metadata.title ?? metadata.agentName;
+                const prLink = metadata.prLink;
                 return {
                     sessionId,
-                    ...(name === null ? {} : { name }),
-                    lastPrompt: getClaudeLastPrompt(recovery.entries),
-                    updatedAt: metadata.mtime.toISOString(),
-                    status: this.sessionStatus(recovery.issue, recovery.entries.length),
-                    issue: recovery.issue,
+                    ...(name === undefined ? {} : { name }),
+                    ...(metadata.tag === undefined ? {} : { tag: metadata.tag }),
+                    ...(metadata.agentName === undefined
+                        ? {}
+                        : { agentName: metadata.agentName }),
+                    ...(metadata.agentColor === undefined
+                        ? {}
+                        : { agentColor: metadata.agentColor }),
+                    ...(metadata.agentSetting === undefined
+                        ? {}
+                        : { agentSetting: metadata.agentSetting }),
+                    ...(metadata.permissionMode === undefined
+                        ? {}
+                        : { permissionMode: metadata.permissionMode }),
+                    ...(metadata.mode === undefined ? {} : { mode: metadata.mode }),
+                    lastPrompt: metadata.lastPrompt ?? null,
+                    updatedAt: index.updatedAt,
+                    status: this.sessionStatus(index.issue, index.entries.length),
+                    issue: index.issue,
                     ...(prLink
                         ? {
                             prNumber: prLink.prNumber,
@@ -1415,15 +1569,18 @@ export class ClaudeSessionService {
                 };
             }
             catch (error) {
-                if (typeof error.code === 'string') {
+                if (error instanceof ClaudeSessionIndexCandidateError)
+                    return null;
+                if (['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code ?? '')) {
                     return null;
                 }
                 throw error;
             }
-        }));
+        });
         return summaries
             .filter((summary) => summary !== null)
-            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) ||
+            left.sessionId.localeCompare(right.sessionId));
     }
     async inspect(sessionId) {
         this.assertSessionPersistence();
@@ -1440,10 +1597,32 @@ export class ClaudeSessionService {
             throw error;
         }
         const recovery = await this.store(sessionId).loadReadOnly();
-        const prLink = getClaudePrLink(recovery.entries, sessionId);
+        const sessionMetadata = reduceClaudeSessionMetadata(recovery.entries, sessionId);
+        const prLink = sessionMetadata.prLink;
         return {
             sessionId,
-            lastPrompt: getClaudeLastPrompt(recovery.entries),
+            ...(sessionMetadata.title === undefined
+                ? {}
+                : { name: sessionMetadata.title }),
+            ...(sessionMetadata.tag === undefined
+                ? {}
+                : { tag: sessionMetadata.tag }),
+            ...(sessionMetadata.agentName === undefined
+                ? {}
+                : { agentName: sessionMetadata.agentName }),
+            ...(sessionMetadata.agentColor === undefined
+                ? {}
+                : { agentColor: sessionMetadata.agentColor }),
+            ...(sessionMetadata.agentSetting === undefined
+                ? {}
+                : { agentSetting: sessionMetadata.agentSetting }),
+            ...(sessionMetadata.permissionMode === undefined
+                ? {}
+                : { permissionMode: sessionMetadata.permissionMode }),
+            ...(sessionMetadata.mode === undefined
+                ? {}
+                : { mode: sessionMetadata.mode }),
+            lastPrompt: sessionMetadata.lastPrompt ?? null,
             updatedAt: metadata.mtime.toISOString(),
             status: this.sessionStatus(recovery.issue, recovery.entries.length),
             issue: recovery.issue,
@@ -1479,6 +1658,84 @@ export class ClaudeSessionService {
             throw error;
         }
     }
+    async registerResumePath(requestedPath) {
+        this.assertSessionPersistence();
+        const path = resolve(requestedPath);
+        const pathMetadata = await lstat(path);
+        if (!pathMetadata.isFile()) {
+            throw new Error(`Claude resume path must be a regular JSONL file: ${path}`);
+        }
+        if (extname(path).toLowerCase() !== '.jsonl') {
+            throw new Error(`Claude resume path must end in .jsonl: ${path}`);
+        }
+        const sessionId = basename(path, '.jsonl');
+        if (!isClaudeSessionId(sessionId)) {
+            throw new Error(`Claude resume path filename must be a session UUID: ${path}`);
+        }
+        const canonicalPath = await realpath(path);
+        const exact = this.pathsForCwd(sessionId, this.activeCwd());
+        const candidate = new ClaudeTranscriptStore({
+            sessionFile: canonicalPath,
+            lockFile: join(exact.praxisRoot, 'locks', `${sessionId}.lock`),
+            schema: this.schema,
+        });
+        const snapshot = await candidate.load();
+        if (!snapshot.tail.newlineTerminated) {
+            throw new Error('Claude resume transcript must be newline-terminated');
+        }
+        if (snapshot.entries.length === 0) {
+            throw new Error('Claude resume transcript must not be empty');
+        }
+        let matchingSessionIdentity = false;
+        for (const entry of snapshot.entries) {
+            if (entry.sessionId === sessionId)
+                matchingSessionIdentity = true;
+            if (typeof entry.sessionId === 'string' &&
+                entry.sessionId !== sessionId) {
+                throw new Error(`Claude resume transcript contains a different sessionId: ${String(entry.sessionId)}`);
+            }
+        }
+        if (!matchingSessionIdentity) {
+            throw new Error('Claude resume transcript is missing its sessionId');
+        }
+        const selected = selectClaudeTranscriptFromNewestLeaf(snapshot.entries);
+        this.explicitSessionFiles.set(sessionId, canonicalPath);
+        this.explicitResumeLeafUuids.set(sessionId, selected.leafUuid);
+        this.discoveredProjectRoots.set(sessionId, dirname(canonicalPath));
+        const metadata = reduceClaudeSessionMetadata(snapshot.entries, sessionId);
+        const prLink = metadata.prLink;
+        return {
+            sessionId,
+            ...(metadata.title === undefined ? {} : { name: metadata.title }),
+            ...(metadata.tag === undefined ? {} : { tag: metadata.tag }),
+            ...(metadata.agentName === undefined
+                ? {}
+                : { agentName: metadata.agentName }),
+            ...(metadata.agentColor === undefined
+                ? {}
+                : { agentColor: metadata.agentColor }),
+            ...(metadata.agentSetting === undefined
+                ? {}
+                : { agentSetting: metadata.agentSetting }),
+            ...(metadata.permissionMode === undefined
+                ? {}
+                : { permissionMode: metadata.permissionMode }),
+            ...(metadata.mode === undefined ? {} : { mode: metadata.mode }),
+            lastPrompt: metadata.lastPrompt ?? null,
+            updatedAt: pathMetadata.mtime.toISOString(),
+            status: this.sessionStatus(null, snapshot.entries.length),
+            issue: null,
+            ...(prLink === undefined
+                ? {}
+                : {
+                    prNumber: prLink.prNumber,
+                    ...(prLink.prUrl === undefined ? {} : { prUrl: prLink.prUrl }),
+                    ...(prLink.prRepository === undefined
+                        ? {}
+                        : { prRepository: prLink.prRepository }),
+                }),
+        };
+    }
     async transcript(sessionId, resumeSessionAt) {
         await this.discoverProjectRoot(sessionId);
         try {
@@ -1498,6 +1755,24 @@ export class ClaudeSessionService {
             throw error;
         }
     }
+    async interruption(sessionId) {
+        this.assertSessionPersistence();
+        await this.discoverProjectRoot(sessionId);
+        const snapshot = await this.store(sessionId).loadReadOnly();
+        if (snapshot.entries.length === 0) {
+            throw new Error(`Claude session not found: ${sessionId}`);
+        }
+        return classifyClaudeInterruption(snapshot.entries);
+    }
+    async metadata(sessionId) {
+        this.assertSessionPersistence();
+        await this.discoverProjectRoot(sessionId);
+        const snapshot = await this.store(sessionId).loadReadOnly();
+        if (snapshot.entries.length === 0) {
+            throw new Error(`Claude session not found: ${sessionId}`);
+        }
+        return reduceClaudeSessionMetadata(snapshot.entries, sessionId);
+    }
     async rename(sessionId, name) {
         this.assertWritable();
         const normalized = name.trim();
@@ -1508,16 +1783,44 @@ export class ClaudeSessionService {
             if (snapshot.entries.length === 0) {
                 throw new Error(`Claude session not found: ${sessionId}`);
             }
+            this.rememberDurableMetadata(sessionId, snapshot.entries);
             if (this.hasSessionName(snapshot.entries, normalized))
                 return;
-            const appendResult = await lease.appendMany(snapshot.tail, this.sessionNameEntries(sessionId, normalized));
+            const entries = this.sessionNameEntries(sessionId, normalized);
+            const appendResult = await lease.appendMany(snapshot.tail, entries);
             if (appendResult.status === 'conflict') {
                 throw new Error(`Claude transcript rename conflict: ${appendResult.reason}`);
             }
+            this.rememberDurableMetadata(sessionId, [...snapshot.entries, ...entries]);
         });
         if (result.status === 'conflict') {
             throw new Error(`Claude transcript rename conflict: ${result.reason}`);
         }
+        this.durableMetadataSessions.add(sessionId);
+    }
+    async tag(sessionId, tag) {
+        this.assertWritable();
+        const normalized = tag.trim();
+        const entry = createClaudeTagEntry(sessionId, normalized);
+        const result = await this.turnStore(sessionId).withLease(async (lease) => {
+            const snapshot = await lease.load();
+            if (snapshot.entries.length === 0) {
+                throw new Error(`Claude session not found: ${sessionId}`);
+            }
+            this.rememberDurableMetadata(sessionId, snapshot.entries);
+            const current = reduceClaudeSessionMetadata(snapshot.entries, sessionId);
+            if (current.tag === normalized)
+                return;
+            const appendResult = await lease.append(snapshot.tail, entry);
+            if (appendResult.status === 'conflict') {
+                throw new Error(`Claude transcript tag conflict: ${appendResult.reason}`);
+            }
+            this.rememberDurableMetadata(sessionId, [...snapshot.entries, entry]);
+        });
+        if (result.status === 'conflict') {
+            throw new Error(`Claude transcript tag conflict: ${result.reason}`);
+        }
+        this.durableMetadataSessions.add(sessionId);
     }
     async changeCwd(sessionId, requestedCwd) {
         this.assertWritable();
@@ -1976,6 +2279,18 @@ export class ClaudeSessionService {
             if (appendResult.status === 'conflict') {
                 throw new Error(`Claude transcript append conflict: ${appendResult.reason}`);
             }
+            const metadataEntries = createClaudeDurableMetadataSnapshot([...snapshot.entries, ...entries], sessionId);
+            if (metadataEntries.length > 0) {
+                const metadataAppend = await lease.appendMany(appendResult.tail, metadataEntries);
+                if (metadataAppend.status === 'conflict') {
+                    throw new Error(`Claude metadata snapshot conflict: ${metadataAppend.reason}`);
+                }
+            }
+            this.rememberDurableMetadata(sessionId, [
+                ...snapshot.entries,
+                ...entries,
+                ...metadataEntries,
+            ]);
             this.options.projectMemoryRecall?.recordCompact(sessionId);
             this.options.eventSink?.({
                 type: 'compact-boundary',
@@ -2234,8 +2549,9 @@ export class ClaudeSessionService {
     }
     async costSnapshot(sessionId) {
         const existing = this.sessionCostTrackers.get(sessionId);
-        if (existing)
-            return existing.snapshot();
+        if (existing) {
+            return this.withDetachedSubagentUsage(sessionId, existing.snapshot());
+        }
         const store = this.options.costStateStore;
         const loaded = store ? await store.load(sessionId) : null;
         const tracker = new ClaudeSessionCostTracker({
@@ -2243,6 +2559,78 @@ export class ClaudeSessionService {
             ...(loaded ? { restored: loaded } : {}),
         });
         this.sessionCostTrackers.set(sessionId, tracker);
+        return this.withDetachedSubagentUsage(sessionId, tracker.snapshot());
+    }
+    async withDetachedSubagentUsage(sessionId, base) {
+        const tracker = new ClaudeSessionCostTracker({
+            sessionId,
+            restored: base,
+        });
+        const directory = join(this.paths(sessionId).praxisRoot, 'subagent-lifecycle', sessionId);
+        let entries;
+        try {
+            entries = await readdir(directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return base;
+            throw error;
+        }
+        for (const file of entries) {
+            const agentId = file.endsWith('.json') ? file.slice(0, -5) : '';
+            if (!isClaudeAgentId(agentId))
+                continue;
+            try {
+                const lifecycle = await new SubagentLifecycleStore(this.paths(sessionId).praxisRoot, sessionId, agentId).read();
+                for (const notification of lifecycle?.notifications ?? []) {
+                    if (notification.accounting?.kind !== 'detached' ||
+                        !notification.accounting.delivered ||
+                        notification.result === null) {
+                        continue;
+                    }
+                    const rows = Object.entries(notification.result.modelUsage ?? {
+                        [notification.accounting.model]: notification.result.usage,
+                    });
+                    if (rows.length === 0) {
+                        tracker.recordDurations({
+                            ...(notification.result.durationApiMs === undefined
+                                ? {}
+                                : { apiDurationMs: notification.result.durationApiMs }),
+                            ...(notification.result.durationApiWithoutRetriesMs === undefined
+                                ? {}
+                                : {
+                                    durationApiWithoutRetriesMs: notification.result.durationApiWithoutRetriesMs,
+                                }),
+                        });
+                        continue;
+                    }
+                    for (const [index, [model, usage]] of rows.entries()) {
+                        const pricing = this.options.pricing?.resolve(model);
+                        const costUsd = pricing ? usageCostUsd(usage, pricing) : undefined;
+                        tracker.recordTurn({
+                            model,
+                            usage,
+                            ...(costUsd === undefined ? {} : { costUsd }),
+                            ...(usage.webSearchRequests === undefined
+                                ? {}
+                                : { webSearchRequests: usage.webSearchRequests }),
+                            ...(index === 0
+                                ? {
+                                    apiDurationMs: notification.result.durationApiMs,
+                                    apiDurationWithoutRetriesMs: notification.result.durationApiWithoutRetriesMs,
+                                }
+                                : {}),
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                this.options.eventSink?.({
+                    type: 'warning',
+                    message: `Could not account detached subagent ${agentId}: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
         return tracker.snapshot();
     }
     async executeTurn(sessionId, prompt, requireExisting, signal, name, images = [], documents = [], resumeSessionAt, shellCommand, skipUserPrompt = false) {
@@ -2256,6 +2644,9 @@ export class ClaudeSessionService {
             throw new Error('Shell command must not be empty');
         }
         await this.activateSessionCostTracker(sessionId);
+        if (this.options.sessionPersistence !== false) {
+            this.durableMetadataSessions.add(sessionId);
+        }
         await this.ensureFileResources(sessionId, signal);
         this.worktreeManager?.bindSession(sessionId);
         if (this.options.initialWorktree) {
@@ -2283,6 +2674,7 @@ export class ClaudeSessionService {
                 }
             }
             let snapshot = await lease.load();
+            let automaticReplayPrompt;
             if (requireExisting &&
                 this.options.sessionPersistence === false &&
                 snapshot.entries.length === 0) {
@@ -2296,12 +2688,43 @@ export class ClaudeSessionService {
             if (requireExisting && snapshot.entries.length === 0) {
                 throw new Error(`Claude session not found: ${sessionId}`);
             }
+            this.rememberDurableMetadata(sessionId, snapshot.entries);
             if (resumeSessionAt !== undefined) {
                 snapshot = {
                     entries: selectClaudeTranscriptAtMessage(snapshot.entries, resumeSessionAt),
                     tail: { ...snapshot.tail, branchParentUuid: resumeSessionAt },
                 };
             }
+            else if (this.explicitResumeLeafUuids.has(sessionId)) {
+                const selected = selectClaudeTranscriptFromNewestLeaf(snapshot.entries);
+                this.explicitResumeLeafUuids.set(sessionId, selected.leafUuid);
+                snapshot = {
+                    entries: selected.entries,
+                    tail: { ...snapshot.tail, branchParentUuid: selected.leafUuid },
+                };
+            }
+            if (requireExisting &&
+                resumeSessionAt === undefined &&
+                this.options.resumeInterruptedTurn === true &&
+                shellCommand === undefined &&
+                !skipUserPrompt &&
+                !(this.options.approveRecovery !== undefined &&
+                    findUnresolvedClaudeToolCalls(snapshot.entries).length > 0)) {
+                const interruption = classifyClaudeInterruption(snapshot.entries);
+                if ((interruption.kind === 'interrupted-prompt' ||
+                    interruption.kind === 'interrupted-turn') &&
+                    interruption.prompt !== undefined &&
+                    interruption.replayEntries !== undefined) {
+                    automaticReplayPrompt = interruption.prompt;
+                    snapshot = {
+                        entries: interruption.replayEntries,
+                        tail: {
+                            ...snapshot.tail,
+                            branchParentUuid: interruption.replayParentUuid ?? null,
+                        },
+                    };
+                }
+            }
             const initialTransition = this.worktreeManager?.consumeTransition('__initial__');
             if (initialTransition && snapshot.entries.length === 0) {
                 const stateEntry = {
@@ -2314,6 +2737,7 @@ export class ClaudeSessionService {
                     entries: [...snapshot.entries, stateEntry],
                     tail: stateTail,
                 };
+                this.rememberDurableMetadata(sessionId, snapshot.entries);
             }
             this.restoreWorktree(snapshot.entries);
             this.options.interactiveTools?.restore(sessionId, snapshot.entries);
@@ -2329,18 +2753,20 @@ export class ClaudeSessionService {
                     entries: [...snapshot.entries, ...entries],
                     tail: appendResult.tail,
                 };
+                this.rememberDurableMetadata(sessionId, snapshot.entries);
             }
             const agentName = this.options.agent ?? getClaudeAgentSetting(snapshot.entries);
             const agent = this.resolveAgent(agentName);
             const provider = this.providerForAgent(agent);
             this.activeProvider = provider;
-            const effectivePrompt = !requireExisting &&
-                !skipUserPrompt &&
-                !this.options.agentInitialPromptHandledExternally &&
-                shellCommand === undefined &&
-                agent?.initialPrompt
-                ? `${agent.initialPrompt}\n\n${prompt}`
-                : prompt;
+            const effectivePrompt = automaticReplayPrompt ??
+                (!requireExisting &&
+                    !skipUserPrompt &&
+                    !this.options.agentInitialPromptHandledExternally &&
+                    shellCommand === undefined &&
+                    agent?.initialPrompt
+                    ? `${agent.initialPrompt}\n\n${prompt}`
+                    : prompt);
             const projectMemoryRecallTurn = !skipUserPrompt && shellCommand === undefined
                 ? this.options.projectMemoryRecall?.prefetch({
                     sessionId,
@@ -2545,8 +2971,17 @@ export class ClaudeSessionService {
                             backgroundTaskNotifications: (waitForRunning) => taskTools.notifications(waitForRunning),
                         }
                         : {}),
+                    notificationDelivered: (notification) => transcriptContainsBackgroundAgentNotification(snapshot.entries, notification),
+                    stopOwnedBackgroundAgent: (ownerSessionId, agentId) => this.backgroundTasks.stopAgent(ownerSessionId, agentId),
+                    outputOwnedBackgroundAgent: (ownerSessionId, agentId, options) => this.backgroundTasks.outputAgent(ownerSessionId, agentId, options),
+                    sendOwnedBackgroundAgent: (ownerSessionId, agentId, message, summary, toolUseId) => this.sendOwnedBackgroundAgent(ownerSessionId, agentId, message, summary, toolUseId),
                 })
                 : null;
+            if (subagentExecutor) {
+                this.subagentExecutors.add(subagentExecutor);
+                this.subagentExecutorSessions.set(subagentExecutor, sessionId);
+                this.backgroundTasks.registerAgents(sessionId, subagentExecutor);
+            }
             const agentTools = subagentExecutor
                 ? subagentExecutor.registry(sessionId, 0, (callId) => currentPromptId ??
                     this.promptIdForToolCall(snapshot.entries, callId))
@@ -2847,6 +3282,7 @@ export class ClaudeSessionService {
                             tail: followUpTail,
                         };
                         currentTurnUserMessages?.push(content);
+                        await Promise.all(this.sessionSubagentExecutors(sessionId, true).map((executor) => executor.acknowledgeNotifications([content])));
                     }
                 },
             };
@@ -3302,6 +3738,18 @@ export class ClaudeSessionService {
                         entries: [...snapshot.entries, ...entries],
                         tail: appendResult.tail,
                     };
+                    const metadataEntries = createClaudeDurableMetadataSnapshot(snapshot.entries, sessionId);
+                    if (metadataEntries.length > 0) {
+                        const metadataAppend = await lease.appendMany(snapshot.tail, metadataEntries);
+                        if (metadataAppend.status === 'conflict') {
+                            throw new Error(`Claude metadata snapshot conflict: ${metadataAppend.reason}`);
+                        }
+                        snapshot = {
+                            entries: [...snapshot.entries, ...metadataEntries],
+                            tail: metadataAppend.tail,
+                        };
+                    }
+                    this.rememberDurableMetadata(sessionId, snapshot.entries);
                     await this.runAdvisoryHook(sessionId, 'PostCompact', { trigger: 'auto', compact_summary: compacted.summary }, 'auto', signal);
                     // The boundary is durable: mirror Claude's full-compact behavior by
                     // rerunning SessionStart with source compact and refreshing the
@@ -3550,7 +3998,15 @@ export class ClaudeSessionService {
                                         messages.push(`Stop hook error: ${outcome.blockedReason}`);
                                     }
                                 }
-                                const background = await subagentExecutor?.notifications(true);
+                                const claimedAgentIds = new Set(this.sessionSubagentExecutors(sessionId, true).flatMap((executor) => executor.notificationClaimAgentIds()));
+                                await Promise.all(this.sessionSubagentExecutors(sessionId, true).map((executor) => {
+                                    const delivered = (notification) => transcriptContainsBackgroundAgentNotification(snapshot.entries, notification);
+                                    return this.hostedSubagents.has(executor)
+                                        ? executor.reconcileDetachedNotifications(delivered)
+                                        : executor.reconcileDeliveredNotifications(delivered);
+                                }));
+                                await subagentExecutor?.hydratePersistedTasks(sessionId, this.activeCwd(), claimedAgentIds);
+                                const background = await this.collectSubagentNotifications(sessionId, subagentExecutor ?? undefined);
                                 if (background)
                                     messages.push(...background.messages);
                                 const workflow = await this.workflowManager?.notifications(true);
@@ -3720,12 +4176,18 @@ export class ClaudeSessionService {
                     throw new Error('Could not locate final assistant response');
                 }
                 if (!skipUserPrompt) {
-                    await this.append(lease, snapshot.tail, createClaudeLastPromptEntry({
+                    const lastPrompt = createClaudeLastPromptEntry({
                         sessionId,
                         lastPrompt: effectivePrompt,
                         leafUuid: finalLeafUuid,
-                    }));
+                    });
+                    const tail = await this.append(lease, snapshot.tail, lastPrompt);
+                    snapshot = {
+                        entries: [...snapshot.entries, lastPrompt],
+                        tail,
+                    };
                 }
+                this.rememberDurableMetadata(sessionId, snapshot.entries);
                 const totalUsage = mergeUsage(mergeUsage(mergeUsage(recoveryUsage, compactionUsage), shellUsage), result.usage);
                 const tracker = this.sessionCostTrackers.get(sessionId);
                 if (!tracker) {
@@ -4104,6 +4566,14 @@ export class ClaudeSessionService {
     }
     paths(sessionId) {
         const exact = this.pathsForCwd(sessionId, this.sessionCwds.get(sessionId) ?? this.activeCwd());
+        const explicitSessionFile = this.explicitSessionFiles.get(sessionId);
+        if (explicitSessionFile !== undefined) {
+            return {
+                ...exact,
+                projectRoot: dirname(explicitSessionFile),
+                sessionFile: explicitSessionFile,
+            };
+        }
         if (this.options.dataPlane === 'native')
             return exact;
         const discovered = this.discoveredProjectRoots.get(sessionId);
@@ -4364,7 +4834,7 @@ export class ClaudeSessionService {
         }
     }
     async appendBackgroundNotification(sessionId, content) {
-        while (true) {
+        while (!this.closing) {
             const result = await this.turnStore(sessionId).withLease(async (lease) => {
                 const snapshot = await lease.load();
                 if (snapshot.entries.length === 0) {
@@ -4410,16 +4880,23 @@ export class ClaudeSessionService {
                 }
             });
             if (result.status === 'completed')
-                return;
+                return true;
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
+        return false;
     }
-    enqueueBackgroundNotifications(sessionId, messages) {
+    enqueueBackgroundNotifications(sessionId, messages, onAppended) {
         const previous = this.backgroundNotificationWrites.get(sessionId);
-        const queued = (previous ?? Promise.resolve()).then(async () => {
+        const queued = (previous ?? Promise.resolve(true)).then(async (previousCompleted) => {
+            if (!previousCompleted || this.closing)
+                return false;
             for (const message of messages) {
-                await this.appendBackgroundNotification(sessionId, message);
+                if (!(await this.appendBackgroundNotification(sessionId, message))) {
+                    return false;
+                }
+                await onAppended?.(message);
             }
+            return true;
         });
         this.backgroundNotificationWrites.set(sessionId, queued);
         const cleanup = () => {
@@ -4509,6 +4986,41 @@ export class ClaudeSessionService {
             schema: this.schema,
         });
     }
+    /**
+     * Refreshes metadata under the transcript lease before writing a compact
+     * tail snapshot. This prevents a long-lived process from overwriting a
+     * newer title or tag appended by another writer.
+     */
+    async reappendDurableMetadata(sessionId) {
+        if (this.options.sessionPersistence === false)
+            return;
+        await this.discoverProjectRoot(sessionId);
+        let result;
+        try {
+            result = await this.store(sessionId).withLease(async (lease) => {
+                const snapshot = await lease.loadIndex?.();
+                if (snapshot === undefined)
+                    return;
+                if (snapshot.entries.length === 0)
+                    return;
+                const entries = mergeClaudeDurableMetadataSnapshot(this.durableMetadataSnapshots.get(sessionId) ?? [], snapshot.tailEntries, sessionId);
+                if (entries.length === 0)
+                    return;
+                const appended = await lease.appendMetadataSnapshot(snapshot.tail, entries);
+                if (appended.status === 'conflict') {
+                    throw new Error(`Claude metadata snapshot conflict: ${appended.reason}`);
+                }
+            });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        if (result.status === 'conflict') {
+            throw new Error(`Claude metadata snapshot conflict: ${result.reason}`);
+        }
+    }
     turnStore(sessionId) {
         if (this.options.sessionPersistence !== false)
             return this.store(sessionId);
@@ -4519,6 +5031,12 @@ export class ClaudeSessionService {
         }
         return store;
     }
+    rememberDurableMetadata(sessionId, observed) {
+        const snapshot = mergeClaudeDurableMetadataSnapshot(this.durableMetadataSnapshots.get(sessionId) ?? [], observed, sessionId);
+        if (snapshot.length > 0) {
+            this.durableMetadataSnapshots.set(sessionId, snapshot);
+        }
+    }
     assertSessionPersistence() {
         if (this.options.sessionPersistence === false) {
             throw new Error('Session persistence is disabled');
@@ -4773,7 +5291,9 @@ export class ClaudeSessionService {
         return result.tail;
     }
     logicalTailUuid(tail) {
-        return tail.branchParentUuid ?? tail.lastUuid;
+        return 'branchParentUuid' in tail
+            ? (tail.branchParentUuid ?? null)
+            : tail.lastUuid;
     }
 }
 //# sourceMappingURL=session-service.js.map