praxis-agent 0.25.0 → 0.27.0

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

@@ -1,9 +1,14 @@
-import type { ModelMessage } from '../core/runtime.js';
+import { type ModelMessage } from '../core/runtime.js';
 /** Versioned, explicit progress state for one session's extracted memory. */
 export interface SessionMemoryState {
     schemaVersion: 1;
     initialized: boolean;
     lastObservedTokens: number;
+    /** Current-context growth baseline after a durable compaction reduction. */
+    growthBaselineTokens?: number;
+    /** Latest extraction attempt occupancy, successful or failed. Older
+     * sidecars omit it and fall back to the successful watermark. */
+    lastAttemptedTokens?: number;
     lastObservedToolCalls: number;
     lastSummarizedMessageId: string | null;
     extractionStartedAt: number | null;
@@ -19,6 +24,10 @@ export declare class SessionMemoryTimeoutError extends Error {
     constructor(message: string);
 }
 export declare function createFreshSessionMemoryState(): SessionMemoryState;
+export interface SessionMemorySnapshot {
+    state: SessionMemoryState;
+    summary: string;
+}
 export interface SessionMemoryStoreOptions {
     configRoot: string;
     sessionId: string;
@@ -35,13 +44,23 @@ export interface SessionMemoryStoreOptions {
  */
 export declare class SessionMemoryStore {
     private readonly directory;
+    private readonly artifactsDirectory;
     private readonly stateFile;
     private readonly summaryFile;
     constructor(options: SessionMemoryStoreOptions);
     load(): Promise<SessionMemoryState>;
+    /** Reads the pointer record once, then resolves exactly the artifact named
+     *  by that record. Concurrent commits cannot pair an old watermark with a
+     *  newer summary. */
+    loadSnapshot(): Promise<SessionMemorySnapshot>;
+    private loadRecord;
     loadSummary(): Promise<string>;
+    private loadSummaryForRecord;
     writeSummary(summary: string): Promise<void>;
-    writeState(state: SessionMemoryState): Promise<void>;
+    writeState(state: SessionMemoryState, summaryFile?: string): Promise<void>;
+    /** Writes an immutable summary artifact, then atomically commits its pointer
+     *  with the progress watermark. summary.md is a best-effort readable mirror. */
+    commitExtraction(state: SessionMemoryState, summary: string): Promise<void>;
     clear(): Promise<void>;
 }
 export interface SessionMemoryExtractorInput {
@@ -49,15 +68,18 @@ export interface SessionMemoryExtractorInput {
     tokens: number;
     toolCalls: number;
     messages?: readonly ModelMessage[];
+    signal: AbortSignal;
 }
 export type SessionMemoryExtractor = (input: SessionMemoryExtractorInput) => Promise<string> | string;
 export interface SessionMemoryControllerOptions {
     store: SessionMemoryStore;
     extractor: SessionMemoryExtractor;
+    onExtractionError?: (error: unknown) => void;
     initTokens?: number;
     updateTokens?: number;
     updateToolCalls?: number;
     waitTimeoutMs?: number;
+    staleExtractionMs?: number;
 }
 /**
  * Serialized extraction lifecycle for one session. Concurrent callers of
@@ -71,20 +93,23 @@ export declare class SessionMemoryController {
     private readonly updateTokens;
     private readonly updateToolCalls;
     private readonly waitTimeoutMs;
+    private readonly staleExtractionMs;
     private stateValue;
     private summaryValue;
     private inFlight;
+    private extractionController;
     private loading;
     private observedTokens;
+    private tokenBaseline;
+    private attemptTokenBaseline;
     private observedToolCalls;
+    private closed;
     constructor(options: SessionMemoryControllerOptions);
     observe(tokens: number, toolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
-    /**
-     * Adds non-negative deltas to the current cumulative observed totals and
-     * delegates to the serialized extraction path with those cumulative totals.
-     * The persisted counters only advance once an extraction succeeds.
-     */
-    observeDelta(inputTokens: number, toolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
+    /** Observes the current provider-visible context occupancy and a per-turn
+     *  tool-call delta. Unlike provider input-token deltas, occupancy may shrink
+     *  after compaction; that establishes a new growth baseline. */
+    observeContext(currentTokens: number, turnToolCalls: 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
@@ -97,14 +122,22 @@ export declare class SessionMemoryController {
     state(): Promise<SessionMemoryState>;
     /**
      * 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.
+     * Normal turns do not await this diagnostic seam.
      */
     waitForIdle(): Promise<void>;
+    /** Compact consumes only the last committed artifact. It waits softly for a
+     *  useful extraction, swallows retryable failures, and cancels stale work. */
+    waitForCompact(): Promise<void>;
+    /** Cancels owned extraction work and waits only for the configured bounded
+     *  interval. A provider that ignores AbortSignal cannot hold service close. */
+    close(): Promise<void>;
     clear(): Promise<void>;
     private ensureLoaded;
     private loadState;
     private isExtractionDue;
     private runExtraction;
+    private assertOpen;
+    private rebaseAfterContextReduction;
+    private waitBoundedly;
 }
 //# sourceMappingURL=session-memory.d.ts.map

package/dist/application/session-memory.js

@@ -1,5 +1,7 @@
+import { createHash } from 'node:crypto';
 import { readFile, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { AgentRunCancelledError } from '../core/runtime.js';
 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. */
@@ -21,6 +23,8 @@ export function createFreshSessionMemoryState() {
         schemaVersion: 1,
         initialized: false,
         lastObservedTokens: 0,
+        growthBaselineTokens: 0,
+        lastAttemptedTokens: 0,
         lastObservedToolCalls: 0,
         lastSummarizedMessageId: null,
         extractionStartedAt: null,
@@ -49,6 +53,14 @@ function assertValidSessionMemoryState(value) {
     if (!isNonNegativeSafeInteger(record.lastObservedTokens)) {
         throw new SessionMemoryStateError('Session memory state lastObservedTokens must be a non-negative safe integer');
     }
+    if (record.growthBaselineTokens !== undefined &&
+        !isNonNegativeSafeInteger(record.growthBaselineTokens)) {
+        throw new SessionMemoryStateError('Session memory state growthBaselineTokens must be a non-negative safe integer when present');
+    }
+    if (record.lastAttemptedTokens !== undefined &&
+        !isNonNegativeSafeInteger(record.lastAttemptedTokens)) {
+        throw new SessionMemoryStateError('Session memory state lastAttemptedTokens must be a non-negative safe integer when present');
+    }
     if (!isNonNegativeSafeInteger(record.lastObservedToolCalls)) {
         throw new SessionMemoryStateError('Session memory state lastObservedToolCalls must be a non-negative safe integer');
     }
@@ -67,6 +79,7 @@ function assertValidSessionMemoryState(value) {
         throw new SessionMemoryStateError('Session memory state extractionError must be a string or null');
     }
 }
+const SESSION_MEMORY_ARTIFACT_PATTERN = /^artifacts\/[a-f0-9]{64}\.md$/u;
 function parseSessionMemoryState(source) {
     let value;
     try {
@@ -76,7 +89,34 @@ function parseSessionMemoryState(source) {
         throw new SessionMemoryStateError('Session memory state is not valid JSON');
     }
     assertValidSessionMemoryState(value);
-    return value;
+    const record = value;
+    if (record.summaryFile !== undefined &&
+        (typeof record.summaryFile !== 'string' ||
+            !SESSION_MEMORY_ARTIFACT_PATTERN.test(record.summaryFile))) {
+        throw new SessionMemoryStateError('Session memory state summaryFile must be a safe artifact path when present');
+    }
+    const state = {
+        schemaVersion: record.schemaVersion,
+        initialized: record.initialized,
+        lastObservedTokens: record.lastObservedTokens,
+        ...(record.growthBaselineTokens === undefined
+            ? {}
+            : { growthBaselineTokens: record.growthBaselineTokens }),
+        ...(record.lastAttemptedTokens === undefined
+            ? {}
+            : { lastAttemptedTokens: record.lastAttemptedTokens }),
+        lastObservedToolCalls: record.lastObservedToolCalls,
+        lastSummarizedMessageId: record.lastSummarizedMessageId,
+        extractionStartedAt: record.extractionStartedAt,
+        extractionCompletedAt: record.extractionCompletedAt,
+        extractionError: record.extractionError,
+    };
+    return {
+        state,
+        ...(typeof record.summaryFile === 'string'
+            ? { summaryFile: record.summaryFile }
+            : {}),
+    };
 }
 /**
  * Durable sidecar for one session's extracted memory. Claude compatibility
@@ -89,6 +129,7 @@ function parseSessionMemoryState(source) {
  */
 export class SessionMemoryStore {
     directory;
+    artifactsDirectory;
     stateFile;
     summaryFile;
     constructor(options) {
@@ -102,21 +143,50 @@ export class SessionMemoryStore {
         this.directory = resolve(options.sidecarRoot ?? resolve(options.configRoot, 'praxis'), 'session-memory', options.sessionId);
         this.stateFile = join(this.directory, 'state.json');
         this.summaryFile = join(this.directory, 'summary.md');
+        this.artifactsDirectory = join(this.directory, 'artifacts');
     }
     async load() {
+        return (await this.loadRecord()).state;
+    }
+    /** Reads the pointer record once, then resolves exactly the artifact named
+     *  by that record. Concurrent commits cannot pair an old watermark with a
+     *  newer summary. */
+    async loadSnapshot() {
+        const record = await this.loadRecord();
+        return {
+            state: record.state,
+            summary: await this.loadSummaryForRecord(record),
+        };
+    }
+    async loadRecord() {
         let source;
         try {
             source = await readFile(this.stateFile, 'utf8');
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                return createFreshSessionMemoryState();
+                return { state: createFreshSessionMemoryState() };
             }
             throw error;
         }
         return parseSessionMemoryState(source);
     }
     async loadSummary() {
+        const record = await this.loadRecord();
+        return this.loadSummaryForRecord(record);
+    }
+    async loadSummaryForRecord(record) {
+        if (record.summaryFile !== undefined) {
+            try {
+                return await readFile(join(this.directory, record.summaryFile), 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    throw new SessionMemoryStateError(`Session memory summary artifact is missing: ${record.summaryFile}`);
+                }
+                throw error;
+            }
+        }
         let source;
         try {
             source = await readFile(this.summaryFile, 'utf8');
@@ -134,19 +204,59 @@ export class SessionMemoryStore {
         }
         await writeFileAtomically(this.summaryFile, summary);
     }
-    async writeState(state) {
+    async writeState(state, summaryFile) {
         assertValidSessionMemoryState(state);
-        const existing = await this.load();
-        if (state.lastObservedTokens < existing.lastObservedTokens ||
-            state.lastObservedToolCalls < existing.lastObservedToolCalls) {
-            throw new SessionMemoryStateError('Session memory observed counters must be monotonic');
+        if (summaryFile !== undefined &&
+            !SESSION_MEMORY_ARTIFACT_PATTERN.test(summaryFile)) {
+            throw new SessionMemoryStateError('Session memory summaryFile must be a safe artifact path');
         }
-        await writeFileAtomically(this.stateFile, `${JSON.stringify(state, null, 2)}\n`);
+        const existing = await this.loadRecord();
+        if (state.lastObservedToolCalls < existing.state.lastObservedToolCalls) {
+            throw new SessionMemoryStateError('Session memory observed tool-call counter must be monotonic');
+        }
+        await writeFileAtomically(this.stateFile, `${JSON.stringify({
+            ...state,
+            ...(summaryFile !== undefined
+                ? { summaryFile }
+                : existing.summaryFile !== undefined
+                    ? { summaryFile: existing.summaryFile }
+                    : {}),
+        }, null, 2)}\n`);
+    }
+    /** Writes an immutable summary artifact, then atomically commits its pointer
+     *  with the progress watermark. summary.md is a best-effort readable mirror. */
+    async commitExtraction(state, summary) {
+        if (typeof summary !== 'string' || summary.trim().length === 0) {
+            throw new SessionMemoryStateError('Session memory summary must be a non-empty string');
+        }
+        const existing = await this.loadRecord();
+        const digest = createHash('sha256')
+            .update(state.lastSummarizedMessageId ?? '')
+            .update('\0')
+            .update(summary)
+            .digest('hex');
+        const summaryFile = `artifacts/${digest}.md`;
+        const artifact = join(this.directory, summaryFile);
+        await writeFileAtomically(artifact, summary);
+        try {
+            await this.writeState(state, summaryFile);
+        }
+        catch (error) {
+            if (existing.summaryFile !== summaryFile) {
+                await rm(artifact, { force: true }).catch(() => undefined);
+            }
+            throw error;
+        }
+        await this.writeSummary(summary).catch(() => undefined);
+        // Superseded artifacts remain immutable and readable for any concurrent
+        // reader that loaded their pointer before this commit. clear() performs
+        // lifecycle-safe reclamation after the controller is idle.
     }
     async clear() {
         await Promise.all([
             rm(this.stateFile, { force: true }),
             rm(this.summaryFile, { force: true }),
+            rm(this.artifactsDirectory, { recursive: true, force: true }),
         ]);
     }
 }
@@ -162,18 +272,25 @@ export class SessionMemoryController {
     updateTokens;
     updateToolCalls;
     waitTimeoutMs;
+    staleExtractionMs;
     stateValue = null;
     summaryValue = '';
     inFlight = null;
+    extractionController = null;
     loading = null;
     observedTokens = 0;
+    tokenBaseline = 0;
+    attemptTokenBaseline = 0;
     observedToolCalls = 0;
+    closed = false;
     constructor(options) {
         this.options = options;
         this.initTokens = options.initTokens ?? 10_000;
         this.updateTokens = options.updateTokens ?? 5_000;
         this.updateToolCalls = options.updateToolCalls ?? 3;
         this.waitTimeoutMs = options.waitTimeoutMs ?? 15_000;
+        this.staleExtractionMs =
+            options.staleExtractionMs ?? STALE_EXTRACTION_THRESHOLD_MS;
         for (const [name, value] of [
             ['initTokens', this.initTokens],
             ['updateTokens', this.updateTokens],
@@ -188,9 +305,16 @@ export class SessionMemoryController {
             this.waitTimeoutMs <= 0) {
             throw new SessionMemoryStateError('Session memory waitTimeoutMs must be a positive number');
         }
+        if (typeof this.staleExtractionMs !== 'number' ||
+            !Number.isFinite(this.staleExtractionMs) ||
+            this.staleExtractionMs <= 0) {
+            throw new SessionMemoryStateError('Session memory staleExtractionMs must be a positive number');
+        }
     }
     async observe(tokens, toolCalls, messageId, messages) {
+        const messageSnapshot = cloneMessages(messages);
         await this.ensureLoaded();
+        this.assertOpen();
         const state = this.stateValue;
         if (state === null) {
             throw new SessionMemoryStateError('Session memory state is unavailable');
@@ -202,38 +326,32 @@ export class SessionMemoryController {
         if (typeof messageId !== 'string' || messageId.length === 0) {
             throw new SessionMemoryStateError('Session memory message ID must be a non-empty string');
         }
-        if (tokens < state.lastObservedTokens ||
-            toolCalls < state.lastObservedToolCalls) {
-            throw new SessionMemoryStateError(`Session memory observed counters regressed (tokens ${tokens} < ${state.lastObservedTokens}, toolCalls ${toolCalls} < ${state.lastObservedToolCalls})`);
+        if (toolCalls < state.lastObservedToolCalls) {
+            throw new SessionMemoryStateError(`Session memory observed tool-call counter regressed (${toolCalls} < ${state.lastObservedToolCalls})`);
         }
+        await this.rebaseAfterContextReduction(tokens);
         // 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);
+        return this.scheduleExtraction(tokens, toolCalls, messageId, messageSnapshot, naturalBreak);
     }
-    /**
-     * Adds non-negative deltas to the current cumulative observed totals and
-     * delegates to the serialized extraction path with those cumulative totals.
-     * The persisted counters only advance once an extraction succeeds.
-     */
-    async observeDelta(inputTokens, toolCalls, messageId, messages) {
+    /** Observes the current provider-visible context occupancy and a per-turn
+     *  tool-call delta. Unlike provider input-token deltas, occupancy may shrink
+     *  after compaction; that establishes a new growth baseline. */
+    async observeContext(currentTokens, turnToolCalls, messageId, messages) {
+        const messageSnapshot = cloneMessages(messages);
         await this.ensureLoaded();
-        const state = this.stateValue;
-        if (state === null) {
-            throw new SessionMemoryStateError('Session memory state is unavailable');
-        }
-        if (!isNonNegativeSafeInteger(inputTokens) ||
-            !isNonNegativeSafeInteger(toolCalls)) {
-            throw new SessionMemoryStateError('Session memory observed deltas must be non-negative safe integers');
+        this.assertOpen();
+        if (!isNonNegativeSafeInteger(currentTokens) ||
+            !isNonNegativeSafeInteger(turnToolCalls)) {
+            throw new SessionMemoryStateError('Session memory context occupancy and tool-call delta must be non-negative safe integers');
         }
         if (typeof messageId !== 'string' || messageId.length === 0) {
             throw new SessionMemoryStateError('Session memory message ID must be a non-empty string');
         }
-        this.observedTokens += inputTokens;
-        this.observedToolCalls += toolCalls;
-        // 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);
+        await this.rebaseAfterContextReduction(currentTokens);
+        this.observedToolCalls += turnToolCalls;
+        return this.scheduleExtraction(currentTokens, this.observedToolCalls, messageId, messageSnapshot, turnToolCalls === 0);
     }
     /**
      * Records the observed totals and starts an extraction when the fixed
@@ -241,19 +359,23 @@ export class SessionMemoryController {
      * 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.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);
+            const controller = new AbortController();
+            this.extractionController = controller;
+            const extraction = this.runExtraction(this.observedTokens, this.observedToolCalls, messageId, messages, controller.signal);
             this.inFlight = extraction;
             extraction
                 .catch(() => undefined)
                 .finally(() => {
-                if (this.inFlight === extraction)
+                if (this.inFlight === extraction) {
                     this.inFlight = null;
+                    this.extractionController = null;
+                }
             });
         }
         return true;
@@ -273,25 +395,45 @@ export class SessionMemoryController {
     }
     /**
      * 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.
+     * Normal turns do not await this diagnostic seam.
      */
     async waitForIdle() {
         await this.ensureLoaded();
         const extraction = this.inFlight;
         if (extraction === null)
             return;
-        let timer;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(resolve, this.waitTimeoutMs);
-        });
-        try {
-            await Promise.race([extraction, timeout]);
-        }
-        finally {
-            if (timer !== undefined)
-                clearTimeout(timer);
+        await extraction;
+    }
+    /** Compact consumes only the last committed artifact. It waits softly for a
+     *  useful extraction, swallows retryable failures, and cancels stale work. */
+    async waitForCompact() {
+        await this.ensureLoaded();
+        const extraction = this.inFlight;
+        if (extraction === null)
+            return;
+        const startedAt = this.stateValue?.extractionStartedAt;
+        if (startedAt !== null &&
+            startedAt !== undefined &&
+            Date.now() - startedAt >= this.staleExtractionMs) {
+            this.extractionController?.abort();
+            // Stale work is no longer useful to compact. The extraction owns its
+            // eventual retryable error commit and cannot commit a summary after the
+            // aborted signal is observed.
+            return;
         }
+        const completed = await this.waitBoundedly(extraction, true);
+        if (!completed)
+            this.extractionController?.abort();
+    }
+    /** Cancels owned extraction work and waits only for the configured bounded
+     *  interval. A provider that ignores AbortSignal cannot hold service close. */
+    async close() {
+        this.closed = true;
+        const extraction = this.inFlight;
+        this.extractionController?.abort();
+        if (extraction === null)
+            return;
+        await this.waitBoundedly(extraction, true);
     }
     async clear() {
         await this.ensureLoaded();
@@ -302,6 +444,8 @@ export class SessionMemoryController {
         const fresh = createFreshSessionMemoryState();
         this.stateValue = fresh;
         this.observedTokens = fresh.lastObservedTokens;
+        this.tokenBaseline = fresh.lastObservedTokens;
+        this.attemptTokenBaseline = fresh.lastObservedTokens;
         this.observedToolCalls = fresh.lastObservedToolCalls;
         this.summaryValue = '';
     }
@@ -315,10 +459,7 @@ export class SessionMemoryController {
         return this.loading;
     }
     async loadState() {
-        const [state, summary] = await Promise.all([
-            this.options.store.load(),
-            this.options.store.loadSummary(),
-        ]);
+        const { state, summary } = await this.options.store.loadSnapshot();
         if (state.extractionStartedAt !== null &&
             state.extractionCompletedAt === null) {
             const elapsed = Date.now() - state.extractionStartedAt;
@@ -326,7 +467,7 @@ export class SessionMemoryController {
                 ...state,
                 extractionStartedAt: null,
                 extractionCompletedAt: null,
-                extractionError: elapsed >= STALE_EXTRACTION_THRESHOLD_MS
+                extractionError: elapsed >= this.staleExtractionMs
                     ? `Session memory extraction is stale after ${elapsed}ms`
                     : 'Session memory extraction was interrupted',
             };
@@ -337,6 +478,10 @@ export class SessionMemoryController {
             this.stateValue = state;
         }
         this.observedTokens = this.stateValue.lastObservedTokens;
+        this.tokenBaseline =
+            this.stateValue.growthBaselineTokens ?? this.stateValue.lastObservedTokens;
+        this.attemptTokenBaseline =
+            this.stateValue.lastAttemptedTokens ?? this.stateValue.lastObservedTokens;
         this.observedToolCalls = this.stateValue.lastObservedToolCalls;
         this.summaryValue = summary;
     }
@@ -344,57 +489,68 @@ export class SessionMemoryController {
         const state = this.stateValue;
         if (state === null)
             return false;
-        if (!state.initialized)
-            return tokens >= this.initTokens;
+        if (!state.initialized) {
+            return tokens >= this.initTokens && tokens > this.attemptTokenBaseline;
+        }
         // 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)
+        if (tokens - this.tokenBaseline < this.updateTokens ||
+            tokens <= this.attemptTokenBaseline) {
             return false;
+        }
         return (toolCalls - state.lastObservedToolCalls >= this.updateToolCalls ||
             naturalBreak);
     }
-    async runExtraction(tokens, toolCalls, messageId, messages) {
+    async runExtraction(tokens, toolCalls, messageId, messages, signal) {
         const state = this.stateValue;
         if (state === null) {
             throw new SessionMemoryStateError('Session memory state is unavailable');
         }
-        this.stateValue = {
+        const started = {
             ...state,
+            lastAttemptedTokens: tokens,
             extractionStartedAt: Date.now(),
             extractionCompletedAt: null,
             extractionError: null,
         };
-        await this.options.store.writeState(this.stateValue);
+        this.attemptTokenBaseline = tokens;
         try {
+            await this.options.store.writeState(started);
+            this.stateValue = started;
+            if (signal?.aborted || this.closed)
+                throw new AgentRunCancelledError();
             const summary = await this.options.extractor({
                 summary: this.summaryValue,
                 tokens,
                 toolCalls,
                 ...(messages?.length ? { messages } : {}),
+                signal: signal ?? new AbortController().signal,
             });
+            if (signal?.aborted || this.closed)
+                throw new AgentRunCancelledError();
             if (typeof summary !== 'string' || summary.trim().length === 0) {
                 throw new SessionMemoryStateError('Session memory extractor returned an empty summary');
             }
-            // Persist the summary before the completed state so a crash in between
-            // is recovered as a stale extraction and safely re-extracted.
-            await this.options.store.writeSummary(summary);
-            this.stateValue = {
+            const completed = {
                 ...this.stateValue,
                 initialized: true,
                 lastObservedTokens: tokens,
+                growthBaselineTokens: tokens,
                 lastObservedToolCalls: toolCalls,
                 lastSummarizedMessageId: messageId,
                 extractionStartedAt: null,
                 extractionCompletedAt: Date.now(),
                 extractionError: null,
             };
-            await this.options.store.writeState(this.stateValue);
+            await this.options.store.commitExtraction(completed, summary);
+            this.stateValue = completed;
+            this.tokenBaseline = tokens;
             this.summaryValue = summary;
         }
         catch (error) {
             const failure = error instanceof Error ? error.message : String(error);
             this.stateValue = {
-                ...this.stateValue,
+                ...started,
                 extractionStartedAt: null,
                 extractionCompletedAt: null,
                 extractionError: failure,
@@ -402,8 +558,53 @@ export class SessionMemoryController {
             await this.options.store
                 .writeState(this.stateValue)
                 .catch(() => undefined);
+            try {
+                this.options.onExtractionError?.(error);
+            }
+            catch {
+                // Operational warning sinks cannot change extraction lifecycle state.
+            }
             throw error;
         }
     }
+    assertOpen() {
+        if (this.closed) {
+            throw new SessionMemoryStateError('Session memory controller is closed');
+        }
+    }
+    async rebaseAfterContextReduction(tokens) {
+        if (tokens >= this.tokenBaseline && tokens >= this.attemptTokenBaseline) {
+            return;
+        }
+        this.tokenBaseline = Math.min(this.tokenBaseline, tokens);
+        this.attemptTokenBaseline = Math.min(this.attemptTokenBaseline, tokens);
+        if (this.stateValue === null)
+            return;
+        this.stateValue = {
+            ...this.stateValue,
+            growthBaselineTokens: this.tokenBaseline,
+            lastAttemptedTokens: this.attemptTokenBaseline,
+        };
+        await this.options.store.writeState(this.stateValue);
+    }
+    async waitBoundedly(extraction, ignoreFailure) {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), this.waitTimeoutMs);
+        });
+        try {
+            return await Promise.race([
+                (ignoreFailure ? extraction.catch(() => undefined) : extraction).then(() => true),
+                timeout,
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+}
+function cloneMessages(messages) {
+    return messages === undefined ? undefined : structuredClone(messages);
 }
 //# sourceMappingURL=session-memory.js.map

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

@@ -3,6 +3,7 @@ import type { ClaudeConditionalRuleResolver } from '../compatibility/claude/cont
 import { type DataPlane } from '../persistence/data-plane.js';
 import { type ClaudeFileResource, type ClaudeFileResourceConfig } from '../compatibility/claude/file-resources.js';
 import { type ClaudeDisplayTranscriptItem } from '../compatibility/claude/projection.js';
+import { type ClaudeTranscriptEntry } from '../compatibility/claude/schema.js';
 import { type ModelDocument, type ModelImage, type ModelToolCall, type ModelProvider, type ModelUsage, type PermissionApproval, type PermissionDecision, type PermissionResolver, type PermissionUpdate, type RuntimeEventSink, type ToolRegistry } from '../core/runtime.js';
 import { type BackgroundTaskSnapshot } from './background-task-runtime.js';
 import type { ModelPricingRegistry } from '../core/usage.js';
@@ -57,6 +58,9 @@ export interface ClaudeSessionServiceOptions {
     enableWorkflows?: boolean;
     providerForModel?: (model: string) => ModelProvider;
     providerForMainModel?: (model: string) => ModelProvider;
+    /** Creates a provider adapter dedicated to Session memory requests so
+     *  adapter-local cache and retry state are not shared with the foreground. */
+    sessionMemoryProviderFactory?: () => ModelProvider;
     explicitModel?: boolean;
     explicitSystemPrompt?: boolean;
     agentInitialPromptHandledExternally?: boolean;
@@ -71,9 +75,8 @@ export interface ClaudeSessionServiceOptions {
     brief?: boolean;
     collectMetrics?: boolean;
     sessionPersistence?: boolean;
-    /** Enable durable per-session memory extraction and injection. Defaults to
-     *  enabled whenever session persistence is enabled; ignored when
-     *  `sessionPersistence === false`. */
+    /** Enable durable per-session memory extraction and injection. It runs only
+     *  when persistence and an isolated provider factory are available. */
     enableSessionMemory?: boolean;
     sessionKind?: 'bg';
     workspace?: WorkspaceContext;
@@ -161,6 +164,9 @@ export interface RewindPoint {
     fileRestoreAvailable: boolean;
 }
 export declare function workflowTokenTarget(prompt: string): number | null;
+/** Walks back from the active tail to the inclusive start of the recent suffix
+ *  retained verbatim, then completes sibling adjacency at the boundary. */
+export declare function memoryPreservedSuffixStart(activeEntries: readonly ClaudeTranscriptEntry[]): number;
 export type HookSessionEndReason = 'clear' | 'resume' | 'other';
 export declare class ClaudeSessionService {
     private readonly options;
@@ -183,6 +189,7 @@ export declare class ClaudeSessionService {
     private activeCostSessionId;
     private closeCostSavePromise;
     private readonly sessionMemoryControllers;
+    private resolvedSessionMemoryProvider;
     private readonly hookLifecycle;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
@@ -244,6 +251,13 @@ export declare class ClaudeSessionService {
     private sessionNameEntries;
     private hasSessionName;
     private sessionName;
+    /** Conservative selective-preservation seam for full compact: when the
+     *  durable session memory watermark matches an active entry, summarize the
+     *  last good memory artifact plus the post-watermark branch and retain a
+     *  recent suffix. Returns null to fall back to the existing full-compaction
+     *  behavior (missing/invalid watermark, empty projection, or oversized
+     *  projection). */
+    private selectMemoryPreservedCompact;
     private lastMessageUuid;
     private promptIdForToolCall;
     private assistantIdForToolCall;
@@ -281,6 +295,8 @@ export declare class ClaudeSessionService {
     private boundSessionMemorySummary;
     private formatSessionMemoryConversation;
     private extractSessionMemory;
+    private sessionMemoryProvider;
+    private sessionMemoryProviderFactory;
     private toolCapabilities;
     private capabilityToolNames;
     private append;

package/dist/application/session-service.js

@@ -13,7 +13,7 @@ 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 { selectClaudeSchemaAdapter, } from '../compatibility/claude/schema.js';
-import { findUnresolvedClaudeToolCalls } from '../compatibility/claude/tool-links.js';
+import { findUnresolvedClaudeToolCalls, getClaudeContentBlocks, } from '../compatibility/claude/tool-links.js';
 import { createClaudeAgentSettingEntry, createClaudeHookAttachmentEntries, createClaudeLastPromptEntry, createClaudeRuleAttachmentEntry, translateProviderEvents, } from '../compatibility/claude/translation.js';
 import { AgentRunCancelledError, AgentRuntime, } from '../core/runtime.js';
 import { BackgroundTaskRuntime, } from './background-task-runtime.js';
@@ -302,6 +302,149 @@ Update the durable session memory from the conversation so far. Preserve:
 Omit transient chatter, credentials, secrets, or personal data.
 
 Return ONLY an updated Markdown document that becomes the session's durable memory. Do not call tools. Do not include any prose outside the Markdown document.`;
+/** Memory-anchored manual compact keeps a recent suffix of at least five
+ *  text-bearing messages and approximately ten thousand tokens when the active
+ *  branch can provide them. Larger suffixes stay conservative. */
+const MEMORY_COMPACT_MIN_SUFFIX_MESSAGES = 5;
+const MEMORY_COMPACT_MIN_SUFFIX_TOKENS = 10_000;
+/** Above this estimated post-compact envelope the selective path falls back to
+ *  full compaction instead of retaining an oversized active projection. */
+const MEMORY_COMPACT_MAX_PROJECTION_TOKENS = 40_000;
+const MEMORY_COMPACT_MAX_SUMMARY_TOKENS = 8_192;
+function isTextBearingClaudeEntry(entry) {
+    if (typeof entry.message !== 'object' ||
+        entry.message === null ||
+        Array.isArray(entry.message)) {
+        return false;
+    }
+    const message = entry.message;
+    const content = message.content;
+    if (message.role === 'user') {
+        if (typeof content === 'string')
+            return content.trim().length > 0;
+        if (!Array.isArray(content))
+            return false;
+        return content.some((block) => typeof block === 'object' &&
+            block !== null &&
+            (block.type === 'text' ||
+                block.type === 'tool_result' ||
+                block.type === 'image' ||
+                block.type === 'document'));
+    }
+    if (message.role === 'assistant') {
+        if (!Array.isArray(content))
+            return false;
+        return content.some((block) => typeof block === 'object' &&
+            block !== null &&
+            (block.type === 'text' ||
+                block.type === 'tool_use' ||
+                block.type === 'thinking'));
+    }
+    return false;
+}
+function claudeToolResultIds(entry) {
+    const ids = new Set();
+    if (entry.type !== 'user')
+        return ids;
+    for (const block of getClaudeContentBlocks(entry)) {
+        if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+            ids.add(block.tool_use_id);
+        }
+    }
+    return ids;
+}
+function claudeAssistantHasToolUse(entry, ids) {
+    if (entry.type !== 'assistant')
+        return false;
+    return getClaudeContentBlocks(entry).some((block) => block.type === 'tool_use' &&
+        typeof block.id === 'string' &&
+        ids.has(block.id));
+}
+function claudeAssistantResponseId(entry) {
+    if (entry?.type !== 'assistant' ||
+        typeof entry.message !== 'object' ||
+        entry.message === null ||
+        Array.isArray(entry.message)) {
+        return null;
+    }
+    const id = entry.message.id;
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}
+/** Claude transcripts may normalize one provider response into consecutive
+ *  assistant records with the same message.id. Keep the whole response on one
+ *  side of the compact boundary so thinking and tool siblings stay together. */
+function completeClaudeAssistantResponseBoundary(activeEntries, startIndex, lowerBound) {
+    const responseId = claudeAssistantResponseId(activeEntries[startIndex]);
+    if (responseId === null)
+        return startIndex;
+    let boundary = startIndex;
+    for (let index = startIndex - 1; index >= lowerBound; index -= 1) {
+        const candidate = activeEntries[index];
+        if (claudeAssistantResponseId(candidate) !== responseId)
+            break;
+        boundary = index;
+    }
+    return boundary;
+}
+/** Pulls the preserved-suffix boundary backward so a tool_use assistant entry
+ *  and its tool_result user entry stay siblings: the suffix never opens with an
+ *  orphaned tool_result and the compacted input never ends with a dangling
+ *  tool_use. Same-response thinking/tool blocks live in one assistant entry,
+ *  so entry-level cutting never splits them. */
+function completeClaudeToolPairBoundary(activeEntries, startIndex, lowerBound) {
+    let boundary = startIndex;
+    while (boundary < activeEntries.length) {
+        const entry = activeEntries[boundary];
+        if (!entry)
+            break;
+        const ids = claudeToolResultIds(entry);
+        if (ids.size === 0)
+            break;
+        let extended = false;
+        for (let index = boundary - 1; index >= lowerBound; index -= 1) {
+            const candidate = activeEntries[index];
+            if (candidate && claudeAssistantHasToolUse(candidate, ids)) {
+                boundary = index;
+                extended = true;
+                break;
+            }
+        }
+        if (!extended)
+            break;
+    }
+    return boundary;
+}
+/** Walks back from the active tail to the inclusive start of the recent suffix
+ *  retained verbatim, then completes sibling adjacency at the boundary. */
+export function memoryPreservedSuffixStart(activeEntries) {
+    let latestCompactBoundary = 0;
+    for (let index = activeEntries.length - 1; index >= 0; index -= 1) {
+        if (activeEntries[index]?.isCompactSummary === true) {
+            latestCompactBoundary = index;
+            break;
+        }
+    }
+    let start = activeEntries.length;
+    let textBearing = 0;
+    let estimatedTokens = 0;
+    for (let index = activeEntries.length - 1; index >= latestCompactBoundary; index -= 1) {
+        const entry = activeEntries[index];
+        if (!entry)
+            continue;
+        start = index;
+        if (!isTextBearingClaudeEntry(entry))
+            continue;
+        textBearing += 1;
+        estimatedTokens += estimateModelRequestTokens(projectClaudeModelMessages([entry]));
+        if (textBearing >= MEMORY_COMPACT_MIN_SUFFIX_MESSAGES &&
+            (estimatedTokens >= MEMORY_COMPACT_MIN_SUFFIX_TOKENS ||
+                index === latestCompactBoundary)) {
+            break;
+        }
+    }
+    const toolSafeStart = completeClaudeToolPairBoundary(activeEntries, start, latestCompactBoundary);
+    return completeClaudeAssistantResponseBoundary(activeEntries, toolSafeStart, latestCompactBoundary);
+}
 function validPromptSuggestion(value) {
     const suggestion = value.trim();
     if (!suggestion)
@@ -450,6 +593,7 @@ export class ClaudeSessionService {
     activeCostSessionId;
     closeCostSavePromise;
     sessionMemoryControllers = new Map();
+    resolvedSessionMemoryProvider;
     hookLifecycle;
     runtimeCwd;
     constructor(options) {
@@ -600,6 +744,7 @@ export class ClaudeSessionService {
         await Promise.all([...this.backgroundNotificationWrites.values()]);
         this.hostedSubagents.clear();
         this.backgroundTasks.clear();
+        await Promise.all([...this.sessionMemoryControllers.values()].map((controller) => controller.close()));
         this.sessionMemoryControllers.clear();
         await this.workflowManager?.close();
         this.closeCostSavePromise ??= this.persistActiveSessionCost();
@@ -1464,6 +1609,7 @@ export class ClaudeSessionService {
             let selectedEntries = activeEntries;
             let logicalParentUuid = this.lastMessageUuid(activeEntries);
             let preservedEntries = [];
+            let memoryMessage;
             if (selection) {
                 const targetIndex = activeEntries.findIndex((entry) => entry.uuid === selection.messageId);
                 if (targetIndex < 0) {
@@ -1486,8 +1632,18 @@ export class ClaudeSessionService {
                             : this.lastMessageUuid(selectedEntries);
                 }
             }
+            else {
+                const memorySelection = await this.selectMemoryPreservedCompact(sessionId, activeEntries);
+                if (memorySelection) {
+                    selectedEntries = [...memorySelection.compactedEntries];
+                    preservedEntries = [...memorySelection.preservedEntries];
+                    logicalParentUuid = memorySelection.logicalParentUuid;
+                    memoryMessage = memorySelection.memoryMessage;
+                }
+            }
             const selectedMessages = projectClaudeModelMessages(selectedEntries);
             const messages = [
+                ...(memoryMessage === undefined ? [] : [memoryMessage]),
                 ...selectedMessages,
                 ...(selection?.context
                     ? [
@@ -1588,7 +1744,11 @@ export class ClaudeSessionService {
                         },
                         preservedUuids: preservedEntries.flatMap((entry) => typeof entry.uuid === 'string' ? [entry.uuid] : []),
                     }
-                    : {}),
+                    : memoryMessage
+                        ? {
+                            preservedUuids: preservedEntries.flatMap((entry) => typeof entry.uuid === 'string' ? [entry.uuid] : []),
+                        }
+                        : {}),
                 createUuid: () => uuids.shift() ?? randomUUID(),
             });
             const appendResult = await lease.appendMany(snapshot.tail, entries);
@@ -2562,7 +2722,7 @@ export class ClaudeSessionService {
                     ];
                     const irreducible = budget.evaluate(irreducibleMessages, definitions);
                     budget.assertFits(irreducible);
-                    const logicalParentUuid = compactionAnchorUuid;
+                    let logicalParentUuid = compactionAnchorUuid;
                     if (!logicalParentUuid || historyMessages.length === 0) {
                         budget.assertFits(predicted);
                         throw new Error('Cannot compact an empty Claude transcript');
@@ -2570,8 +2730,17 @@ export class ClaudeSessionService {
                     if (findUnresolvedClaudeToolCalls(snapshot.entries).length > 0) {
                         throw new Error('Cannot compact a Claude session with unresolved tool calls');
                     }
-                    if (sessionMemory) {
-                        await sessionMemory.waitForIdle();
+                    const memorySelection = sessionMemory
+                        ? await this.selectMemoryPreservedCompact(sessionId, selectClaudeActiveTranscript(snapshot.entries))
+                        : null;
+                    const compactorMessages = memorySelection
+                        ? [
+                            memorySelection.memoryMessage,
+                            ...projectClaudeModelMessages(memorySelection.compactedEntries),
+                        ]
+                        : historyMessages;
+                    if (memorySelection) {
+                        logicalParentUuid = memorySelection.logicalParentUuid;
                     }
                     this.options.eventSink?.({ type: 'state', state: 'compacting' });
                     const compactEnvelope = budget.evaluate([
@@ -2593,7 +2762,7 @@ export class ClaudeSessionService {
                         targetTokens = 1;
                     }
                     const compacted = await (this.options.compactor ?? new ModelCompactor(provider)).compact({
-                        messages: historyMessages,
+                        messages: compactorMessages,
                         targetTokens,
                         contextWindowTokens: budget.contextWindowTokens,
                         ...(signal ? { signal } : {}),
@@ -2625,6 +2794,11 @@ export class ClaudeSessionService {
                             cwd: this.activeCwd(),
                             claudeVersion: this.options.claudeVersion,
                             gitBranch: null,
+                            ...(memorySelection
+                                ? {
+                                    preservedUuids: memorySelection.preservedEntries.flatMap((entry) => typeof entry.uuid === 'string' ? [entry.uuid] : []),
+                                }
+                                : {}),
                             createUuid: () => uuids.shift() ?? randomUUID(),
                             now: () => timestamp,
                         });
@@ -3147,21 +3321,25 @@ 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)}`,
-                    });
+                    const memorySnapshot = projectClaudeModelMessages(snapshot.entries);
+                    const providerVisibleMessages = [
+                        ...contextMessages,
+                        ...injectTurnContext(memorySnapshot),
+                    ];
+                    const currentContextTokens = budget
+                        ? budget.evaluate(providerVisibleMessages, definitions)
+                            .occupancyTokens
+                        : estimateModelRequestTokens(providerVisibleMessages, definitions);
                     try {
-                        await sessionMemory.observeDelta(turnInputTokens, currentTurnToolCalls, finalLeafUuid, projectClaudeModelMessages(snapshot.entries));
-                        // Normal turns schedule extraction without awaiting it; failures
-                        // surface as a warning while the sidecar stays retryable.
-                        sessionMemory.waitForIdle().catch(warn);
+                        await sessionMemory.observeContext(currentContextTokens, currentTurnToolCalls, finalLeafUuid, memorySnapshot);
                     }
                     catch (error) {
                         // A failed observation must not fail the user turn; the sidecar
                         // retains a retryable error for the next observation.
-                        warn(error);
+                        this.options.eventSink?.({
+                            type: 'warning',
+                            message: `Session memory observation failed: ${error instanceof Error ? error.message : String(error)}`,
+                        });
                     }
                 }
                 turnCompleted = true;
@@ -3279,6 +3457,67 @@ export class ClaudeSessionService {
             return agentName;
         return null;
     }
+    /** Conservative selective-preservation seam for full compact: when the
+     *  durable session memory watermark matches an active entry, summarize the
+     *  last good memory artifact plus the post-watermark branch and retain a
+     *  recent suffix. Returns null to fall back to the existing full-compaction
+     *  behavior (missing/invalid watermark, empty projection, or oversized
+     *  projection). */
+    async selectMemoryPreservedCompact(sessionId, activeEntries) {
+        const controller = this.sessionMemoryController(sessionId);
+        if (controller === null)
+            return null;
+        await controller.waitForCompact();
+        let watermark = null;
+        let memorySummary = '';
+        try {
+            const [state, summary] = await Promise.all([
+                controller.state(),
+                controller.summary(),
+            ]);
+            watermark = state.lastSummarizedMessageId;
+            memorySummary = summary;
+        }
+        catch {
+            return null;
+        }
+        if (watermark === null || watermark.length === 0)
+            return null;
+        if (memorySummary.trim().length === 0)
+            return null;
+        const watermarkIndex = activeEntries.findIndex((entry) => entry.uuid === watermark);
+        if (watermarkIndex < 0)
+            return null;
+        const suffixStart = memoryPreservedSuffixStart(activeEntries);
+        if (suffixStart <= 0 || suffixStart <= watermarkIndex + 1)
+            return null;
+        const compactedEntries = activeEntries.slice(watermarkIndex + 1, suffixStart);
+        const preservedEntries = activeEntries.slice(suffixStart);
+        const preservedMessages = projectClaudeModelMessages(preservedEntries);
+        if (projectClaudeModelMessages(compactedEntries).length === 0)
+            return null;
+        const memoryMessage = { role: 'user', content: memorySummary };
+        if (estimateModelRequestTokens([
+            {
+                role: 'user',
+                content: formatClaudeCompactSummary(''),
+            },
+            ...preservedMessages,
+        ]) +
+            MEMORY_COMPACT_MAX_SUMMARY_TOKENS >
+            MEMORY_COMPACT_MAX_PROJECTION_TOKENS) {
+            return null;
+        }
+        const logicalParentUuid = this.lastMessageUuid(activeEntries.slice(0, suffixStart));
+        if (logicalParentUuid === null)
+            return null;
+        return {
+            compactedEntries,
+            preservedEntries,
+            memoryMessage,
+            logicalParentUuid,
+        };
+    }
     lastMessageUuid(entries) {
         for (let index = entries.length - 1; index >= 0; index -= 1) {
             const entry = entries[index];
@@ -3869,7 +4108,9 @@ export class ClaudeSessionService {
             return false;
         if (this.options.sessionPersistence === false)
             return false;
-        return true;
+        if (this.options.sessionKind === 'bg')
+            return false;
+        return this.sessionMemoryProviderFactory() !== null;
     }
     sessionMemoryController(sessionId) {
         if (!this.sessionMemoryEnabled() || !isClaudeSessionId(sessionId)) {
@@ -3883,7 +4124,11 @@ export class ClaudeSessionService {
                     sessionId,
                     sidecarRoot: this.paths(sessionId).praxisRoot,
                 }),
-                extractor: (input) => this.extractSessionMemory(sessionId, input),
+                extractor: (input) => this.extractSessionMemory(input),
+                onExtractionError: (error) => this.options.eventSink?.({
+                    type: 'warning',
+                    message: `Session memory extraction failed: ${error instanceof Error ? error.message : String(error)}`,
+                }),
             });
             this.sessionMemoryControllers.set(sessionId, controller);
         }
@@ -3934,10 +4179,16 @@ export class ClaudeSessionService {
                 parts.push(`Tool result: ${message.content}`);
             }
         }
-        return this.boundSessionMemorySummary(parts.join('\n\n'));
+        // The successful watermark names the newest message in this snapshot, so
+        // extraction must receive every message in full. Summary injection remains
+        // bounded separately; provider refusal leaves the old watermark retryable.
+        return parts.join('\n\n');
     }
-    async extractSessionMemory(sessionId, input) {
-        const provider = this.provider();
+    async extractSessionMemory(input) {
+        const provider = this.sessionMemoryProvider();
+        if (provider === null) {
+            throw new SessionMemoryStateError('Session memory requires an isolated provider factory');
+        }
         const messages = [
             { role: 'system', content: SESSION_MEMORY_EXTRACTION_PROMPT },
             ...(input.summary.trim().length === 0
@@ -3957,8 +4208,11 @@ export class ClaudeSessionService {
                     },
                 ]),
         ];
-        const metrics = await completeMeteredModelRequest(provider, { messages }, {
-            onMetrics: (recorded) => this.recordAuxiliaryMetrics(sessionId, recorded),
+        // Session memory is operational side work: it never contributes to the
+        // foreground result or the persisted session cost/usage tracker.
+        const metrics = await completeMeteredModelRequest(provider, {
+            messages,
+            signal: input.signal,
         });
         if (metrics.toolCalls.length > 0) {
             throw new SessionMemoryStateError('Session memory extraction must not call tools');
@@ -3969,6 +4223,24 @@ export class ClaudeSessionService {
         }
         return summary;
     }
+    sessionMemoryProvider() {
+        if (this.resolvedSessionMemoryProvider !== undefined) {
+            return this.resolvedSessionMemoryProvider;
+        }
+        const factory = this.sessionMemoryProviderFactory();
+        this.resolvedSessionMemoryProvider = factory?.() ?? null;
+        return this.resolvedSessionMemoryProvider;
+    }
+    sessionMemoryProviderFactory() {
+        if (this.options.sessionMemoryProviderFactory) {
+            return this.options.sessionMemoryProviderFactory;
+        }
+        const selectProvider = this.options.providerForMainModel ?? this.options.providerForModel;
+        const foregroundModel = this.options.provider?.model;
+        return foregroundModel && selectProvider
+            ? () => selectProvider(foregroundModel)
+            : null;
+    }
     toolCapabilities() {
         const taskNames = this.options.taskToolNames ?? [];
         const input = {

package/dist/cli-runtime.d.ts

@@ -178,6 +178,10 @@ export interface CliDependencies extends InteractiveServiceFactory {
  * to the existing default behavior (undefined).
  */
 export declare function resolveRuntimeModel(explicitModel: string | undefined, environment: NodeJS.ProcessEnv, settings: PraxisRuntimeSettings | undefined): string | undefined;
+/** Builds the default CLI's isolated Session-memory adapter seam. Each
+ * invocation reconstructs the selected main-model provider stack instead of
+ * sharing foreground adapter-local cache and retry state. */
+export declare function createSessionMemoryProviderFactory(providerForMainModel: ((model: string) => ModelProvider) | undefined, model: string | undefined): (() => ModelProvider) | undefined;
 export declare function resolveInteractiveRuntimeSettingsLocation(dataPlane: DataPlane, environment?: NodeJS.ProcessEnv): {
     configRoot: string;
     statePath: string;

package/dist/cli-runtime.js

@@ -749,6 +749,14 @@ export function resolveRuntimeModel(explicitModel, environment, settings) {
         (envModel !== undefined && envModel.trim() !== '' ? envModel : undefined) ??
         settingsModel);
 }
+/** Builds the default CLI's isolated Session-memory adapter seam. Each
+ * invocation reconstructs the selected main-model provider stack instead of
+ * sharing foreground adapter-local cache and retry state. */
+export function createSessionMemoryProviderFactory(providerForMainModel, model) {
+    if (!providerForMainModel || !model)
+        return undefined;
+    return () => providerForMainModel(model);
+}
 export function resolveInteractiveRuntimeSettingsLocation(dataPlane, environment = process.env) {
     const configRoot = resolveDataPlaneRoot({ dataPlane, environment });
     return {
@@ -854,6 +862,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         projectIdentity: await resolveClaudeProjectIdentity({ cwd }),
         sidecarPath: resolveUnknownCostSidecarPath(dataPlane, configRoot),
     });
+    const sessionMemoryProviderFactory = createSessionMemoryProviderFactory(providerForMainModel, model);
     const options = {
         configRoot,
         dataPlane,
@@ -879,6 +888,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             : { maxBudgetUsd: cli.maxBudgetUsd }),
         pricing: ModelPricingRegistry.fromEnvironment(runtimeEnvironment.PRAXIS_PRICING_JSON),
         collectMetrics: true,
+        ...(sessionMemoryProviderFactory ? { sessionMemoryProviderFactory } : {}),
         ...(sessionKind === undefined ? {} : { sessionKind }),
         workspace,
         ...(cli.worktreeRequested

package/package.json

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