@animalabs/agent-framework 0.22.1 → 0.22.2

package/dist/test/present-while-acting.test.js

@@ -22,6 +22,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { AgentFramework } from '../src/index.js';
 import { MockMembrane, createMockResponse } from './helpers/mock-membrane.js';
+import { MembraneError } from '@animalabs/membrane';
+import { JsStore } from '@animalabs/chronicle';
 // ---------------------------------------------------------------------------
 // Test module: tools that optionally emit a mid-turn external message
 // ---------------------------------------------------------------------------
@@ -39,8 +41,18 @@ class RobotModule {
     interjectionMetadata = null;
     /** Delay tool completion so live routing deterministically precedes it. */
     toolDelayMs = 0;
+    /** Run once, during the next turn start's context gathering (the turn is
+     *  alive and its stream doesn't exist yet). */
+    startHook = null;
     async start(_ctx) { }
     async stop() { }
+    async gatherContext() {
+        const hook = this.startHook;
+        this.startHook = null;
+        if (hook)
+            await hook();
+        return [];
+    }
     getTools() {
         return [
             {
@@ -150,12 +162,12 @@ describe('present while acting', () => {
     afterEach(() => {
         rmSync(tempDir, { recursive: true, force: true });
     });
-    async function createFramework() {
+    async function createFramework(agentOptions = {}) {
         const framework = await AgentFramework.create({
             storePath: join(tempDir, 'test.chronicle'),
             membrane: membrane.asMembrane(),
             agents: [
-                { name: 'assistant', model: 'test-model', systemPrompt: 'You are a robot pilot.' },
+                { name: 'assistant', model: 'test-model', systemPrompt: 'You are a robot pilot.', ...agentOptions },
             ],
             modules: [module],
         });
@@ -335,11 +347,11 @@ describe('present while acting', () => {
         };
         // Simulate an explicit send into #portables earlier in THIS turn (the
         // production record happens on the MCPL send path; the harness module's
-        // tools are not MCPL, so seed the turn-scoped set mid-turn — after the
-        // turn-start clear, before the injection boundary).
+        // tools are not MCPL, so seed the turn's engaged set mid-turn — after
+        // the turn opens, before the injection boundary).
         const origHandle = module.handleToolCall.bind(module);
         module.handleToolCall = async (call) => {
-            framework.turnEngagedChannels.set('assistant', new Set(['discord:guild:portables']));
+            framework.turnRouting.get('assistant').engaged.add('discord:guild:portables');
             return origHandle(call);
         };
         trigger(framework);
@@ -371,7 +383,7 @@ describe('present while acting', () => {
         };
         const origHandle = module.handleToolCall.bind(module);
         module.handleToolCall = async (call) => {
-            framework.turnEngagedChannels.set('assistant', new Set(['discord:guild:hospital']));
+            framework.turnRouting.get('assistant').engaged.add('discord:guild:hospital');
             return origHandle(call);
         };
         trigger(framework);
@@ -432,6 +444,937 @@ describe('present while acting', () => {
         assert.equal(notices.length, 1, 'only the boot-baseline announcement — no re-pin chatter');
         await framework.stop();
     });
+    // -------------------------------------------------------------------------
+    // Every later start of the turn keeps its locus
+    // -------------------------------------------------------------------------
+    // A framework retry, the compile a capacity hold defers a turn to, the
+    // re-inference on unstreamed tool results and a budget restart all keep
+    // the turn's locus, re-pins included. A message that no tool boundary
+    // weighed, because none of the turn's streams was running or its boundary
+    // couldn't re-pin, still moves it at the turn's next start, by the mid-turn
+    // rule: a conversational message that addressed the agent, or that follows
+    // up in a channel the turn sent into.
+    /** Make each stream in `indices` (1-based) end with `error` instead of completing. */
+    function failStream(indices, error) {
+        const failing = new Set(Array.isArray(indices) ? indices : [indices]);
+        const makeStream = membrane.streamYielding.bind(membrane);
+        let streams = 0;
+        membrane.streamYielding = (request, options) => {
+            const stream = makeStream(request, options);
+            const n = ++streams;
+            const iterate = stream[Symbol.asyncIterator].bind(stream);
+            stream[Symbol.asyncIterator] = async function* () {
+                for await (const event of { [Symbol.asyncIterator]: iterate }) {
+                    if (event.type === 'complete' && failing.has(n)) {
+                        yield { type: 'error', error: error(request) };
+                        return;
+                    }
+                    yield event;
+                }
+            };
+            return stream;
+        };
+    }
+    /** Feed a response to the Nth turn start (1-based) the moment it begins. */
+    function feedStart(framework, start, ...responses) {
+        let starts = 0;
+        framework.onTrace((event) => {
+            if (event.type !== 'inference:started' || ++starts !== start)
+                return;
+            responses.forEach((blocks, i) => membrane.pushResponse(createMockResponse(blocks, i < responses.length - 1 ? 'tool_use' : undefined)));
+        });
+    }
+    /** An organization acceleration 429, which holds the turn for a later compile. */
+    const accelerationLimit = (request) => new MembraneError({
+        type: 'rate_limit', retryable: true, httpStatus: 429,
+        message: "This request would exceed your organization's maximum usage increase rate for input tokens per minute",
+        rawError: { status: 429 }, rawRequest: request,
+    });
+    /** Bring the agent's capacity hold to its deadline and release it, as its
+     *  timer does then, and run the deferred compile. */
+    async function release(framework) {
+        const internals = framework;
+        const hold = internals.providerAccelerationCooldowns.get('assistant');
+        assert.ok(hold, 'the turn is held');
+        hold.until = Date.now();
+        internals.releaseProviderAccelerationCooldown('assistant');
+        await framework.runUntilIdle();
+    }
+    /** A message someone sends, stored as the test module stores it. */
+    async function say(framework, text, metadata) {
+        framework.pushEvent({ type: 'external-message', source: 'test', content: text, metadata });
+        await framework.runUntilIdle();
+    }
+    /** Remove a stored message, as the retraction of an unread coalesced message does (removePlacement). */
+    function withdraw(framework, text) {
+        const cm = framework.getAgent('assistant').getContextManager();
+        const message = cm.getAllMessages().find((m) => m.content.some((b) => b.type === 'text' && b.text === text));
+        assert.ok(message, `"${text}" is stored`);
+        cm.removeMessage(message.id);
+    }
+    const addressed = (channelId) => ({ channelId, tags: ['chat:addressed'] });
+    const ambient = (channelId) => ({ channelId, tags: ['chat:ambient', 'chat:from-human'] });
+    /** The `[routing] The conversation moved to …` notices, by channel. */
+    const movedTo = (framework) => framework.getAgent('assistant').getContextManager().getAllMessages()
+        .filter((m) => m.metadata?.kind === 'routing-notice')
+        .flatMap((m) => m.content.filter((b) => b.type === 'text').map((b) => b.text))
+        .map((text) => /^\[routing\] The conversation moved to (\S+) /.exec(text)?.[1])
+        .filter((channel) => channel !== undefined);
+    it("a framework retry keeps the turn's locus, a mid-turn re-pin included", async () => {
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        module.interjection = 'quick question for you';
+        module.interjectionMetadata = addressed('discord:dm:antra');
+        failStream(1, () => new Error('synthetic transient stream error'));
+        feedStart(framework, 2, [{ type: 'text', text: 'Answering after the retry.' }]);
+        trigger(framework);
+        await framework.runUntilIdle();
+        assert.equal(membrane.calls.length, 2, 'the error was retried');
+        assert.deepEqual(routed, [
+            { text: 'Answering after the retry.', locus: 'discord:dm:antra' },
+        ], 'the retry speaks where the re-pin moved the turn, not at a re-resolved locus');
+        await framework.stop();
+    });
+    for (const [label, metadata, expected] of [
+        ['an addressed message from another channel moves the locus there, with the notice',
+            addressed('discord:dm:antra'), 'discord:dm:antra'],
+        ['ambient traffic in another channel leaves the locus where it was',
+            ambient('discord:guild:lounge'), 'chan-live-1'],
+        // Tune-out stamps a message it diverts, and a resident's compiled view
+        // leaves it out, so the agent never sees it.
+        ['an addressed message that tune-out diverts leaves the locus where it was',
+            { ...addressed('discord:dm:antra'), tuneOut: { epochId: 'epoch-1' } }, 'chan-live-1'],
+        ['an addressed system marker from another channel leaves the locus where it was',
+            { ...addressed('discord:dm:antra'), system: true }, 'chan-live-1'],
+    ]) {
+        it(`during a capacity hold, ${label}`, async () => {
+            membrane.pushResponse(createMockResponse([
+                { type: 'text', text: 'On it.' },
+                { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+            ], 'tool_use'));
+            membrane.pushResponse(createMockResponse([]));
+            const framework = await createFramework();
+            const routed = stubChannelRegistry(framework);
+            module.toolDelayMs = 25;
+            failStream(1, accelerationLimit);
+            feedStart(framework, 2, [{ type: 'text', text: 'Here is the rest.' }]);
+            trigger(framework);
+            await framework.runUntilIdle();
+            // No turn is alive during the hold, so the message is stored at once.
+            await say(framework, 'a message during the hold', metadata);
+            assert.equal(membrane.calls.length, 1, 'the turn is still held');
+            await release(framework);
+            assert.equal(membrane.calls.length, 2, 'one deferred compile');
+            assert.deepEqual(routed, [
+                { text: 'On it.', locus: 'chan-live-1' },
+                { text: 'Here is the rest.', locus: expected },
+            ]);
+            assert.deepEqual(movedTo(framework), expected === 'chan-live-1' ? [] : [expected], 'a re-pin tells the agent, and nothing else does');
+            await framework.stop();
+        });
+    }
+    for (const [label, messages, expected] of [
+        ['an addressed message withdrawn before the deferred compile moves nothing',
+            [['soon withdrawn', 'discord:dm:antra', true]], 'chan-live-1'],
+        ['the newest addressed message that remains moves the locus, when a newer one is withdrawn',
+            [['still there', 'discord:dm:antra', false], ['soon withdrawn', 'discord:dm:q', true]], 'discord:dm:antra'],
+    ]) {
+        it(`during a capacity hold, ${label}`, async () => {
+            membrane.pushResponse(createMockResponse([
+                { type: 'text', text: 'On it.' },
+                { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+            ], 'tool_use'));
+            membrane.pushResponse(createMockResponse([]));
+            const framework = await createFramework();
+            const routed = stubChannelRegistry(framework);
+            module.toolDelayMs = 25;
+            failStream(1, accelerationLimit);
+            feedStart(framework, 2, [{ type: 'text', text: 'Here is the rest.' }]);
+            trigger(framework);
+            await framework.runUntilIdle();
+            for (const [text, channelId] of messages)
+                await say(framework, text, addressed(channelId));
+            // Each withdrawn message leaves the agent's store before the turn's
+            // next start, so the agent never sees it there.
+            for (const [text, , withdrawn] of messages)
+                if (withdrawn)
+                    withdraw(framework, text);
+            await release(framework);
+            assert.equal(membrane.calls.length, 2, 'one deferred compile');
+            assert.deepEqual(routed, [
+                { text: 'On it.', locus: 'chan-live-1' },
+                { text: 'Here is the rest.', locus: expected },
+            ]);
+            assert.deepEqual(movedTo(framework), expected === 'chan-live-1' ? [] : [expected], 'a re-pin tells the agent, and nothing else does');
+            await framework.stop();
+        });
+    }
+    it("during a capacity hold, a store that can't be read at the deferred compile fails the start rather than drop the arrival", async () => {
+        // Adapted from a reviewer's probe: a read that fails says nothing about
+        // whether the message is there, so it can't count as a withdrawal.
+        membrane.pushResponse(createMockResponse([
+            { type: 'text', text: 'On it.' },
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        failStream(1, accelerationLimit);
+        // Were the failed read taken as a withdrawal, the compile would run and
+        // answer here, at the turn's old channel.
+        feedStart(framework, 2, [{ type: 'text', text: 'Here is the rest.' }]);
+        trigger(framework);
+        await framework.runUntilIdle();
+        await say(framework, 'a question for you', addressed('discord:dm:antra'));
+        const cm = framework.getAgent('assistant').getContextManager();
+        const arrival = cm.getAllMessages().find((m) => m.content.some((b) => b.type === 'text' && b.text === 'a question for you'));
+        const getMessage = cm.getMessage.bind(cm);
+        cm.getMessage = (id) => {
+            if (id === arrival.id)
+                throw new Error('store unavailable');
+            return getMessage(id);
+        };
+        try {
+            await assert.rejects(release(framework), /store unavailable/);
+        }
+        finally {
+            cm.getMessage = getMessage;
+        }
+        assert.equal(membrane.calls.length, 1, 'the deferred compile never ran');
+        assert.deepEqual(routed, [{ text: 'On it.', locus: 'chan-live-1' }], 'and the turn spoke nowhere else');
+        assert.deepEqual(movedTo(framework), [], 'nor told the agent of a move');
+        await framework.stop();
+    });
+    it("a message a tool boundary already weighed doesn't take the locus back at a later start", async () => {
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c2', name: 'robot--move', input: { dir: 'east' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        const internals = framework;
+        const origHandle = module.handleToolCall.bind(module);
+        module.handleToolCall = async (call) => {
+            if (call.id === 'c1') {
+                // Someone addresses the agent from a DM: the first boundary re-pins
+                // there. The message's wake waits behind the turn, as a real one
+                // would, and is released with the hold.
+                module.interjection = 'quick question for you';
+                module.interjectionMetadata = addressed('discord:dm:antra');
+                internals.pendingRequests.push({
+                    agentName: 'assistant', reason: 'channel-message', source: 'test', timestamp: Date.now(),
+                    channelId: 'discord:dm:antra', addressed: true,
+                });
+            }
+            else {
+                // The turn sent into #portables, and a follow-up there re-pins the
+                // second boundary (seeded: this module's tools aren't MCPL sends).
+                internals.turnRouting.get('assistant').engaged.add('discord:guild:portables');
+                module.interjection = 'replying on portables';
+                module.interjectionMetadata = ambient('discord:guild:portables');
+            }
+            return origHandle(call);
+        };
+        failStream(1, accelerationLimit);
+        feedStart(framework, 2, [{ type: 'text', text: 'Back now.' }]);
+        trigger(framework);
+        await framework.runUntilIdle();
+        await release(framework);
+        assert.equal(membrane.calls.length, 2, 'one deferred compile');
+        assert.deepEqual(routed, [
+            { text: 'Back now.', locus: 'discord:guild:portables' },
+        ], "the DM, weighed at the first boundary, doesn't move the locus back from #portables");
+        assert.deepEqual(movedTo(framework), ['discord:dm:antra', 'discord:guild:portables']);
+        await framework.stop();
+    });
+    it("an arrival a start has used doesn't move the locus again after a later re-pin", async () => {
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        const origHandle = module.handleToolCall.bind(module);
+        module.handleToolCall = async (call) => {
+            if (call.id === 'c2') {
+                // In the second stream, someone else addresses the agent: its boundary re-pins.
+                module.interjection = 'over here now';
+                module.interjectionMetadata = addressed('discord:dm:q');
+            }
+            return origHandle(call);
+        };
+        failStream([1, 2], accelerationLimit);
+        feedStart(framework, 2, [{ type: 'tool_use', id: 'c2', name: 'robot--move', input: { dir: 'east' } }], []);
+        feedStart(framework, 3, [{ type: 'text', text: 'Back now.' }]);
+        trigger(framework);
+        await framework.runUntilIdle();
+        await say(framework, 'quick question for you', addressed('discord:dm:antra'));
+        // The first release uses the DM; its stream re-pins to q, then is held again.
+        await release(framework);
+        assert.equal(membrane.calls.length, 2);
+        await release(framework);
+        assert.equal(membrane.calls.length, 3, 'two deferred compiles');
+        assert.deepEqual(movedTo(framework), ['discord:dm:antra', 'discord:dm:q']);
+        assert.deepEqual(routed, [
+            { text: 'Back now.', locus: 'discord:dm:q' },
+        ], 'the second release keeps the re-pin its stream made');
+        await framework.stop();
+    });
+    it('a message deferred in a start that fails before its stream lands then, so a newer one during the hold wins', async () => {
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        // The host holds the agent once when its stream can't be set up. (Asked
+        // again at the release, it lets the hold go.)
+        let hostHolds = 0;
+        framework
+            .providerHoldHook = (error) => error.message === 'stream setup failed' && hostHolds++ === 0
+            ? { holdMs: 60_000, reason: 'host hold' } : undefined;
+        // Stream one is held at its end; the start after the first release
+        // fails before its stream exists, and the host holds it; the third start
+        // answers.
+        const makeStream = membrane.streamYielding.bind(membrane);
+        let calls = 0;
+        membrane.streamYielding = (request, options) => {
+            const n = ++calls;
+            if (n === 2)
+                throw new Error('stream setup failed');
+            const stream = makeStream(request, options);
+            const iterate = stream[Symbol.asyncIterator].bind(stream);
+            stream[Symbol.asyncIterator] = async function* () {
+                for await (const event of { [Symbol.asyncIterator]: iterate }) {
+                    if (event.type === 'complete' && n === 1) {
+                        yield { type: 'error', error: accelerationLimit(request) };
+                        return;
+                    }
+                    yield event;
+                }
+            };
+            return stream;
+        };
+        feedStart(framework, 2, [{ type: 'text', text: 'Back now.' }]);
+        trigger(framework);
+        await framework.runUntilIdle();
+        // During the second start, before its stream exists, a DM arrives and is
+        // deferred: the start holds the turn. (Written directly: the run loop
+        // that would store an event's message is busy with this start.)
+        const store = framework;
+        let deferredInStart = -1;
+        module.startHook = async () => {
+            store.addMessage('Antra', [{ type: 'text', text: 'quick question for you' }], addressed('discord:dm:antra'));
+            deferredInStart = store.deferredMessages.length;
+        };
+        await release(framework);
+        assert.equal(deferredInStart, 1, 'the DM was deferred while the start held the turn');
+        assert.equal(calls, 2, 'the second start failed before its stream');
+        // During the second hold, someone else addresses the agent.
+        await say(framework, 'over here', addressed('discord:dm:q'));
+        await release(framework);
+        assert.equal(calls, 3, 'the third start compiled');
+        assert.deepEqual(routed, [
+            { text: 'Back now.', locus: 'discord:dm:q' },
+        ], 'the newer message wins: the deferred one landed when its start failed');
+        await framework.stop();
+    });
+    for (const [label, withdrawn, expected] of [
+        ['re-pins to an addressed message its over-budget boundary left unweighed', false, 'discord:dm:antra'],
+        ['moves nothing for such a message withdrawn before it starts', true, 'chan-live-1'],
+    ]) {
+        it(`a budget restart ${label}`, async () => {
+            const overBudget = createMockResponse([
+                { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+            ], 'tool_use');
+            overBudget.usage = { inputTokens: 100, outputTokens: 5 };
+            membrane.pushResponse(overBudget);
+            const framework = await createFramework({ maxStreamTokens: 20 });
+            const routed = stubChannelRegistry(framework);
+            module.toolDelayMs = 25;
+            module.interjection = 'quick question for you';
+            module.interjectionMetadata = addressed('discord:dm:antra');
+            feedStart(framework, 2, [{ type: 'text', text: 'After the restart.' }]);
+            if (withdrawn) {
+                // The boundary has stored the message and left it to the restart as
+                // an arrival, by the id it was stored under; it leaves the store
+                // before the restart starts.
+                framework.onTrace((event) => {
+                    if (event.type === 'inference:stream_restarted')
+                        withdraw(framework, 'quick question for you');
+                });
+            }
+            trigger(framework);
+            await framework.runUntilIdle();
+            assert.equal(membrane.calls.length, 2, 'the turn restarted for its budget');
+            assert.deepEqual(routed, [
+                { text: 'After the restart.', locus: expected },
+            ]);
+            assert.deepEqual(movedTo(framework), withdrawn ? [] : [expected]);
+            await framework.stop();
+        });
+    }
+    for (const [label, messages, expected] of [
+        ["keeps the turn's locus", [], 'chan-turn'],
+        ['moves it to the newest addressed arrival',
+            [addressed('discord:dm:antra'), addressed('discord:dm:q')], 'discord:dm:q'],
+        ['moves it to a follow-up in a channel the turn engaged',
+            [ambient('discord:guild:portables')], 'discord:guild:portables'],
+        ['leaves it for a reaction in a channel the turn engaged',
+            [{ channelId: 'discord:guild:portables', tags: ['chat:reaction'] }], 'chan-turn'],
+    ]) {
+        it(`a re-inference on unstreamed tool results ${label}`, async () => {
+            membrane.pushResponse(createMockResponse([{ type: 'text', text: 'Carrying on.' }]));
+            const framework = await createFramework();
+            const routed = stubChannelRegistry(framework);
+            const internals = framework;
+            // The turn's earlier stream froze `chan-turn` as its locus, sent into
+            // #portables, and left its tool results for the non-streaming
+            // fallback's re-inference. Messages arrive before that starts.
+            const open = {
+                locus: 'chan-turn', triggerChannel: 'chan-turn', engaged: new Set(['discord:guild:portables']),
+                destination: null, hybridHold: false, continuation: false, deliveries: [], suppressed: 0, arrivals: [],
+            };
+            internals.turnRouting.set('assistant', open);
+            internals.openLogical.set('assistant', open);
+            for (const metadata of messages)
+                await say(framework, 'a message', metadata);
+            internals.pendingRequests.push({ agentName: 'assistant', reason: 'tool_results_ready', source: 'framework', timestamp: Date.now() });
+            await framework.runUntilIdle();
+            assert.deepEqual(routed, [{ text: 'Carrying on.', locus: expected }]);
+            assert.deepEqual(movedTo(framework), expected === 'chan-turn' ? [] : [expected], 'a re-pin leaves its notice');
+            await framework.stop();
+        });
+    }
+    it('the start that continues the turn weighs a message its own flush lands, and a delivery assembled for it', async () => {
+        membrane.pushResponse(createMockResponse([{ type: 'text', text: 'Carrying on.' }]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        const internals = framework;
+        const open = {
+            locus: 'chan-turn', triggerChannel: 'chan-turn', engaged: new Set(),
+            destination: null, hybridHold: false, continuation: false, deliveries: [], suppressed: 0, arrivals: [],
+        };
+        internals.turnRouting.set('assistant', open);
+        internals.openLogical.set('assistant', open);
+        try {
+            // A delivery assembled while a start of the turn holds it (the
+            // coalescing assembly writes past the deferral) is an arrival too.
+            internals.activeTurnTokens.set('assistant', -1);
+            internals.addMessage('Antra', [{ type: 'text', text: 'batched' }], addressed('discord:dm:q'), { bypassDeferralFor: 'assistant' });
+            internals.activeTurnTokens.delete('assistant');
+            assert.deepEqual(open.arrivals.map((a) => a.channelId), ['discord:dm:q']);
+            // A message still deferred when the turn's next start begins lands in
+            // that start's own flush, and is the newest arrival.
+            internals.deferredMessages.push({
+                id: 'deferred-1', seq: 1, participant: 'Antra', forAgent: 'assistant',
+                content: [{ type: 'text', text: 'quick question for you' }], metadata: addressed('discord:dm:antra'),
+            });
+            internals.pendingRequests.push({ agentName: 'assistant', reason: 'tool_results_ready', source: 'framework', timestamp: Date.now() });
+            await framework.runUntilIdle();
+            assert.deepEqual(routed, [{ text: 'Carrying on.', locus: 'discord:dm:antra' }]);
+            assert.deepEqual(movedTo(framework), ['discord:dm:antra']);
+        }
+        finally {
+            await framework.stop();
+        }
+    });
+    it('a start that throws before its stream ends its logical turn, so the next start opens its own', async () => {
+        membrane.pushResponse(createMockResponse([{ type: 'text', text: 'Hello there.' }]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        // The registry is unavailable for the first start, which throws after it
+        // has opened its turn, outside the stream's own failure handling.
+        const registry = framework.channelRegistry;
+        const resolve = registry.resolveLocus;
+        let failed = false;
+        registry.resolveLocus = (agent) => {
+            if (!failed) {
+                failed = true;
+                throw new Error('registry unavailable');
+            }
+            return resolve(agent);
+        };
+        const internals = framework;
+        trigger(framework);
+        await assert.rejects(framework.runUntilIdle(), /registry unavailable/);
+        assert.equal(internals.openLogical.has('assistant'), false, 'the failed start left no turn open');
+        trigger(framework);
+        await framework.runUntilIdle();
+        assert.deepEqual(routed, [{ text: 'Hello there.', locus: 'chan-live-1' }], 'the next start resolved a locus of its own');
+        await framework.stop();
+    });
+    it("a silent turn's tool boundary doesn't re-pin its locus or tell it the conversation moved", async () => {
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([{ type: 'text', text: 'quiet' }]));
+        const framework = await createFramework();
+        stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        module.interjection = 'quick question for you';
+        module.interjectionMetadata = addressed('discord:dm:antra');
+        const internals = framework;
+        internals.pendingRequests.push({
+            agentName: 'assistant', reason: 'heartbeat', source: 'framework', timestamp: Date.now(), suppressProse: true,
+        });
+        await framework.runUntilIdle();
+        assert.equal(module.interjection, null, 'the silent turn ran its tool round, and the DM arrived during it');
+        assert.deepEqual(movedTo(framework), [], 'no routing notice in a turn that routes no prose');
+        await framework.stop();
+    });
+    it("a start that continues the turn and throws before it takes the turn's routing still ends the turn", async () => {
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        failStream(1, accelerationLimit);
+        feedStart(framework, 2, [{ type: 'text', text: 'A new turn.' }]);
+        const internals = framework;
+        trigger(framework);
+        await framework.runUntilIdle();
+        assert.equal(internals.openLogical.has('assistant'), true, 'the held turn is open');
+        // The deferred compile's checkpoint fails before the start takes the turn.
+        const checkpoint = internals.recordTurnCheckpoint.bind(framework);
+        internals.recordTurnCheckpoint = () => { throw new Error('checkpoint failed'); };
+        await assert.rejects(release(framework), /checkpoint failed/);
+        internals.recordTurnCheckpoint = checkpoint;
+        assert.equal(internals.openLogical.has('assistant'), false, 'the held turn ended with its failed compile');
+        trigger(framework);
+        await framework.runUntilIdle();
+        assert.deepEqual(routed, [{ text: 'A new turn.', locus: 'chan-live-2' }], 'the next start opened its own turn and resolved its own locus');
+        await framework.stop();
+    });
+    it("an ephemeral run whose start throws outside its stream fails with that error, not by its watchdog", async () => {
+        // Adapted from a reviewer's probe. On main the run waited for its startup
+        // watchdog (30 s by default), which fails it as a zombie.
+        const framework = await AgentFramework.create({
+            storePath: join(tempDir, 'ephemeral.chronicle'),
+            membrane: membrane.asMembrane(),
+            agents: [],
+            modules: [],
+            syncIntervalMs: 0,
+        });
+        const internals = framework;
+        const checkpoint = internals.recordTurnCheckpoint.bind(framework);
+        internals.recordTurnCheckpoint = (agentName) => {
+            if (agentName === 'worker')
+                throw new Error('checkpoint store unavailable');
+            checkpoint(agentName);
+        };
+        const error = console.error;
+        console.error = () => { };
+        try {
+            const { agent, contextManager } = await framework.createEphemeralAgent({
+                name: 'worker', model: 'test-model', systemPrompt: 'Do the task.', allowedTools: 'all',
+            });
+            contextManager.addMessage('user', [{ type: 'text', text: 'Run once.' }]);
+            const run = framework.runEphemeralToCompletion(agent, contextManager, { startupTimeoutMs: 3_000 });
+            framework.start();
+            await assert.rejects(run, /checkpoint store unavailable/, "the run fails with its start's error");
+        }
+        finally {
+            console.error = error;
+            await framework.stop();
+        }
+    });
+    it("a silent start that throws leaves an open prose turn alone", async () => {
+        const framework = await createFramework();
+        stubChannelRegistry(framework);
+        const internals = framework;
+        const open = {
+            locus: 'chan-turn', engaged: new Set(), destination: null, hybridHold: false,
+            continuation: false, deliveries: [], suppressed: 0, arrivals: [],
+        };
+        internals.openLogical.set('assistant', open);
+        internals.recordTurnCheckpoint = () => { throw new Error('checkpoint failed'); };
+        internals.pendingRequests.push({
+            agentName: 'assistant', reason: 'heartbeat', source: 'framework', timestamp: Date.now(), suppressProse: true,
+        });
+        await assert.rejects(framework.runUntilIdle(), /checkpoint failed/);
+        assert.equal(internals.openLogical.get('assistant'), open);
+        await framework.stop();
+    });
+    it("a resume after stop() continues its turn, and opens it again for the turn's later starts", async () => {
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        const routed = stubChannelRegistry(framework);
+        failStream(1, () => new Error('synthetic transient stream error'));
+        feedStart(framework, 2, [{ type: 'text', text: 'After the retry.' }]);
+        const internals = framework;
+        // A turn that crossed its budget before a stop(): its routing state is
+        // live, and stop() ended every open turn. Its budget restart now runs,
+        // and its stream fails and is retried.
+        const turn = {
+            locus: 'chan-turn', triggerChannel: 'chan-turn', engaged: new Set(), destination: null, hybridHold: false,
+            continuation: false, deliveries: [], suppressed: 0, arrivals: [],
+        };
+        internals.turnRouting.set('assistant', turn);
+        internals.pendingRequests.push({
+            agentName: 'assistant', reason: 'context_budget_restart', source: 'framework', timestamp: Date.now(),
+        });
+        // The retry of a resume is a resume too, and takes the turn's routing
+        // state whatever is open. The turn must be open while its streams run, so
+        // that its other later starts, such as a re-inference on unstreamed tool
+        // results, continue it rather than open a new one.
+        const openAtStart = [];
+        framework.onTrace((event) => {
+            if (event.type === 'inference:started')
+                openAtStart.push(internals.openLogical.get('assistant'));
+        });
+        await framework.runUntilIdle();
+        assert.equal(membrane.calls.length, 2, 'the restart was retried');
+        assert.deepEqual(openAtStart.map((open) => open === turn), [true, true], 'the resumed turn was open again while each of its streams ran');
+        assert.equal(internals.openLogical.get('assistant'), undefined, "the turn completed");
+        assert.deepEqual(routed, [{ text: 'After the retry.', locus: 'chan-turn' }], "the retry continued the resumed turn's routing");
+        await framework.stop();
+    });
+    it("a silent turn's over-budget boundary leaves no arrival on an open prose turn", async () => {
+        const overBudget = createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use');
+        overBudget.usage = { inputTokens: 100, outputTokens: 5 };
+        membrane.pushResponse(overBudget);
+        const framework = await createFramework({ maxStreamTokens: 20 });
+        const routed = stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        module.interjection = 'quick question for you';
+        module.interjectionMetadata = addressed('discord:dm:antra');
+        feedStart(framework, 2, [{ type: 'text', text: 'quiet' }]);
+        const internals = framework;
+        // Built by hand, as #312's silent-start test does: production runs no
+        // silent turn while a prose turn is open.
+        const open = {
+            locus: 'chan-turn', engaged: new Set(), destination: null, hybridHold: false,
+            continuation: false, deliveries: [], suppressed: 0, arrivals: [],
+        };
+        internals.openLogical.set('assistant', open);
+        internals.pendingRequests.push({
+            agentName: 'assistant', reason: 'heartbeat', source: 'framework', timestamp: Date.now(), suppressProse: true,
+        });
+        await framework.runUntilIdle();
+        assert.equal(membrane.calls.length, 2, 'the silent turn crossed its budget and restarted');
+        assert.deepEqual(routed, [], 'and its restart stayed silent');
+        assert.equal(module.interjection, null, 'the DM arrived during its tool round');
+        assert.deepEqual(open.arrivals, [], "the silent turn's injections are no arrival of the prose turn");
+        await framework.stop();
+    });
+    it("a failed start's flush stores each deferred message on its own, so one failure loses no other", async () => {
+        membrane.pushResponse(createMockResponse([
+            { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+        ], 'tool_use'));
+        membrane.pushResponse(createMockResponse([]));
+        const framework = await createFramework();
+        stubChannelRegistry(framework);
+        module.toolDelayMs = 25;
+        let hostHolds = 0;
+        framework
+            .providerHoldHook = (error) => error.message === 'stream setup failed' && hostHolds++ === 0
+            ? { holdMs: 60_000, reason: 'host hold' } : undefined;
+        const makeStream = membrane.streamYielding.bind(membrane);
+        let calls = 0;
+        membrane.streamYielding = (request, options) => {
+            const n = ++calls;
+            if (n === 2)
+                throw new Error('stream setup failed');
+            const stream = makeStream(request, options);
+            const iterate = stream[Symbol.asyncIterator].bind(stream);
+            stream[Symbol.asyncIterator] = async function* () {
+                for await (const event of { [Symbol.asyncIterator]: iterate }) {
+                    if (event.type === 'complete' && n === 1) {
+                        yield { type: 'error', error: accelerationLimit(request) };
+                        return;
+                    }
+                    yield event;
+                }
+            };
+            return stream;
+        };
+        const store = framework;
+        const add = store.addMessage.bind(framework);
+        // The store refuses the first message when the failed start's flush lands it.
+        store.addMessage = (participant, content, metadata, opts) => {
+            if (opts?.deferredWriteId && content[0].text === 'poison')
+                throw new Error('store refused');
+            return add(participant, content, metadata, opts);
+        };
+        trigger(framework);
+        await framework.runUntilIdle();
+        module.startHook = async () => {
+            store.addMessage('Antra', [{ type: 'text', text: 'poison' }], {});
+            store.addMessage('Antra', [{ type: 'text', text: 'second' }], {});
+        };
+        await release(framework);
+        assert.equal(calls, 2, 'the second start failed before its stream');
+        const texts = framework.getAgent('assistant').getContextManager().getAllMessages()
+            .flatMap((m) => m.content.filter((b) => b.type === 'text').map((b) => b.text));
+        assert.ok(texts.includes('second'), 'the message behind the refused one was stored');
+        assert.ok(!texts.includes('poison'));
+        await framework.stop();
+    });
+    for (const [label, notice] of [
+        ['a re-pin', 'The conversation moved to'],
+        ["a turn's announcement", 'Your plain speech now lands in'],
+    ]) {
+        it(`the announce baseline moves only once ${label}'s notice is stored`, async () => {
+            membrane.pushResponse(createMockResponse([
+                { type: 'tool_use', id: 'c1', name: 'robot--move', input: { dir: 'north' } },
+            ], 'tool_use'));
+            membrane.pushResponse(createMockResponse([{ type: 'text', text: 'Done.' }]));
+            const framework = await createFramework();
+            stubChannelRegistry(framework);
+            module.toolDelayMs = 25;
+            if (notice === 'The conversation moved to') {
+                // Someone addresses the agent mid-turn from a DM: the turn re-pins.
+                module.interjection = 'quick question for you';
+                module.interjectionMetadata = addressed('discord:dm:antra');
+            }
+            const cm = framework.getAgent('assistant').getContextManager();
+            const add = cm.addMessage.bind(cm);
+            cm.addMessage = (participant, content, metadata) => {
+                if (content[0]?.text?.includes(notice))
+                    throw new Error('store refused');
+                return add(participant, content, metadata);
+            };
+            const baseline = framework.lastAnnouncedLocus;
+            trigger(framework);
+            await framework.runUntilIdle();
+            if (notice === 'The conversation moved to') {
+                assert.equal(baseline.get('assistant'), 'chan-live-1', 'the agent was last told of the locus the turn opened at');
+            }
+            else {
+                assert.equal(baseline.has('assistant'), false, 'the agent was never told a locus');
+            }
+            await framework.stop();
+        });
+    }
+    // A tool's late write lands in the turn that called it: a send's engaged
+    // channel, and a channel_open's move of the locus. (The dispatch functions
+    // run on a bare framework, as checkpoint-attribution.test.ts's harness does.)
+    function bareFramework() {
+        const framework = Object.create(AgentFramework.prototype);
+        framework.emitTrace = () => { };
+        framework.pushEvent = () => { };
+        framework.conversationAgentHomes = new Map();
+        framework.lastAnnouncedLocus = new Map();
+        framework.activeTurnTriggers = new Map();
+        framework.openLogical = new Map();
+        return framework;
+    }
+    const until = async (done, label) => {
+        for (const end = Date.now() + 2000; !done();) {
+            if (Date.now() > end)
+                throw new Error(`timed out waiting for ${label}`);
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    };
+    // stop() ends every open turn, but a fresh start that awaits a deferred
+    // batch's assembly while the stop runs reaches its routing after it, opens
+    // its turn, and is then dropped before its stream sends anything: before
+    // its compile, once stop() has closed admission, or after it, once a
+    // restart has begun a lifecycle of its own.
+    for (const restartFirst of [false, true]) {
+        const name = restartFirst
+            ? "a start whose compile spans a stop() and restart is dropped and leaves no turn open, so the next start opens its own"
+            : "a start that stop() drops before its compile leaves no turn open, so the first start after a restart opens its own";
+        it(name, async () => {
+            // A store the framework doesn't own, so the same instance can start again.
+            const store = JsStore.openOrCreate({ path: join(tempDir, 'restart.chronicle') });
+            const framework = await AgentFramework.create({
+                store,
+                membrane: membrane.asMembrane(),
+                agents: [{ name: 'assistant', model: 'test-model', systemPrompt: 'You are a robot pilot.' }],
+                modules: [module],
+                syncIntervalMs: 0,
+                maintenanceIntervalMs: 0,
+            });
+            module.framework = framework;
+            const routed = stubChannelRegistry(framework);
+            const internals = framework;
+            const agent = framework.getAgent('assistant');
+            const wake = () => ({
+                agentName: 'assistant', reason: 'external-message', source: 'test', timestamp: Date.now(),
+            });
+            let entered;
+            const assembling = new Promise((resolve) => { entered = resolve; });
+            let release;
+            const released = new Promise((resolve) => { release = resolve; });
+            internals.pushCoalescer = {
+                pendingBatches: () => true,
+                assemble: async () => {
+                    entered();
+                    await released;
+                    return { settled: new Set(), materialized: new Set() };
+                },
+                suspend: () => { },
+                isRendering: () => false,
+            };
+            const lines = [];
+            const error = console.error;
+            try {
+                console.error = (...args) => { lines.push(args.map(String).join(' ')); };
+                try {
+                    const dropped = internals.startAgentStream(agent, wake());
+                    await assembling;
+                    await framework.stop();
+                    if (restartFirst)
+                        framework.start();
+                    release();
+                    await dropped;
+                }
+                finally {
+                    console.error = error;
+                }
+                if (restartFirst) {
+                    assert.ok(lines.some((line) => /stopped and started again/.test(line) && /dropped before it sends anything/.test(line)), lines.join('\n'));
+                }
+                else {
+                    assert.equal(membrane.calls.length, 0, 'the start was dropped before its compile');
+                }
+                assert.deepEqual(routed, [], 'the dropped start routed nothing');
+                assert.equal(internals.openLogical.has('assistant'), false, 'the dropped start left no turn open');
+                if (!restartFirst)
+                    framework.start();
+                internals.pushCoalescer = undefined;
+                membrane.pushResponse(createMockResponse([{ type: 'text', text: 'After the restart.' }]));
+                await internals.startAgentStream(agent, wake());
+                await until(() => routed.length > 0, "the next turn's speech");
+                // The dropped start resolved chan-live-1. Continuing its turn would
+                // have kept that locus, without resolving one.
+                assert.deepEqual(routed, [{ text: 'After the restart.', locus: 'chan-live-2' }], 'the next start resolved a locus of its own');
+            }
+            finally {
+                release();
+                await framework.stop();
+                store.close();
+            }
+        });
+    }
+    it("a send's engaged channel is recorded on the turn that sent, however late its open resolves", async () => {
+        const sending = { engaged: new Set() };
+        const next = { engaged: new Set() };
+        let resolveOpen;
+        const framework = bareFramework();
+        framework.mcplServerRegistry = {
+            getServer: (id) => id === 'chat' ? {
+                id: 'chat',
+                sendToolsCall: async () => ({ content: [{ type: 'text', text: 'sent' }] }),
+            } : null,
+        };
+        framework.mcplServerConfigs = new Map([['chat', { id: 'chat', toolPrefix: 'chat' }]]);
+        framework.mcplToolFeatureSets = new Map();
+        framework.checkpointManager = null;
+        framework.channelRegistry = {
+            openIfClosedForSend: () => new Promise((resolve) => { resolveOpen = resolve; }),
+        };
+        framework.turnRouting = new Map([['assistant', sending]]);
+        const results = [];
+        framework.pushEvent = (event) => { if (event.type === 'tool-result')
+            results.push(event); };
+        framework.dispatchMcplToolCall('assistant', {
+            id: 'send-1', name: 'chat--send_message', input: { channelId: 'discord:guild:portables', text: 'hi' },
+        }, 'chat', 'chat');
+        await until(() => results.length > 0 && resolveOpen !== undefined, 'the send to finish');
+        // The turn that sent has ended, and the next turn is the agent's live routing.
+        framework.turnRouting.set('assistant', next);
+        resolveOpen({ status: 'already-open', channelId: 'discord:guild:portables' });
+        await until(() => sending.engaged.size > 0, 'the open to resolve');
+        assert.deepEqual([...sending.engaged], ['discord:guild:portables']);
+        assert.deepEqual([...next.engaged], [], "the next turn didn't send there");
+    });
+    // A channel_open's result can land after a later start has made another
+    // object the agent's live routing. While the turn that called is open, the
+    // result moves that turn's locus and tells the agent. Once the turn has
+    // ended, the tool-result handler drops the result, so the agent never reads
+    // it, and nothing moves, whether or not a later start has come yet.
+    for (const [label, after, moves] of [
+        ['moves the locus of its turn, still open, when a silent start\'s routing is the live one', 'silent start', true],
+        ['moves no locus once its turn has ended and the next turn has opened', 'next turn', false],
+        ['moves no locus once its turn has settled, before any later start', 'settled', false],
+    ]) {
+        it(`a channel_open whose result lands late ${label}`, async () => {
+            const calling = { engaged: new Set(), locus: 'chan-before' };
+            const other = { engaged: new Set(), locus: 'chan-next' };
+            let resolveOpen;
+            const framework = bareFramework();
+            framework.agents = new Map([['assistant', { proseRouting: 'locus' }]]);
+            framework.channelRegistry = {
+                handleChannelToolCall: () => new Promise((resolve) => { resolveOpen = resolve; }),
+            };
+            framework.turnRouting = new Map([['assistant', calling]]);
+            framework.openLogical = new Map([['assistant', calling]]);
+            const results = [];
+            framework.pushEvent = (event) => {
+                if (event.type === 'tool-result')
+                    results.push(event);
+            };
+            framework.dispatchChannelToolCall('assistant', {
+                id: 'open-1', name: 'channel_open', input: { channelId: 'discord:guild:observatory' },
+            });
+            await until(() => resolveOpen !== undefined, 'the open to start');
+            const turnRouting = framework.turnRouting;
+            const openLogical = framework.openLogical;
+            if (after === 'silent start')
+                turnRouting.set('assistant', other);
+            if (after === 'next turn') {
+                turnRouting.set('assistant', other);
+                openLogical.set('assistant', other);
+            }
+            if (after === 'settled')
+                openLogical.delete('assistant');
+            resolveOpen({ success: true, data: { channelId: 'discord:guild:observatory' } });
+            await until(() => results.length > 0, 'the tool result');
+            assert.equal(calling.triggerChannel, 'discord:guild:observatory', 'the turn that called records the channel it opened');
+            assert.equal(calling.locus, moves ? 'discord:guild:observatory' : 'chan-before');
+            assert.deepEqual(other, { engaged: new Set(), locus: 'chan-next' }, 'the other routing state is untouched');
+            assert.equal(framework.lastAnnouncedLocus.get('assistant'), moves ? 'discord:guild:observatory' : undefined, "the announce baseline moves with the locus, for a move the agent is told");
+            assert.equal(results[0].result.data?.routing !== undefined, moves, 'and the result says so only then');
+        });
+    }
+    for (const [label, silent, expected] of [
+        ['while its turn runs moves the locus and the announce baseline, and says so', false, 'discord:guild:observatory'],
+        ['in a silent turn moves no locus, and claims none', true, 'chan-before'],
+    ]) {
+        it(`a channel_open ${label}`, async () => {
+            const calling = { engaged: new Set(), locus: 'chan-before' };
+            const framework = bareFramework();
+            framework.agents = new Map([['assistant', { proseRouting: 'locus' }]]);
+            framework.channelRegistry = {
+                handleChannelToolCall: async () => ({ success: true, data: { channelId: 'discord:guild:observatory' } }),
+            };
+            framework.turnRouting = new Map([['assistant', calling]]);
+            if (!silent)
+                framework.openLogical = new Map([['assistant', calling]]);
+            framework.activeTurnTriggers.set('assistant', silent ? { suppressProse: true } : {});
+            const results = [];
+            framework.pushEvent = (event) => {
+                if (event.type === 'tool-result')
+                    results.push(event);
+            };
+            framework.dispatchChannelToolCall('assistant', {
+                id: 'open-1', name: 'channel_open', input: { channelId: 'discord:guild:observatory' },
+            });
+            await until(() => results.length > 0, 'the tool result');
+            assert.equal(calling.locus, expected);
+            assert.equal(framework.lastAnnouncedLocus.get('assistant'), silent ? undefined : 'discord:guild:observatory');
+            assert.equal(results[0].result.data?.routing !== undefined, !silent, 'the result tells the agent only of a move it made');
+        });
+    }
     it('a prose turn ends with a [delivered] receipt naming where the prose landed', async () => {
         // Explicit sends receipt themselves via tool_result; auto-routed prose
         // previously vanished with no in-window trace — the agent could never