mixdog 0.9.51 → 0.9.52

package/scripts/interrupted-turn-history-test.mjs

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+process.env.MIXDOG_AGENT_TRACE_DISABLE = '1';
+const DATA_DIR = mkdtempSync(join(tmpdir(), 'mixdog-interrupted-turn-'));
+process.env.MIXDOG_DATA_DIR = DATA_DIR;
+
+const PACKAGE_PATH = fileURLToPath(new URL('../package.json', import.meta.url));
+const USER_INTERRUPTION_MESSAGE = '[Request interrupted by user]';
+const TOOL_USE_INTERRUPTION_MESSAGE = '[Request interrupted by user for tool use]';
+const STREAMING_INTERRUPTED_TOOL_RESULT = 'Interrupted by user';
+const TOOL_USE_REJECT_RESULT = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
+
+function deferred() {
+    let resolve;
+    const promise = new Promise((done) => { resolve = done; });
+    return { promise, resolve };
+}
+
+function waitForAbort(opts) {
+    return new Promise((_resolve, reject) => {
+        const signal = opts?.signal;
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+}
+
+test('interrupted turns keep Claude Code-compatible model history boundaries', { concurrency: false }, async (t) => {
+    const { initProviders, getProvider } = await import('../src/runtime/agent/orchestrator/providers/registry.mjs');
+    await initProviders({ gemini: { enabled: true, apiKey: 'test-only' } });
+    const provider = getProvider('gemini');
+    const {
+        abortSessionTurn,
+        askSession,
+        createSession,
+        getSession,
+    } = await import('../src/runtime/agent/orchestrator/session/manager.mjs');
+    const { saveSessionAsync } = await import('../src/runtime/agent/orchestrator/session/store.mjs');
+
+    const createTestSession = (tools = []) => createSession({
+        provider: 'gemini',
+        model: 'gemini-test',
+        tools,
+        cwd: process.cwd(),
+        skipAgentRules: true,
+        skipSkills: true,
+        compaction: { auto: false },
+    });
+    const expectInterrupted = async (promise) => {
+        await assert.rejects(promise, (error) => error?.name === 'SessionClosedError');
+    };
+
+    await t.test('before response: rewinds the provisional user turn', async () => {
+        const session = createTestSession();
+        const baselineMessages = session.messages.slice();
+        const baselineSessionStart = session.sessionStartMetaInjected === true;
+        const entered = deferred();
+        provider.send = async (_messages, _model, _tools, opts) => {
+            entered.resolve();
+            return waitForAbort(opts);
+        };
+
+        const asking = askSession(session.id, 'cancel before response', null, null, process.cwd());
+        await entered.promise;
+        assert.equal(abortSessionTurn(session.id, 'user-cancel'), true);
+        await expectInterrupted(asking);
+
+        const persisted = getSession(session.id);
+        assert.deepEqual(persisted.messages, baselineMessages);
+        assert.equal(persisted.sessionStartMetaInjected === true, baselineSessionStart);
+        assert.equal(persisted.liveTurnMessages, null);
+    });
+
+    await t.test('streaming: preserves a partial response without a newline', async () => {
+        const session = createTestSession();
+        const streamed = deferred();
+        provider.send = async (_messages, _model, _tools, opts) => {
+            opts.onTextDelta?.('partial without newline');
+            streamed.resolve();
+            return waitForAbort(opts);
+        };
+
+        const asking = askSession(
+            session.id,
+            'stream a partial response',
+            null,
+            null,
+            process.cwd(),
+            null,
+            { onTextDelta: () => {} },
+        );
+        await streamed.promise;
+        abortSessionTurn(session.id, 'user-cancel');
+        await expectInterrupted(asking);
+
+        const persisted = getSession(session.id);
+        const partial = persisted.messages.find((message) => (
+            message.role === 'assistant' && message.content === 'partial without newline'
+        ));
+        assert.deepEqual(partial, {
+            role: 'assistant',
+            content: 'partial without newline',
+        });
+        assert.equal(persisted.messages.at(-1)?.content, USER_INTERRUPTION_MESSAGE);
+        assert.equal(persisted.liveTurnMessages, null);
+    });
+
+    await t.test('queued interrupt: preserves progress without a synthetic marker', async () => {
+        const session = createTestSession();
+        const streamed = deferred();
+        provider.send = async (_messages, _model, _tools, opts) => {
+            opts.onTextDelta?.('partial before queued redirect');
+            streamed.resolve();
+            return waitForAbort(opts);
+        };
+
+        const asking = askSession(
+            session.id,
+            'active request',
+            null,
+            null,
+            process.cwd(),
+            null,
+            { onTextDelta: () => {} },
+        );
+        await streamed.promise;
+        abortSessionTurn(session.id, 'interrupt');
+        await expectInterrupted(asking);
+
+        const persisted = getSession(session.id);
+        assert.deepEqual(persisted.messages.at(-1), {
+            role: 'assistant',
+            content: 'partial before queued redirect',
+        });
+        assert.equal(persisted.messages.some((message) => (
+            message.content === USER_INTERRUPTION_MESSAGE
+            || message.content === TOOL_USE_INTERRUPTION_MESSAGE
+        )), false);
+    });
+
+    await t.test('streaming tool use: closes an unstarted call with an error result', async () => {
+        const session = createTestSession();
+        const observed = deferred();
+        provider.send = async (_messages, _model, _tools, opts) => {
+            opts.onToolCall?.({
+                id: 'streaming_shell',
+                name: 'shell',
+                arguments: { command: 'echo not-started' },
+            });
+            observed.resolve();
+            return waitForAbort(opts);
+        };
+
+        const asking = askSession(session.id, 'prepare a shell call', null, null, process.cwd());
+        await observed.promise;
+        abortSessionTurn(session.id, 'user-cancel');
+        await expectInterrupted(asking);
+
+        const persisted = getSession(session.id);
+        assert.equal(persisted.messages.some((message) => (
+            message.role === 'assistant'
+            && message.toolCalls?.some((call) => call.id === 'streaming_shell')
+        )), true);
+        assert.deepEqual(
+            persisted.messages.find((message) => (
+                message.role === 'tool' && message.toolCallId === 'streaming_shell'
+            )),
+            {
+                role: 'tool',
+                content: STREAMING_INTERRUPTED_TOOL_RESULT,
+                toolCallId: 'streaming_shell',
+                toolKind: 'error',
+            },
+        );
+        assert.equal(persisted.messages.at(-1)?.content, USER_INTERRUPTION_MESSAGE);
+    });
+
+    await t.test('streamed eager tool: preserves a result completed before the provider response', async () => {
+        const session = createTestSession('readonly');
+        const eagerCompleted = deferred();
+        provider.send = async (_messages, _model, _tools, opts) => {
+            opts.onToolCall?.({
+                id: 'eager_read',
+                name: 'read',
+                arguments: { path: PACKAGE_PATH, offset: 0, limit: 1 },
+            });
+            return waitForAbort(opts);
+        };
+        const asking = askSession(
+            session.id,
+            'run an eager read',
+            null,
+            null,
+            process.cwd(),
+            null,
+            {
+                onToolResult: (message) => {
+                    if (message?.__earlyNotify !== true) return;
+                    eagerCompleted.resolve();
+                    abortSessionTurn(session.id, 'user-cancel');
+                },
+            },
+        );
+        await eagerCompleted.promise;
+        await expectInterrupted(asking);
+
+        const persisted = getSession(session.id);
+        const assistant = persisted.messages.find((message) => (
+            message.role === 'assistant'
+            && message.toolCalls?.some((call) => call.id === 'eager_read')
+        ));
+        const result = persisted.messages.find((message) => (
+            message.role === 'tool' && message.toolCallId === 'eager_read'
+        ));
+        assert.ok(assistant, 'streamed tool_use is retained before send() returns');
+        assert.ok(result, 'completed eager result is retained');
+        assert.notEqual(result.content, STREAMING_INTERRUPTED_TOOL_RESULT);
+        assert.equal(persisted.messages.at(-1)?.content, USER_INTERRUPTION_MESSAGE);
+    });
+
+    let toolSession;
+    await t.test('tool execution: keeps completed results and closes unfinished calls', async () => {
+        toolSession = createTestSession();
+        provider.send = async () => ({
+            content: 'checking both slices',
+            toolCalls: [
+                { id: 'read_one', name: 'read', arguments: { path: PACKAGE_PATH, offset: 0, limit: 1 } },
+                { id: 'read_two', name: 'read', arguments: { path: PACKAGE_PATH, offset: 1, limit: 1 } },
+            ],
+            stopReason: 'tool_use',
+        });
+        let toolResults = 0;
+        const asking = askSession(
+            toolSession.id,
+            'read two slices',
+            null,
+            null,
+            process.cwd(),
+            null,
+            {
+                onToolResult: () => {
+                    toolResults += 1;
+                    if (toolResults === 1) abortSessionTurn(toolSession.id, 'user-cancel');
+                },
+            },
+        );
+        await expectInterrupted(asking);
+
+        const persisted = getSession(toolSession.id);
+        const results = persisted.messages.filter((message) => message.role === 'tool');
+        assert.equal(results.length, 2);
+        assert.equal(results[0].toolCallId, 'read_one');
+        assert.notEqual(results[0].content, TOOL_USE_REJECT_RESULT);
+        assert.deepEqual(
+            { id: results[1].toolCallId, content: results[1].content, kind: results[1].toolKind },
+            { id: 'read_two', content: TOOL_USE_REJECT_RESULT, kind: 'error' },
+        );
+        assert.equal(persisted.messages.at(-1)?.content, TOOL_USE_INTERRUPTION_MESSAGE);
+    });
+
+    await t.test('recovery: the next model request receives the closed tool trajectory', async () => {
+        let capturedMessages = null;
+        provider.send = async (messages, _model, _tools, opts) => {
+            capturedMessages = JSON.parse(JSON.stringify(messages));
+            opts.onTextDelta?.('recovered');
+            return { content: 'recovered', stopReason: 'STOP' };
+        };
+        const result = await askSession(toolSession.id, 'continue after interrupt', null, null, process.cwd());
+        assert.equal(result.content, 'recovered');
+        assert.equal(capturedMessages.some((message) => (
+            message.role === 'tool'
+            && message.toolCallId === 'read_two'
+            && message.content === TOOL_USE_REJECT_RESULT
+        )), true);
+        assert.equal(capturedMessages.some((message) => message.content === TOOL_USE_INTERRUPTION_MESSAGE), true);
+    });
+
+    let chainedSession;
+    await t.test('later iteration: preserves completed tool history, steering, and the current partial', async () => {
+        chainedSession = createTestSession();
+        let sendCount = 0;
+        const secondStream = deferred();
+        provider.send = async (_messages, _model, _tools, opts) => {
+            sendCount += 1;
+            if (sendCount === 1) {
+                opts.onTextDelta?.('first iteration preamble');
+                return {
+                    content: 'first iteration preamble',
+                    toolCalls: [
+                        { id: 'chain_read', name: 'read', arguments: { path: PACKAGE_PATH, offset: 0, limit: 1 } },
+                    ],
+                    stopReason: 'tool_use',
+                };
+            }
+            opts.onTextDelta?.('later partial');
+            secondStream.resolve();
+            return waitForAbort(opts);
+        };
+        let steeringDrained = false;
+        const asking = askSession(
+            chainedSession.id,
+            'run a chained turn',
+            null,
+            null,
+            process.cwd(),
+            null,
+            {
+                onTextDelta: () => {},
+                drainSteering: () => {
+                    if (steeringDrained) return [];
+                    steeringDrained = true;
+                    return [{ content: 'queued redirect', text: 'queued redirect', count: 1 }];
+                },
+            },
+        );
+        await secondStream.promise;
+        abortSessionTurn(chainedSession.id, 'user-cancel');
+        await expectInterrupted(asking);
+
+        const persisted = getSession(chainedSession.id);
+        assert.equal(persisted.messages.some((message) => (
+            message.role === 'tool' && message.toolCallId === 'chain_read'
+        )), true);
+        assert.equal(persisted.messages.some((message) => (
+            message.role === 'user'
+            && message.content === 'queued redirect'
+            && message.meta?.source === 'steering'
+        )), true);
+        assert.equal(persisted.messages.some((message) => (
+            message.role === 'assistant'
+            && message.content === 'later partial'
+        )), true);
+        assert.equal(persisted.messages.at(-1)?.content, USER_INTERRUPTION_MESSAGE);
+    });
+
+    await t.test('recovery and disk: partial/steering history survives the next send and storage flush', async () => {
+        let capturedMessages = null;
+        provider.send = async (messages) => {
+            capturedMessages = JSON.parse(JSON.stringify(messages));
+            return { content: 'chain recovered', stopReason: 'STOP' };
+        };
+        await askSession(chainedSession.id, 'finish the chain', null, null, process.cwd());
+        assert.equal(capturedMessages.some((message) => (
+            message.role === 'assistant'
+            && message.content === 'later partial'
+        )), true);
+        assert.equal(capturedMessages.some((message) => (
+            message.role === 'user' && message.content === 'queued redirect'
+        )), true);
+
+        const latestSession = getSession(chainedSession.id);
+        await saveSessionAsync(latestSession, { expectedGeneration: latestSession.generation });
+        const diskSession = JSON.parse(readFileSync(
+            join(DATA_DIR, 'sessions', `${chainedSession.id}.json`),
+            'utf8',
+        ));
+        assert.equal(diskSession.messages.some((message) => (
+            message.role === 'assistant' && message.content === 'later partial'
+        )), true);
+        assert.equal(diskSession.messages.some((message) => message.content === USER_INTERRUPTION_MESSAGE), true);
+        assert.equal(Object.hasOwn(diskSession, 'liveTurnMessages'), false);
+    });
+});

package/scripts/lifecycle-api-test.mjs

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createLifecycleApi } from '../src/session-runtime/lifecycle-api.mjs';
+import {
+  _clearWebSocketPoolForTest,
+  _seedWebSocketEntryForTest,
+  closeOpenaiWsPoolForSession,
+} from '../src/runtime/agent/orchestrator/providers/openai-ws-pool.mjs';
+
+function socket() {
+  return {
+    closed: [],
+    close(_code, reason) {
+      this.closed.push(reason);
+    },
+  };
+}
+
+function lifecycleFor(session) {
+  let current = session;
+  return createLifecycleApi({
+    getSession: () => current,
+    setSession: (value) => { current = value; },
+    getRoute: () => ({}),
+    setRoute: () => {},
+    getConfig: () => ({}),
+    getMode: () => 'full',
+    getCurrentCwd: () => '/test',
+    setCloseRequested: () => {},
+    getMemoryModPromise: () => null,
+    setMemoryModPromise: () => {},
+    setSessionNeedsCwdRefresh: () => {},
+    hooks: { dispatch: () => {}, flushRules: () => {} },
+    hookCommonPayload: (payload) => payload,
+    mgr: {
+      closeSession: (id, reason) => {
+        closeOpenaiWsPoolForSession(id, `session-close:${reason}`);
+        return true;
+      },
+    },
+    statusRoutes: { clearGatewaySessionRoute: () => {} },
+    channels: { stop: () => null },
+    agentTool: { closeAll: () => {} },
+    mcpClient: { disconnectAll: () => null },
+    warmupTimers: {},
+    prewarmTimers: {},
+    flushConfigSave: () => {},
+    flushBackendSave: () => {},
+    flushOutputStyleSave: () => {},
+    withTeardownDeadline: (promise) => promise,
+    closePatchRuntimeIfLoaded: () => null,
+    invalidateContextStatusCache: () => {},
+    invalidatePreSessionToolSurface: () => {},
+    notificationListeners: { clear: () => {} },
+    remoteStateListeners: { clear: () => {} },
+  });
+}
+
+test('lifecycle drains the OpenAI WS pool only for process exit', async () => {
+  _clearWebSocketPoolForTest();
+  globalThis.__mixdogOpenaiWsRuntimeLoaded = true;
+  const replacementSocket = socket();
+  const retainedSocket = socket();
+  _seedWebSocketEntryForTest({ poolKey: 'replacement', auth: {}, cacheKey: '', entry: { socket: replacementSocket } });
+  _seedWebSocketEntryForTest({ poolKey: 'retained', auth: {}, cacheKey: '', entry: { socket: retainedSocket } });
+
+  await lifecycleFor({ id: 'replacement', messages: [], liveTurnMessages: [] }).close('engine-replace');
+
+  assert.deepEqual(replacementSocket.closed, ['session-close:engine-replace']);
+  assert.deepEqual(retainedSocket.closed, []);
+
+  await lifecycleFor({ id: 'exit-session', messages: [], liveTurnMessages: [] }).close('cli-exit');
+
+  assert.deepEqual(retainedSocket.closed, ['cli-exit']);
+});

package/scripts/max-output-recovery-test.mjs

@@ -37,6 +37,7 @@ async function run(provider, messages = [{ role: 'user', content: 'answer fully'
     return agentLoop(provider, messages, 'fake-model', [], options.onToolCall, process.cwd(), {
         onTextDelta: options.onTextDelta,
         session: options.session,
+        providerState: options.providerState,
     });
 }
 
@@ -117,6 +118,45 @@ test('Gemini MAX_TOKENS ProviderIncompleteError enters the same bounded recovery
     assert.equal(provider.sent[1][1].content, 'gemini ');
 });
 
+test('Gemini MAX_TOKENS continuation preserves provider-scoped replay metadata', async () => {
+    const providerMetadata = {
+        gemini: { thoughtParts: [{ text: 'signed thought', thoughtSignature: 'sig-gemini' }] },
+    };
+    const incomplete = Object.assign(new Error('MAX_TOKENS'), {
+        code: 'PROVIDER_INCOMPLETE',
+        providerIncomplete: true,
+        finishReason: 'MAX_TOKENS',
+        partialContent: 'first ',
+        providerMetadata,
+    });
+    const provider = queuedProvider([
+        incomplete,
+        { content: 'second', stopReason: 'end_turn' },
+    ]);
+    await run(provider);
+    assert.deepEqual(provider.sent[1][1].providerMetadata, providerMetadata);
+});
+
+test('Gemini partial-final stall commits signed provider metadata with partial text', async () => {
+    const providerMetadata = {
+        gemini: {
+            thoughtParts: [{ text: 'private', thoughtSignature: 'sig-private' }],
+            textParts: [{ text: 'partial answer', thoughtSignature: 'sig-text' }],
+        },
+    };
+    const stalled = Object.assign(new Error('stalled'), {
+        streamStalled: true,
+        pendingToolUse: false,
+        emittedToolCall: false,
+        partialContent: 'partial answer',
+        providerMetadata,
+    });
+    const messages = [{ role: 'user', content: 'answer' }];
+    const result = await run(queuedProvider([stalled]), messages);
+    assert.equal(result.content, 'partial answer');
+    assert.deepEqual(result.providerMetadata, providerMetadata);
+});
+
 test('pause_turn and Gemini OTHER preserve prior non-empty semantics and do not recover', async () => {
     for (const stopReason of ['pause_turn', 'OTHER']) {
         const provider = queuedProvider([{ content: `partial-${stopReason}`, stopReason }]);
@@ -245,6 +285,21 @@ test('clean end_turn is unchanged and does not enter recovery', async () => {
     assert.deepEqual(messages, [{ role: 'user', content: 'answer fully' }]);
 });
 
+test('providerState distinguishes no update from an explicit clear for other providers', async () => {
+    const initial = { otherProvider: { continuation: 'keep' } };
+    const noUpdate = await run(queuedProvider([
+        { content: 'done', stopReason: 'end_turn' },
+    ]), undefined, { providerState: initial });
+    assert.deepEqual(noUpdate.providerState, initial);
+    assert.equal(noUpdate.providerStateUpdated, false);
+
+    const cleared = await run(queuedProvider([
+        { content: 'done', stopReason: 'end_turn', providerState: null },
+    ]), undefined, { providerState: initial });
+    assert.equal(cleared.providerState, null);
+    assert.equal(cleared.providerStateUpdated, true);
+});
+
 test('tool-call turns keep the normal tool execution path', async () => {
     const provider = queuedProvider([
         {

package/scripts/mcp-grace-deferred-test.mjs

@@ -11,13 +11,14 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import {
     applyDeferredToolSurface,
+    rebuildDeferredToolSurfaceForProvider,
     refreshInitialDeferredMcpSurface,
     reconcileDeferredMcpToolCatalog,
 } from '../src/session-runtime/tool-catalog.mjs';
 
-function baseSession() {
+function baseSession(provider = 'anthropic-oauth') {
     return {
-        provider: 'legacy',
+        provider,
         tools: [{ name: 'read', description: 'read a file' }, { name: 'grep', description: 'search' }],
         messages: [{ role: 'system', content: 'BASE PROMPT' }],
     };
@@ -26,9 +27,9 @@ function baseSession() {
 // A freshly-created session: the create-time surface is baked WITHOUT any MCP
 // (server still mid-handshake at create). `shell` is a deferred (non-active)
 // standalone tool so BP1 carries a manifest block even before MCP arrives.
-function createdSession() {
-    const session = baseSession();
-    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }], { provider: 'legacy' });
+function createdSession(provider = 'anthropic-oauth') {
+    const session = baseSession(provider);
+    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }], { provider: session.provider });
     return session;
 }
 
@@ -93,7 +94,7 @@ test('recreated session (MCP already connected at create) seeds its manifest, no
     // surface at create time, so a cwd-change recreate seeds its BP1 directly and
     // never needs the first-turn refresh.
     const session = baseSession();
-    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }, mcpTool], { provider: 'legacy' });
+    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }, mcpTool], { provider: session.provider });
     assert.ok(systemContent(session).includes('mcp__unity__get_scene'), 'MCP in recreated BP1');
     assert.ok(session.deferredAnnouncedTools.includes('mcp__unity__get_scene'), 'recreated MCP pre-marked announced');
 
@@ -128,7 +129,7 @@ test('a second newly-connected MCP tool re-renders BP1 in place (both listed, st
 test('a resumed session (no fresh flag, prior baked BP1) is NOT refreshed on its next turn', () => {
     // A prior run baked BP1 with the MCP tool; resume reloads that transcript.
     const session = baseSession();
-    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }, mcpTool], { provider: 'legacy' });
+    applyDeferredToolSurface(session, 'full', [{ name: 'shell', description: 'run a command' }, mcpTool], { provider: session.provider });
     const before = systemContent(session);
     const announcedBefore = [...session.deferredAnnouncedTools];
     // Resume path never sets the per-session fresh flag.
@@ -139,11 +140,86 @@ test('a resumed session (no fresh flag, prior baked BP1) is NOT refreshed on its
     assert.deepEqual([...session.deferredAnnouncedTools], announcedBefore, 'announced set unchanged on resume');
 });
 
-test('a fresh session (flagged) is refreshed exactly once, then falls to the late path', () => {
-    const session = createdSession();
+test('fresh-session refresh state is isolated, one-shot, and survives provider switches without leaking', () => {
+    const refreshedSession = createdSession();
+    const noOpSession = createdSession();
+    refreshedSession.deferredInitialRefreshPending = true;
+    noOpSession.deferredInitialRefreshPending = true;
+
+    assert.equal(firstTurnGate(refreshedSession, [mcpTool]), 'refreshed', 'fresh session refreshes on its first turn');
+    assert.equal(refreshedSession.deferredInitialRefreshPending, false, 'fresh flag consumed (one-shot)');
+    assert.equal(noOpSession.deferredInitialRefreshPending, true, 'consuming one session does not consume another');
+    assert.ok(refreshedSession.deferredAnnouncedTools.includes('mcp__unity__get_scene'), 'first-turn MCP pre-announced');
+    assert.ok(!noOpSession.deferredAnnouncedTools.includes('mcp__unity__get_scene'), 'announced state does not leak between sessions');
+    assert.equal(firstTurnGate(refreshedSession, [mcpTool2]), 'late', 'second turn no longer refreshes');
+
+    rebuildDeferredToolSurfaceForProvider(noOpSession, 'xai');
+    noOpSession.provider = 'xai';
+    const beforeNoOp = systemContent(noOpSession);
+    assert.equal(beforeNoOp.includes('<available-deferred-tools>'), false, 'canonical switch removes native manifest state');
+    assert.equal(firstTurnGate(noOpSession, []), 'refresh-noop', 'canonical provider consumes an empty one-shot without a manifest refresh');
+    assert.equal(noOpSession.deferredInitialRefreshPending, false, 'no-op also consumes the fresh flag');
+    assert.equal(systemContent(noOpSession), beforeNoOp, 'canonical no-op leaves the initial manifest byte-identical');
+
+    rebuildDeferredToolSurfaceForProvider(noOpSession, 'anthropic-oauth');
+    noOpSession.provider = 'anthropic-oauth';
+    assert.equal(firstTurnGate(noOpSession, [mcpTool2]), 'late', 'switching back cannot resurrect first-turn refresh state');
+    assert.ok(!noOpSession.deferredAnnouncedTools.includes('mcp__unity__run_tests'), 'post-switch tool remains eligible for the late path');
+});
+
+test('legacy canonical snapshot gains a grace-connected MCP tool for the first turn and session lifetime', () => {
+    const session = createdSession('legacy');
     session.deferredInitialRefreshPending = true;
-    assert.equal(firstTurnGate(session, [mcpTool]), 'refreshed', 'fresh session refreshes on its first turn');
-    assert.equal(session.deferredInitialRefreshPending, false, 'fresh flag consumed (one-shot)');
-    assert.ok(session.deferredAnnouncedTools.includes('mcp__unity__get_scene'), 'first-turn MCP pre-announced');
-    assert.equal(firstTurnGate(session, [mcpTool2]), 'late', 'second turn no longer refreshes');
+    const before = systemContent(session);
+
+    assert.equal(firstTurnGate(session, [mcpTool]), 'refreshed', 'grace fold updates the canonical snapshot');
+    assert.ok(session.tools.some((tool) => tool.name === mcpTool.name), 'tool is provider-visible on the first turn');
+    assert.ok(session.deferredCallableTools.includes(mcpTool.name), 'tool is callable for the session');
+    assert.ok(session.deferredToolCatalog.some((tool) => tool.name === mcpTool.name), 'tool persists in the session catalog');
+    assert.equal(systemContent(session), before, 'canonical refresh does not introduce a native manifest');
+    assert.equal(systemContent(session).includes('<available-deferred-tools>'), false);
+
+    const toolsOnce = JSON.stringify(session.tools);
+    assert.equal(refreshInitialDeferredMcpSurface(session, [mcpTool]), false, 'repeated fold is a no-op');
+    assert.equal(JSON.stringify(session.tools), toolsOnce, 'repeated fold leaves the fixed surface byte-identical');
+    assert.equal(firstTurnGate(session, [mcpTool]), 'late', 'one-shot gate remains consumed');
+});
+
+test('legacy to Anthropic and back preserves grace MCP availability without manifest leakage or duplication', () => {
+    const session = createdSession('legacy');
+    assert.equal(refreshInitialDeferredMcpSurface(session, [mcpTool]), true);
+
+    rebuildDeferredToolSurfaceForProvider(session, 'anthropic-oauth');
+    session.provider = 'anthropic-oauth';
+    assert.ok(session.deferredToolCatalog.some((tool) => tool.name === mcpTool.name), 'native switch retains the MCP catalog entry');
+    assert.ok(systemContent(session).includes(mcpTool.name), 'native switch advertises the retained deferred tool');
+    assert.equal((systemContent(session).match(/<available-deferred-tools>/g) || []).length, 1, 'native switch creates one manifest');
+
+    rebuildDeferredToolSurfaceForProvider(session, 'legacy');
+    session.provider = 'legacy';
+    assert.ok(session.tools.some((tool) => tool.name === mcpTool.name), 'canonical switch restores the MCP tool to the active surface');
+    assert.ok(session.deferredCallableTools.includes(mcpTool.name), 'canonical switch keeps the MCP tool callable');
+    assert.equal(systemContent(session).includes('<available-deferred-tools>'), false, 'native manifest does not leak back to canonical');
+    assert.deepEqual(session.deferredAnnouncedTools, [], 'native announcement state does not leak back to canonical');
+
+    rebuildDeferredToolSurfaceForProvider(session, 'anthropic-oauth');
+    session.provider = 'anthropic-oauth';
+    assert.equal((systemContent(session).match(/<available-deferred-tools>/g) || []).length, 1, 'repeat switch still creates only one manifest');
+});
+
+test('canonical MCP arriving after the first-turn grace keeps the fixed snapshot and emits no late reminder', () => {
+    const session = createdSession('legacy');
+    session.deferredInitialRefreshPending = true;
+    assert.equal(firstTurnGate(session, []), 'refresh-noop');
+    const before = JSON.stringify(session.tools);
+    let enqueued = null;
+
+    const result = reconcileDeferredMcpToolCatalog(session, [mcpTool2], {
+        enqueue: (text) => { enqueued = text; return true; },
+    });
+    assert.equal(result, null, 'canonical reconciliation keeps the create/grace snapshot fixed');
+    assert.equal(JSON.stringify(session.tools), before, 'post-grace MCP does not churn the canonical surface');
+    assert.equal(session.deferredToolCatalog.some((tool) => tool.name === mcpTool2.name), false);
+    assert.equal(enqueued, null, 'canonical provider emits no native late reminder');
+    assert.equal(systemContent(session).includes('<available-deferred-tools>'), false);
 });