larkin 0.4.1 → 0.4.2

package/README.md

@@ -1,6 +1,12 @@
-# Larkin
+<p align="center">
+  <img src="./assets/readme/larkin-hero.svg" width="100%" alt="Larkin connecting Codex, Claude Code, and Pi agent runtimes to Feishu with a local dashboard and message surfaces.">
+</p>
 
-Larkin connects Codex, Claude Code, and Pi agent runtimes to Feishu (Lark). It provides a local runtime host, persistent sessions, reminders, interactive messages, and a local dashboard.
+<p align="center">
+  <a href="#quick-start">Quick start</a> · <a href="#requirements">Requirements</a> · <a href="#what-it-does">What it does</a> · <a href="#installation">Installation</a> · <a href="#usage">Usage</a> · <a href="#setup-and-configuration">Setup and configuration</a> · <a href="#details">Details</a> · <a href="#development">Development</a>
+</p>
+
+Larkin is a local Runtime Host that connects Codex, Claude Code, and Pi agent runtimes to Feishu (Lark). It keeps sessions, reminders, interactive messages, and a local dashboard close to the machine that runs them.
 
 ## Requirements
 
@@ -9,9 +15,56 @@ Larkin connects Codex, Claude Code, and Pi agent runtimes to Feishu (Lark). It p
 - At least one supported agent runtime and its authentication
 - Bun 1.3.14 when running the npm package or building from source (standalone binaries bundle their own runtime)
 
+## Quick start
+
+```bash
+npx larkin@latest setup
+npx larkin@latest start
+npx larkin@latest status
+```
+
+## What it does
+
+<table>
+<tr>
+<td valign="top">
+
+**Runtime host**
+
+Connect supported coding-agent runtimes to Feishu from one local process.
+
+</td>
+<td valign="top">
+
+**Persistent workflow**
+
+Keep sessions and reminders available across runs.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**Message surfaces**
+
+Work with Feishu messages, interactive cards, and related automation.
+
+</td>
+<td valign="top">
+
+**Local visibility**
+
+Inspect the host through the embedded dashboard and OpenTelemetry traces.
+
+</td>
+</tr>
+</table>
+
+The rest of this document uses the short `larkin` form; it works as-is after `npm install -g larkin`, or prefix any command with `npx larkin@latest` to run it without installing.
+
 ## Installation
 
-Larkin is published to the npm registry and also distributed as standalone binaries. Prefer npm:
+Prefer npm:
 
 ```bash
 # Run the latest version directly with npx — no install step, always the newest release
@@ -26,39 +79,24 @@ Standalone binaries for macOS, Linux, and Windows (x64) are attached to every [G
 
 ## Usage
 
-```bash
-npx larkin@latest setup
-npx larkin@latest start
-npx larkin@latest status
-```
-
-The rest of this document uses the short `larkin` form; it works as-is after `npm install -g larkin`, or prefix any command with `npx larkin@latest` to run it without installing.
-
-Run `larkin --help` or `larkin config --help` for the available commands and configuration options. Local configuration is stored under `~/.larkin` by default; set `LARKIN_CONFIG_DIR` to use another directory.
+Run `larkin --help` or `larkin config --help` for the available commands and configuration options. `larkin agents` reports event readiness, reply-scope readiness, subscription mode/status/dimension, arrivals, and read failures. Local configuration is stored under `~/.larkin` by default; set `LARKIN_CONFIG_DIR` to use another directory.
 
 ### Feishu message links
 
 Feishu clients do not reliably render Markdown links such as `[label](URL)` as clickable in text or Markdown messages. When a recipient must be able to open a link, keep the complete bare HTTPS URL visible, for example: Issue 115 — https://github.com/eddiearc/larkin/issues/115. A label may accompany it, but must not replace the bare URL. Larkin does not rewrite exact, verbatim, or user-authored message bodies to enforce this guidance.
 
-During setup, a new Agent is offered Pi first, followed by Codex and Claude Code. Pi can use an existing
-official `pi` installation or the official Pi runtime bundled in Larkin. The bundled option supports
-DeepSeek, Kimi/Moonshot, MiniMax, Zhipu/BigModel, and a custom OpenAI-compatible Base URL. Provider keys
-are stored only in the selected Agent's private provider directory, not in the ordinary Agent config. Setup
-also discovers every API-key and OAuth/subscription login exposed by the pinned official Pi registry and
-delegates those flows to Pi. Use `larkin pi-auth status` or `larkin pi-auth logout <provider>` to manage them.
-The builtin Pi runtime loads Larkin's two supported extensions inline: background subagents and the 60-second
-foreground bash timeout guard are enabled without writing extension files or arguments. A compatible external
-Pi installation keeps the existing explicit `-e` extension path.
+## Setup and configuration
+
+During setup, a new Agent is offered Pi first, followed by Codex and Claude Code. Provider keys are stored only in the selected Agent's private provider directory, not in the ordinary Agent config. Setup also discovers every API-key and OAuth/subscription login exposed by the pinned official Pi registry and delegates those flows to Pi.
+
+Use `larkin pi-auth status` or `larkin pi-auth logout <provider>` to manage Pi auth. The builtin Pi runtime loads Larkin's two supported extensions inline: background subagents and the 60-second foreground bash timeout guard are enabled without writing extension files or arguments. A compatible external Pi installation keeps the existing explicit `-e` extension path.
 
-### Windows support boundary and optional autostart
+<details>
+<summary>Windows support and optional autostart</summary>
 
-Windows 11 x64 core support covers the standalone CLI, local Runtime Host startup, builtin Pi RPC with the
-inline extensions above, and the embedded Dashboard. Provider authentication, the official `lark-cli`, and
-external Codex, Claude Code, or Pi executables remain separately installed dependencies; secret-bearing live
-channel/provider tests are intentionally outside the hosted Windows CI gate.
+Windows 11 x64 core support covers the standalone CLI, local Runtime Host startup, builtin Pi RPC with the inline extensions above, and the embedded Dashboard. Provider authentication, the official `lark-cli`, and external Codex, Claude Code, or Pi executables remain separately installed dependencies; secret-bearing live channel/provider tests are intentionally outside the hosted Windows CI gate.
 
-An Administrator account can optionally start Larkin at that account's interactive logon with Task Scheduler.
-From an elevated PowerShell prompt, adjust the executable and working-directory paths first:
+An Administrator account can optionally start Larkin at that account's interactive logon with Task Scheduler. From an elevated PowerShell prompt, adjust the executable and working-directory paths first:
 
 ```powershell
 $Exe = 'C:\Tools\Larkin\larkin.exe'
@@ -69,13 +107,13 @@ Register-ScheduledTask -TaskName 'Larkin Runtime Host' -Action $Action -Trigger
   -Description 'Start Larkin for this Administrator account at logon' -RunLevel Highest
 ```
 
-This is an optional per-user Administrator-logon task, not SYSTEM boot support or a Windows service. Keep the
-account profile available because Larkin stores its state there. Release executables are currently unsigned;
-normal Windows security policy and SmartScreen decisions still apply.
+This is an optional per-user Administrator-logon task, not SYSTEM boot support or a Windows service. Keep the account profile available because Larkin stores its state there. Release executables are currently unsigned; normal Windows security policy and SmartScreen decisions still apply.
+</details>
 
-For supported Feishu cloud-document comments (`doc`, `docx`, `sheet`, and `file`), the safe default accepts only comments or replies that @ the Bot. Document comments never reuse IM `require`/`free` settings. An explicit platform-verified application-dimension Bot subscription accepts every supported comment event that Feishu actually delivers, whether or not it mentions the Bot. Larkin stores accepted comments as `kind=document_comment` canonical Inbox events and wakes the Bot's persistent Agent. Replies are bound back to the exact comment; whole-document comments use Feishu's top-level fallback. `larkin setup --comment-subscription application` makes the broad trigger surface explicit, creates the Bot subscription through the official `lark-cli` structured API, and then verifies it with the read-only platform status API. `--comment-subscription none` explicitly removes that application subscription and verifies removal. Until positive status verification, only @Bot comments enter the Inbox. Setup requests `docs:document.comment:create` for both in-thread replies and whole-document `create_v2` fallback, while retaining `drive:drive` for event/read support. `larkin agents` reports event readiness, reply-scope readiness, subscription mode/status/dimension, arrivals, and read failures.
+## Details
 
-## OpenTelemetry traces
+<details>
+<summary>OpenTelemetry traces</summary>
 
 Larkin records a privacy-safe timing waterfall for each woken Feishu message. Tracing is always enabled, and ended spans first enter a durable local OTLP/HTTP JSON spool. Message processing therefore does not depend on an observability backend being reachable.
 
@@ -136,6 +174,7 @@ larkin.message.process
 ```
 
 The compose stack binds Grafana, Tempo, and OTLP only to `127.0.0.1` and persists `/data`. It is intended for development, demos, and testing. Do not expose its default credentials or plaintext OTLP port publicly; use a deployment-owned TLS/authenticated endpoint or private network for remote automatic upload.
+</details>
 
 ## Development
 

package/assets/readme/larkin-hero.svg

@@ -0,0 +1,111 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="400" viewBox="0 0 1200 400" role="img" aria-labelledby="title desc">
+  <title id="title">Larkin local runtime host</title>
+  <desc id="desc">A project-native hero showing Codex, Claude Code, and Pi connecting through Larkin to Feishu, reminders, interactive messages, and a local dashboard.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#07111f"/>
+      <stop offset="100%" stop-color="#0c1730"/>
+    </linearGradient>
+    <radialGradient id="glow-cyan" cx="0" cy="0" r="1">
+      <stop offset="0%" stop-color="#00b8d9" stop-opacity="0.34"/>
+      <stop offset="100%" stop-color="#00b8d9" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow-blue" cx="0" cy="0" r="1">
+      <stop offset="0%" stop-color="#1456f0" stop-opacity="0.28"/>
+      <stop offset="100%" stop-color="#1456f0" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="core" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#11284f"/>
+      <stop offset="100%" stop-color="#0e1f3f"/>
+    </linearGradient>
+    <linearGradient id="pill" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#11203f"/>
+      <stop offset="100%" stop-color="#0b1528"/>
+    </linearGradient>
+    <pattern id="grid" width="36" height="36" patternUnits="userSpaceOnUse">
+      <path d="M 36 0 L 0 0 0 36" fill="none" stroke="#ffffff" stroke-opacity="0.04" stroke-width="1"/>
+    </pattern>
+  </defs>
+
+  <rect width="1200" height="400" rx="28" fill="url(#bg)"/>
+  <rect width="1200" height="400" rx="28" fill="url(#grid)"/>
+  <circle cx="140" cy="60" r="230" fill="url(#glow-cyan)"/>
+  <circle cx="1080" cy="52" r="260" fill="url(#glow-blue)"/>
+  <circle cx="1010" cy="340" r="220" fill="url(#glow-cyan)" opacity="0.45"/>
+
+  <g id="title-block" transform="translate(56 56)" fill="#f7fbff" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif">
+    <text x="0" y="0" font-size="16" font-weight="700" letter-spacing="3.4" fill="#8fb7d8">LOCAL RUNTIME HOST</text>
+    <text x="0" y="80" font-size="76" font-weight="800" letter-spacing="-1.8">Larkin</text>
+    <text x="0" y="128" font-size="30" font-weight="600" fill="#d9e8ff">Connect Codex, Claude Code, and Pi</text>
+    <text x="0" y="166" font-size="30" font-weight="600" fill="#d9e8ff">to Feishu with one local host.</text>
+    <text x="0" y="210" font-size="20" font-weight="500" fill="#9cb4cf">Persistent sessions · reminders · interactive messages · local dashboard</text>
+
+    <g transform="translate(0 238)" font-size="18" font-weight="700" fill="#ecf4ff">
+      <rect x="0" y="0" width="138" height="38" rx="19" fill="#0f1b33" stroke="#223556"/>
+      <text x="69" y="24" text-anchor="middle">npm package</text>
+      <rect x="150" y="0" width="176" height="38" rx="19" fill="#0f1b33" stroke="#223556"/>
+      <text x="238" y="24" text-anchor="middle">standalone binaries</text>
+      <rect x="338" y="0" width="150" height="38" rx="19" fill="#0f1b33" stroke="#223556"/>
+      <text x="413" y="24" text-anchor="middle">Bun 1.3.14</text>
+    </g>
+
+    <g transform="translate(0 292)">
+      <rect x="0" y="0" width="408" height="48" rx="14" fill="#07111f" stroke="#244068"/>
+      <text x="18" y="31" font-size="18" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" fill="#8ff0ff">npx larkin@latest setup</text>
+      <text x="240" y="31" font-size="18" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" fill="#8fb7d8">→ start → status</text>
+    </g>
+  </g>
+
+  <g id="project-proof" transform="translate(706 50)" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif">
+    <rect x="0" y="0" width="444" height="300" rx="26" fill="#0b162b" fill-opacity="0.92" stroke="#2a3f63"/>
+    <text x="24" y="34" font-size="16" font-weight="700" letter-spacing="2.6" fill="#8fb7d8">RUNTIME GRAPH</text>
+
+    <g fill="#eff6ff" font-size="17" font-weight="700">
+      <rect x="24" y="74" width="120" height="44" rx="22" fill="url(#pill)" stroke="#264267"/>
+      <text x="84" y="101" text-anchor="middle">Codex</text>
+
+      <rect x="24" y="136" width="120" height="44" rx="22" fill="url(#pill)" stroke="#264267"/>
+      <text x="84" y="163" text-anchor="middle">Claude Code</text>
+
+      <rect x="24" y="198" width="120" height="44" rx="22" fill="url(#pill)" stroke="#264267"/>
+      <text x="84" y="225" text-anchor="middle">Pi</text>
+    </g>
+
+    <g stroke-linecap="round" fill="#eff6ff">
+      <path d="M144 96 C 196 96, 220 118, 252 132" stroke="#00b8d9" stroke-opacity="0.76" stroke-width="3"/>
+      <path d="M144 158 C 196 158, 220 154, 252 150" stroke="#1456f0" stroke-opacity="0.76" stroke-width="3"/>
+      <path d="M144 220 C 196 220, 220 186, 252 168" stroke="#a3402c" stroke-opacity="0.72" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 122, 328 108" stroke="#00b8d9" stroke-opacity="0.42" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 156, 328 156" stroke="#1456f0" stroke-opacity="0.42" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 192, 328 214" stroke="#a3402c" stroke-opacity="0.42" stroke-width="3"/>
+      <path d="M322 150 C 338 150, 352 232, 328 266" stroke="#8fb7d8" stroke-opacity="0.42" stroke-width="3"/>
+    </g>
+
+    <g>
+      <rect x="252" y="92" width="70" height="116" rx="26" fill="url(#core)" stroke="#00b8d9" stroke-opacity="0.7"/>
+      <rect x="266" y="108" width="42" height="18" rx="9" fill="#0b162b" stroke="#27456f"/>
+      <text x="287" y="122" text-anchor="middle" font-size="10" font-weight="800" fill="#8fb7d8" letter-spacing="1.6">CORE</text>
+      <text x="287" y="158" text-anchor="middle" font-size="24" font-weight="800" fill="#f7fbff">LARKIN</text>
+      <text x="287" y="181" text-anchor="middle" font-size="12" font-weight="600" fill="#9cb4cf">local host</text>
+    </g>
+
+    <g fill="#eff6ff" font-size="15" font-weight="700">
+      <rect x="328" y="92" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="113" text-anchor="middle">Feishu</text>
+
+      <rect x="328" y="144" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="165" text-anchor="middle">Cards</text>
+
+      <rect x="328" y="196" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="217" text-anchor="middle">Reminders</text>
+
+      <rect x="328" y="248" width="92" height="34" rx="17" fill="#0f1b33" stroke="#264267"/>
+      <text x="374" y="269" text-anchor="middle">Dashboard</text>
+    </g>
+
+    <g>
+      <rect x="24" y="254" width="214" height="26" rx="13" fill="#07111f" stroke="#244068"/>
+      <text x="38" y="272" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" fill="#8fb7d8">sessions + traces + local config</text>
+    </g>
+  </g>
+</svg>

package/dist/agent/agent-state-store.cjs

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentStateStore = void 0;
+exports.AgentStateStore = exports.ContextOverflowRecoveryError = void 0;
 exports.createAgentStateStore = createAgentStateStore;
 const fs = __importStar(require("node:fs"));
 const crypto = __importStar(require("node:crypto"));
@@ -42,6 +42,7 @@ const root_layout_js_1 = require("../platform/root-layout.cjs");
 const process_state_js_1 = require("../platform/process-state.cjs");
 const secure_metadata_js_1 = require("../platform/secure-metadata.cjs");
 const inbox_projection_js_1 = require("./inbox-projection.cjs");
+const provider_error_classifier_js_1 = require("../runtime/provider-error-classifier.cjs");
 const JSON_KEYS = new Set([
     "agentState", "status", "map", "replyctx", "botIdentity", "senderProfiles", "readReceipts", "pendingReact", "runtimeDeliveries", "inboxState", "freshnessState", "documentComments", "reminders", "interactions",
 ]);
@@ -197,6 +198,15 @@ function validInboxLockOwner(value) {
         && typeof owner.processStartToken === "string" && !!owner.processStartToken
         && typeof owner.nonce === "string" && /^[0-9a-f-]{36}$/i.test(owner.nonce);
 }
+class ContextOverflowRecoveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ContextOverflowRecoveryError";
+    }
+}
+exports.ContextOverflowRecoveryError = ContextOverflowRecoveryError;
 class AgentStateStore {
     paths;
     boundary;
@@ -728,6 +738,189 @@ class AgentStateStore {
             return { status: "missing", code: "canonical_inbox_row_missing" };
         });
     }
+    /**
+     * Re-arm only the durable deliveries proven to be the context-window incident.
+     * The Inbox bytes are intentionally untouched. An optional synchronous commit
+     * hook lets RuntimeHost swap its in-memory generation while this same lock is
+     * still held. If the hook fails, the ledger is restored before the lock is
+     * released. The callback also receives a guarded rollback for post-callback
+     * commit failures before retry scheduling begins.
+     */
+    rearmContextOverflow(onCommit, expected) {
+        let lockActive = true;
+        try {
+            return this.withInboxTransaction(() => {
+                let rows;
+                try {
+                    rows = this.readNdjson("inbox");
+                }
+                catch {
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox is malformed");
+                }
+                if (rows.length === 0)
+                    throw new ContextOverflowRecoveryError("inbox_empty", "canonical Inbox backlog is empty");
+                const messageIds = new Set();
+                for (const row of rows) {
+                    try {
+                        (0, inbox_projection_js_1.targetKeyOfInboxEnvelope)(row);
+                    }
+                    catch {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox contains a malformed row");
+                    }
+                    if (typeof row.message_id !== "string" || !row.message_id) {
+                        throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "canonical Inbox row has no message identity");
+                    }
+                    if (messageIds.has(row.message_id))
+                        throw new ContextOverflowRecoveryError("duplicate_message_id", "canonical Inbox contains duplicate message identities");
+                    messageIds.add(row.message_id);
+                }
+                const ledger = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                if (!Array.isArray(ledger.records))
+                    throw new ContextOverflowRecoveryError("canonical_inbox_malformed", "Runtime delivery ledger is malformed");
+                const ledgerRecords = ledger.records;
+                const matches = new Map();
+                const deliveryIds = new Set();
+                const inputIds = new Set();
+                for (const candidate of ledger.records) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        continue;
+                    if (typeof record.deliveryId !== "string" || !record.deliveryId)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a matching Runtime delivery record has no delivery identity");
+                    if (!record.input || typeof record.input !== "object" || Array.isArray(record.input)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has no Runtime input identity");
+                    }
+                    const input = record.input;
+                    if (typeof input.inputId !== "string" || !input.inputId.trim()
+                        || typeof input.deliveryId !== "string" || input.deliveryId !== record.deliveryId) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "a matching Runtime delivery record has malformed input identity");
+                    }
+                    if (matches.has(record.messageId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a canonical Inbox row maps to multiple delivery records");
+                    if (deliveryIds.has(record.deliveryId))
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "matching Runtime delivery records share a delivery identity");
+                    if (inputIds.has(input.inputId))
+                        throw new ContextOverflowRecoveryError("duplicate_input_id", "matching Runtime delivery records share an input identity");
+                    deliveryIds.add(record.deliveryId);
+                    inputIds.add(input.inputId);
+                    matches.set(record.messageId, record);
+                }
+                if (expected?.messageId && !messageIds.has(expected.messageId)) {
+                    throw new ContextOverflowRecoveryError("delivery_missing", "the expected context-overflow message is not in canonical Inbox");
+                }
+                if (expected?.messageId) {
+                    const expectedRecord = matches.get(expected.messageId);
+                    if (!expectedRecord || (expected.deliveryId && expectedRecord.deliveryId !== expected.deliveryId)
+                        || (expected.inputId && expectedRecord.input.inputId !== expected.inputId)) {
+                        throw new ContextOverflowRecoveryError("delivery_identity_invalid", "the expected context-overflow delivery identity changed");
+                    }
+                }
+                for (const messageId of messageIds) {
+                    const record = matches.get(messageId);
+                    if (!record)
+                        throw new ContextOverflowRecoveryError("delivery_missing", "a canonical Inbox row has no Runtime delivery record");
+                    if (record.status !== "error" || record.retryable === true) {
+                        throw new ContextOverflowRecoveryError("delivery_not_terminal", "a canonical Inbox row is not backed by a non-retryable terminal Runtime error");
+                    }
+                    const reasonCategory = (0, provider_error_classifier_js_1.classifyStrictProviderError)((0, provider_error_classifier_js_1.buildStrictProviderErrorInput)({
+                        reason: record.reason, errorCategory: record.errorCategory,
+                    }));
+                    if (record.retryable !== false || reasonCategory !== "context_window"
+                        || (record.errorCategory !== undefined && record.errorCategory !== "context_window")) {
+                        throw new ContextOverflowRecoveryError("delivery_not_context_window", "a Runtime delivery error is not classified as context_window");
+                    }
+                }
+                for (const candidate of ledgerRecords) {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        continue;
+                    const record = candidate;
+                    if (typeof record.deliveryId === "string" && deliveryIds.has(record.deliveryId)
+                        && (typeof record.messageId !== "string" || !messageIds.has(record.messageId))) {
+                        throw new ContextOverflowRecoveryError("delivery_duplicate", "a matching delivery identity is also used by an unrelated Runtime delivery record");
+                    }
+                }
+                const updatedAt = new Date().toISOString();
+                const records = ledgerRecords.map((candidate) => {
+                    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                        return candidate;
+                    const record = candidate;
+                    if (typeof record.messageId !== "string" || !messageIds.has(record.messageId))
+                        return candidate;
+                    return { ...record, status: "pending", retryable: true, updatedAt,
+                        reason: "context-window recovery rearmed the retained Inbox delivery" };
+                });
+                const committedLedger = { ...ledger, records };
+                let restored = false;
+                const restoreUnlocked = () => {
+                    if (restored)
+                        return;
+                    const current = this.readJson("runtimeDeliveries", { version: 1, records: [] });
+                    if (!Array.isArray(current.records))
+                        throw new Error("Runtime delivery rollback found a malformed ledger");
+                    const originalMatching = ledgerRecords.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return typeof record.messageId === "string" && messageIds.has(record.messageId);
+                    });
+                    const originalDeliveryIds = new Set(originalMatching.flatMap((candidate) => {
+                        const deliveryId = candidate.deliveryId;
+                        return typeof deliveryId === "string" ? [deliveryId] : [];
+                    }));
+                    const currentMatching = current.records.filter((candidate) => {
+                        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                            return false;
+                        const record = candidate;
+                        return (typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                            || (typeof record.messageId === "string" && messageIds.has(record.messageId));
+                    });
+                    const matchingRestored = currentMatching.length === originalMatching.length
+                        && currentMatching.every((candidate, index) => JSON.stringify(candidate) === JSON.stringify(originalMatching[index]));
+                    if (!matchingRestored) {
+                        const unrelated = current.records.filter((candidate) => {
+                            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                                return true;
+                            const record = candidate;
+                            return !((typeof record.deliveryId === "string" && originalDeliveryIds.has(record.deliveryId))
+                                || (typeof record.messageId === "string" && messageIds.has(record.messageId)));
+                        });
+                        const restoredRecords = [...unrelated];
+                        for (const candidate of originalMatching) {
+                            const originalIndex = ledgerRecords.indexOf(candidate);
+                            restoredRecords.splice(Math.min(originalIndex, restoredRecords.length), 0, candidate);
+                        }
+                        this.writeJson("runtimeDeliveries", { ...current, records: restoredRecords });
+                    }
+                    restored = true;
+                };
+                const rollback = () => {
+                    if (lockActive)
+                        restoreUnlocked();
+                    else
+                        this.withInboxTransaction(restoreUnlocked);
+                };
+                try {
+                    this.writeJson("runtimeDeliveries", committedLedger);
+                    onCommit?.([...messageIds], rollback);
+                }
+                catch (error) {
+                    try {
+                        rollback();
+                    }
+                    catch {
+                        throw new Error("context-window recovery ledger rollback failed");
+                    }
+                    throw error;
+                }
+                return { rearmedCount: messageIds.size, remainingPendingCount: rows.length };
+            });
+        }
+        finally {
+            lockActive = false;
+        }
+    }
     /**
      * Recoverably bridge an outbox wake into the canonical Inbox. A durable
      * Runtime ledger is authoritative after the Inbox has been drained, so a