praxis-agent 0.24.0 → 0.25.0

package/dist/application/session-memory.d.ts

@@ -85,11 +85,21 @@ export declare class SessionMemoryController {
      * The persisted counters only advance once an extraction succeeds.
      */
     observeDelta(inputTokens: number, toolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
+    /**
+     * Records the observed totals and starts an extraction when the fixed
+     * eligibility contract is met. Returns true when an extraction is running or
+     * was just scheduled; callers on normal turns never await the extraction.
+     */
+    private scheduleExtraction;
     /** Safe snapshot of the loaded durable summary; empty when none exists. */
     summary(): Promise<string>;
     /** Safe snapshot of the loaded session memory state. */
     state(): Promise<SessionMemoryState>;
-    /** Resolves when no extraction is running; rejects on failure or timeout. */
+    /**
+     * Resolves when no extraction is running; rejects on extraction failure.
+     * Compact callers wait softly: if extraction outlives the bounded
+     * `waitTimeoutMs`, this resolves so compaction can proceed anyway.
+     */
     waitForIdle(): Promise<void>;
     clear(): Promise<void>;
     private ensureLoaded;

package/dist/application/session-memory.js

@@ -2,6 +2,8 @@ import { readFile, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { isClaudeSessionId } from '../compatibility/claude/paths.js';
 import { writeFileAtomically } from '../platform/atomic-write.js';
+/** A persisted extraction this old is recovered as stale and safely re-extracted. */
+const STALE_EXTRACTION_THRESHOLD_MS = 60_000;
 export class SessionMemoryStateError extends Error {
     name = 'SessionMemoryStateError';
     constructor(message) {
@@ -170,8 +172,8 @@ export class SessionMemoryController {
         this.options = options;
         this.initTokens = options.initTokens ?? 10_000;
         this.updateTokens = options.updateTokens ?? 5_000;
-        this.updateToolCalls = options.updateToolCalls ?? 20;
-        this.waitTimeoutMs = options.waitTimeoutMs ?? 30_000;
+        this.updateToolCalls = options.updateToolCalls ?? 3;
+        this.waitTimeoutMs = options.waitTimeoutMs ?? 15_000;
         for (const [name, value] of [
             ['initTokens', this.initTokens],
             ['updateTokens', this.updateTokens],
@@ -204,22 +206,10 @@ export class SessionMemoryController {
             toolCalls < state.lastObservedToolCalls) {
             throw new SessionMemoryStateError(`Session memory observed counters regressed (tokens ${tokens} < ${state.lastObservedTokens}, toolCalls ${toolCalls} < ${state.lastObservedToolCalls})`);
         }
-        this.observedTokens = Math.max(this.observedTokens, tokens);
-        this.observedToolCalls = Math.max(this.observedToolCalls, toolCalls);
-        if (!this.isExtractionDue(this.observedTokens, this.observedToolCalls)) {
-            return false;
-        }
-        if (this.inFlight === null) {
-            const extraction = this.runExtraction(this.observedTokens, this.observedToolCalls, messageId, messages);
-            this.inFlight = extraction;
-            extraction
-                .catch(() => undefined)
-                .finally(() => {
-                if (this.inFlight === extraction)
-                    this.inFlight = null;
-            });
-        }
-        return true;
+        // A direct absolute observation reports a natural break when no tool calls
+        // have accumulated since the last successful extraction.
+        const naturalBreak = toolCalls === state.lastObservedToolCalls;
+        return this.scheduleExtraction(tokens, toolCalls, messageId, messages, naturalBreak);
     }
     /**
      * Adds non-negative deltas to the current cumulative observed totals and
@@ -241,7 +231,32 @@ export class SessionMemoryController {
         }
         this.observedTokens += inputTokens;
         this.observedToolCalls += toolCalls;
-        return this.observe(this.observedTokens, this.observedToolCalls, messageId, messages);
+        // A zero-tool-call turn is a natural break: the last assistant turn made
+        // no tool calls.
+        return this.scheduleExtraction(this.observedTokens, this.observedToolCalls, messageId, messages, toolCalls === 0);
+    }
+    /**
+     * Records the observed totals and starts an extraction when the fixed
+     * eligibility contract is met. Returns true when an extraction is running or
+     * was just scheduled; callers on normal turns never await the extraction.
+     */
+    scheduleExtraction(tokens, toolCalls, messageId, messages, naturalBreak) {
+        this.observedTokens = Math.max(this.observedTokens, tokens);
+        this.observedToolCalls = Math.max(this.observedToolCalls, toolCalls);
+        if (!this.isExtractionDue(this.observedTokens, this.observedToolCalls, naturalBreak)) {
+            return false;
+        }
+        if (this.inFlight === null) {
+            const extraction = this.runExtraction(this.observedTokens, this.observedToolCalls, messageId, messages);
+            this.inFlight = extraction;
+            extraction
+                .catch(() => undefined)
+                .finally(() => {
+                if (this.inFlight === extraction)
+                    this.inFlight = null;
+            });
+        }
+        return true;
     }
     /** Safe snapshot of the loaded durable summary; empty when none exists. */
     async summary() {
@@ -256,15 +271,19 @@ export class SessionMemoryController {
         }
         return { ...this.stateValue };
     }
-    /** Resolves when no extraction is running; rejects on failure or timeout. */
+    /**
+     * Resolves when no extraction is running; rejects on extraction failure.
+     * Compact callers wait softly: if extraction outlives the bounded
+     * `waitTimeoutMs`, this resolves so compaction can proceed anyway.
+     */
     async waitForIdle() {
         await this.ensureLoaded();
         const extraction = this.inFlight;
         if (extraction === null)
             return;
         let timer;
-        const timeout = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new SessionMemoryTimeoutError(`Session memory extraction did not complete within ${this.waitTimeoutMs}ms`)), this.waitTimeoutMs);
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, this.waitTimeoutMs);
         });
         try {
             await Promise.race([extraction, timeout]);
@@ -307,7 +326,7 @@ export class SessionMemoryController {
                 ...state,
                 extractionStartedAt: null,
                 extractionCompletedAt: null,
-                extractionError: elapsed >= this.waitTimeoutMs
+                extractionError: elapsed >= STALE_EXTRACTION_THRESHOLD_MS
                     ? `Session memory extraction is stale after ${elapsed}ms`
                     : 'Session memory extraction was interrupted',
             };
@@ -321,14 +340,18 @@ export class SessionMemoryController {
         this.observedToolCalls = this.stateValue.lastObservedToolCalls;
         this.summaryValue = summary;
     }
-    isExtractionDue(tokens, toolCalls) {
+    isExtractionDue(tokens, toolCalls, naturalBreak) {
         const state = this.stateValue;
         if (state === null)
             return false;
         if (!state.initialized)
             return tokens >= this.initTokens;
-        return (tokens - state.lastObservedTokens >= this.updateTokens ||
-            toolCalls - state.lastObservedToolCalls >= this.updateToolCalls);
+        // Unchanged context must not retrigger; tool-call growth alone is never
+        // enough without at least the update-token growth.
+        if (tokens - state.lastObservedTokens < this.updateTokens)
+            return false;
+        return (toolCalls - state.lastObservedToolCalls >= this.updateToolCalls ||
+            naturalBreak);
     }
     async runExtraction(tokens, toolCalls, messageId, messages) {
         const state = this.stateValue;

package/dist/application/session-service.d.ts

@@ -161,6 +161,7 @@ export interface RewindPoint {
     fileRestoreAvailable: boolean;
 }
 export declare function workflowTokenTarget(prompt: string): number | null;
+export type HookSessionEndReason = 'clear' | 'resume' | 'other';
 export declare class ClaudeSessionService {
     private readonly options;
     private readonly schema;
@@ -182,6 +183,7 @@ export declare class ClaudeSessionService {
     private activeCostSessionId;
     private closeCostSavePromise;
     private readonly sessionMemoryControllers;
+    private readonly hookLifecycle;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
     nextScheduledPrompt(signal?: AbortSignal): Promise<ScheduledPrompt | null>;
@@ -198,6 +200,7 @@ export declare class ClaudeSessionService {
     stopTask(sessionId: string, taskId: string): Promise<void>;
     private applyPermissionUpdates;
     close(): Promise<void>;
+    transitionHookSession(sessionId: string, reason: Exclude<HookSessionEndReason, 'other'>): Promise<void>;
     createHostedToolRegistry(sessionId: string): ToolRegistry;
     run(prompt: string, signal?: AbortSignal, sessionId?: string, name?: string, images?: readonly ModelImage[], documents?: readonly ModelDocument[]): Promise<SessionRunResult>;
     runShell(command: string, signal?: AbortSignal, sessionId?: string, name?: string): Promise<SessionRunResult>;

package/dist/application/session-service.js

@@ -319,6 +319,116 @@ function validSessionName(value) {
         ? name.toLocaleLowerCase()
         : null;
 }
+const SESSION_END_HOOK_TIMEOUT_MS = 15_000;
+class HookLifecycle {
+    hooks;
+    eventSink;
+    sessions = new Map();
+    pendingSource;
+    constructor(hooks, eventSink) {
+        this.hooks = hooks;
+        this.eventSink = eventSink;
+    }
+    async start(sessionId, input, fallbackSource, signal) {
+        let state = this.sessions.get(sessionId);
+        if (state?.started)
+            return undefined;
+        if (state?.starting)
+            return state.starting;
+        state = {
+            input,
+            started: false,
+            starting: undefined,
+            ending: undefined,
+        };
+        this.sessions.set(sessionId, state);
+        const source = this.pendingSource ?? fallbackSource;
+        this.pendingSource = undefined;
+        state.starting = this.hooks?.run({ ...input, hook_event_name: 'SessionStart', source }, source, signal);
+        try {
+            const outcome = await state.starting;
+            state.started = true;
+            return outcome;
+        }
+        catch (error) {
+            this.sessions.delete(sessionId);
+            throw error;
+        }
+        finally {
+            state.starting = undefined;
+        }
+    }
+    async refresh(sessionId, input, signal) {
+        const state = this.sessions.get(sessionId);
+        if (state)
+            state.input = input;
+        return this.hooks?.run({ ...input, hook_event_name: 'SessionStart', source: 'compact' }, 'compact', signal);
+    }
+    async transition(sessionId, reason) {
+        await this.end(sessionId, reason);
+        this.pendingSource = reason;
+    }
+    async end(sessionId, reason) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return;
+        if (state.starting)
+            await state.starting;
+        if (!state.started)
+            return;
+        if (state.ending)
+            return state.ending;
+        state.ending = this.runEnd(state.input, reason).finally(() => {
+            this.sessions.delete(sessionId);
+        });
+        await state.ending;
+    }
+    async close() {
+        await Promise.all([...this.sessions.keys()].map((sessionId) => this.end(sessionId, 'other')));
+    }
+    async runEnd(input, reason) {
+        if (!this.hooks)
+            return;
+        const controller = new AbortController();
+        let timer;
+        try {
+            const timeout = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`timed out after ${SESSION_END_HOOK_TIMEOUT_MS}ms`));
+                }, SESSION_END_HOOK_TIMEOUT_MS);
+            });
+            const outcome = await Promise.race([
+                this.hooks.run({ ...input, hook_event_name: 'SessionEnd', reason }, reason, controller.signal),
+                timeout,
+            ]);
+            for (const execution of outcome.executions) {
+                if (execution.exitCode === 0)
+                    continue;
+                const detail = execution.stderr.trim() ||
+                    execution.stdout.trim() ||
+                    `exit code ${execution.exitCode}`;
+                this.warn(detail);
+            }
+            if (outcome.blockedReason && outcome.executions.at(-1)?.exitCode === 0) {
+                this.warn(outcome.blockedReason);
+            }
+        }
+        catch (error) {
+            this.warn(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    warn(detail) {
+        this.eventSink?.({
+            type: 'warning',
+            message: `SessionEnd hook failed: ${detail}`,
+        });
+    }
+}
 export class ClaudeSessionService {
     options;
     schema;
@@ -340,9 +450,11 @@ export class ClaudeSessionService {
     activeCostSessionId;
     closeCostSavePromise;
     sessionMemoryControllers = new Map();
+    hookLifecycle;
     runtimeCwd;
     constructor(options) {
         this.options = options;
+        this.hookLifecycle = new HookLifecycle(options.hooks, options.eventSink);
         this.runtimeCwd = options.workspace?.cwd() ?? options.cwd;
         this.schema = selectClaudeSchemaAdapter(options.claudeVersion);
         this.scheduledPrompts =
@@ -481,6 +593,7 @@ export class ClaudeSessionService {
         }
     }
     async close() {
+        await this.hookLifecycle.close();
         this.scheduledPrompts?.close();
         await Promise.all([...this.hostedSubagents].map((executor) => executor.close()));
         await Promise.resolve();
@@ -494,6 +607,9 @@ export class ClaudeSessionService {
         this.mcpClosePromise ??= this.options.mcp?.close?.() ?? Promise.resolve();
         await this.mcpClosePromise;
     }
+    async transitionHookSession(sessionId, reason) {
+        await this.hookLifecycle.transition(sessionId, reason);
+    }
     createHostedToolRegistry(sessionId) {
         const baseTools = this.options.tools;
         if (!baseTools)
@@ -755,7 +871,7 @@ export class ClaudeSessionService {
             ...(onDelta ? { onTextDelta: onDelta } : {}),
             onMetrics: (recorded) => this.recordAuxiliaryMetrics(activeSessionId, recorded),
         });
-        budget?.observeUsage(metrics.usage);
+        budget?.observeUsage(metrics.usage, messages);
         if (metrics.toolCalls.length > 0) {
             throw new Error('Side questions cannot call tools; press f to fork');
         }
@@ -2243,17 +2359,11 @@ export class ClaudeSessionService {
                     }
                 },
             };
+            let turnCompleted = false;
             try {
-                if (this.options.hooks) {
-                    const outcome = await this.options.hooks.run({
-                        ...hookSession,
-                        hook_event_name: 'SessionStart',
-                        source: requireExisting ? 'resume' : 'startup',
-                    }, requireExisting ? 'resume' : 'startup', signal);
+                const outcome = await this.hookLifecycle.start(sessionId, hookSession, requireExisting ? 'resume' : 'startup', signal);
+                if (outcome) {
                     await recordHookOutcome(outcome, pendingRecoveryToolCallIds.size > 0);
-                    if (outcome.blockedReason) {
-                        throw new Error(`SessionStart hook error: ${outcome.blockedReason}`);
-                    }
                 }
                 const approveRecovery = this.options.approveRecovery;
                 const recoveryRequest = {
@@ -2620,15 +2730,9 @@ export class ClaudeSessionService {
                     // runtime-only context so the next request retains current
                     // instructions, plan state, session memory, and hook context.
                     if (this.options.hooks) {
-                        const outcome = await this.options.hooks.run({
-                            ...hookSession,
-                            hook_event_name: 'SessionStart',
-                            source: 'compact',
-                        }, 'compact', signal);
-                        await recordHookOutcome(outcome);
-                        if (outcome.blockedReason) {
-                            throw new Error(`SessionStart hook error: ${outcome.blockedReason}`);
-                        }
+                        const outcome = await this.hookLifecycle.refresh(sessionId, hookSession, signal);
+                        if (outcome)
+                            await recordHookOutcome(outcome);
                     }
                     await refreshRuntimeContext();
                     this.options.eventSink?.({
@@ -2947,7 +3051,7 @@ export class ClaudeSessionService {
                     : undefined) ??
                     Object.values(result.modelUsage ?? {})[0] ??
                     result.usage;
-                budget?.observeUsage(observedUsage);
+                budget?.observeUsage(observedUsage, runtimeRequest.messages, definitions);
                 if (structuredCapture && structuredCapture.calls !== 1) {
                     throw new Error(`StructuredOutput must be called exactly once (received ${structuredCapture.calls})`);
                 }
@@ -3044,19 +3148,23 @@ export class ClaudeSessionService {
                 }
                 if (sessionMemory && finalLeafUuid) {
                     const turnInputTokens = result.usage?.inputTokens ?? 0;
+                    const warn = (error) => this.options.eventSink?.({
+                        type: 'warning',
+                        message: `Session memory extraction failed: ${error instanceof Error ? error.message : String(error)}`,
+                    });
                     try {
                         await sessionMemory.observeDelta(turnInputTokens, currentTurnToolCalls, finalLeafUuid, projectClaudeModelMessages(snapshot.entries));
-                        await sessionMemory.waitForIdle();
+                        // Normal turns schedule extraction without awaiting it; failures
+                        // surface as a warning while the sidecar stays retryable.
+                        sessionMemory.waitForIdle().catch(warn);
                     }
                     catch (error) {
-                        // A failed extraction must not fail the user turn; the sidecar
+                        // A failed observation must not fail the user turn; the sidecar
                         // retains a retryable error for the next observation.
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `Session memory extraction failed: ${error instanceof Error ? error.message : String(error)}`,
-                        });
+                        warn(error);
                     }
                 }
+                turnCompleted = true;
                 return {
                     sessionId,
                     text: structuredCapture && structuredCapture.calls === 1
@@ -3074,35 +3182,8 @@ export class ClaudeSessionService {
                 };
             }
             finally {
-                try {
-                    const outcome = await this.options.hooks?.run({
-                        ...hookSession,
-                        hook_event_name: 'SessionEnd',
-                        reason: 'other',
-                    }, 'other');
-                    const failedExecutions = outcome?.executions.filter((execution) => execution.exitCode !== 0) ?? [];
-                    for (const execution of failedExecutions) {
-                        const detail = execution.stderr.trim() ||
-                            execution.stdout.trim() ||
-                            `exit code ${execution.exitCode}`;
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `SessionEnd hook failed: ${detail}`,
-                        });
-                    }
-                    if (outcome?.blockedReason &&
-                        outcome.executions.at(-1)?.exitCode === 0) {
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `SessionEnd hook failed: ${outcome.blockedReason}`,
-                        });
-                    }
-                }
-                catch (error) {
-                    this.options.eventSink?.({
-                        type: 'warning',
-                        message: `SessionEnd hook failed: ${error instanceof Error ? error.message : String(error)}`,
-                    });
+                if (!turnCompleted) {
+                    await this.hookLifecycle.end(sessionId, 'other');
                 }
             }
         });
@@ -3774,6 +3855,10 @@ export class ClaudeSessionService {
         return new ContextBudget({
             contextWindowTokens,
             windowSource: 'capability',
+            onAccountingDiagnostic: (message) => this.options.eventSink?.({
+                type: 'warning',
+                message: `Context usage accounting: ${message}`,
+            }),
             ...(this.options.contextReserveTokens === undefined
                 ? {}
                 : { reserveTokens: this.options.contextReserveTokens }),

package/dist/application/subagent-service.js

@@ -1461,6 +1461,10 @@ export class ClaudeSubagentExecutor {
             const contextBudget = options.provider.capabilities.contextWindowTokens
                 ? new ContextBudget({
                     contextWindowTokens: options.provider.capabilities.contextWindowTokens,
+                    onAccountingDiagnostic: (message) => this.options.eventSink?.({
+                        type: 'warning',
+                        message: `Context usage accounting: ${message}`,
+                    }),
                     ...(this.options.contextReserveTokens === undefined
                         ? {}
                         : { reserveTokens: this.options.contextReserveTokens }),
@@ -1469,6 +1473,7 @@ export class ClaudeSubagentExecutor {
             const definitions = options.provider.capabilities.tools
                 ? runtimeTools.definitions()
                 : [];
+            let observedMessages;
             const assembleMessages = async () => {
                 const assembledContext = await this.options.contextAssembler?.assemble({
                     cwd,
@@ -1479,6 +1484,7 @@ export class ClaudeSubagentExecutor {
                     ...injectFirstUserMessageContext(projectClaudeModelMessages(snapshot.entries), assembledContext?.firstUserMessageContext),
                     ...preloadedSkills,
                 ];
+                observedMessages = messages;
                 if (contextBudget) {
                     contextBudget.assertFits(contextBudget.evaluate(messages, definitions));
                 }
@@ -1547,6 +1553,7 @@ export class ClaudeSubagentExecutor {
                     : {}),
                 ...(options.signal ? { signal: options.signal } : {}),
             });
+            contextBudget?.observeUsage(result.usage, observedMessages ?? [], definitions);
             this.options.eventSink?.({
                 type: 'task-progress',
                 taskId: options.agentId,

package/dist/cli/interactive.d.ts

@@ -72,6 +72,7 @@ interface InteractiveSessionCommands {
         id: string;
         prompt: string;
     } | null>;
+    transitionHookSession?(sessionId: string, reason: 'clear' | 'resume'): Promise<void>;
     close?(): Promise<void>;
 }
 export interface InteractiveServiceFactory {

package/dist/cli/interactive.js

@@ -3435,9 +3435,16 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
         if (selectingSession) {
             if (key.escape || value === '\u001B') {
                 if (pickerIncludesNewSessionRef.current && allowNewSession) {
-                    setSessionId(null);
-                    setPendingFork(false);
                     setSelectingSession(false);
+                    const previousSessionId = sessionIdRef.current;
+                    void (async () => {
+                        if (previousSessionId) {
+                            const commands = await service();
+                            await commands.transitionHookSession?.(previousSessionId, 'clear');
+                        }
+                        openSession(null);
+                        setPendingFork(false);
+                    })().catch(warn);
                 }
                 else if (allowNewSession) {
                     setSelectingSession(false);
@@ -3462,10 +3469,18 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 const selected = filterSessionChoices(currentPickerChoices, sessionSearchRef.current)[selectedIndexRef.current];
                 if (selected === undefined)
                     return;
-                openSession(selected?.sessionId ?? null);
-                if (!selected)
-                    setPendingFork(false);
                 setSelectingSession(false);
+                const nextSessionId = selected?.sessionId ?? null;
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId && previousSessionId !== nextSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, nextSessionId === null ? 'clear' : 'resume');
+                    }
+                    openSession(nextSessionId);
+                    if (!selected)
+                        setPendingFork(false);
+                })().catch(warn);
             }
             else if (key.backspace || key.delete) {
                 sessionSearchRef.current = sessionSearchRef.current.slice(0, -1);
@@ -5220,28 +5235,40 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 updateMenu({ kind: 'help', tabIndex: 0, selectedIndex: 0 });
             }
             else if (prompt === '/new') {
-                statusLineSessionId.current = randomUUID();
-                setSessionId(null);
-                setSessionColor(undefined);
-                setPendingFork(false);
-                append({ kind: 'notice', text: 'Started a new session.' });
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, 'clear');
+                    }
+                    statusLineSessionId.current = randomUUID();
+                    openSession(null);
+                    setPendingFork(false);
+                    append({ kind: 'notice', text: 'Started a new session.' });
+                })().catch(warn);
             }
             else if (prompt === '/clear') {
-                statusLineSessionId.current = randomUUID();
-                setSessionId(null);
-                setSessionColor(undefined);
-                setPendingFork(false);
-                setHistory([]);
-                setUsage(undefined);
-                setCostUsd(undefined);
-                streamingFrameRef.current?.resetText();
-                streamingFrameRef.current?.resetThinking();
-                streamingFrameRef.current?.flush();
-                setThinkingExpanded(false);
-                setStatus('ready');
-                inputHistoryRef.current = [];
-                inputHistoryIndexRef.current = null;
-                inputHistoryDraftRef.current = '';
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, 'clear');
+                    }
+                    statusLineSessionId.current = randomUUID();
+                    openSession(null);
+                    setPendingFork(false);
+                    setHistory([]);
+                    setUsage(undefined);
+                    setCostUsd(undefined);
+                    streamingFrameRef.current?.resetText();
+                    streamingFrameRef.current?.resetThinking();
+                    streamingFrameRef.current?.flush();
+                    setThinkingExpanded(false);
+                    setStatus('ready');
+                    inputHistoryRef.current = [];
+                    inputHistoryIndexRef.current = null;
+                    inputHistoryDraftRef.current = '';
+                })().catch(warn);
             }
             else if (prompt === '/model') {
                 updateMenu({ kind: 'model', selectedIndex: 0 });

package/dist/cli-runtime.js

@@ -1577,6 +1577,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             rename: (sessionId, name) => service.rename(sessionId, name),
             sessionNameSuggestion: (sessionId, signal) => service.sessionNameSuggestion(sessionId, signal),
             nextScheduledPrompt: (signal) => service.nextScheduledPrompt(signal),
+            transitionHookSession: (sessionId, reason) => service.transitionHookSession(sessionId, reason),
             close: async () => {
                 let failure;
                 try {

package/dist/compatibility/claude/fork.js

@@ -181,8 +181,10 @@ export function createClaudeNativeFork({ source, sourceSessionId, sessionId, res
             (metadata.direction === 'from' ||
                 metadata.direction === 'up_to'));
     });
+    const hasCompactHistory = source.some((entry) => entry.isCompactSummary === true ||
+        (entry.type === 'system' && entry.subtype === 'compact_boundary'));
     const activeSource = resumeSessionAt === undefined
-        ? hasSelectiveSummary
+        ? hasCompactHistory || hasSelectiveSummary
             ? selectClaudeActiveTranscript(source)
             : source
         : selectClaudeTranscriptAtMessage(source, resumeSessionAt);

package/dist/compatibility/claude/history.js

@@ -18,7 +18,11 @@ function latestLeafUuid(entries) {
             entry.isSidechain !== true);
         if (!hasNewDescendant)
             return summary.uuid;
-        break;
+        // After compaction the active leaf continues from the boundary's logical
+        // parent. Ignore unrelated physical entries that do not descend from the
+        // boundary and keep the compact summary as the leaf when none do.
+        const continuation = latestCompactBranchLeafUuid(entries, index + 1, boundary ? entryUuid(boundary) : null, summary.uuid);
+        return continuation === null ? summary.uuid : continuation;
     }
     for (let index = entries.length - 1; index >= 0; index -= 1) {
         const entry = entries[index];
@@ -33,6 +37,45 @@ function latestLeafUuid(entries) {
     }
     return null;
 }
+function latestCompactBranchLeafUuid(entries, fromIndex, boundaryUuid, summaryUuid) {
+    const byUuid = new Map();
+    for (const entry of entries) {
+        const uuid = entryUuid(entry);
+        if (uuid && entry.isSidechain !== true)
+            byUuid.set(uuid, entry);
+    }
+    for (let index = entries.length - 1; index >= fromIndex; index -= 1) {
+        const entry = entries[index];
+        if (!entry || entry.isSidechain === true)
+            continue;
+        const candidate = entry.type === 'last-prompt' && typeof entry.leafUuid === 'string'
+            ? entry.leafUuid
+            : entryUuid(entry);
+        if (candidate === null)
+            continue;
+        let uuid = candidate;
+        const seen = new Set();
+        while (uuid !== null) {
+            if (uuid === summaryUuid || uuid === boundaryUuid)
+                return candidate;
+            if (seen.has(uuid))
+                break;
+            seen.add(uuid);
+            const node = byUuid.get(uuid);
+            if (!node)
+                break;
+            uuid =
+                node.type === 'system' &&
+                    node.subtype === 'compact_boundary' &&
+                    typeof node.logicalParentUuid === 'string'
+                    ? node.logicalParentUuid
+                    : typeof node.parentUuid === 'string'
+                        ? node.parentUuid
+                        : null;
+        }
+    }
+    return null;
+}
 function ancestryUuids(entries, leafUuid) {
     const byUuid = new Map();
     for (const entry of entries) {
@@ -72,6 +115,9 @@ function selectAncestry(entries, leafUuid) {
         const uuid = entryUuid(entry);
         if (uuid) {
             return (active.has(uuid) ||
+                (entry.type === 'attachment' &&
+                    typeof entry.parentUuid === 'string' &&
+                    active.has(entry.parentUuid)) ||
                 (entry.type === 'user' &&
                     typeof entry.sourceToolAssistantUUID === 'string' &&
                     active.has(entry.sourceToolAssistantUUID)));

package/dist/core/context-budget.d.ts

@@ -5,6 +5,9 @@ export interface ContextBudgetOptions {
     /** Declares whether the configured window came from a provider capability so
      *  reports can distinguish provider-derived decisions from estimates. */
     windowSource?: 'capability' | 'estimate';
+    /** Receives at most one bounded diagnostic when provider accounting is
+     * malformed and the deterministic estimate fallback is used. */
+    onAccountingDiagnostic?: (message: string) => void;
 }
 export interface ContextBudgetEvaluateOptions {
     /** Most recent provider usage observation; a positive `contextWindow` is
@@ -18,6 +21,11 @@ export interface ContextBudgetEvaluateOptions {
 export type ContextBudgetSource = 'provider' | 'capability' | 'estimate';
 export interface ContextBudgetReport {
     estimatedTokens: number;
+    /** Total context occupancy used for overflow accounting: the actual provider
+     *  input/cache tokens at the observation watermark plus deterministic
+     *  estimated tokens added after that watermark. Without a usable watermark
+     *  this equals `estimatedTokens`. */
+    occupancyTokens: number;
     contextWindowTokens: number;
     reserveTokens: number;
     availableTokens: number;
@@ -37,10 +45,29 @@ export declare class ContextBudget {
     readonly reserveTokens: number;
     readonly windowSource: 'capability' | 'estimate';
     private observedUsage;
+    /** Actual provider input/cache tokens at the most recent usable observation;
+     *  the watermark that anchors later occupancy. */
+    private watermarkActualInputTokens;
+    /** Deterministic estimate of the request snapshot captured at observation
+     *  time; only growth beyond this baseline is added to the watermark. */
+    private watermarkBaselineEstimate;
+    private accountingDiagnosticEmitted;
+    private readonly onAccountingDiagnostic;
     constructor(options: ContextBudgetOptions);
-    observeUsage(usage: ModelUsage): void;
+    /** Record a completed provider request: `usage` carries the actual token
+     *  counts and `messages`/`tools` are the exact snapshot used for that
+     *  request. The snapshot's deterministic estimate becomes the watermark
+     *  baseline so later evaluations add only post-watermark growth. Malformed
+     *  usage is ignored (fail-open) and never throws; a valid `contextWindow`
+     *  still updates the effective window through `observedUsage`. */
+    observeUsage(usage: ModelUsage, messages?: readonly ModelMessage[], tools?: readonly ModelToolDefinition[]): void;
     effectiveContextWindow(usage?: ModelUsage): number;
     evaluate(messages: readonly ModelMessage[], tools?: readonly ModelToolDefinition[], options?: ContextBudgetEvaluateOptions): ContextBudgetReport;
+    /** Occupancy anchored at the actual input/cache watermark, adding only the
+     *  deterministic estimated growth past the observation baseline. Without a
+     *  usable watermark this is the plain estimate fallback. */
+    private anchoredOccupancyTokens;
+    private emitAccountingDiagnostic;
     assertFits(report: ContextBudgetReport): void;
     /** Returns the positive provider-reported context window, if any. */
     private providerContextWindow;

package/dist/core/context-budget.js

@@ -74,11 +74,38 @@ export function estimateModelRequestTokens(messages, tools = []) {
         estimateTextTokens(JSON.stringify(tool.inputSchema)), 0);
     return messageTokens + toolTokens;
 }
+/** Normalized provider input occupancy counting input and cache-read/creation
+ *  fields without output tokens. Returns `undefined` for malformed, negative,
+ *  or non-safe usage so accounting fails open. */
+function normalizedInputAndCacheTokens(usage) {
+    if (!Number.isSafeInteger(usage.inputTokens) ||
+        usage.inputTokens < 0 ||
+        (usage.cacheReadInputTokens !== undefined &&
+            (!Number.isSafeInteger(usage.cacheReadInputTokens) ||
+                usage.cacheReadInputTokens < 0)) ||
+        (usage.cacheCreationInputTokens !== undefined &&
+            (!Number.isSafeInteger(usage.cacheCreationInputTokens) ||
+                usage.cacheCreationInputTokens < 0))) {
+        return undefined;
+    }
+    const candidate = (usage.inputTokens ?? 0) +
+        (usage.cacheReadInputTokens ?? 0) +
+        (usage.cacheCreationInputTokens ?? 0);
+    return Number.isSafeInteger(candidate) ? candidate : undefined;
+}
 export class ContextBudget {
     contextWindowTokens;
     reserveTokens;
     windowSource;
     observedUsage;
+    /** Actual provider input/cache tokens at the most recent usable observation;
+     *  the watermark that anchors later occupancy. */
+    watermarkActualInputTokens;
+    /** Deterministic estimate of the request snapshot captured at observation
+     *  time; only growth beyond this baseline is added to the watermark. */
+    watermarkBaselineEstimate;
+    accountingDiagnosticEmitted = false;
+    onAccountingDiagnostic;
     constructor(options) {
         requirePositiveInteger(options.contextWindowTokens, 'Context window tokens');
         const defaultReserve = Math.min(8192, Math.max(1, Math.floor(options.contextWindowTokens / 10)));
@@ -90,15 +117,32 @@ export class ContextBudget {
         this.contextWindowTokens = options.contextWindowTokens;
         this.reserveTokens = reserveTokens;
         this.windowSource = options.windowSource ?? 'estimate';
+        this.onAccountingDiagnostic = options.onAccountingDiagnostic;
     }
-    observeUsage(usage) {
+    /** Record a completed provider request: `usage` carries the actual token
+     *  counts and `messages`/`tools` are the exact snapshot used for that
+     *  request. The snapshot's deterministic estimate becomes the watermark
+     *  baseline so later evaluations add only post-watermark growth. Malformed
+     *  usage is ignored (fail-open) and never throws; a valid `contextWindow`
+     *  still updates the effective window through `observedUsage`. */
+    observeUsage(usage, messages = [], tools = []) {
         this.observedUsage = usage;
+        const actualInputTokens = normalizedInputAndCacheTokens(usage);
+        if (actualInputTokens === undefined) {
+            this.emitAccountingDiagnostic();
+            return;
+        }
+        if (messages.length === 0 && tools.length === 0)
+            return;
+        this.watermarkActualInputTokens = actualInputTokens;
+        this.watermarkBaselineEstimate = estimateModelRequestTokens(messages, tools);
     }
     effectiveContextWindow(usage) {
         return this.providerContextWindow(usage) ?? this.contextWindowTokens;
     }
     evaluate(messages, tools = [], options = {}) {
         const estimatedTokens = estimateModelRequestTokens(messages, tools);
+        const occupancyTokens = this.anchoredOccupancyTokens(estimatedTokens);
         const providerWindow = this.providerContextWindow(options.lastUsage);
         const contextWindowTokens = providerWindow ?? this.contextWindowTokens;
         const outputTokens = options.outputTokens !== undefined &&
@@ -107,10 +151,11 @@ export class ContextBudget {
             ? options.outputTokens
             : 0;
         const availableTokens = Math.max(0, contextWindowTokens - this.reserveTokens);
-        const overflowTokens = Math.max(0, estimatedTokens + outputTokens - availableTokens);
+        const overflowTokens = Math.max(0, occupancyTokens + outputTokens - availableTokens);
         const shouldCompact = options.promptTooLong === true || overflowTokens > 0;
         return {
             estimatedTokens,
+            occupancyTokens,
             contextWindowTokens,
             reserveTokens: this.reserveTokens,
             availableTokens,
@@ -119,6 +164,29 @@ export class ContextBudget {
             source: providerWindow === undefined ? this.windowSource : 'provider',
         };
     }
+    /** Occupancy anchored at the actual input/cache watermark, adding only the
+     *  deterministic estimated growth past the observation baseline. Without a
+     *  usable watermark this is the plain estimate fallback. */
+    anchoredOccupancyTokens(estimatedTokens) {
+        if (this.watermarkActualInputTokens === undefined ||
+            this.watermarkBaselineEstimate === undefined) {
+            return estimatedTokens;
+        }
+        const growthAfterWatermark = Math.max(0, estimatedTokens - this.watermarkBaselineEstimate);
+        return this.watermarkActualInputTokens + growthAfterWatermark;
+    }
+    emitAccountingDiagnostic() {
+        if (this.accountingDiagnosticEmitted)
+            return;
+        this.accountingDiagnosticEmitted = true;
+        try {
+            this.onAccountingDiagnostic?.('Provider input usage was malformed; using deterministic context estimates.');
+        }
+        catch {
+            // Diagnostics are strictly best-effort. A broken sink must never turn
+            // fail-open accounting into a healthy-turn failure.
+        }
+    }
     assertFits(report) {
         if (report.shouldCompact)
             throw new ContextOverflowError(report);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",