@animalabs/agent-framework 0.22.1 → 0.22.2

package/dist/test/maintenance-timer.test.js

@@ -4,6 +4,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { AgentFramework } from '../src/index.js';
+import { OperatorActionError } from '../src/operator-log.js';
+import { MembraneError } from '@animalabs/membrane';
 class QueuedStrategy {
     name = 'queued-test';
     ticks = 0;
@@ -56,6 +58,291 @@ class FailingStrategy {
         return [];
     }
 }
+/** A strategy whose every pass takes one tick, then meets the same failure. */
+class WorkThenFailStrategy {
+    name = 'work-then-fail-test';
+    ticks = 0;
+    checkReadiness() {
+        return { ready: false, description: 'compression queued' };
+    }
+    async tick(_ctx) {
+        this.ticks++;
+        if (this.ticks % 2 === 0)
+            throw new Error('provider rejected maintenance request');
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy whose initialization always fails. */
+class RefusingInitStrategy {
+    name = 'refusing-init-test';
+    async initialize(_ctx) {
+        throw new Error('strategy initialization failed for the test');
+    }
+    checkReadiness() {
+        return { ready: false, description: 'not expected' };
+    }
+    async tick(_ctx) { }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy that refuses on its own, as the autobiographical one does for a branch it hasn't reloaded. */
+class StaleStrategy {
+    name = 'stale-test';
+    checkReadiness() {
+        throw new Error('StaleStrategy.checkReadiness requires reinitialization for the current branch generation');
+    }
+    getProgressSnapshot() {
+        throw new Error('StaleStrategy.getProgressSnapshot requires reinitialization for the current branch generation');
+    }
+    async tick(_ctx) { }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy whose readiness query refuses with whatever text it's given. */
+class SayingStrategy {
+    name = 'saying-test';
+    says = 'the first refusal';
+    checkReadiness() {
+        throw new Error(this.says);
+    }
+    async tick(_ctx) { }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy with work pending that no tick finishes. */
+class NeverReadyStrategy {
+    name = 'never-ready-test';
+    checkReadiness() {
+        return { ready: false, description: 'never ready' };
+    }
+    async tick(_ctx) { }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy whose tick fences its own manager with a failed initialization. */
+class FencingTickStrategy {
+    name = 'fencing-tick-test';
+    manager;
+    checkReadiness() {
+        return { ready: false, description: 'fencing tick queued' };
+    }
+    async tick(_ctx) {
+        await this.manager?.setStrategy(new RefusingInitStrategy()).catch(() => undefined);
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy with work pending whose tick runs a hook: a surgery can begin inside a pass. */
+class HookedTickStrategy {
+    name = 'hooked-tick-test';
+    ticks = 0;
+    onTick;
+    checkReadiness() {
+        return { ready: false, description: 'hooked tick queued' };
+    }
+    async tick(_ctx) {
+        this.ticks++;
+        this.onTick?.();
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy with no maintenance to do. */
+class ReadyStrategy {
+    name = 'ready-test';
+    checkReadiness() {
+        return { ready: true };
+    }
+    async tick(_ctx) { }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy whose first tick waits on a gate, and that notes what it sees. */
+class GatedTickStrategy {
+    name = 'gated-tick-test';
+    ticks = 0;
+    ticksUnderHold = 0;
+    branchAtFirstTickEnd;
+    storeOpenAtFirstTickEnd;
+    framework;
+    open;
+    gate = new Promise((resolve) => { this.open = resolve; });
+    release() {
+        this.open?.();
+    }
+    checkReadiness() {
+        return { ready: false, description: 'gated tick queued' };
+    }
+    async tick(_ctx) {
+        this.ticks++;
+        if (this.framework.surgeryHold)
+            this.ticksUnderHold++;
+        if (this.ticks === 1) {
+            await this.gate;
+            this.storeOpenAtFirstTickEnd = !this.framework.store.isClosed();
+            this.branchAtFirstTickEnd = this.framework.getAgent('agent').getContextManager().currentBranch().name;
+        }
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/**
+ * A strategy whose first tick makes a provider call that parks at the agent's
+ * provider gate, as one does once a cooldown a primary call started has ended
+ * and the retry turn it queued hasn't run yet.
+ */
+class ParkedCallTickStrategy {
+    name = 'parked-call-tick-test';
+    ticks = 0;
+    calls = 0;
+    outcome;
+    framework;
+    checkReadiness() {
+        return { ready: false, description: 'parked call queued' };
+    }
+    async tick(_ctx) {
+        this.ticks++;
+        if (this.ticks > 1)
+            return;
+        const internals = this.framework;
+        internals.providerGate('agent').primaryPending = true;
+        try {
+            await internals.withAuxiliaryAdmission('agent', async () => { this.calls++; });
+            this.outcome = 'ran';
+        }
+        catch (error) {
+            this.outcome = error.name;
+            throw error;
+        }
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A provider's stated wait of `ms`, as membrane reports a 429 with retry-after. */
+function heldFor(ms) {
+    return new MembraneError({
+        type: 'rate_limit', retryable: true, httpStatus: 429, retryAfterMs: ms,
+        message: 'rate limited for the test', rawError: { status: 429 },
+    });
+}
+/** A strategy whose first tick calls stop() before its first await, then notes whether the store was still open when it ended. */
+class StopInTickStrategy {
+    name = 'stop-in-tick-test';
+    ticks = 0;
+    framework;
+    stopping;
+    stoppedBeforeTickEnd;
+    storeOpenAtTickEnd;
+    checkReadiness() {
+        return { ready: false, description: 'compression queued' };
+    }
+    async tick(_ctx) {
+        this.ticks++;
+        if (this.ticks > 1)
+            return;
+        this.stopping = this.framework.stop();
+        // A stop() that doesn't wait for this tick settles first; one that does
+        // can't settle before it ends, so the second second is this tick's.
+        const first = await Promise.race([
+            this.stopping.then(() => 'stopped', () => 'stopped'),
+            new Promise((resolve) => setTimeout(() => resolve('waited'), 1000)),
+        ]);
+        this.stoppedBeforeTickEnd = first === 'stopped';
+        this.storeOpenAtTickEnd = !this.framework.store.isClosed();
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy whose every tick meets the same failure, its second only once its gate opens. */
+class GatedRepeatFailureStrategy {
+    name = 'gated-repeat-failure-test';
+    ticks = 0;
+    open;
+    gate = new Promise((resolve) => { this.open = resolve; });
+    release() {
+        this.open?.();
+    }
+    checkReadiness() {
+        return { ready: false, description: 'compression blocked' };
+    }
+    async tick(_ctx) {
+        this.ticks++;
+        if (this.ticks === 2)
+            await this.gate;
+        throw new Error('provider rejected maintenance request');
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy whose first tick waits on a gate, then calls its manager's membrane, as a compression would. */
+class CallAfterGateStrategy {
+    name = 'call-after-gate-test';
+    ticks = 0;
+    entered = false;
+    outcome;
+    open;
+    gate = new Promise((resolve) => { this.open = resolve; });
+    release() {
+        this.open?.();
+    }
+    checkReadiness() {
+        return { ready: false, description: 'a compression queued' };
+    }
+    async tick(ctx) {
+        this.ticks++;
+        if (this.ticks > 1)
+            return;
+        this.entered = true;
+        await this.gate;
+        try {
+            await ctx.membrane?.complete({
+                model: 'test-model',
+                config: { model: 'test-model' },
+                messages: [{ role: 'user', content: [{ type: 'text', text: 'compress' }] }],
+            });
+            this.outcome = 'sent';
+        }
+        catch (error) {
+            this.outcome = error.name;
+            throw error;
+        }
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
+/** A strategy whose ticks succeed and whose readiness can't be read once all of a pass's ticks have run. */
+class RefusesAfterTicksStrategy {
+    name = 'refuses-after-ticks-test';
+    ticks = 0;
+    failTick = false;
+    checkReadiness() {
+        if (this.ticks >= 8 || (this.failTick && this.ticks > 0))
+            throw new Error('readiness refused after the ticks');
+        return { ready: false, description: 'work queued' };
+    }
+    async tick(_ctx) {
+        this.ticks++;
+        if (this.failTick)
+            throw new Error('tick failed');
+    }
+    select(_store, _log, _budget) {
+        return [];
+    }
+}
 class ToolModule {
     name = 'maintenance-tools';
     async start(_ctx) { }
@@ -97,6 +384,12 @@ class CapturingMembrane {
         return this;
     }
 }
+/** The first pass the timer recorded. The history lists the newest first, and
+ *  under load more passes can end before a test reads it. */
+function firstPass(framework) {
+    const history = framework.getContextMaintenanceSnapshot().history;
+    return history[history.length - 1];
+}
 async function waitFor(predicate, timeoutMs = 1000) {
     const deadline = Date.now() + timeoutMs;
     while (!predicate()) {
@@ -253,8 +546,1277 @@ describe('queued context maintenance timer', () => {
                     pending: 'compression blocked',
                 },
             });
-            await waitFor(() => framework.getContextMaintenanceSnapshot().history.length > 0);
-            assert.equal(framework.getContextMaintenanceSnapshot().history[0].agents[0].error, 'provider rejected maintenance request');
+            // Every pass meets the same failure. It is alerted once, and the
+            // passes that only repeat it stay out of the history.
+            await waitFor(() => framework.maintenanceRunId >= 3);
+            const history = framework.getContextMaintenanceSnapshot().history;
+            assert.equal(history.length, 1);
+            assert.equal(history[0].agents[0].error, 'provider rejected maintenance request');
+            assert.equal(alerts.length, 1);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('an agent whose readiness can\'t be read fails alone: its run records the error and it gets its own alert', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-refused-'));
+        const healthy = new QueuedStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [
+                { name: 'fenced', model: 'test-model', systemPrompt: 'test', strategy: new QueuedStrategy() },
+                { name: 'healthy', model: 'test-model', systemPrompt: 'test', strategy: healthy },
+            ],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const alerts = [];
+        framework.opsAlert = (kind, agentName, _message, opts) => alerts.push({ kind, agentName, data: opts?.data });
+        // A failed strategy initialization fences the context manager: its state
+        // queries throw until a successful switchBranch or setStrategy.
+        const fenced = framework.getAgent('fenced').getContextManager();
+        await assert.rejects(fenced.setStrategy(new RefusingInitStrategy()), /strategy initialization failed for the test/);
+        assert.throws(() => fenced.isReady(), /requires successful strategy initialization/);
+        try {
+            framework.start();
+            await waitFor(() => healthy.ticks >= 2);
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.some((run) => run.agents.some((agent) => agent.agentName === 'healthy' && agent.readyAfter === true)));
+            const snapshot = framework.getContextMaintenanceSnapshot();
+            const run = snapshot.history.find((r) => r.agents.some((agent) => agent.agentName === 'healthy'));
+            const fencedRun = run.agents.find((agent) => agent.agentName === 'fenced');
+            assert.equal(fencedRun?.ticks, 0);
+            assert.match(fencedRun?.error ?? '', /requires successful strategy initialization/);
+            const entry = snapshot.agents.find((agent) => agent.agentName === 'fenced');
+            assert.equal(entry?.ready, false);
+            assert.match(entry?.error ?? '', /requires successful strategy initialization/);
+            assert.ok(alerts.some((alert) => alert.agentName === 'fenced' && alert.data?.scope === 'agent'));
+            assert.equal(alerts.some((alert) => alert.data?.scope === 'pass'), false);
+            assert.equal(alerts.some((alert) => alert.agentName === 'healthy'), false);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a failure that begins during the pass is that agent\'s error and alert, not the pass\'s', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-refused-after-'));
+        const strategy = new FencingTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        strategy.manager = framework.getAgent('agent').getContextManager();
+        const alerts = [];
+        framework.opsAlert = (kind, agentName, _message, opts) => alerts.push({ kind, agentName, data: opts?.data });
+        try {
+            framework.start();
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.length >= 1);
+            const run = firstPass(framework).agents[0];
+            assert.equal(run.agentName, 'agent');
+            assert.equal(run.ticks, 1);
+            assert.match(run.error ?? '', /requires successful strategy initialization/);
+            assert.equal(run.readyAfter, undefined);
+            assert.ok(alerts.some((alert) => alert.agentName === 'agent' && alert.kind === 'context-maintenance-failed' && alert.data?.scope === 'agent'));
+            assert.equal(alerts.some((alert) => alert.data?.scope === 'pass'), false);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a strategy that can\'t report its readiness or its progress fails that agent alone, and the snapshot still answers', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-stale-'));
+        const healthy = new QueuedStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [
+                { name: 'stale', model: 'test-model', systemPrompt: 'test', strategy: new StaleStrategy() },
+                { name: 'healthy', model: 'test-model', systemPrompt: 'test', strategy: healthy },
+            ],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const alerts = [];
+        framework.opsAlert = (kind, agentName, _message, opts) => alerts.push({ kind, agentName, data: opts?.data });
+        try {
+            framework.start();
+            await waitFor(() => healthy.ticks >= 2);
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.some((run) => run.agents.some((agent) => agent.agentName === 'healthy' && agent.readyAfter === true)));
+            const snapshot = framework.getContextMaintenanceSnapshot();
+            const entry = snapshot.agents.find((agent) => agent.agentName === 'stale');
+            assert.equal(entry?.ready, false);
+            assert.match(entry?.error ?? '', /requires reinitialization for the current branch generation/);
+            assert.equal(entry?.progress, undefined);
+            assert.ok(alerts.some((alert) => alert.agentName === 'stale' && alert.data?.scope === 'agent'));
+            assert.equal(alerts.some((alert) => alert.data?.scope === 'pass'), false);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('whatever throws while one agent\'s maintenance is prepared is that agent\'s failure alone', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-prepare-throws-'));
+        const healthy = new QueuedStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [
+                { name: 'broken', model: 'test-model', systemPrompt: 'test', strategy: new QueuedStrategy() },
+                { name: 'healthy', model: 'test-model', systemPrompt: 'test', strategy: healthy },
+            ],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const alerts = [];
+        framework.opsAlert = (kind, agentName, _message, opts) => alerts.push({ kind, agentName, data: opts?.data });
+        const internals = framework;
+        const gateBlocked = internals.providerGateBlocked.bind(framework);
+        internals.providerGateBlocked = (name) => {
+            if (name === 'broken')
+                throw new Error('gate read failed');
+            return gateBlocked(name);
+        };
+        try {
+            framework.start();
+            await waitFor(() => healthy.ticks >= 2);
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.some((run) => run.agents.some((agent) => agent.agentName === 'broken' && agent.error !== undefined)));
+            const run = framework.getContextMaintenanceSnapshot().history.find((candidate) => candidate.agents.some((agent) => agent.agentName === 'broken'));
+            const broken = run.agents.find((agent) => agent.agentName === 'broken');
+            assert.equal(broken.error, 'gate read failed');
+            assert.equal(broken.ticks, 0);
+            assert.ok(alerts.some((alert) => alert.agentName === 'broken' && alert.data?.scope === 'agent'));
+            assert.equal(alerts.some((alert) => alert.data?.scope === 'pass'), false);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a failure that lasts is logged and alerted once, and again once the agent has recovered', async (t) => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-lasting-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'fenced', model: 'test-model', systemPrompt: 'test', strategy: new QueuedStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const alerts = [];
+        framework.opsAlert = (kind, agentName) => alerts.push(`${kind}:${agentName}`);
+        const internals = framework;
+        let passes = 0;
+        const runPass = internals.runQueuedMaintenance.bind(framework);
+        internals.runQueuedMaintenance = () => { passes++; return runPass(); };
+        const logged = t.mock.method(console, 'error', () => { });
+        const failedLines = () => logged.mock.calls.filter((call) => String(call.arguments[0]).includes('[context-maintenance] agent=fenced failed:')).length;
+        const runsWithError = () => framework.getContextMaintenanceSnapshot().history.filter((run) => run.agents.some((agent) => agent.agentName === 'fenced' && agent.error !== undefined)).length;
+        const cm = framework.getAgent('fenced').getContextManager();
+        const fence = () => assert.rejects(cm.setStrategy(new RefusingInitStrategy()), /strategy initialization failed for the test/);
+        await fence();
+        try {
+            framework.start();
+            await waitFor(() => passes >= 3);
+            assert.deepEqual(alerts, ['context-maintenance-failed:fenced']);
+            assert.equal(failedLines(), 1);
+            assert.equal(runsWithError(), 1, 'the passes that only repeat the failure stay out of the history');
+            // Recovered with nothing to do: passes find it ready and skip it.
+            await cm.setStrategy(new ReadyStrategy());
+            const after = passes;
+            await waitFor(() => passes >= after + 3);
+            await fence();
+            await waitFor(() => alerts.length === 2);
+            assert.equal(failedLines(), 2);
+            // Recovered with work no tick finishes: a pass runs it without a failure.
+            await cm.setStrategy(new NeverReadyStrategy());
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.some((run) => run.agents.some((agent) => agent.agentName === 'fenced' && agent.ticks > 0 && agent.error === undefined)));
+            await fence();
+            await waitFor(() => alerts.length === 3);
+            assert.equal(failedLines(), 3);
+            assert.deepEqual(new Set(alerts), new Set(['context-maintenance-failed:fenced']));
+        }
+        finally {
+            logged.mock.restore();
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a failure that lasts is alerted again when its whole text changes, and again once the alert cooldown has passed', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-lasting-text-'));
+        const strategy = new SayingStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'saying', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const alerts = [];
+        framework.opsAlert = (_kind, _agentName, text) => alerts.push(text);
+        const internals = framework;
+        let passes = 0;
+        const runPass = internals.runQueuedMaintenance.bind(framework);
+        internals.runQueuedMaintenance = () => { passes++; return runPass(); };
+        const passed = async (n) => { const after = passes; await waitFor(() => passes >= after + n); };
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            framework.start();
+            await waitFor(() => alerts.length === 1);
+            await passed(3);
+            assert.deepEqual(alerts, ['the first refusal']);
+            // Two long texts that differ only in their middle, which the bounded
+            // text a run records leaves out: the alert follows the whole text.
+            const long = (middle) => `${'a'.repeat(3_000)} ${middle} ${'z'.repeat(3_000)}`;
+            strategy.says = long('one');
+            await waitFor(() => alerts.length === 2);
+            strategy.says = long('two');
+            await waitFor(() => alerts.length === 3);
+            await passed(3);
+            assert.equal(alerts.length, 3);
+            // Unchanged, it is alerted again once the cooldown has passed.
+            internals.opsAlertCooldownMs = 0;
+            await waitFor(() => alerts.length >= 5);
+            assert.ok(alerts.slice(3).every((text) => text === long('two')));
+        }
+        finally {
+            console.error = quiet;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a failure that lasts is posted to the webhook again a cooldown after its last post, whatever changed-text report came between', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-webhook-reminder-'));
+        const strategy = new SayingStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'saying', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const internals = framework;
+        let passes = 0;
+        const runPass = internals.runQueuedMaintenance.bind(framework);
+        internals.runQueuedMaintenance = () => { passes++; return runPass(); };
+        const passed = async (n) => { const after = passes; await waitFor(() => passes >= after + n); };
+        // The real opsAlert, with a webhook whose posts are recorded.
+        const posts = [];
+        const realFetch = globalThis.fetch;
+        globalThis.fetch = (async (_url, init) => {
+            posts.push(String(JSON.parse(String(init?.body)).content));
+            return new Response('{}');
+        });
+        const hook = process.env.CONNECTOME_OPS_WEBHOOK;
+        process.env.CONNECTOME_OPS_WEBHOOK = 'http://webhook.invalid/hook';
+        const realNow = Date.now;
+        const start = realNow();
+        let offset = 0;
+        Date.now = () => realNow() + offset;
+        const minute = 60_000;
+        const maintenancePosts = () => posts.filter((post) => post.includes('context-maintenance-failed'));
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            framework.start();
+            await waitFor(() => maintenancePosts().length === 1);
+            assert.match(maintenancePosts()[0], /the first refusal/);
+            // 14 minutes on, the text changes: it's reported, and the webhook,
+            // still within its cooldown, doesn't post it.
+            offset = 14 * minute;
+            strategy.says = 'the second refusal';
+            await passed(3);
+            assert.equal(maintenancePosts().length, 1);
+            // At 15 minutes the webhook's cooldown since its post has passed.
+            offset = 15 * minute + 1_000;
+            await waitFor(() => maintenancePosts().length === 2);
+            assert.match(maintenancePosts()[1], /the second refusal/);
+            assert.ok(Date.now() - start < 16 * minute);
+        }
+        finally {
+            console.error = quiet;
+            Date.now = realNow;
+            globalThis.fetch = realFetch;
+            if (hook === undefined)
+                delete process.env.CONNECTOME_OPS_WEBHOOK;
+            else
+                process.env.CONNECTOME_OPS_WEBHOOK = hook;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a readiness refusal read after an agent\'s last tick is that agent\'s failure, alerted once', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-refused-after-ticks-'));
+        const strategy = new RefusesAfterTicksStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            // start() runs one pass at once; none follows within the test.
+            maintenanceIntervalMs: 60_000,
+        });
+        const alerts = [];
+        framework.opsAlert = (kind, agentName, message) => alerts.push(`${kind}:${agentName}:${message}`);
+        try {
+            framework.start();
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.length >= 1);
+            const run = firstPass(framework).agents[0];
+            assert.equal(run.ticks, 8);
+            assert.equal(run.error, 'readiness refused after the ticks');
+            assert.equal(run.readyAfter, undefined);
+            assert.deepEqual(alerts, ['context-maintenance-failed:agent:readiness refused after the ticks']);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a run records an agent\'s first failure: a readiness refusal after a failed tick isn\'t reported again', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-first-failure-'));
+        const strategy = new RefusesAfterTicksStrategy();
+        strategy.failTick = true;
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 60_000,
+        });
+        const alerts = [];
+        framework.opsAlert = (kind, agentName, message) => alerts.push(`${kind}:${agentName}:${message}`);
+        try {
+            framework.start();
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.length >= 1);
+            const run = firstPass(framework).agents[0];
+            assert.equal(run.ticks, 0);
+            assert.equal(run.error, 'tick failed');
+            assert.deepEqual(alerts, ['context-maintenance-failed:agent:tick failed']);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    for (const surgery of [
+        { verb: 'roll back', run: (framework, first) => framework.rollbackToMessage('agent', { messageId: first }) },
+        { verb: 'suppress', run: (framework, first) => framework.suppressMessages('agent', { messageIds: [first] }) },
+        {
+            verb: 'switch branch',
+            who: 'every agent',
+            run: (framework, first) => {
+                framework.getAgent('agent').getContextManager().branchAt(first, 'elsewhere');
+                return framework.switchBranch('elsewhere');
+            },
+        },
+    ]) {
+        it(`a ${surgery.verb} that begins during a tick waits for it before it moves the branch, and resume refuses while the ${surgery.verb} holds the store`, { timeout: 10_000 }, async () => {
+            const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-surgery-waits-'));
+            const strategy = new GatedTickStrategy();
+            const framework = await AgentFramework.create({
+                storePath: join(dir, 'store'),
+                membrane,
+                agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+                modules: [],
+                syncIntervalMs: 0,
+                maintenanceIntervalMs: 10,
+            });
+            strategy.framework = framework;
+            const cm = framework.getAgent('agent').getContextManager();
+            const first = String(cm.addMessage('user', [{ type: 'text', text: 'm1' }]));
+            cm.addMessage('user', [{ type: 'text', text: 'm2' }]);
+            const internals = framework;
+            try {
+                await framework.quiesce();
+                framework.start();
+                await waitFor(() => strategy.ticks === 1);
+                const moved = surgery.run(framework, first);
+                await waitFor(() => internals.surgeryHold !== null);
+                await assert.rejects(framework.resume(), (error) => error instanceof OperatorActionError && error.code === 'agent-busy'
+                    && error.message.includes(`a live ${surgery.verb} for ${surgery.who ?? 'agent'} holds the store`));
+                assert.equal(cm.currentBranch().name, 'main', `the ${surgery.verb} waits for the running tick`);
+                strategy.release();
+                await moved;
+                assert.equal(strategy.branchAtFirstTickEnd, 'main');
+                assert.equal(strategy.ticksUnderHold, 0, `the pass starts no tick while the ${surgery.verb} holds the store`);
+                assert.notEqual(cm.currentBranch().name, 'main');
+                const status = await framework.resume();
+                assert.equal(status.quiesced, false);
+            }
+            finally {
+                strategy.release();
+                await framework.stop();
+                rmSync(dir, { recursive: true, force: true });
+            }
+        });
+    }
+    for (const surgery of [
+        { verb: 'roll back', run: (framework, first) => framework.rollbackToMessage('agent', { messageId: first }) },
+        { verb: 'suppress', run: (framework, first) => framework.suppressMessages('agent', { messageIds: [first] }) },
+        {
+            verb: 'switch branch',
+            run: (framework, first) => {
+                framework.getAgent('agent').getContextManager().branchAt(first, 'elsewhere');
+                return framework.switchBranch('elsewhere');
+            },
+        },
+    ]) {
+        it(`a ${surgery.verb} withdraws a maintenance call parked at the provider gate rather than waiting on it, and that is no failure`, { timeout: 10_000 }, async () => {
+            const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-parked-call-'));
+            const strategy = new ParkedCallTickStrategy();
+            const framework = await AgentFramework.create({
+                storePath: join(dir, 'store'),
+                membrane,
+                agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+                modules: [],
+                syncIntervalMs: 0,
+                maintenanceIntervalMs: 10,
+            });
+            strategy.framework = framework;
+            const alerts = [];
+            framework.opsAlert = (kind, agentName, message) => alerts.push(`${kind}:${agentName}:${message}`);
+            const cm = framework.getAgent('agent').getContextManager();
+            const first = String(cm.addMessage('user', [{ type: 'text', text: 'm1' }]));
+            cm.addMessage('user', [{ type: 'text', text: 'm2' }]);
+            const internals = framework;
+            const quiet = console.error;
+            console.error = () => { };
+            try {
+                await framework.quiesce();
+                framework.start();
+                await waitFor(() => internals.providerGate('agent').auxiliaryWaiters.length === 1);
+                const moved = surgery.run(framework, first);
+                const outcome = await Promise.race([
+                    moved.then(() => 'moved'),
+                    new Promise((resolve) => setTimeout(() => resolve(`the ${surgery.verb} still waits`), 3_000)),
+                ]);
+                assert.equal(outcome, 'moved');
+                assert.equal(strategy.outcome, 'MaintenanceWithdrawnError');
+                assert.equal(strategy.calls, 0, 'the withdrawn call sent nothing');
+                assert.notEqual(cm.currentBranch().name, 'main');
+                assert.deepEqual(alerts.filter((alert) => alert.startsWith('context-maintenance-failed')), []);
+                const run = firstPass(framework).agents[0];
+                assert.equal(run.error, undefined);
+            }
+            finally {
+                console.error = quiet;
+                await framework.stop();
+                rmSync(dir, { recursive: true, force: true });
+            }
+        });
+    }
+    it('a maintenance provider call made while a surgery holds the store is withdrawn before it is sent, with the gate closed too', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-withdrawn-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: new GatedTickStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        const internals = framework;
+        try {
+            for (const closed of [false, true]) {
+                let ran = false;
+                const release = internals.reserveStoreForSurgery('roll back', 'agent');
+                // Closed: a cooldown's retry turn is queued, which the hold keeps from
+                // starting, so a call that parked would never be woken.
+                internals.providerGate('agent').primaryPending = closed;
+                try {
+                    const admitted = internals.withAuxiliaryAdmission('agent', async () => { ran = true; });
+                    void admitted.catch(() => { });
+                    const outcome = await Promise.race([
+                        admitted.then(() => 'admitted', (error) => error),
+                        new Promise((resolve) => setTimeout(() => resolve('parked'), 1_000)),
+                    ]);
+                    assert.ok(outcome instanceof Error && outcome.name === 'MaintenanceWithdrawnError'
+                        && outcome.message === 'maintenance call withdrawn: a live roll back for agent holds the store', `${closed ? 'gate closed' : 'gate open'}: ${outcome instanceof Error ? outcome.message : String(outcome)}`);
+                    assert.equal(ran, false);
+                }
+                finally {
+                    internals.providerGate('agent').primaryPending = false;
+                    release();
+                }
+            }
+            assert.equal(await internals.withAuxiliaryAdmission('agent', async () => 7), 7, 'admitted again once the hold is released');
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a parked maintenance call woken while its gate is still closed parks again, and goes once the gate opens', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-parks-again-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: new GatedTickStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        const internals = framework;
+        try {
+            const gate = internals.providerGate('agent');
+            gate.primaryPending = true;
+            let ran = false;
+            const call = internals.withAuxiliaryAdmission('agent', async () => { ran = true; return 7; });
+            await waitFor(() => gate.auxiliaryWaiters.length === 1);
+            for (const resolve of gate.auxiliaryWaiters.splice(0))
+                resolve();
+            await waitFor(() => gate.auxiliaryWaiters.length === 1);
+            assert.equal(ran, false, 'woken with the gate still closed, it parked again');
+            gate.primaryPending = false;
+            internals.flushAuxiliaryAdmission('agent');
+            assert.equal(await call, 7);
+            assert.equal(ran, true);
+        }
+        finally {
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    for (const kind of ['resident', 'conversation agent']) {
+        for (const held of [false, true]) {
+            it(`a ${kind}'s tick that reaches its provider under a surgery's hold is withdrawn${held ? ', though a provider wait holds its model' : ''}`, { timeout: 10_000 }, async () => {
+                const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-surgery-withdrawn-'));
+                const provider = new CapturingMembrane();
+                const tick = new CallAfterGateStrategy();
+                const conversational = kind === 'conversation agent';
+                const framework = await AgentFramework.create({
+                    storePath: join(dir, 'store'),
+                    membrane: provider.asMembrane(),
+                    agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: conversational ? new ReadyStrategy() : tick }],
+                    modules: [],
+                    syncIntervalMs: 0,
+                    maintenanceIntervalMs: 10,
+                    ...(conversational ? { conversations: { templateAgent: 'agent', strategyFactory: () => tick } } : {}),
+                });
+                const internals = framework;
+                const name = conversational ? 'agent-conv-1' : 'agent';
+                const alerts = [];
+                framework.opsAlert = (kind, agentName) => alerts.push(`${kind}:${agentName}`);
+                const quiet = console.error;
+                console.error = () => { };
+                try {
+                    if (conversational)
+                        await internals.createConversationAgent(name, 'chan-1');
+                    if (held)
+                        internals.recordProviderWait(name, 'test-model', heldFor(60_000));
+                    framework.start();
+                    await waitFor(() => tick.entered);
+                    const release = internals.reserveStoreForSurgery('roll back', 'agent');
+                    try {
+                        tick.release();
+                        await waitFor(() => tick.outcome !== undefined);
+                        assert.equal(tick.outcome, 'MaintenanceWithdrawnError');
+                        assert.equal(provider.calls.length, 0, 'the withdrawn call sent nothing');
+                    }
+                    finally {
+                        release();
+                    }
+                    assert.deepEqual(alerts.filter((alert) => alert.startsWith('context-maintenance-failed')), []);
+                }
+                finally {
+                    console.error = quiet;
+                    tick.release();
+                    await framework.stop();
+                    rmSync(dir, { recursive: true, force: true });
+                }
+            });
+        }
+    }
+    it('a pass that only meets a failure already reported stays out of the history', { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-repeats-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: new FailingStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        framework.opsAlert = () => { };
+        const internals = framework;
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            framework.start();
+            await waitFor(() => internals.maintenanceRunId >= 4);
+            const history = framework.getContextMaintenanceSnapshot().history;
+            assert.equal(history.length, 1, 'the first report only, though four passes met the failure');
+            assert.equal(history[0].id, 1);
+            assert.ok(history[0].agents[0].error);
+        }
+        finally {
+            console.error = quiet;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("an operator's maintain keeps the pass it ran in the history, though the pass only met a failure already reported", { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-requested-pass-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: new FailingStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        framework.opsAlert = () => { };
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            framework.start();
+            const first = await framework.maintenanceTick();
+            assert.equal(first.ran, true);
+            const reported = first.history[0].id;
+            assert.ok(first.history[0].agents[0].error, 'the first pass reports the failure');
+            const second = await framework.maintenanceTick();
+            assert.equal(second.ran, true);
+            assert.ok(second.history[0].id > reported, 'the newest run is the pass the second maintain ran');
+            assert.ok(second.history[0].agents[0].error);
+        }
+        finally {
+            console.error = quiet;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("a maintain whose pass had nothing to run leaves no request for the next pass", { timeout: 10_000 }, async () => {
+        // Gordon-2414's probe. While the agent's own call holds its provider gate,
+        // a maintain's pass queues nothing and records no run, so the next pass,
+        // which nobody asked for and which meets only the failure already
+        // reported, stays out of the history.
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-request-reset-'));
+        const strategy = new FailingStrategy();
+        let ticks = 0;
+        const failingTick = strategy.tick.bind(strategy);
+        strategy.tick = async (ctx) => { ticks++; return failingTick(ctx); };
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        const internals = framework;
+        framework.opsAlert = () => { };
+        const quiet = console.error;
+        const quietWarn = console.warn;
+        console.error = () => { };
+        console.warn = () => { };
+        try {
+            framework.start();
+            const first = await framework.maintenanceTick();
+            assert.equal(first.history.length, 1, 'the first maintain reports the failure');
+            internals.acquirePrimaryProviderGate('agent');
+            const second = await framework.maintenanceTick();
+            assert.equal(second.ran, true);
+            assert.equal(second.history.length, 1, 'a pass with nothing queued records no run');
+            assert.equal(ticks, 1, 'the second maintain ran no tick');
+            internals.releasePrimaryProviderGate('agent');
+            internals.startQueuedMaintenance();
+            await internals.maintenancePass;
+            assert.equal(ticks, 2, 'the pass nobody asked for ran its tick');
+            assert.equal(framework.getContextMaintenanceSnapshot().history.length, 1, 'the repeat nobody asked for stays out of the history');
+        }
+        finally {
+            console.error = quiet;
+            console.warn = quietWarn;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("a maintain that joins a pass already running keeps that pass in the history", { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-request-join-'));
+        const strategy = new GatedRepeatFailureStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        const internals = framework;
+        framework.opsAlert = () => { };
+        const quiet = console.error;
+        const quietWarn = console.warn;
+        console.error = () => { };
+        console.warn = () => { };
+        try {
+            framework.start();
+            const first = await framework.maintenanceTick();
+            assert.equal(first.history.length, 1, 'the first maintain reports the failure');
+            // A pass nobody asked for, whose tick waits on the gate.
+            internals.startQueuedMaintenance();
+            await waitFor(() => strategy.ticks === 2);
+            // The maintain joins it, and the pass then meets the failure already reported.
+            const joining = framework.maintenanceTick();
+            strategy.release();
+            const joined = await joining;
+            assert.equal(joined.ran, true);
+            assert.equal(strategy.ticks, 2, 'the maintain started no pass of its own');
+            assert.equal(joined.history.length, 2, 'the pass the maintain joined is kept');
+            assert.ok(joined.history[0].id > first.history[0].id);
+        }
+        finally {
+            console.error = quiet;
+            console.warn = quietWarn;
+            strategy.release();
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a pass that took a tick before meeting a failure already reported stays in the history', { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-repeats-after-work-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: new WorkThenFailStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        framework.opsAlert = () => { };
+        const internals = framework;
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            framework.start();
+            await waitFor(() => internals.maintenanceRunId >= 4);
+            const history = framework.getContextMaintenanceSnapshot().history;
+            assert.ok(history.length >= 3, `each finished pass did work, so each is kept (${history.length})`);
+            for (const run of history) {
+                assert.equal(run.agents[0].ticks, 1);
+                assert.ok(run.agents[0].error);
+            }
+        }
+        finally {
+            console.error = quiet;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    for (const kind of ['resident', 'conversation agent'])
+        for (const held of [false, true]) {
+            it(`a ${kind}'s maintenance call made once stop() has begun is withdrawn${held ? ', though a provider wait holds its model,' : ''} and no failure is reported`, { timeout: 10_000 }, async () => {
+                const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-stopping-'));
+                const provider = new CapturingMembrane();
+                const tick = new CallAfterGateStrategy();
+                const conversational = kind === 'conversation agent';
+                const framework = await AgentFramework.create({
+                    storePath: join(dir, 'store'),
+                    membrane: provider.asMembrane(),
+                    agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: conversational ? new ReadyStrategy() : tick }],
+                    modules: [],
+                    syncIntervalMs: 0,
+                    maintenanceIntervalMs: 10,
+                    ...(conversational ? { conversations: { templateAgent: 'agent', strategyFactory: () => tick } } : {}),
+                });
+                const internals = framework;
+                const name = conversational ? 'agent-conv-1' : 'agent';
+                const alerts = [];
+                framework.opsAlert = (...args) => { alerts.push(args.map(String).join(' ')); };
+                const quiet = console.error;
+                const logged = [];
+                console.error = (...args) => { logged.push(args.map(String).join(' ')); };
+                let stopping;
+                try {
+                    if (conversational)
+                        await internals.createConversationAgent(name, 'chan-1');
+                    if (held)
+                        internals.recordProviderWait(name, 'test-model', heldFor(60_000));
+                    framework.start();
+                    await waitFor(() => tick.entered);
+                    stopping = framework.stop();
+                    tick.release();
+                    await waitFor(() => tick.outcome !== undefined);
+                    await stopping;
+                    assert.equal(tick.outcome, 'MaintenanceWithdrawnError');
+                    assert.equal(provider.calls.length, 0, 'the withdrawn call sent nothing');
+                    assert.ok(logged.some((line) => line.includes(`[context-maintenance] agent=${name} stopped: maintenance call withdrawn: provider admission closed while stopping (${name})`)), logged.join('\n'));
+                    assert.deepEqual(alerts, [], 'no alert');
+                    for (const run of framework.getContextMaintenanceSnapshot().history) {
+                        for (const record of run.agents)
+                            assert.equal(record.error, undefined, `no failure recorded for ${record.agentName}`);
+                    }
+                }
+                finally {
+                    console.error = quiet;
+                    tick.release();
+                    await (stopping ?? framework.stop());
+                    rmSync(dir, { recursive: true, force: true });
+                }
+            });
+        }
+    it('stop() withdraws a maintenance call parked at the provider gate, and that is no failure', { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-parked-stop-'));
+        const strategy = new ParkedCallTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        strategy.framework = framework;
+        const alerts = [];
+        framework.opsAlert = (...args) => { alerts.push(args.map(String).join(' ')); };
+        const internals = framework;
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            framework.start();
+            await waitFor(() => internals.providerGate('agent').auxiliaryWaiters.length === 1);
+            await framework.stop();
+            assert.equal(strategy.outcome, 'MaintenanceWithdrawnError');
+            assert.equal(strategy.calls, 0, 'the withdrawn call sent nothing');
+            assert.deepEqual(alerts, []);
+        }
+        finally {
+            console.error = quiet;
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('an over-budget drain kick starts in a framework that was never started, as one run with runUntilIdle() is', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-drain-unstarted-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: new ReadyStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        const internals = framework;
+        const alerts = [];
+        framework.opsAlert = (...args) => { alerts.push(args.map(String).join(' ')); };
+        const quiet = console.error;
+        const logged = [];
+        console.error = (...args) => { logged.push(args.map(String).join(' ')); };
+        try {
+            internals.noteInferenceExhausted('agent', 'compile refused', false, 'over_budget');
+            assert.equal(internals.overBudgetDrains.size, 1, 'a kick was started');
+            assert.ok(alerts.some((alert) => alert.includes('drain breaker kicking;')), alerts.join('\n'));
+            await Promise.all([...internals.overBudgetDrains]);
+            assert.ok(logged.some((line) => line.includes('drain kicked for agent (OverBudget breaker, 8 ticks)')), logged.join('\n'));
+        }
+        finally {
+            console.error = quiet;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("a stop() begun from inside the refusal's alert waits for the kick the alert reports, which ticks none", { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-drain-stop-in-alert-'));
+        const strategy = new GatedTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        strategy.framework = framework;
+        const internals = framework;
+        const alerts = [];
+        let drainsAtAlert = -1;
+        let stopping;
+        // An ops:alert listener that stops the framework, as the alert is raised.
+        framework.opsAlert = (kind, _agentName, message) => {
+            if (kind !== 'context-refusal')
+                return;
+            alerts.push(message);
+            drainsAtAlert = internals.overBudgetDrains.size;
+            stopping ??= framework.stop();
+        };
+        const logged = [];
+        const quiet = console.error;
+        console.error = (...args) => { logged.push(args.map(String).join(' ')); };
+        try {
+            internals.noteInferenceExhausted('agent', 'compile refused', false, 'over_budget');
+            assert.ok(stopping, 'the alert began stop()');
+            assert.match(alerts[0] ?? '', /drain breaker kicking;/);
+            assert.equal(drainsAtAlert, 1, 'the kick joined the drains stop() waits for before the alert');
+            await stopping;
+            assert.equal(strategy.ticks, 0, 'the kick ticked none');
+            assert.ok(logged.some((line) => line.includes('drain kicked for agent (OverBudget breaker, 0 ticks, stopped as the framework stops)')), 'the kick says it stopped, and why');
+        }
+        finally {
+            console.error = quiet;
+            strategy.release();
+            await (stopping ?? framework.stop());
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("a surgery begun from inside the refusal's alert waits for the kick the alert reports, which ticks none", { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-drain-surgery-in-alert-'));
+        const strategy = new GatedTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        strategy.framework = framework;
+        const cm = framework.getAgent('agent').getContextManager();
+        const first = String(cm.addMessage('user', [{ type: 'text', text: 'm1' }]));
+        cm.addMessage('user', [{ type: 'text', text: 'm2' }]);
+        const internals = framework;
+        const alerts = [];
+        let drainsAtAlert = -1;
+        let moving;
+        // An ops:alert listener that rolls the agent back, as the alert is raised.
+        framework.opsAlert = (kind, _agentName, message) => {
+            if (kind !== 'context-refusal')
+                return;
+            alerts.push(message);
+            drainsAtAlert = internals.overBudgetDrains.size;
+            moving ??= framework.rollbackToMessage('agent', { messageId: first });
+        };
+        const logged = [];
+        const quiet = console.error;
+        console.error = (...args) => { logged.push(args.map(String).join(' ')); };
+        try {
+            internals.noteInferenceExhausted('agent', 'compile refused', false, 'over_budget');
+            assert.ok(moving, 'the alert began a rollback');
+            assert.match(alerts[0] ?? '', /drain breaker kicking;/);
+            assert.equal(drainsAtAlert, 1, 'the kick joined the drains the rollback waits for before the alert');
+            await moving;
+            assert.equal(strategy.ticks, 0, 'the kick ticked none');
+            assert.ok(logged.some((line) => line.includes('drain kicked for agent (OverBudget breaker, 0 ticks, stopped while a surgery holds the store)')), 'the kick says it stopped, and why');
+            assert.notEqual(cm.currentBranch().name, 'main', 'the rollback went on once the kick ended');
+        }
+        finally {
+            console.error = quiet;
+            strategy.release();
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("a stop() made from a drain's first tick, before that tick's first await, waits for the tick", { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-drain-stop-in-tick-'));
+        const strategy = new StopInTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        strategy.framework = framework;
+        const internals = framework;
+        framework.opsAlert = () => { };
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            internals.noteInferenceExhausted('agent', 'compile refused', false, 'over_budget');
+            await waitFor(() => strategy.stopping !== undefined);
+            await strategy.stopping;
+            assert.equal(strategy.stoppedBeforeTickEnd, false, 'stop() waited for the tick');
+            assert.equal(strategy.storeOpenAtTickEnd, true, 'the tick ended before the store closed');
+        }
+        finally {
+            console.error = quiet;
+            await (strategy.stopping ?? framework.stop());
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('no over-budget drain kick starts once stop() has begun', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-drain-after-stop-'));
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy: new ReadyStrategy() }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        const internals = framework;
+        const alerts = [];
+        framework.opsAlert = (...args) => { alerts.push(args.map(String).join(' ')); };
+        const quiet = console.error;
+        const logged = [];
+        console.error = (...args) => { logged.push(args.map(String).join(' ')); };
+        try {
+            framework.start();
+            const stopping = framework.stop();
+            internals.noteInferenceExhausted('agent', 'compile refused', false, 'over_budget');
+            assert.equal(internals.overBudgetDrains.size, 0, 'no kick was started');
+            assert.ok(alerts.some((alert) => alert.startsWith('context-refusal agent ')
+                && alert.includes('drain breaker not kicked: the framework is stopping;')), alerts.join('\n'));
+            await stopping;
+            assert.ok(!logged.some((line) => line.includes('drain kicked')), logged.join('\n'));
+        }
+        finally {
+            console.error = quiet;
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a surgery that takes the store while resume waits for a tick is refused by resume after the wait', { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-resume-rechecks-'));
+        const strategy = new GatedTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        strategy.framework = framework;
+        const cm = framework.getAgent('agent').getContextManager();
+        const first = String(cm.addMessage('user', [{ type: 'text', text: 'm1' }]));
+        cm.addMessage('user', [{ type: 'text', text: 'm2' }]);
+        const internals = framework;
+        try {
+            await framework.quiesce();
+            framework.start();
+            await waitFor(() => strategy.ticks === 1);
+            // resume() finds no surgery and waits for the running tick; the
+            // rollback takes the store meanwhile.
+            const resuming = framework.resume();
+            void resuming.catch(() => { });
+            const moved = framework.rollbackToMessage('agent', { messageId: first });
+            await waitFor(() => internals.surgeryHold !== null);
+            strategy.release();
+            await assert.rejects(resuming, (error) => error instanceof OperatorActionError && error.code === 'agent-busy'
+                && error.message.includes('a live roll back for agent holds the store'));
+            assert.equal(framework.getHostModeStatus().quiesced, true, 'the host stays quiesced');
+            await moved;
+        }
+        finally {
+            strategy.release();
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a rollback waits for an over-budget drain kick\'s tick in flight, and the kick ticks no more under the hold', { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-drain-hold-'));
+        const strategy = new GatedTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        strategy.framework = framework;
+        const cm = framework.getAgent('agent').getContextManager();
+        const first = String(cm.addMessage('user', [{ type: 'text', text: 'm1' }]));
+        cm.addMessage('user', [{ type: 'text', text: 'm2' }]);
+        const internals = framework;
+        const quiet = console.error;
+        console.error = () => { };
+        try {
+            // A refused compile kicks the drain, whose first tick waits on the gate.
+            internals.noteInferenceExhausted('agent', 'compile refused', false, 'over_budget');
+            await waitFor(() => strategy.ticks === 1);
+            const moved = framework.rollbackToMessage('agent', { messageId: first });
+            await waitFor(() => internals.surgeryHold !== null);
+            assert.equal(cm.currentBranch().name, 'main', 'the rollback waits for the drain kick\'s tick');
+            strategy.release();
+            await moved;
+            assert.equal(strategy.branchAtFirstTickEnd, 'main');
+            assert.equal(strategy.ticksUnderHold, 0, 'the kick starts no tick while the rollback holds the store');
+            assert.notEqual(cm.currentBranch().name, 'main');
+        }
+        finally {
+            console.error = quiet;
+            strategy.release();
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("stop() waits for an over-budget drain kick's tick in flight, and the kick ticks no more once stop() has begun", { timeout: 10_000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-drain-stop-'));
+        const strategy = new GatedTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 0,
+        });
+        strategy.framework = framework;
+        const internals = framework;
+        const quiet = console.error;
+        console.error = () => { };
+        let stopped = false;
+        try {
+            framework.start();
+            // A refused compile kicks the drain, whose first tick waits on the gate.
+            internals.noteInferenceExhausted('agent', 'compile refused', false, 'over_budget');
+            await waitFor(() => strategy.ticks === 1);
+            const stopping = framework.stop().then(() => { stopped = true; });
+            // A stop() that didn't wait would close the store with the tick held:
+            // it gets half a second to.
+            await waitFor(() => stopped, 500).catch(() => { });
+            assert.equal(stopped, false, 'stop() waits for the kick\'s tick in flight');
+            strategy.release();
+            await stopping;
+            assert.equal(strategy.storeOpenAtFirstTickEnd, true, 'the tick in flight ended before the store closed');
+            assert.equal(strategy.ticks, 1, 'the kick starts no tick once stop() has begun');
+        }
+        finally {
+            console.error = quiet;
+            strategy.release();
+            if (!stopped)
+                await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('no pass starts while a surgery holds the store', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-surgery-hold-'));
+        const strategy = new QueuedStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const internals = framework;
+        internals.surgeryHold = { verb: 'rollback', agentName: 'agent', since: Date.now() };
+        // Count the passes the timer starts while the store is held.
+        let passes = 0;
+        const runPass = internals.runQueuedMaintenance.bind(framework);
+        internals.runQueuedMaintenance = () => { passes++; return runPass(); };
+        try {
+            framework.start();
+            await waitFor(() => passes >= 3);
+            assert.equal(strategy.ticks, 0);
+            assert.equal(framework.getContextMaintenanceSnapshot().history.length, 0);
+            internals.surgeryHold = null;
+            await waitFor(() => strategy.ticks >= 2);
+        }
+        finally {
+            internals.surgeryHold = null;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a pass starts no new tick once a surgery holds the store', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-surgery-mid-pass-'));
+        const strategy = new HookedTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const internals = framework;
+        const alerts = [];
+        framework.opsAlert = (kind) => alerts.push(kind);
+        strategy.onTick = () => {
+            internals.surgeryHold = { verb: 'rollback', agentName: 'agent', since: Date.now() };
+        };
+        try {
+            framework.start();
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.length >= 1);
+            const run = firstPass(framework).agents[0];
+            assert.equal(strategy.ticks, 1);
+            assert.equal(run.ticks, 1);
+            assert.equal(run.error, undefined);
+            // The surgery waits for the pass before it switches, so reading the
+            // agent's readiness after its tick is safe.
+            assert.equal(run.readyAfter, false);
+            assert.equal(run.pendingAfter, 'hooked tick queued');
+            assert.deepEqual(alerts, []);
+        }
+        finally {
+            internals.surgeryHold = null;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a failure a pass meets while a surgery waits for it is reported as any failure', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-surgery-failure-'));
+        const strategy = new HookedTickStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        const internals = framework;
+        const alerts = [];
+        framework.opsAlert = (kind) => alerts.push(kind);
+        strategy.onTick = () => {
+            internals.surgeryHold = { verb: 'rollback', agentName: 'agent', since: Date.now() };
+            throw new Error('the tick failed while a surgery waited');
+        };
+        const logged = [];
+        const consoleError = console.error;
+        console.error = (...args) => { logged.push(args.map(String).join(' ')); };
+        try {
+            framework.start();
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.length >= 1);
+            const run = firstPass(framework).agents[0];
+            assert.equal(run.ticks, 0);
+            assert.equal(run.error, 'the tick failed while a surgery waited');
+            assert.deepEqual(alerts, ['context-maintenance-failed']);
+            assert.ok(logged.some((line) => line.includes('[context-maintenance] agent=agent failed:')
+                && line.includes('the tick failed while a surgery waited')));
+        }
+        finally {
+            console.error = consoleError;
+            internals.surgeryHold = null;
+            await framework.stop();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('a pass that ends before its agent is ready records what is still pending', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'af-maintenance-pending-after-'));
+        const strategy = new NeverReadyStrategy();
+        const framework = await AgentFramework.create({
+            storePath: join(dir, 'store'),
+            membrane,
+            agents: [{ name: 'agent', model: 'test-model', systemPrompt: 'test', strategy }],
+            modules: [],
+            syncIntervalMs: 0,
+            maintenanceIntervalMs: 10,
+        });
+        try {
+            framework.start();
+            await waitFor(() => framework.getContextMaintenanceSnapshot().history.length >= 1);
+            const run = framework.getContextMaintenanceSnapshot().history.at(-1).agents[0];
+            assert.equal(run.ticks, 8);
+            assert.equal(run.readyAfter, false);
+            assert.equal(run.pendingBefore, 'never ready');
+            assert.equal(run.pendingAfter, 'never ready');
         }
         finally {
             await framework.stop();