@zhin.js/harness 0.0.0-stage → 0.0.0

package/lib/harness.js

@@ -0,0 +1,731 @@
+/**
+ * ADR 0048 Agent Harness — composition (H1).
+ *
+ * Wires the components behind the contracts: every mail is attenuated,
+ * funded from its sender's grant, admitted by the guard kernel, journaled,
+ * and only then posted to the mailbox. The agent layer supplies the turn
+ * runner and calls `send` from its collaboration tools.
+ *
+ * Semantics:
+ * - `ask` is synchronous for the asker: `send` resolves with the target's
+ *   reply; the reply is journaled as a `result` mail but not posted to the
+ *   asker's mailbox (the asker's turn is still running and consumes it).
+ * - `delegate` is asynchronous: `send` resolves once the work is admitted;
+ *   the target's reply is posted to the delegator's mailbox as a `result`
+ *   mail, which wakes it with a new turn.
+ * - `tell` expects nothing back.
+ * - An `ask` whose target is (transitively) waiting on the asker would
+ *   deadlock the serial mailbox; it is denied as `wait_cycle` and escalated.
+ * - A denial with `escalate: true` freezes the whole engagement: an
+ *   `escalated` event is journaled, `onEscalate` is called once so the host
+ *   can ask the principal, every outstanding ask / delegate is cancelled
+ *   (askers get a `cancelled` reply), and later sends are denied as `frozen`.
+ * - An engagement closes when it has no running or queued turns and no
+ *   outstanding ask / delegate; its root grant is closed then.
+ * - Inbound mail (`human` / `timer` / `event`) enters through `deliver`
+ *   (`open` is the same call): it opens an engagement and posts the root mail
+ *   into the entry actor's inbox lane (D1). The inbox policy (`inbox.policy`,
+ *   D2) decides what the mail does to that lane, also while a turn of the
+ *   lane is running (mid-turn): queue, merge, supersede the running turn,
+ *   stop it, or reject. Every turn of every actor runs inside the mailbox;
+ *   there is no externally running root turn (H3, Q6).
+ * - A merged batch (Q2) may span several engagements (one per human
+ *   message); each engagement is accounted for by its own mails.
+ * - A `result` for a mail that ran on an explicit lane returns on that lane,
+ *   so delegated results wait for the lane's running turn (the root turn)
+ *   instead of running beside it.
+ */
+import { ALL, DEFAULT_GUARD_LIMITS, } from './contracts.js';
+import { agentOf } from './authority.js';
+import { reconstructBoardFromEvents } from './journal.js';
+export function createHarness(options) {
+    const limits = options.limits ?? DEFAULT_GUARD_LIMITS;
+    const clock = options.clock ?? Date.now;
+    let counter = 0;
+    const newId = options.newId ?? (() => `m${++counter}`);
+    const engagements = new Map();
+    const allEngagements = new Map();
+    const sentDelegations = new Map();
+    const boards = new Map();
+    const askWaiters = new Map();
+    /** asker actor → actors it is currently waiting on (per engagement). */
+    const waitingOn = new Map();
+    let closed = false;
+    const reportError = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch { /* reporting must not throw */ }
+    };
+    const mailbox = options.createMailbox({
+        run: async (actor, batch, signal, control) => {
+            const engagementId = batch[0]?.engagementId;
+            if (engagementId) {
+                await record(engagementId, 'turn_started', { actor, mails: batch.map((mail) => mail.id) }).catch(reportError);
+            }
+            return options.runTurn(actor, batch, signal, control);
+        },
+        maxConcurrentTurns: options.maxConcurrentTurns ?? 8,
+        maxQueuedPerKey: options.maxQueuedPerKey ?? 16,
+        ...(options.inbox?.policy ? { policy: options.inbox.policy } : {}),
+        ...(options.inbox?.queueTtlMs !== undefined ? { queueTtlMs: options.inbox.queueTtlMs } : {}),
+        ...(options.inbox?.now ? { now: options.inbox.now } : {}),
+        ...(options.inbox?.setTimer ? { setTimer: options.inbox.setTimer } : {}),
+        onTurnFinished: (key, batch, result) => onTurnFinished(key, batch, result),
+    });
+    function graphOf(state) {
+        return {
+            engagement: state.engagement,
+            get mails() { return state.mails; },
+            get: (id) => state.byId.get(id),
+        };
+    }
+    async function record(engagementId, type, data) {
+        await options.journal.append({ engagementId, at: clock(), type, data });
+    }
+    function admit(state, mail) {
+        state.mails.push(mail);
+        state.byId.set(mail.id, mail);
+    }
+    function waitKey(engagementId, actor) {
+        return `${engagementId}\u0000${actor}`;
+    }
+    /** True when `target` is, directly or transitively, waiting on `asker`. */
+    function wouldCycle(engagementId, asker, target) {
+        if (asker === target)
+            return true;
+        const seen = new Set();
+        const stack = [target];
+        for (let actor = stack.pop(); actor !== undefined; actor = stack.pop()) {
+            if (actor === asker)
+                return true;
+            if (seen.has(actor))
+                continue;
+            seen.add(actor);
+            for (const next of waitingOn.get(waitKey(engagementId, actor)) ?? [])
+                stack.push(next);
+        }
+        return false;
+    }
+    function mailSummary(mail) {
+        return {
+            mailId: mail.id,
+            kind: mail.kind,
+            from: mail.from.kind === 'actor' ? mail.from.actor : mail.from.kind === 'human' ? `human:${mail.from.principal.id}` : `system:${mail.from.source}`,
+            to: mail.to,
+            causationId: mail.causationId ?? null,
+            grantId: mail.grantId,
+            tools: mail.authority.tools.kind === 'all' ? '*' : [...mail.authority.tools.names],
+            trust: mail.authority.trust,
+        };
+    }
+    async function escalate(state, mail, code, reason) {
+        if (state.frozen)
+            return;
+        state.frozen = { code, reason };
+        await record(state.engagement.id, 'escalated', { ...mailSummary(mail), code, reason });
+        // Stop every branch still in flight; their askers receive a cancelled reply.
+        for (const id of [...state.outstanding]) {
+            if (!mailbox.cancel(id, `engagement frozen: ${reason}`)) {
+                const waiter = askWaiters.get(id);
+                if (waiter) {
+                    askWaiters.delete(id);
+                    state.outstanding.delete(id);
+                    waiter.resolve({ status: 'cancelled', content: `engagement frozen: ${reason}` });
+                }
+            }
+        }
+        try {
+            await options.onEscalate?.({ engagement: state.engagement, mail, code, reason });
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+    async function maybeCloseEngagement(state) {
+        if (state.closed || state.pendingTurns > 0 || state.outstanding.size > 0)
+            return;
+        state.closed = true;
+        const snapshot = options.ledger.close(state.engagement.rootGrantId);
+        await record(state.engagement.id, 'engagement_closed', {
+            status: state.frozen ? 'escalated' : 'completed',
+            ...(state.frozen ? { reason: state.frozen.reason } : {}),
+            budget: snapshot.ok ? { spent: snapshot.value.spent, granted: snapshot.value.granted } : null,
+        });
+        await options.journal.compact?.(state.engagement.id).catch(reportError);
+        engagements.delete(state.engagement.id);
+        try {
+            options.onEngagementClosed?.(state.engagement);
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+    function post(state, mail) {
+        const posted = mailbox.post(mail);
+        if (!posted.accepted) {
+            return { ok: false, code: posted.code === 'mailbox_closed' ? 'closed' : posted.code, reason: posted.message };
+        }
+        // A stop request is consumed by the inbox: it never becomes a turn.
+        if (posted.disposition !== 'stopped')
+            state.pendingTurns += 1;
+        return { ok: true, disposition: posted.disposition, position: posted.position };
+    }
+    async function onTurnFinished(key, batch, result) {
+        // A merged batch (Q2) may carry mails of several engagements.
+        const byEngagement = new Map();
+        for (const mail of batch) {
+            const list = byEngagement.get(mail.engagementId);
+            if (list)
+                list.push(mail);
+            else
+                byEngagement.set(mail.engagementId, [mail]);
+        }
+        for (const [engagementId, mails] of byEngagement) {
+            const state = engagements.get(engagementId);
+            if (!state)
+                continue;
+            state.pendingTurns -= mails.length;
+            try {
+                await record(state.engagement.id, 'turn_finished', {
+                    actor: key.actor,
+                    mails: mails.map((mail) => mail.id),
+                    status: result.status,
+                    ...(result.reason ? { reason: result.reason } : {}),
+                    ...(engagementId !== key.engagementId ? { carriedBy: key.engagementId } : {}),
+                });
+                for (const mail of mails) {
+                    if (mail.body.kind === 'tell')
+                        options.ledger.close(mail.grantId);
+                    if (mail.body.kind !== 'ask' && mail.body.kind !== 'delegate')
+                        continue;
+                    await reply(state, mail, result);
+                }
+            }
+            catch (error) {
+                reportError(error);
+            }
+            finally {
+                await maybeCloseEngagement(state).catch(reportError);
+            }
+        }
+    }
+    /** Sends the target's reply for an ask / delegate back to its sender. */
+    async function reply(state, request, result) {
+        if (request.from.kind !== 'actor')
+            return;
+        const requester = request.from.actor;
+        const content = result.content ?? '';
+        const parent = request.causationId ? state.byId.get(request.causationId) : undefined;
+        const back = Object.freeze({
+            id: newId(),
+            kind: 'result',
+            engagementId: state.engagement.id,
+            causationId: request.id,
+            from: Object.freeze({ kind: 'actor', actor: request.to }),
+            to: requester,
+            // Back on the requester's lane, behind the turn that asked (it may still be running).
+            ...(parent?.lane !== undefined && parent.to === requester ? { lane: parent.lane } : {}),
+            // The reply runs with the requester's own authority and grant, never the replier's.
+            authority: parent?.authority ?? request.authority,
+            grantId: parent?.grantId ?? request.grantId,
+            body: Object.freeze({ kind: 'result', inReplyTo: request.id, status: result.status, content }),
+            createdAt: clock(),
+        });
+        options.ledger.close(request.grantId);
+        state.outstanding.delete(request.id);
+        const ceiling = options.ceilingOf(agentOf(requester), state.engagement.id);
+        const decision = ceiling
+            ? options.guard.admitMail(back, { graph: graphOf(state), targetCeiling: ceiling, limits })
+            : { allow: false, code: 'not_accepted_by_target', reason: `unknown agent ${requester}`, escalate: false };
+        if (!decision.allow) {
+            await record(state.engagement.id, 'mail_denied', { ...mailSummary(back), code: decision.code, reason: decision.reason });
+            askWaiters.get(request.id)?.resolve({ status: 'failed', content: decision.reason });
+            askWaiters.delete(request.id);
+            return;
+        }
+        admit(state, back);
+        await record(state.engagement.id, 'mail_admitted', mailSummary(back));
+        const waiter = askWaiters.get(request.id);
+        if (waiter) {
+            askWaiters.delete(request.id);
+            waitingOn.get(waitKey(state.engagement.id, waiter.asker))?.delete(request.to);
+            waiter.resolve({ status: result.status, content });
+            return;
+        }
+        const posted = post(state, back);
+        if (!posted.ok)
+            await record(state.engagement.id, 'mail_denied', { ...mailSummary(back), code: posted.code, reason: posted.reason });
+    }
+    async function deliver(input) {
+        if (closed)
+            return { ok: false, code: 'closed', reason: 'harness is closed' };
+        const engagementId = newId();
+        const ceiling = options.ceilingOf(agentOf(input.entry), engagementId);
+        if (!ceiling)
+            return { ok: false, code: 'unknown_agent', reason: `unknown agent ${agentOf(input.entry)}` };
+        const rootGrantId = options.ledger.openRoot(input.budget);
+        const rootMailId = newId();
+        const engagement = Object.freeze({
+            id: engagementId,
+            principal: input.principal,
+            rootMailId,
+            rootGrantId,
+            venue: input.venue,
+            openedAt: clock(),
+        });
+        const from = input.body.kind === 'human'
+            ? { kind: 'human', principal: input.principal }
+            : { kind: 'system', source: input.body.kind === 'timer' ? 'timer' : 'event' };
+        const root = Object.freeze({
+            id: rootMailId,
+            kind: input.body.kind,
+            engagementId,
+            from: Object.freeze(from),
+            to: input.entry,
+            ...(input.lane !== undefined ? { lane: input.lane } : {}),
+            authority: options.rootAuthority(input.principal, ceiling, { approvers: input.approvers }),
+            grantId: rootGrantId,
+            body: input.body,
+            createdAt: clock(),
+        });
+        const state = {
+            engagement,
+            initialBudget: input.budget,
+            mails: [],
+            byId: new Map(),
+            pendingTurns: 0,
+            outstanding: new Set(),
+            closed: false,
+        };
+        engagements.set(engagementId, state);
+        allEngagements.set(engagementId, state);
+        await record(engagementId, 'engagement_opened', {
+            principal: input.principal.id,
+            initiator: input.principal,
+            ...(input.venue ? { venue: input.venue } : {}),
+            entry: input.entry,
+            rootMailId,
+            rootGrantId,
+            budget: input.budget,
+            ...(input.lane !== undefined ? { lane: input.lane } : {}),
+        });
+        const decision = options.guard.admitMail(root, { graph: graphOf(state), targetCeiling: ceiling, limits });
+        if (!decision.allow) {
+            await record(engagementId, 'mail_denied', { ...mailSummary(root), code: decision.code, reason: decision.reason });
+            await maybeCloseEngagement(state);
+            return { ok: false, code: decision.code, reason: decision.reason };
+        }
+        admit(state, root);
+        await record(engagementId, 'mail_admitted', mailSummary(root));
+        if (closed) {
+            await maybeCloseEngagement(state);
+            return { ok: false, code: 'closed', reason: 'harness is closed' };
+        }
+        try {
+            input.onPosting?.(root);
+        }
+        catch (error) {
+            reportError(error);
+        }
+        const posted = post(state, root);
+        if (!posted.ok) {
+            await record(engagementId, 'mail_denied', { ...mailSummary(root), code: posted.code, reason: posted.reason });
+            await maybeCloseEngagement(state);
+            return { ok: false, code: posted.code, reason: posted.reason };
+        }
+        if (posted.disposition === 'stopped')
+            await maybeCloseEngagement(state);
+        return { ok: true, engagement, root, disposition: posted.disposition, position: posted.position };
+    }
+    async function sendInternal(from, current, request, overrides) {
+        const state = engagements.get(current.engagementId);
+        const deny = async (code, reason, mail, escalateIt = false) => {
+            if (state && mail) {
+                await record(state.engagement.id, 'mail_denied', { ...mailSummary(mail), code, reason });
+                if (escalateIt)
+                    await escalate(state, mail, code, reason);
+            }
+            return { ok: false, accepted: false, code, reason, escalated: escalateIt && Boolean(state && mail) };
+        };
+        if (closed)
+            return deny('closed', 'harness is closed');
+        if (!state || state.closed)
+            return deny('unknown_engagement', `engagement ${current.engagementId} is not open`);
+        if (state.frozen) {
+            return {
+                ok: false,
+                accepted: false,
+                code: 'frozen',
+                reason: `collaboration is paused for the human to decide: ${state.frozen.reason}`,
+                escalated: true,
+            };
+        }
+        if (current.to !== from || !state.byId.has(current.id)) {
+            return deny('authority_not_attenuated', `${from} is not processing mail ${current.id}`);
+        }
+        const isRemote = Boolean(options.remoteTransport?.canRoute(request.to));
+        const ceiling = options.ceilingOf(agentOf(request.to), state.engagement.id)
+            ?? (isRemote
+                ? {
+                    agent: agentOf(request.to),
+                    tools: ALL,
+                    contacts: ALL,
+                    maxTrust: 'master',
+                    egress: { network: true, hosts: ALL },
+                    acceptsFrom: ALL,
+                }
+                : undefined);
+        if (!ceiling)
+            return deny('unknown_agent', `unknown agent ${agentOf(request.to)}`);
+        const budgetRequest = request.budget ?? ceiling.defaultBudget ?? {};
+        const granted = options.ledger.grant(current.grantId, budgetRequest);
+        const grantId = granted.ok ? granted.value : current.grantId;
+        const body = request.kind === 'ask'
+            ? { kind: 'ask', question: request.text }
+            : request.kind === 'delegate'
+                ? { kind: 'delegate', brief: request.text, ...(request.deliverable ? { deliverable: request.deliverable } : {}) }
+                : { kind: 'tell', content: request.text };
+        const mail = Object.freeze({
+            id: newId(),
+            kind: request.kind,
+            engagementId: state.engagement.id,
+            causationId: overrides?.causationId ?? current.id,
+            from: Object.freeze({ kind: 'actor', actor: from }),
+            to: request.to,
+            authority: overrides?.authority ?? options.attenuate(current.authority, request.narrowing ?? {}, ceiling, from),
+            grantId,
+            body: Object.freeze(body),
+            createdAt: clock(),
+        });
+        if (!granted.ok)
+            return deny('budget_exceeded', granted.message, mail);
+        const decision = options.guard.admitMail(mail, {
+            graph: graphOf(state),
+            targetCeiling: ceiling,
+            senderAuthority: current.authority,
+            limits,
+        });
+        if (!decision.allow) {
+            options.ledger.close(grantId);
+            return deny(decision.code, decision.reason, mail, decision.escalate);
+        }
+        if (request.kind === 'ask' && wouldCycle(state.engagement.id, from, request.to)) {
+            options.ledger.close(grantId);
+            return deny('wait_cycle', `${request.to} is waiting on ${from}; asking it back would deadlock`, mail, true);
+        }
+        admit(state, mail);
+        await record(state.engagement.id, 'mail_admitted', mailSummary(mail));
+        const snapshot = options.ledger.snapshot(grantId);
+        if (granted.ok && request.kind !== 'tell') {
+            await record(state.engagement.id, 'budget_granted', {
+                grantId,
+                parentId: current.grantId,
+                granted: snapshot?.granted ?? null,
+            });
+        }
+        if (request.kind === 'ask' || request.kind === 'delegate') {
+            sentDelegations.set(mail.id, {
+                id: mail.id,
+                engagementId: state.engagement.id,
+                from,
+                to: request.to,
+                authority: mail.authority,
+                parentMail: current,
+                ...(current.lane !== undefined ? { lane: current.lane } : {}),
+            });
+        }
+        if (isRemote && options.remoteTransport) {
+            const remoteTransport = options.remoteTransport;
+            const grantedAmounts = snapshot?.granted ?? {
+                modelCalls: 0,
+                tokens: 0,
+                wallMs: 0,
+                sideEffects: 0,
+            };
+            if (request.kind === 'tell') {
+                void Promise.resolve()
+                    .then(() => remoteTransport.send(mail, grantedAmounts))
+                    .then(async (remoteRes) => {
+                    if (remoteRes?.consumed && Object.keys(remoteRes.consumed).length > 0) {
+                        const ch = options.ledger.charge(grantId, remoteRes.consumed);
+                        await record(state.engagement.id, ch.ok ? 'budget_charged' : 'budget_exceeded', {
+                            grantId,
+                            mailId: mail.id,
+                            usage: remoteRes.consumed,
+                            ...(ch.ok ? {} : { exhausted: ch.exhausted ?? [] }),
+                        });
+                    }
+                })
+                    .catch(reportError)
+                    .finally(() => {
+                    options.ledger.close(grantId);
+                    void maybeCloseEngagement(state).catch(reportError);
+                });
+                return { ok: true, accepted: true, mailId: mail.id, mail };
+            }
+            state.outstanding.add(mail.id);
+            let remoteResult;
+            try {
+                const sendPromise = options.remoteTransport.send(mail, grantedAmounts);
+                if (request.timeoutMs !== undefined && request.timeoutMs > 0) {
+                    let timer;
+                    const timeoutPromise = new Promise((resolve) => {
+                        timer = setTimeout(() => {
+                            resolve({
+                                status: 'cancelled',
+                                content: `remote mail ${mail.id} timed out after ${request.timeoutMs}ms`,
+                            });
+                        }, request.timeoutMs);
+                        timer.unref?.();
+                    });
+                    remoteResult = await Promise.race([sendPromise, timeoutPromise]).finally(() => {
+                        if (timer !== undefined)
+                            clearTimeout(timer);
+                    });
+                }
+                else {
+                    remoteResult = await sendPromise;
+                }
+            }
+            catch (error) {
+                remoteResult = {
+                    status: 'rejected',
+                    content: error instanceof Error ? error.message : String(error),
+                };
+            }
+            finally {
+                state.outstanding.delete(mail.id);
+            }
+            const consumed = remoteResult.consumed ?? { modelCalls: 1 };
+            const chargeRes = options.ledger.charge(grantId, consumed);
+            await record(state.engagement.id, chargeRes.ok ? 'budget_charged' : 'budget_exceeded', {
+                grantId,
+                mailId: mail.id,
+                usage: consumed,
+                ...(chargeRes.ok ? {} : { exhausted: chargeRes.exhausted ?? [] }),
+            });
+            options.ledger.close(grantId);
+            await record(state.engagement.id, 'mail_delivered', { mailId: mail.id, actor: request.to });
+            if (remoteResult.status === 'completed') {
+                await record(state.engagement.id, 'mail_completed', {
+                    mailId: mail.id,
+                    actor: request.to,
+                    status: 'completed',
+                    content: remoteResult.content,
+                });
+            }
+            else {
+                await record(state.engagement.id, 'mail_cancelled', {
+                    mailId: mail.id,
+                    actor: request.to,
+                    status: remoteResult.status,
+                    reason: remoteResult.content,
+                });
+            }
+            await maybeCloseEngagement(state).catch(reportError);
+            const turnStatus = remoteResult.status === 'completed'
+                ? 'completed'
+                : remoteResult.status === 'cancelled'
+                    ? 'cancelled'
+                    : 'failed';
+            return {
+                ok: true,
+                accepted: true,
+                mailId: mail.id,
+                mail,
+                reply: { status: turnStatus, content: remoteResult.content },
+                result: { status: remoteResult.status, content: remoteResult.content },
+            };
+        }
+        if (request.kind !== 'tell')
+            state.outstanding.add(mail.id);
+        let replied;
+        if (request.kind === 'ask') {
+            replied = new Promise((resolve) => askWaiters.set(mail.id, { asker: from, engagementId: state.engagement.id, resolve }));
+            const key = waitKey(state.engagement.id, from);
+            const set = waitingOn.get(key) ?? new Set();
+            set.add(request.to);
+            waitingOn.set(key, set);
+        }
+        const posted = post(state, mail);
+        if (!posted.ok) {
+            state.outstanding.delete(mail.id);
+            askWaiters.delete(mail.id);
+            waitingOn.get(waitKey(state.engagement.id, from))?.delete(request.to);
+            options.ledger.close(grantId);
+            return deny(posted.code, posted.reason, mail);
+        }
+        if (!replied)
+            return { ok: true, accepted: true, mailId: mail.id, mail };
+        const replyVal = await replied;
+        return { ok: true, accepted: true, mailId: mail.id, mail, reply: replyVal, result: replyVal };
+    }
+    return {
+        deliver,
+        open: deliver,
+        remaining(current) {
+            return options.ledger.snapshot(current.grantId)?.remaining;
+        },
+        send(from, current, request) {
+            return sendInternal(from, current, request);
+        },
+        async followUp(input) {
+            const original = sentDelegations.get(input.mailId);
+            if (!original || original.from !== input.from) {
+                return Object.freeze({
+                    ok: false,
+                    accepted: false,
+                    mailId: input.mailId,
+                    code: 'missing_causation',
+                    reason: Object.freeze({
+                        code: 'missing_causation',
+                        detail: !original
+                            ? `unknown delegated mail ${input.mailId}`
+                            : `mail ${input.mailId} was sent by ${original.from}, not ${input.from}`,
+                    }),
+                    escalated: false,
+                });
+            }
+            const state = engagements.get(original.engagementId) ?? allEngagements.get(original.engagementId);
+            if (!state) {
+                return Object.freeze({
+                    ok: false,
+                    accepted: false,
+                    mailId: input.mailId,
+                    code: 'unknown_engagement',
+                    reason: Object.freeze({
+                        code: 'unknown_engagement',
+                        detail: `engagement ${original.engagementId} does not exist`,
+                    }),
+                    escalated: false,
+                });
+            }
+            const wasClosed = state.closed;
+            let carrierMail = original.parentMail;
+            if (wasClosed) {
+                state.closed = false;
+                engagements.set(state.engagement.id, state);
+            }
+            const snap = options.ledger.snapshot(carrierMail.grantId);
+            if (!snap || snap.closed) {
+                const reopenedGrant = options.ledger.openRoot(state.initialBudget);
+                carrierMail = Object.freeze({ ...carrierMail, grantId: reopenedGrant });
+                state.byId.set(carrierMail.id, carrierMail);
+            }
+            const outcome = await sendInternal(input.from, carrierMail, {
+                kind: 'ask',
+                to: original.to,
+                text: `[Follow-up on ${input.mailId}]\n${input.content}`,
+                ...(input.budget ? { budget: input.budget } : {}),
+                ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+            }, {
+                causationId: input.mailId,
+                authority: original.authority,
+            });
+            if (wasClosed) {
+                await maybeCloseEngagement(state).catch(reportError);
+            }
+            if (!outcome.ok) {
+                return Object.freeze({
+                    ok: false,
+                    accepted: false,
+                    mailId: input.mailId,
+                    code: outcome.code,
+                    reason: Object.freeze({ code: outcome.code, detail: outcome.reason }),
+                    escalated: outcome.escalated,
+                });
+            }
+            return Object.freeze({
+                ok: true,
+                accepted: true,
+                mailId: outcome.mail.id,
+                mail: outcome.mail,
+                ...(outcome.reply ? { reply: outcome.reply } : {}),
+                ...(outcome.result ? { result: outcome.result } : outcome.reply ? { result: outcome.reply } : {}),
+            });
+        },
+        async writeBoard(engagementId, input) {
+            const key = typeof input.key === 'string' ? input.key.trim() : '';
+            if (!key)
+                throw new TypeError('Board entry key must be a non-empty string');
+            const kind = input.kind ?? 'note';
+            let board = boards.get(engagementId);
+            if (!board) {
+                board = new Map();
+                boards.set(engagementId, board);
+            }
+            const existing = board.get(key);
+            const version = (existing?.version ?? 0) + 1;
+            const updatedAt = clock();
+            const entry = Object.freeze({
+                key,
+                kind,
+                content: input.content,
+                author: input.author,
+                updatedAt,
+                version,
+                ...(input.status !== undefined ? { status: input.status } : {}),
+            });
+            board.set(key, entry);
+            await record(engagementId, 'board_written', {
+                actor: input.author,
+                key,
+                kind,
+                content: input.content,
+                ...(input.status !== undefined ? { status: input.status } : {}),
+                ...(input.mailId !== undefined ? { mailId: input.mailId } : {}),
+                version,
+            });
+            return entry;
+        },
+        async readBoard(engagementId, filter) {
+            const board = boards.get(engagementId);
+            if (board && board.size > 0) {
+                const entries = [...board.values()].filter((entry) => {
+                    if (filter?.key !== undefined && entry.key !== filter.key)
+                        return false;
+                    if (filter?.kind !== undefined && entry.kind !== filter.kind)
+                        return false;
+                    return true;
+                });
+                return Object.freeze(entries);
+            }
+            const records = await options.journal.read(engagementId);
+            return reconstructBoardFromEvents(records, filter);
+        },
+        async charge(current, usage) {
+            const result = options.ledger.charge(current.grantId, usage);
+            await record(current.engagementId, result.ok ? 'budget_charged' : 'budget_exceeded', {
+                grantId: current.grantId,
+                mailId: current.id,
+                usage,
+                ...(result.ok ? {} : { exhausted: result.exhausted ?? [] }),
+            });
+            return result;
+        },
+        cancel(mailId, reason) {
+            return mailbox.cancel(mailId, reason);
+        },
+        cancelSender(actor, lane, senderId, reason) {
+            return mailbox.cancelSender({ actor, lane }, senderId, reason);
+        },
+        engagement(id) {
+            return engagements.get(id)?.engagement;
+        },
+        graph(id) {
+            const state = engagements.get(id) ?? allEngagements.get(id);
+            return state ? graphOf(state) : undefined;
+        },
+        idle() {
+            return mailbox.idle();
+        },
+        async close(reason) {
+            closed = true;
+            await mailbox.close(reason);
+            for (const waiter of askWaiters.values())
+                waiter.resolve({ status: 'cancelled', content: reason ?? 'harness closed' });
+            askWaiters.clear();
+        },
+    };
+}