@nelsonlongxiang/dsh-open-a2a-net 0.6.42 → 0.7.0

package/lib/skill/references/routing.md

@@ -7,7 +7,7 @@ Files do not go through session messages. Send with `a2a_file_send { paths, team
 ## The receipt contract
 
 Every async route (`wait:false`) registers the task on the peer and returns
-immediately. The peer's target session steers the message into its turn; when
+immediately. The peer's target session queues a sourced `agent.followup` as its own next turn; when
 the turn settles, the peer routes a receipt envelope back to the caller's
 team:
 
@@ -19,6 +19,28 @@ Correlated receipts also carry `{"outcome":"completed","idempotencyKey":"..."}`
 on a following line. Receipts are the ONLY completion signal for async work —
 polling `a2a_teams` cannot see another host's ledger.
 
+## Delivery and cancellation (#356)
+
+Task delivery (local/remote, sync/async) preserves A2A source metadata and queues a separate next turn. The host atomically stores the taskId → full SessionId + MessageId correspondence before submitting. A missing `Agent.followup` is an explicit refusal, never an instruction to use `steer`. Cold targets first pass the existing resolver. Admission, OriginClaim, team scope, taint and the default three-slot cap run before submission.
+
+`delivered` means inbox acceptance, not consumption. Pending rows may expose `consumed:false` and `deliveryObservation:delivered-unconsumed`; CLI `tasks` and `tasks --json` show this. Inbound later claims can become true, while an outbound value is only the selected peer response snapshot, not live remote telemetry. Neither value is an acknowledgement or completion, and it never changes queue counting. Older peers omitting the field remain unknown, not falsely unconsumed.
+
+Cancellation removes the persisted MessageId through `updateQueue remove` if still unclaimed; a claim/removal race becomes the claimed path. Claimed tasks retain an immediate sourced `steer` stop notice, never a queued stop that would wait behind the work. Cancellation bookkeeping keeps priority: commit the original caller cancellation first, then attempt the stop notification. Cross-host peers with the signed queued-cancellation capability receive the body-bound control field tied to the original verified caller key; older peers receive the legacy `[A2A cancel]` text without a task id, best-effort. An unavailable target or failed notification does not undo cancellation, and `removed`/`steered` only report what actually happened. This is stop-notice compatibility, never permission to fall back to steer for task delivery when followup is missing. A reserved/uncertain mapping is not blindly redelivered. Resolve that existing occurrence instead of changing ids to force a second execution.
+
+## Receipt delivery observation (#362)
+
+A formal receipt for your own pending inbound task may return only along that task's frozen receipt target; it does not grant permission to send unrelated traffic. The receiver still completes current source verification and checks the frozen task authority. Do not join extra teams merely to return that correlated receipt.
+
+`answeredAt` means the receiving session has answered locally, not that its receipt arrived. A pending row with `receiptDelivery:receipt-undelivered` explicitly records that delivery is not confirmed; tasks, state and CLI JSON preserve this across restart. The row remains owed even though answered work no longer occupies an execution slot. A successful formal receipt settles the original row; a rejected or failed send must not be reported as completed.
+
+## Temporary receipt delivery failures (#357)
+
+For an automatic receipt, a recognized temporary delivery failure keeps the original task pending with `receiptDelivery:receipt-undelivered`. The host retries the same receipt body and transport id with bounded backoff (1, 2, 4, 8, 16, 30 seconds; at most six retries). Its owner receives a notification, not a substitute receipt. Exhaustion or plugin disposal stops this runtime retry budget without settling the debt; timers are not resumed on restart. Permanent refusals retain the existing receipt-ladder policy. Reconciliation reminders still ask the session to reconcile; host retransmissions do not count as reminder attempts or new work.
+
+## Status diagnostics (#355 / #358②)
+
+`a2a-net status` and `status --json` show `ledgerPersistence` and `nudgeEscalations`. A persistence failure is prominently flagged; `lastError` contains only time/code, and a later successful commit clears it. Nudge counts distinguish a successful queue-call return, an unavailable prompt seam, and a failed call. They are host-local runtime counters, reset with the plugin instance, not receipt or consumption evidence. Missing seams and failures emit safe warnings without task text. These observations never change routing, settlement, retry budgets or capacity.
+
 ## The ledger
 
 `__dsh_a2a/state` splits the ledger into separate fields:
@@ -44,6 +66,14 @@ polling `a2a_teams` cannot see another host's ledger.
 
 A pending row with `answeredAt` records that its actual local target produced a task-attributed final or attempted its own formal receipt. It no longer occupies the `targetQueueCap` limit, even if the caller CLI expired and receipt delivery failed. It is **still pending receipt debt**: do not abandon it just to free capacity, or claim the sender received it. Dead-letter expiry, late receipts and lifetime conservation continue unchanged. State session `queued` and the board both use the same unanswered-row count; unfinished work still counts against the default cap of three. Unrelated agents, unrelated finals and host timeout placeholders cannot mark an answer.
 
+## Idle reconciliation reminders (#351, sourced followup)
+
+The host may send a sourced `[A2A reconciliation reminder]` while the session is truly idle. It lists existing pending task ids, senders, bounded original-message briefs and ages. **It is not a new task, acknowledgement, or completion evidence**: no slot is released and no receipt is owed to the reminder itself. Check each original task and send your own formal receipt to its original sender when the outcome is known (completed / failed / rejected / abandoned). If still working, use an ordinary follow-up; do not use a terminal receipt header merely to mean “in progress”.
+
+Reminder attempts are persisted before injection, merged per session, skipped without counting while busy, and backed off after three attempts to about two hours without stopping. They stop only when the original row leaves pending by a real receipt, cancellation, expiry or another existing terminal path. Counters do not prove the model read a reminder. Local senders may receive one warning; remote push notifications are not shipped. Tasks/state and CLI show attempts, last/next times and “多次提醒未对账”.
+
+#356 queues both idle reminders and local sender notices through `agent.followup`, preserving the declared `a2a-relay` source and lineage. Busy sessions are still skipped by the reminder scheduler; this does not make a reminder an acknowledgement or a new debt. There is no unlabelled human `kind:user` prompt and no fallback to `steer` when `followup` is missing. Receipt authorization, queue counting and synchronous reply ownership do not change. An unwritable ledger fails closed; the host does not invent completion or settle production backlog for you.
+
 ## Idempotency
 
 A route carries a fingerprint (caller + message + team + wait-mode). Re-

package/lib/task-auth.js

@@ -53,7 +53,7 @@ export function sameZoneAdmission(r, caller, targetTeam) {
     const declare = (team, rule) => { if (!declared.has(team))
         declared.set(team, rule); };
     let callerSessionId;
-    for (const entry of r.memberships()) {
+    for (const entry of r.callerMemberships?.() ?? r.memberships()) {
         if (`${r.zone}/${r.id8(entry.session)}` === caller) {
             callerSessionId = entry.session;
             for (const t of entry.teams)
@@ -61,7 +61,7 @@ export function sameZoneAdmission(r, caller, targetTeam) {
         }
     }
     if (callerSessionId === undefined) {
-        for (const id of r.joined()) {
+        for (const id of r.callerJoined?.() ?? r.joined()) {
             if (`${r.zone}/${r.id8(id)}` === caller) {
                 callerSessionId = id;
                 break;
@@ -76,7 +76,7 @@ export function sameZoneAdmission(r, caller, targetTeam) {
         for (const name of r.canvasTeamsOf(callerSessionId))
             declare(r.canvasTeamOf(name), 'canvas-shared');
         for (const name of r.canvasNames()) {
-            if (r.canvasMembersOf(name).includes(caller))
+            if ((r.callerCanvasMembersOf?.(name) ?? r.canvasMembersOf(name)).includes(caller))
                 declare(r.canvasTeamOf(name), 'canvas-shared');
         }
     }

package/lib/task-delivery.js

@@ -0,0 +1,23 @@
+/** #356 correspondence between one admitted task and one durable Session inbox occurrence. */
+import { createHash } from 'node:crypto';
+export const TASK_DELIVERY_CAP = 512;
+/** Keep completed/cancelled occurrence identities through the server idempotency window. */
+export const TASK_DELIVERY_RETENTION_MS = 24 * 60 * 60_000;
+export function deliveryFingerprint(sessionId, text, sender, localFrom) {
+    return createHash('sha256').update(JSON.stringify([sessionId, text, sender ?? '', localFrom ?? ''])).digest('hex');
+}
+export function parseTaskDelivery(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const r = raw;
+    for (const k of ['taskId', 'messageId', 'sessionId'])
+        if (typeof r[k] !== 'string' || r[k].length < 1 || r[k].length > 256)
+            return undefined;
+    if (r.version !== 1 || typeof r.fingerprint !== 'string' || !/^[0-9a-f]{64}$/.test(r.fingerprint) || !Number.isSafeInteger(r.createdAt) || r.createdAt < 0 || !['reserved', 'enqueued', 'claimed', 'cancelled', 'failed'].includes(String(r.state)))
+        return undefined;
+    if (r.taskExpected !== undefined && r.taskExpected !== true)
+        return undefined;
+    if (r.callerKey !== undefined && (typeof r.callerKey !== 'string' || r.callerKey.length > 512))
+        return undefined;
+    return { ...(r.taskExpected === true ? { taskExpected: true } : {}), ...(typeof r.callerKey === 'string' ? { callerKey: r.callerKey } : {}), version: 1, taskId: r.taskId, messageId: r.messageId, sessionId: r.sessionId, fingerprint: r.fingerprint, createdAt: r.createdAt, state: r.state };
+}

package/lib/task-ledger-persistence.js

@@ -0,0 +1,51 @@
+/** Atomic single-writer ledger replacement. Never truncate committed bytes on failure. */
+import { openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Brief AV/indexer contention must not turn into an unbounded synchronous stall. */
+export const LEDGER_RENAME_RETRY_MS = [2, 4];
+const retryWait = new Int32Array(new SharedArrayBuffer(4));
+function renameCommittedFile(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error?.code;
+            if ((code !== 'EPERM' && code !== 'EBUSY') || attempt >= LEDGER_RENAME_RETRY_MS.length)
+                throw error;
+            // The ledger API is synchronous; at most two waits (6ms total), never delete the target.
+            Atomics.wait(retryWait, 0, 0, LEDGER_RENAME_RETRY_MS[attempt]);
+        }
+    }
+}
+export function writeTaskLedger(path, bytes) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = path + '.' + randomUUID() + '.tmp';
+    let fd, owned = false, renamed = false;
+    try {
+        fd = openSync(temporary, 'wx', 0o600);
+        owned = true;
+        writeFileSync(fd, bytes, { encoding: 'utf8' });
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameCommittedFile(temporary, path);
+        renamed = true;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* preserve producer error */ }
+        }
+        if (owned && !renamed) {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* preserve producer error */ }
+        }
+    }
+}

package/lib/task-ledger-rows.js

@@ -118,6 +118,8 @@ export function birthFacts(peer, birth, team = '', sender, now = Date.now(), war
     const receiverMembers = remote && birth.forwarded === true && fact(birth.peerKey) ? parseReceiverMembers(birth.receiverMembers, warn) : undefined;
     return {
         ...withAuth(birth.auth, { direction: 'outbound', team, peer, sender, forwarded: birth.forwarded }, now),
+        ...(typeof birth.consumed === 'boolean' ? { consumed: birth.consumed } : {}),
+        ...(peer === 'local' && fact(birth.receiverSessionId) ? { receiverSessionId: birth.receiverSessionId } : {}),
         ...(receiverMembers !== undefined ? { receiverMembers } : {}),
         ...(remote && birth.forwarded === true ? { forwarded: true } : {}),
         ...(remote && fact(birth.peerKey) ? { peerKey: birth.peerKey } : {}),
@@ -158,6 +160,7 @@ export function withRouting(entry, warn = console.warn) {
     const receiverMembers = remoteOutbound && entry.forwarded === true && fact(entry.peerKey) ? parseReceiverMembers(entry.receiverMembers, warn) : undefined;
     return {
         ...(typeof entry.answeredAt === 'number' && Number.isFinite(entry.answeredAt) && entry.answeredAt >= 0 ? { answeredAt: entry.answeredAt } : {}),
+        ...(entry.receiptDelivery === 'receipt-undelivered' ? { receiptDelivery: 'receipt-undelivered' } : {}),
         ...(receiverMembers !== undefined ? { receiverMembers } : {}),
         ...(remoteOutbound && entry.forwarded === true ? { forwarded: true } : {}),
         ...(remoteOutbound && fact(entry.peerKey) ? { peerKey: entry.peerKey } : {}),
@@ -165,6 +168,8 @@ export function withRouting(entry, warn = console.warn) {
         ...(fact(entry.deliveredTo) ? { deliveredTo: entry.deliveredTo } : {}),
     };
 }
+export const WITHDRAWAL_RESULTS = ['removed', 'claimed-steered', 'withdraw-failed-steered', 'no-agent'];
+export function isWithdrawalResult(value) { return typeof value === 'string' && WITHDRAWAL_RESULTS.includes(value); }
 /**
  * How one archived row ended (gh#31). The recorded field wins; legacy rows
  * fall back to the summary markers this ledger writes itself. The fallback

package/lib/task-ledger.js

@@ -18,11 +18,14 @@
  * illusion: settlements vanished while debts piled up).
  * @module @nelsonlongxiang/dsh-open-a2a-net/task-ledger
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { writeTaskLedger } from "./task-ledger-persistence.js";
+import { safeObservationCode } from "./nudge-observability.js";
+import { parseTaskDelivery, TASK_DELIVERY_CAP, TASK_DELIVERY_RETENTION_MS } from "./task-delivery.js";
+import { parseReminder, REMINDER_LONG_MS } from "./reconciliation-state.js";
 import { parseReceipt, RECEIPT_OUTCOMES } from "./receipt.js";
 import { classifyConservationBlock, ConservationCounters } from "./ledger-conservation.js";
-import { CALLER_ENDED_PREFIX, TASK_CAP, ARCHIVE_CAP, SUMMARY_CAP, TASK_STALE_TTL_MS, ARCHIVE_ENDS, ECHO_SUMMARY, ROUTING_FACT_CAP, SETTLEMENT_ID_CAP, SETTLEMENT_REFUSAL_CAP, withSender, withAuth, routingOf, birthFacts, withRouting, withSettledBy, parseRefusal, archivedEndedBy } from "./task-ledger-rows.js";
+import { CALLER_ENDED_PREFIX, TASK_CAP, ARCHIVE_CAP, SUMMARY_CAP, TASK_STALE_TTL_MS, ARCHIVE_ENDS, ECHO_SUMMARY, ROUTING_FACT_CAP, SETTLEMENT_ID_CAP, SETTLEMENT_REFUSAL_CAP, withSender, withAuth, routingOf, birthFacts, withRouting, withSettledBy, parseRefusal, archivedEndedBy, WITHDRAWAL_RESULTS, isWithdrawalResult } from "./task-ledger-rows.js";
 export * from "./task-ledger-rows.js";
 /**
  * Bounded outbound-task ledger with whole-file persistence. Pure of any
@@ -47,6 +50,111 @@ export class TaskLedger {
     /** Injectable clock (option `now`). */
     now;
     warn;
+    /** Last successful commit, for rollback when a mutation cannot persist. */
+    committed = '';
+    deliveries = [];
+    deliveryRestoreError = false;
+    markConsumed(taskId, consumed) {
+        const row = this.tasks.find(r => r.taskId === taskId);
+        if (!row || row.consumed === true || row.consumed === consumed)
+            return;
+        row.consumed = consumed;
+        this.persist();
+    }
+    deliveryFor(taskId) {
+        if (this.deliveryRestoreError)
+            throw Error('task delivery correspondence is corrupt; automatic re-delivery refused');
+        const row = this.deliveries.find(r => r.taskId === taskId);
+        return row ? { ...row } : undefined;
+    }
+    deliveryByMessage(sessionId, messageId) {
+        if (this.deliveryRestoreError)
+            throw Error('task delivery correspondence is corrupt');
+        const row = this.deliveries.find(r => r.sessionId === sessionId && r.messageId === messageId);
+        return row ? { ...row } : undefined;
+    }
+    reserveDelivery(record) {
+        const parsed = parseTaskDelivery(record);
+        if (!parsed)
+            throw Error('invalid task delivery correspondence');
+        const old = this.deliveryFor(record.taskId);
+        if (old) {
+            if (old.sessionId !== record.sessionId || old.fingerprint !== record.fingerprint)
+                throw Error('task delivery identity conflict');
+            return old;
+        }
+        this.deliveries = this.deliveries.filter(row => this.tasks.some(t => t.taskId === row.taskId) || this.now() - row.createdAt <= TASK_DELIVERY_RETENTION_MS);
+        if (this.deliveries.length >= TASK_DELIVERY_CAP)
+            throw Error('task delivery correspondence capacity reached; refusing untracked delivery');
+        this.deliveries.push(parsed);
+        this.persist();
+        return { ...parsed };
+    }
+    updateDelivery(taskId, state) {
+        const row = this.deliveries.find(r => r.taskId === taskId);
+        if (!row)
+            throw Error('unknown task delivery correspondence');
+        row.state = state;
+        if (state === 'claimed') {
+            const task = this.tasks.find(r => r.taskId === taskId);
+            if (task)
+                task.consumed = true;
+        }
+        this.persist();
+    }
+    reminderRecoveryPending = false;
+    reminders = Object.create(null);
+    reminderSessions = Object.create(null);
+    reminderSessionAt(id) { return Object.hasOwn(this.reminderSessions, id) ? this.reminderSessions[id] : undefined; }
+    reminderState(taskId) { const r = Object.hasOwn(this.reminders, taskId) ? this.reminders[taskId] : undefined; return r ? { ...r } : undefined; }
+    /** Atomic observation update; no task status, answer, or conservation mutation. */
+    saveReminders(updates, session) {
+        // Validate all input before touching either observation table.
+        if (session && (session.id.length < 1 || session.id.length > 256 || (session.at !== undefined && (!Number.isSafeInteger(session.at) || session.at < 0))))
+            throw Error('invalid reminder session throttle');
+        for (const update of updates)
+            if (update.state && !parseReminder(update.state))
+                throw Error('invalid reminder state');
+        this.reminders = Object.assign(Object.create(null), Object.fromEntries(Object.entries(this.reminders).filter(([id]) => this.tasks.some(row => row.taskId === id && row.status === 'pending'))));
+        if (session) {
+            if (session.at === undefined)
+                delete this.reminderSessions[session.id];
+            else if (session.id.length <= 256 && Number.isSafeInteger(session.at) && session.at >= 0)
+                this.reminderSessions[session.id] = session.at;
+            else
+                throw Error('invalid reminder session throttle');
+            this.reminderSessions = Object.fromEntries(Object.entries(this.reminderSessions).sort((a, b) => b[1] - a[1]).slice(0, TASK_CAP));
+        }
+        for (const update of updates) {
+            const row = this.tasks.find(r => r.taskId === update.taskId && r.status === 'pending');
+            if (!row)
+                continue;
+            if (update.state) {
+                const parsed = parseReminder(update.state);
+                if (!parsed)
+                    throw Error('invalid reminder state');
+                this.reminders[update.taskId] = parsed;
+            }
+            else
+                delete this.reminders[update.taskId];
+        }
+        this.persist();
+    }
+    admittedFailure;
+    admittedFailures = 0;
+    noteAdmittedBookkeepingFailure(error) { this.admittedFailures++; this.admittedFailure = { at: this.now(), code: safeObservationCode(error, 'LEDGER_WRITE_FAILED') }; }
+    orphanDelivery(taskId) {
+        const row = this.deliveryFor(taskId);
+        return row?.taskExpected === true && (row.state === 'enqueued' || row.state === 'claimed') && !this.tasks.some(r => r.taskId === taskId) && !this.archived.some(r => r.taskId === taskId);
+    }
+    deliveryBookkeepingState() {
+        return { orphaned: this.deliveries.filter(r => r.taskExpected === true && (r.state === 'enqueued' || r.state === 'claimed') && !this.tasks.some(t => t.taskId === r.taskId) && !this.archived.some(t => t.taskId === r.taskId)).length, failures: this.admittedFailures, ...(this.admittedFailure ? { lastError: { ...this.admittedFailure } } : {}) };
+    }
+    writeFailure;
+    /** Diagnostic-only; never implies that a failed mutation committed. No paths or payloads exposed. */
+    persistenceState() {
+        return this.writeFailure ? { ok: false, lastError: { ...this.writeFailure } } : { ok: true };
+    }
     /**
      * @param path - persistence file (`<dsh-home>/a2a/tasks.json`); empty = no persistence.
      * @param options - TTL/capacity overrides; defaults come from the exported constants.
@@ -58,6 +166,14 @@ export class TaskLedger {
         this.now = options?.now ?? (() => Date.now());
         this.warn = options?.warn ?? console.warn;
         this.restore();
+        this.committed = JSON.stringify(this.snapshot());
+        if (this.reminderRecoveryPending) {
+            // Save the recovery deadline once: repeated restarts must not postpone it forever.
+            try {
+                this.persist();
+            }
+            catch { /* diagnostics/last committed debt survive; no send on failure */ }
+        }
     }
     /**
      * Every unsettled task (pending + dead-lettered), most recently tracked first.
@@ -65,7 +181,12 @@ export class TaskLedger {
      * @returns the owed-book records.
      */
     list() {
-        this.sweep(this.now());
+        try {
+            this.sweep(this.now());
+        }
+        catch {
+            // sweep already restored the last commit and recorded the write error. Read faces stay available.
+        }
         return [...this.tasks];
     }
     /** #275: old forwarded canvas debts cannot be safely upgraded by inventing receiver authority. */
@@ -162,7 +283,7 @@ export class TaskLedger {
      * @param from - the caller's receipt target (label or callback address).
      * @param contextId - the delivery's conversation id, kept for follow-up routes (empty omits it).
      */
-    trackInbound(taskId, team, from, contextId, receiptExpected, brief, auth, deliveredTo) {
+    trackInbound(taskId, team, from, contextId, receiptExpected, brief, auth, deliveredTo, receiverSessionId, consumed) {
         if (taskId === '')
             return;
         this.sweep(this.now());
@@ -177,6 +298,8 @@ export class TaskLedger {
                 peer: `local:${from}`,
                 startedAt: this.now(),
                 direction: 'inbound',
+                ...(typeof consumed === 'boolean' ? { consumed } : {}),
+                ...(receiverSessionId ? { receiverSessionId } : {}),
                 ...(receiptExpected === false ? { receiptExpected: false } : {}),
                 ...(contextId !== undefined && contextId !== '' ? { contextId } : {}),
                 ...(brief !== undefined && brief !== '' ? { brief } : {}),
@@ -194,6 +317,7 @@ export class TaskLedger {
         if (row === undefined || !(row.direction === 'inbound' || row.peer === 'local') || (row.deliveredTo ?? row.team) !== target || row.answeredAt !== undefined)
             return false;
         row.answeredAt = this.now();
+        row.receiptDelivery = 'receipt-undelivered';
         this.persist();
         return true;
     }
@@ -271,6 +395,15 @@ export class TaskLedger {
      * the route layer reads team/contextId from here for its best-effort
      * steer, which is the documented boundary until origin-auth lands.
      */
+    recordWithdrawalResult(taskId, result) {
+        if (!WITHDRAWAL_RESULTS.includes(result))
+            throw Error('invalid withdrawal result');
+        const row = this.archived.find(entry => entry.taskId === taskId && entry.endedBy === 'cancelled');
+        if (!row || row.withdrawalResult === result)
+            return;
+        this.archived = this.archived.map(entry => entry === row ? { ...entry, withdrawalResult: result } : entry);
+        this.persist();
+    }
     cancel(taskId, reason) {
         if (taskId === '')
             return { outcome: 'unknown', taskId };
@@ -603,6 +736,36 @@ export class TaskLedger {
             if (snapshot.archived !== undefined && !Array.isArray(snapshot.archived)) {
                 this.counters.damaged = 'snapshot-shape-invalid';
             }
+            if (snapshot.reconciliationReminders && typeof snapshot.reconciliationReminders === 'object') {
+                for (const [id, raw] of Object.entries(snapshot.reconciliationReminders).slice(0, TASK_CAP)) {
+                    const parsed = parseReminder(raw);
+                    if (parsed)
+                        this.reminders[id] = parsed;
+                    else
+                        this.reminderRecoveryPending = true;
+                }
+            }
+            if (snapshot.reconciliationSessions && typeof snapshot.reconciliationSessions === 'object') {
+                this.reminderSessions = Object.fromEntries(Object.entries(snapshot.reconciliationSessions).filter(([id, at]) => id.length > 0 && id.length <= 256 && Number.isSafeInteger(at) && at >= 0).slice(0, TASK_CAP));
+            }
+            if (snapshot.taskDeliveryRestoreError === true)
+                this.deliveryRestoreError = true;
+            if (snapshot.taskDeliveries !== undefined) {
+                if (!Array.isArray(snapshot.taskDeliveries) || snapshot.taskDeliveries.length > TASK_DELIVERY_CAP)
+                    this.deliveryRestoreError = true;
+                else {
+                    const seen = new Set();
+                    for (const raw of snapshot.taskDeliveries) {
+                        const parsed = parseTaskDelivery(raw);
+                        if (!parsed || seen.has(parsed.taskId) || this.deliveries.some(row => row.sessionId === parsed.sessionId && row.messageId === parsed.messageId)) {
+                            this.deliveryRestoreError = true;
+                            break;
+                        }
+                        seen.add(parsed.taskId);
+                        this.deliveries.push(parsed);
+                    }
+                }
+            }
             const entries = snapshot.tasks;
             const restored = [];
             if (Array.isArray(entries)) {
@@ -637,6 +800,7 @@ export class TaskLedger {
                             ...withAuth(entry.auth, entry, this.now()),
                             ...withRouting(entry, this.warn),
                             ...withSettledBy(entry.settledBy),
+                            ...(isWithdrawalResult(entry.withdrawalResult) ? { withdrawalResult: entry.withdrawalResult } : {}),
                         });
                         continue;
                     }
@@ -655,6 +819,8 @@ export class TaskLedger {
                         ...withSender(entry.sender, entry.direction),
                         ...withAuth(entry.auth, entry, this.now()),
                         ...withRouting(entry, this.warn),
+                        ...(typeof entry.receiverSessionId === 'string' && entry.receiverSessionId.length > 0 && entry.receiverSessionId.length <= 256 ? { receiverSessionId: entry.receiverSessionId } : {}),
+                        ...(typeof entry.consumed === 'boolean' ? { consumed: entry.consumed } : {}),
                         status: entry.status === 'dead' ? 'dead' : 'pending',
                         ...(entry.status === 'dead'
                             ? {
@@ -694,6 +860,7 @@ export class TaskLedger {
                         ...withAuth(entry.auth, entry, this.now()),
                         ...withRouting(entry, this.warn),
                         ...withSettledBy(entry.settledBy),
+                        ...(isWithdrawalResult(entry.withdrawalResult) ? { withdrawalResult: entry.withdrawalResult } : {}),
                     });
                 }
             }
@@ -701,6 +868,14 @@ export class TaskLedger {
             // snapshot carried beyond the caps leave the live view but remain in the
             // identity through restoreTrimmed.
             this.tasks = restored.slice(0, TASK_CAP);
+            if (this.reminderRecoveryPending) {
+                const recoveredAt = this.now();
+                for (const row of this.tasks) {
+                    if (row.status !== 'pending' || !Object.hasOwn(snapshot.reconciliationReminders ?? {}, row.taskId) || this.reminders[row.taskId])
+                        continue;
+                    this.reminders[row.taskId] = { version: 1, targetId: row.receiverSessionId ?? 'unresolved-metadata-reset', attempts: 3, deliveredCount: 0, lastAttemptAt: recoveredAt, nextAt: recoveredAt + REMINDER_LONG_MS, requestId: 'metadata-reset', lastResult: 'unknown', diagnostic: 'metadata-reset' };
+                }
+            }
             this.counters.restoreTrimmed += Math.max(0, restored.length - this.tasks.length);
             this.counters.restoreTrimmed += Math.max(0, this.archived.length - this.archiveCap);
             this.archived = this.archived.slice(0, this.archiveCap);
@@ -738,23 +913,47 @@ export class TaskLedger {
     persist() {
         if (this.path === '')
             return;
+        const bytes = JSON.stringify(this.snapshot());
         try {
-            mkdirSync(dirname(this.path), { recursive: true });
-            const snapshot = {
-                tasks: this.tasks.map(task => ({ ...task })),
-                ...(this.archived.length > 0 ? { archived: this.archived.map(entry => ({ ...entry })) } : {}),
-                ...(this.refusals.length > 0 ? { settlementRefusals: this.refusals.map(entry => ({ ...entry, settler: { ...entry.settler } })) } : {}),
-                ...(this.refusalsTotal > 0 ? { settlementRefusalsTotal: this.refusalsTotal } : {}),
-                // gh#154: the conservation counters ride every snapshot once any work
-                // has been tracked (zero-work ledgers stay byte-identical to before).
-                // A damage marker rides too — review r2: it must survive restarts.
-                ...(this.counters.trackedTotal > 0 || this.counters.damaged !== undefined ? { conservation: this.counters.toSnapshot() } : {}),
-            };
-            writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
+            writeTaskLedger(this.path, bytes);
+            this.committed = bytes;
+            this.writeFailure = undefined;
         }
-        catch {
-            // An unwritable home must not break routing; the ledger degrades to
-            // memory-only.
+        catch (error) {
+            const becameUnavailable = this.writeFailure === undefined;
+            this.writeFailure = { at: this.now(), code: safeObservationCode(error, 'LEDGER_WRITE_FAILED') };
+            const previous = JSON.parse(this.committed);
+            this.reminders = Object.assign(Object.create(null), previous.reconciliationReminders ?? {});
+            this.reminderSessions = previous.reconciliationSessions ?? Object.create(null);
+            this.deliveryRestoreError = previous.taskDeliveryRestoreError === true;
+            this.deliveries = previous.taskDeliveries ? previous.taskDeliveries.map(r => ({ ...r })) : [];
+            this.tasks = [...previous.tasks];
+            this.archived = [...previous.archived ?? []];
+            this.refusals = [...previous.settlementRefusals ?? []];
+            this.refusalsTotal = previous.settlementRefusalsTotal ?? 0;
+            Object.assign(this.counters, new ConservationCounters(), previous.conservation ?? {});
+            if (becameUnavailable)
+                try {
+                    this.warn('a2a: ledgerPersistence FAILED at=' + this.writeFailure.at + ' code=' + this.writeFailure.code);
+                }
+                catch { /* diagnostic only */ }
+            throw error;
         }
     }
+    snapshot() {
+        return {
+            tasks: this.tasks.map(task => ({ ...task })),
+            ...(this.deliveryRestoreError ? { taskDeliveryRestoreError: true } : {}),
+            ...(this.deliveries.length ? { taskDeliveries: this.deliveries.map(row => ({ ...row })) } : {}),
+            ...(Object.keys(this.reminderSessions).length ? { reconciliationSessions: { ...this.reminderSessions } } : {}),
+            ...(Object.keys(this.reminders).length ? { reconciliationReminders: Object.fromEntries(Object.entries(this.reminders).filter(([id]) => this.tasks.some(row => row.taskId === id && row.status === 'pending'))) } : {}),
+            ...(this.archived.length > 0 ? { archived: this.archived.map(entry => ({ ...entry })) } : {}),
+            ...(this.refusals.length > 0 ? { settlementRefusals: this.refusals.map(entry => ({ ...entry, settler: { ...entry.settler } })) } : {}),
+            ...(this.refusalsTotal > 0 ? { settlementRefusalsTotal: this.refusalsTotal } : {}),
+            // gh#154: the conservation counters ride every snapshot once any work
+            // has been tracked (zero-work ledgers stay byte-identical to before).
+            // A damage marker rides too — review r2: it must survive restarts.
+            ...(this.counters.trackedTotal > 0 || this.counters.damaged !== undefined ? { conservation: this.counters.toSnapshot() } : {}),
+        };
+    }
 }