@north-light/crouter 0.3.154

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -0,0 +1,942 @@
+// canvas-inbox-watcher.ts — in-process delivery of a canvas node's active inbox.
+//
+// The watcher polls the append-only inbox in physical order, coalesces each quiet
+// burst, and hands hidden situational context and visible digests to pi. A send
+// return is only a handoff. Exact cursor persistence at agent_settled is the
+// durable boundary; an uncommitted process exit is recovered by rereading from
+// the unchanged cursor.
+import { coalesce, readCanceledEntryIds, readCursor, readInboxRange, readInboxSince, writeCursor, } from '../core/feed/inbox.js';
+import { getNode } from '../core/canvas/index.js';
+import { emitEvent } from '../core/events/emit.js';
+import { errorClassFromError } from '../core/events/errors.js';
+import { operationIdContext } from '../core/events/operation-id.js';
+import { readSituationalContext, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
+const DEFAULT_TICK_MS = 800;
+const DEFAULT_DEBOUNCE_MS = 1000;
+const MAX_PENDING_HANDOFFS = 64;
+const REPLAY_RESERVED_HANDOFFS = 2;
+const MAX_ORDINARY_HANDOFFS = MAX_PENDING_HANDOFFS - REPLAY_RESERVED_HANDOFFS;
+const MAX_SOURCE_OPERATION_IDS = 16;
+let currentWatcher;
+let nextGeneration = 0;
+class WatcherFatalError extends Error {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = 'WatcherFatalError';
+    }
+}
+function resolveCadence() {
+    const parse = (raw, fallback) => {
+        if (raw === undefined)
+            return fallback;
+        const value = Number(raw);
+        return Number.isFinite(value) && value > 0 ? value : fallback;
+    };
+    return {
+        tickMs: parse(process.env['CRTR_WATCHER_TICK_MS'], DEFAULT_TICK_MS),
+        debounceMs: parse(process.env['CRTR_WATCHER_DEBOUNCE_MS'], DEFAULT_DEBOUNCE_MS),
+    };
+}
+function currentNodeId() {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    return nodeId === undefined || nodeId.trim() === '' ? undefined : nodeId;
+}
+function isFilesystemError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    try {
+        return typeof error.code === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+function safeErrorClass(error) {
+    try {
+        return errorClassFromError(error);
+    }
+    catch {
+        return { class: 'unknown' };
+    }
+}
+function emitBestEffort(input) {
+    try {
+        emitEvent(input);
+    }
+    catch {
+        // Canonical events are observational; delivery and cursor state stay authoritative.
+    }
+}
+function emitFreshBestEffort(input) {
+    try {
+        operationIdContext.fresh((operationId) => {
+            emitBestEffort({ ...input, operation_id: operationId });
+        });
+    }
+    catch {
+        // Diagnostic emission cannot replace the condition being diagnosed.
+    }
+}
+function emitStoredBestEffort(operationId, input) {
+    try {
+        operationIdContext.run(operationId, () => {
+            emitBestEffort({ ...input, operation_id: operationId });
+        });
+    }
+    catch {
+        // Delivery state remains authoritative when its observational record cannot append.
+    }
+}
+function deliveryFacts(entries, channel) {
+    if (entries.length === 0)
+        throw new Error(`cannot create an empty ${channel} delivery`);
+    const allSourceOperationIds = [...new Set(entries.map((entry) => entry.operation_id))].sort();
+    const omitted = allSourceOperationIds.length - MAX_SOURCE_OPERATION_IDS;
+    return {
+        channel,
+        entryIds: entries.map((entry) => entry.entry_id),
+        throughEntryId: entries.at(-1).entry_id,
+        sourceOperationIds: allSourceOperationIds.slice(0, MAX_SOURCE_OPERATION_IDS),
+        ...(omitted > 0 ? { sourceOperationIdsOmitted: omitted } : {}),
+    };
+}
+function deliveryFields(facts) {
+    return {
+        channel: facts.channel,
+        entry_ids: facts.entryIds,
+        through_entry_id: facts.throughEntryId,
+        source_operation_ids: facts.sourceOperationIds,
+        ...(facts.sourceOperationIdsOmitted === undefined
+            ? {}
+            : { source_operation_ids_omitted: facts.sourceOperationIdsOmitted }),
+    };
+}
+function emitDeliveryCompleted(handoff) {
+    emitStoredBestEffort(handoff.operationId, {
+        level: 'info',
+        event: 'inbox.delivery.completed',
+        outcome: 'succeeded',
+        fields: deliveryFields(handoff),
+    });
+}
+function emitDeliveryFailure(operationId, facts, stage, error) {
+    emitStoredBestEffort(operationId, {
+        level: 'error',
+        event: 'inbox.delivery.failed',
+        outcome: 'failed',
+        error,
+        error_class: safeErrorClass(error),
+        fields: { stage, ...deliveryFields(facts) },
+    });
+}
+function emitDeliveryAbandoned(handoff, reason) {
+    emitStoredBestEffort(handoff.operationId, {
+        level: 'error',
+        event: 'inbox.delivery.failed',
+        outcome: 'failed',
+        error_class: { class: 'unknown' },
+        fields: { stage: 'abandoned', reason, ...deliveryFields(handoff) },
+    });
+}
+function isSessionShutdownReason(value) {
+    return value === 'quit' || value === 'reload' || value === 'new' || value === 'resume' || value === 'fork';
+}
+function disposalReasonForShutdown(reason) {
+    switch (reason) {
+        case 'quit':
+            return 'shutdown';
+        case 'reload':
+        case 'new':
+        case 'resume':
+        case 'fork':
+            return 'reload';
+        default: {
+            const exhaustive = reason;
+            return exhaustive;
+        }
+    }
+}
+function boundedRuntimeReason(value) {
+    if (typeof value === 'string')
+        return value.slice(0, 128);
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint')
+        return String(value).slice(0, 128);
+    return typeof value;
+}
+class CanvasInboxWatcher {
+    pi;
+    cadence;
+    generation;
+    timer;
+    armed = false;
+    lastCtx;
+    streaming = false;
+    nodeId;
+    cursor;
+    durableCursor;
+    buffer = [];
+    lastArrival = 0;
+    pendingHandoffs = [];
+    replay;
+    seeded = false;
+    disposed = false;
+    disposalReason;
+    fatalError;
+    fatalEscaped = false;
+    constructor(pi, cadence, generation) {
+        this.pi = pi;
+        this.cadence = cadence;
+        this.generation = generation;
+    }
+    start() {
+        const capture = (event, ctx) => {
+            if (!this.canMutate())
+                return;
+            this.captureCtx(event, ctx);
+        };
+        // session_start is the ONLY arm point: pi rebinds its action methods
+        // (sendUserMessage/sendMessage) during session construction, AFTER every
+        // extension factory has already run, and emits session_start only once
+        // that bind has happened (see registerCanvasInboxWatcher's header note).
+        // Registering `this.pi.on(...)` here is side-effect-free (no Pi action is
+        // called), so the factory that constructs and starts this watcher can run
+        // safely during extension loading, before actions are bound. Arming the
+        // interval + running the first tick is deferred to `arm()`, which only
+        // this handler calls.
+        this.pi.on('session_start', (event, ctx) => {
+            if (!this.canMutate())
+                return;
+            this.captureCtx(event, ctx);
+            this.arm();
+        });
+        this.pi.on('turn_end', capture);
+        this.pi.on('agent_start', (event, ctx) => {
+            if (!this.canMutate())
+                return;
+            this.captureCtx(event, ctx);
+            this.streaming = true;
+        });
+        this.pi.on('agent_end', (event, ctx) => {
+            if (!this.canMutate())
+                return;
+            this.captureCtx(event, ctx);
+            this.streaming = false;
+            // agent_end can precede retry, compaction, or queued continuation.
+        });
+        this.pi.on('agent_settled', (event, ctx) => {
+            if (!this.canMutate())
+                return;
+            this.captureCtx(event, ctx);
+            const nodeId = currentNodeId();
+            if (nodeId === undefined)
+                return;
+            try {
+                this.assertNodeOwnership(nodeId, 'settle');
+                const refreshHeld = this.readRefreshIntentOrFatal(nodeId, 'settle');
+                if (refreshHeld) {
+                    this.dispose('refresh', true, ctx);
+                }
+                else {
+                    // agent_settled is the authoritative durable boundary: pi guarantees
+                    // every queued continuation has drained, so hasPendingMessages() must
+                    // not veto the commit here.
+                    this.settle(nodeId, ctx, false, false);
+                }
+            }
+            catch (error) {
+                this.dispose('shutdown', false, undefined, { error, stage: 'settle' });
+            }
+        });
+        this.pi.on('session_shutdown', (event) => {
+            if (!this.canMutate())
+                return;
+            let runtimeReason;
+            try {
+                runtimeReason = event?.reason;
+            }
+            catch {
+                runtimeReason = undefined;
+            }
+            const reason = isSessionShutdownReason(runtimeReason)
+                ? disposalReasonForShutdown(runtimeReason)
+                : 'reload';
+            if (!isSessionShutdownReason(runtimeReason)) {
+                emitFreshBestEffort({
+                    level: 'warn',
+                    event: 'inbox.lifecycle.unknown_shutdown_reason',
+                    outcome: 'failed',
+                    fields: { reason: boundedRuntimeReason(runtimeReason) },
+                });
+            }
+            try {
+                const nodeId = currentNodeId();
+                const refreshHeld = nodeId !== undefined && this.readRefreshIntentOrFatal(nodeId, 'settle');
+                // This is the graceful fallback when no agent_settled fired before exit.
+                // It holds both an unconsumed queued handoff and every handoff made to a
+                // conversation being discarded by refresh.
+                this.dispose(reason, true, this.lastCtx, undefined, refreshHeld);
+            }
+            catch (error) {
+                this.dispose(reason, false, undefined, { error, stage: 'settle' });
+            }
+        });
+    }
+    /** Idempotent: arms the poll interval and runs the initial tick exactly
+     *  once, no matter how many times `session_start` fires (a resume, a fork,
+     *  or any other re-emission all land here). Called only from the
+     *  `session_start` handler above, so it never runs before Pi's action
+     *  methods are bound. */
+    arm() {
+        if (this.armed)
+            return;
+        this.armed = true;
+        this.timer = setInterval(() => this.runTick(), this.cadence.tickMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+        // A revived broker can already have persisted inbox work. Buffer it now so
+        // the normal debounce owns delivery instead of waiting a full tick.
+        this.runTick('schedule');
+    }
+    dispose(reason, atSettleBoundary, settleCtx, fatalDisposal, refreshHeld = reason === 'refresh') {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.disposalReason = reason;
+        this.clearTimer();
+        let fatal = fatalDisposal;
+        try {
+            if (atSettleBoundary) {
+                const nodeId = currentNodeId();
+                if (nodeId !== undefined) {
+                    this.assertNodeOwnership(nodeId, 'settle');
+                    this.settle(nodeId, settleCtx, refreshHeld, reason !== 'refresh');
+                }
+            }
+        }
+        catch (error) {
+            fatal = { error, stage: 'settle' };
+        }
+        finally {
+            const abandoned = this.pendingHandoffs.splice(0);
+            this.buffer.length = 0;
+            this.cursor = undefined;
+            this.durableCursor = undefined;
+            this.replay = undefined;
+            this.nodeId = undefined;
+            this.lastCtx = undefined;
+            this.lastArrival = 0;
+            this.streaming = false;
+            this.seeded = false;
+            if (this.ownsCurrentGeneration())
+                currentWatcher = undefined;
+            for (const handoff of abandoned)
+                emitDeliveryAbandoned(handoff, reason);
+        }
+        if (fatal !== undefined) {
+            this.scheduleHandlerFatal(fatal.error, fatal.stage);
+            return;
+        }
+    }
+    ownsCurrentGeneration() {
+        return currentWatcher === this && currentWatcher.generation === this.generation;
+    }
+    canMutate() {
+        return this.ownsCurrentGeneration() && !this.disposed && this.fatalError === undefined;
+    }
+    captureCtx(_event, ctx) {
+        if (ctx !== undefined)
+            this.lastCtx = ctx;
+    }
+    clearTimer() {
+        if (this.timer === undefined)
+            return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    isIdle() {
+        try {
+            if (typeof this.lastCtx?.isIdle === 'function')
+                return this.lastCtx.isIdle() === true;
+        }
+        catch {
+            // The streaming flag remains the local idle signal when context inspection fails.
+        }
+        return !this.streaming;
+    }
+    readRefreshIntentOrFatal(nodeId, stage) {
+        try {
+            return getNode(nodeId)?.intent === 'refresh';
+        }
+        catch (error) {
+            this.raiseReadFatal(stage, error);
+        }
+    }
+    assertNodeOwnership(nodeId, stage) {
+        if (!this.seeded || this.nodeId === undefined || this.nodeId === nodeId)
+            return;
+        this.raiseReadFatal(stage, new Error(`watcher node changed from ${this.nodeId} to ${nodeId}`));
+    }
+    raiseFatal(event, message, error, fields) {
+        if (this.fatalError === undefined) {
+            this.fatalError = new WatcherFatalError(message, error);
+            this.clearTimer();
+            emitFreshBestEffort({
+                level: 'error',
+                event,
+                outcome: 'failed',
+                error,
+                error_class: safeErrorClass(error),
+                fields,
+            });
+        }
+        throw this.fatalError;
+    }
+    raiseReadFatal(stage, error) {
+        return this.raiseFatal('inbox.read.failed', `inbox ${stage} state is corrupt`, error, { stage });
+    }
+    raiseReplayFatal(gate, error) {
+        return this.raiseFatal('inbox.replay.load_failed', 'inbox replay range could not be loaded', error, {
+            after_entry_id: gate.afterEntryId ?? null,
+            through_entry_id: gate.throughEntryId,
+        });
+    }
+    raiseSituationalFatal(markerEntryId, error) {
+        return this.raiseFatal('inbox.situational_context.missing', 'situational context marker has no readable sidecar', error, {
+            entry_id: markerEntryId,
+        });
+    }
+    escapeFatal(error, mode) {
+        if (this.fatalEscaped)
+            return;
+        this.fatalEscaped = true;
+        if (mode === 'throw')
+            throw error;
+        queueMicrotask(() => {
+            throw error;
+        });
+    }
+    scheduleHandlerFatal(error, stage) {
+        let fatal;
+        if (error instanceof WatcherFatalError) {
+            fatal = error;
+        }
+        else {
+            try {
+                this.raiseReadFatal(stage, error);
+            }
+            catch (tagged) {
+                fatal = tagged;
+            }
+        }
+        this.escapeFatal(fatal, 'schedule');
+    }
+    runTick(fatalMode = 'throw') {
+        if (!this.canMutate())
+            return;
+        try {
+            this.tick();
+        }
+        catch (error) {
+            if (error instanceof WatcherFatalError) {
+                this.escapeFatal(error, fatalMode);
+                return;
+            }
+            if (isFilesystemError(error))
+                return;
+            let fatal;
+            try {
+                this.raiseReadFatal('poll', error);
+            }
+            catch (tagged) {
+                fatal = tagged;
+            }
+            this.escapeFatal(fatal, fatalMode);
+        }
+    }
+    pollRead(read) {
+        try {
+            return { ok: true, value: read() };
+        }
+        catch (error) {
+            if (isFilesystemError(error))
+                return { ok: false };
+            this.raiseReadFatal('poll', error);
+        }
+    }
+    seed(nodeId) {
+        this.assertNodeOwnership(nodeId, 'poll');
+        if (this.seeded)
+            return true;
+        const initial = this.pollRead(() => readCursor(nodeId));
+        if (!initial.ok)
+            return false;
+        this.nodeId = nodeId;
+        this.cursor = initial.value;
+        this.durableCursor = initial.value;
+        this.seeded = true;
+        return true;
+    }
+    tick() {
+        const nodeId = currentNodeId();
+        if (nodeId === undefined || !this.seed(nodeId))
+            return;
+        if ((this.replay !== undefined || this.buffer.length > 0) && this.readRefreshIntentOrFatal(nodeId, 'poll'))
+            return;
+        if (this.replay !== undefined) {
+            this.processReplay(nodeId);
+            return;
+        }
+        if (this.buffer.length === 0 && this.pendingHandoffs.length >= MAX_ORDINARY_HANDOFFS)
+            return;
+        if (this.buffer.length > 0) {
+            const plan = this.ordinaryPlan();
+            if (plan.sendCount > 0 && this.pendingHandoffs.length + plan.sendCount > MAX_ORDINARY_HANDOFFS)
+                return;
+        }
+        const read = this.pollRead(() => readInboxSince(nodeId, this.cursor));
+        if (!read.ok)
+            return;
+        const newEntries = read.value;
+        if ((newEntries.length > 0 || this.buffer.length > 0) && this.readRefreshIntentOrFatal(nodeId, 'poll'))
+            return;
+        if (newEntries.length > 0) {
+            this.cursor = newEntries.at(-1).entry_id;
+            this.buffer.push(...newEntries);
+            this.lastArrival = Date.now();
+        }
+        if (this.buffer.length > 0 && Date.now() - this.lastArrival >= this.cadence.debounceMs) {
+            this.flushOrdinary(nodeId);
+        }
+    }
+    missingChannelEntries(entries) {
+        // Interrupt-canceled entries (a human Esc racing a not-yet-injected send —
+        // `POST /v1/nodes/{id}/interrupt`) are excluded from BOTH channels. Read
+        // fresh each plan build: the cancel can land AFTER the entry was buffered.
+        // Filtering here keeps buildPlan and replayCoverageComplete in agreement,
+        // so a fully-canceled replay range still completes. Skipped entries are
+        // never handed off; the durable cursor covers them positionally when a
+        // later entry settles (or they are simply re-filtered after a restart).
+        const canceled = this.nodeId === undefined ? undefined : readCanceledEntryIds(this.nodeId);
+        const live = canceled === undefined || canceled.size === 0
+            ? entries
+            : entries.filter((entry) => !canceled.has(entry.entry_id));
+        const hiddenCoverage = this.coveredEntryIds('hidden');
+        const visibleCoverage = this.coveredEntryIds('visible');
+        return {
+            hiddenEntries: live.filter((entry) => entry.data?.['situational'] === true && !hiddenCoverage.has(entry.entry_id)),
+            visibleEntries: live.filter((entry) => entry.data?.['situationalOnly'] !== true && !visibleCoverage.has(entry.entry_id)),
+        };
+    }
+    visibleRoute(entries, forceStreaming = false) {
+        if (entries.length === 0)
+            return 'none';
+        if (!forceStreaming && this.isIdle())
+            return 'idle';
+        if (entries.some((entry) => entry.tier === 'critical'))
+            return 'critical';
+        if (entries.some((entry) => entry.tier === 'urgent' || entry.kind === 'final'))
+            return 'steer';
+        return 'followUp';
+    }
+    buildPlan(entries) {
+        const { hiddenEntries, visibleEntries } = this.missingChannelEntries(entries);
+        const hiddenIds = new Set(hiddenEntries.map((entry) => entry.entry_id));
+        const visibleIds = new Set(visibleEntries.map((entry) => entry.entry_id));
+        const routedEntries = entries.filter((entry) => hiddenIds.has(entry.entry_id) || visibleIds.has(entry.entry_id));
+        const deferredHold = this.isIdle()
+            && routedEntries.length > 0
+            && routedEntries.every((entry) => entry.tier === 'deferred');
+        const hiddenSend = !deferredHold && hiddenEntries.length > 0;
+        const visibleSend = !deferredHold
+            && visibleEntries.length > 0
+            && (hiddenSend || this.visibleRoute(visibleEntries) !== 'critical');
+        return {
+            hiddenEntries,
+            visibleEntries,
+            deferredHold,
+            sendCount: Number(hiddenSend) + Number(visibleSend),
+        };
+    }
+    ordinaryPlan() {
+        return this.buildPlan(this.buffer);
+    }
+    situationalContent(nodeId, entries) {
+        const markerEntryId = entries.at(-1).entry_id;
+        let text;
+        try {
+            text = readSituationalContext(nodeId);
+        }
+        catch (error) {
+            this.raiseSituationalFatal(markerEntryId, error);
+        }
+        if (text === null) {
+            this.raiseSituationalFatal(markerEntryId, new Error(`missing situational context for entry ${markerEntryId}`));
+        }
+        return `<situational-context>\n${text}\n</situational-context>`;
+    }
+    digest(entries, stage) {
+        try {
+            return coalesce([...entries]);
+        }
+        catch (error) {
+            this.raiseReadFatal(stage, error);
+        }
+    }
+    sendDelivery(channel, entries, send, fatalStage) {
+        if (this.pendingHandoffs.length >= MAX_PENDING_HANDOFFS) {
+            this.raiseReadFatal(fatalStage, new Error(`pending handoff capacity exceeded before ${channel} send`));
+        }
+        let facts;
+        try {
+            facts = deliveryFacts(entries, channel);
+        }
+        catch (error) {
+            this.raiseReadFatal(fatalStage, error);
+        }
+        let operationId;
+        try {
+            operationIdContext.fresh((freshOperationId) => {
+                operationId = freshOperationId;
+                emitBestEffort({
+                    level: 'info',
+                    event: 'inbox.delivery.started',
+                    operation_id: freshOperationId,
+                    fields: deliveryFields(facts),
+                });
+                send();
+            });
+        }
+        catch (error) {
+            if (operationId === undefined)
+                this.raiseReadFatal(fatalStage, error);
+            emitDeliveryFailure(operationId, facts, 'send', error);
+            return 'failed';
+        }
+        if (operationId === undefined) {
+            this.raiseReadFatal(fatalStage, new Error(`${channel} delivery returned without an operation id`));
+        }
+        const handoff = { operationId, ...facts };
+        if (!this.canMutate()) {
+            if (this.disposed && this.disposalReason !== undefined)
+                emitDeliveryAbandoned(handoff, this.disposalReason);
+            return 'inactive';
+        }
+        this.pendingHandoffs.push(handoff);
+        return 'handed-off';
+    }
+    sendHidden(nodeId, entries, content, stage) {
+        return this.sendDelivery('hidden', entries, () => {
+            this.pi.sendMessage({
+                customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
+                content,
+                display: true,
+                details: { nodeId },
+            }, { deliverAs: 'followUp', triggerTurn: true });
+        }, stage);
+    }
+    sendVisible(entries, digest, route, stage) {
+        return this.sendDelivery('visible', entries, () => {
+            if (route === 'idle') {
+                this.pi.sendUserMessage(digest);
+            }
+            else if (route === 'steer' || route === 'followUp') {
+                this.pi.sendUserMessage(digest, { deliverAs: route });
+            }
+            else {
+                throw new Error(`visible send requested for non-send route ${route}`);
+            }
+        }, stage);
+    }
+    abortCritical() {
+        try {
+            this.lastCtx?.abort?.();
+        }
+        catch {
+            // Abort is best-effort; the retained entries remain the retry source.
+        }
+    }
+    requeueFromBatch(batch, entryIds) {
+        if (entryIds.size === 0)
+            return;
+        const retryEntries = batch.filter((entry) => entryIds.has(entry.entry_id));
+        const retryIds = new Set(retryEntries.map((entry) => entry.entry_id));
+        const tail = this.buffer.filter((entry) => !retryIds.has(entry.entry_id));
+        this.buffer.splice(0, this.buffer.length, ...retryEntries, ...tail);
+    }
+    executePlan(nodeId, plan, stage) {
+        const retryEntryIds = new Set();
+        const situationalContent = plan.hiddenEntries.length > 0
+            ? this.situationalContent(nodeId, plan.hiddenEntries)
+            : undefined;
+        const visibleDigest = plan.visibleEntries.length > 0
+            ? this.digest(plan.visibleEntries, stage)
+            : undefined;
+        let hiddenStartedTurn = false;
+        if (plan.hiddenEntries.length > 0) {
+            const result = this.sendHidden(nodeId, plan.hiddenEntries, situationalContent, stage);
+            if (result === 'inactive')
+                return { inactive: true, retryEntryIds };
+            if (result === 'failed') {
+                for (const entry of plan.hiddenEntries)
+                    retryEntryIds.add(entry.entry_id);
+            }
+            else {
+                hiddenStartedTurn = true;
+            }
+        }
+        if (!this.canMutate())
+            return { inactive: true, retryEntryIds };
+        const visibleRoute = this.visibleRoute(plan.visibleEntries, hiddenStartedTurn);
+        if (visibleRoute === 'critical') {
+            this.abortCritical();
+            if (!this.canMutate())
+                return { inactive: true, retryEntryIds };
+            for (const entry of plan.visibleEntries)
+                retryEntryIds.add(entry.entry_id);
+        }
+        else if (visibleRoute === 'idle' || visibleRoute === 'steer' || visibleRoute === 'followUp') {
+            const result = this.sendVisible(plan.visibleEntries, visibleDigest, visibleRoute, stage);
+            if (result === 'inactive')
+                return { inactive: true, retryEntryIds };
+            if (result === 'failed') {
+                for (const entry of plan.visibleEntries)
+                    retryEntryIds.add(entry.entry_id);
+            }
+        }
+        return { inactive: false, retryEntryIds };
+    }
+    flushOrdinary(nodeId) {
+        if (this.buffer.length === 0)
+            return 'empty';
+        const plan = this.ordinaryPlan();
+        if (plan.deferredHold)
+            return 'held';
+        if (this.pendingHandoffs.length + plan.sendCount > MAX_ORDINARY_HANDOFFS)
+            return 'capacity-blocked';
+        const batch = [...this.buffer];
+        const execution = this.executePlan(nodeId, plan, 'poll');
+        if (execution.inactive)
+            return 'attempted';
+        this.buffer.splice(0, batch.length);
+        this.requeueFromBatch(batch, execution.retryEntryIds);
+        return 'attempted';
+    }
+    processReplay(nodeId) {
+        const gate = this.replay;
+        if (gate === undefined)
+            return;
+        if (gate.entries === undefined) {
+            if (gate.attempted) {
+                this.raiseReplayFatal(gate, new Error('replay range was already attempted without retained entries'));
+            }
+            gate.attempted = true;
+            let entries;
+            try {
+                entries = readInboxRange(nodeId, gate.afterEntryId, gate.throughEntryId);
+            }
+            catch (error) {
+                this.raiseReplayFatal(gate, error);
+            }
+            if (entries.length === 0 || entries.at(-1).entry_id !== gate.throughEntryId) {
+                this.raiseReplayFatal(gate, new Error('replay range did not retain its inclusive target'));
+            }
+            gate.entries = entries;
+        }
+        const entries = gate.entries;
+        const plan = this.buildPlan(entries);
+        if (plan.hiddenEntries.length === 0 && plan.visibleEntries.length === 0) {
+            if (this.replay === gate)
+                this.replay = undefined;
+            return;
+        }
+        if (plan.deferredHold)
+            return;
+        if (this.pendingHandoffs.length + plan.sendCount > MAX_PENDING_HANDOFFS)
+            return;
+        const execution = this.executePlan(nodeId, plan, 'poll');
+        if (execution.inactive)
+            return;
+        if (this.canMutate() && this.replay === gate && this.replayCoverageComplete(entries)) {
+            this.replay = undefined;
+        }
+    }
+    coveredEntryIds(channel) {
+        const covered = new Set();
+        for (const handoff of this.pendingHandoffs) {
+            if (handoff.channel !== channel)
+                continue;
+            for (const entryId of handoff.entryIds)
+                covered.add(entryId);
+        }
+        return covered;
+    }
+    replayCoverageComplete(entries) {
+        const missing = this.missingChannelEntries(entries);
+        return missing.hiddenEntries.length === 0 && missing.visibleEntries.length === 0;
+    }
+    settle(nodeId, ctx, refreshHeld, holdPendingMessages) {
+        if (refreshHeld)
+            return 'held';
+        if (holdPendingMessages) {
+            try {
+                if (ctx?.hasPendingMessages?.() === true)
+                    return 'held';
+            }
+            catch {
+                // A missing context signal does not invent a pending-message hold.
+            }
+        }
+        if (this.replay !== undefined)
+            return 'held';
+        if (this.pendingHandoffs.length === 0)
+            return 'settled';
+        const physical = this.readPhysicalSettlementState(nodeId);
+        if (physical.durableIndex >= 0) {
+            const alreadyDurable = this.detachPending((handoff) => physical.throughIndexes.get(handoff) <= physical.durableIndex);
+            for (const handoff of alreadyDurable)
+                emitDeliveryCompleted(handoff);
+        }
+        const eligible = this.pendingHandoffs.filter((handoff) => {
+            const throughIndex = physical.throughIndexes.get(handoff);
+            return physical.blockedIndex === undefined || throughIndex < physical.blockedIndex;
+        });
+        if (eligible.length === 0)
+            return 'settled';
+        let target = eligible[0];
+        for (const handoff of eligible.slice(1)) {
+            if (physical.throughIndexes.get(handoff) > physical.throughIndexes.get(target))
+                target = handoff;
+        }
+        const targetIndex = physical.throughIndexes.get(target);
+        try {
+            writeCursor(nodeId, target.throughEntryId);
+        }
+        catch (error) {
+            const eligibleSet = new Set(eligible);
+            const failed = this.detachPending((handoff) => eligibleSet.has(handoff));
+            this.replay = {
+                afterEntryId: this.durableCursor,
+                throughEntryId: target.throughEntryId,
+                attempted: false,
+            };
+            for (const handoff of failed) {
+                emitDeliveryFailure(handoff.operationId, handoff, 'cursor_commit', error);
+            }
+            return 'settled';
+        }
+        this.durableCursor = target.throughEntryId;
+        const completed = this.detachPending((handoff) => physical.throughIndexes.get(handoff) <= targetIndex);
+        for (const handoff of completed)
+            emitDeliveryCompleted(handoff);
+        return 'settled';
+    }
+    readPhysicalSettlementState(nodeId) {
+        let entries;
+        try {
+            entries = readInboxSince(nodeId);
+        }
+        catch (error) {
+            this.raiseReadFatal('settle', error);
+        }
+        try {
+            const indexes = new Map();
+            entries.forEach((entry, index) => indexes.set(entry.entry_id, index));
+            const indexOf = (entryId, owner) => {
+                const index = indexes.get(entryId);
+                if (index === undefined)
+                    throw new Error(`${owner} entry_id is absent from the physical inbox: ${entryId}`);
+                return index;
+            };
+            const durableIndex = this.durableCursor === undefined ? -1 : indexOf(this.durableCursor, 'durable cursor');
+            const cursorIndex = this.cursor === undefined ? -1 : indexOf(this.cursor, 'read cursor');
+            if (cursorIndex < durableIndex)
+                throw new Error('read cursor precedes the durable cursor');
+            let previousBufferIndex = -1;
+            let blockedIndex;
+            const bufferedIds = new Set();
+            for (const entry of this.buffer) {
+                if (bufferedIds.has(entry.entry_id))
+                    throw new Error(`buffer contains duplicate entry_id: ${entry.entry_id}`);
+                bufferedIds.add(entry.entry_id);
+                const index = indexOf(entry.entry_id, 'buffer');
+                if (index <= previousBufferIndex)
+                    throw new Error('buffer is not in physical inbox order');
+                if (index <= durableIndex)
+                    throw new Error('buffer contains an entry at or before the durable cursor');
+                if (cursorIndex < index)
+                    throw new Error('buffer contains an entry beyond the read cursor');
+                previousBufferIndex = index;
+                blockedIndex = blockedIndex === undefined ? index : Math.min(blockedIndex, index);
+            }
+            const throughIndexes = new Map();
+            for (const handoff of this.pendingHandoffs) {
+                if (handoff.entryIds.length === 0)
+                    throw new Error('pending handoff has no entry_ids');
+                if (handoff.entryIds.at(-1) !== handoff.throughEntryId) {
+                    throw new Error('pending handoff through_entry_id is not its physical-last attempted entry');
+                }
+                let previousIndex = -1;
+                const handoffIds = new Set();
+                for (const entryId of handoff.entryIds) {
+                    if (handoffIds.has(entryId))
+                        throw new Error(`pending handoff contains duplicate entry_id: ${entryId}`);
+                    handoffIds.add(entryId);
+                    const index = indexOf(entryId, 'pending handoff');
+                    if (index <= previousIndex)
+                        throw new Error('pending handoff entry_ids are not in physical inbox order');
+                    if (cursorIndex < index)
+                        throw new Error('pending handoff contains an entry beyond the read cursor');
+                    previousIndex = index;
+                }
+                const throughIndex = indexOf(handoff.throughEntryId, 'pending handoff through');
+                if (throughIndex !== previousIndex)
+                    throw new Error('pending handoff through_entry_id is physically inconsistent');
+                throughIndexes.set(handoff, throughIndex);
+            }
+            return { throughIndexes, durableIndex, blockedIndex };
+        }
+        catch (error) {
+            this.raiseReadFatal('settle', error);
+        }
+    }
+    detachPending(predicate) {
+        const removed = [];
+        for (let index = this.pendingHandoffs.length - 1; index >= 0; index -= 1) {
+            const handoff = this.pendingHandoffs[index];
+            if (!predicate(handoff))
+                continue;
+            removed.push(...this.pendingHandoffs.splice(index, 1));
+        }
+        removed.reverse();
+        return removed;
+    }
+}
+function installWatcher(pi, cadence) {
+    currentWatcher?.dispose('reload', false);
+    const watcher = new CanvasInboxWatcher(pi, cadence, ++nextGeneration);
+    currentWatcher = watcher;
+    try {
+        watcher.start();
+    }
+    catch (error) {
+        watcher.dispose('reload', false);
+        throw error;
+    }
+    return watcher;
+}
+/** Register one current watcher. `start()` only wires up pi's event handlers —
+ *  it calls no Pi action, so this is safe to run during extension factory
+ *  execution, before Pi has bound its action methods (sendUserMessage /
+ *  sendMessage throw until then). The watcher only starts polling and sending
+ *  once its own `session_start` handler fires and arms it — the first event
+ *  Pi emits once actions are bound. The returned disposer owns only this
+ *  registration's generation. */
+export function registerCanvasInboxWatcher(pi) {
+    const watcher = installWatcher(pi, resolveCadence());
+    return () => watcher.dispose('shutdown', false);
+}
+export default registerCanvasInboxWatcher;