@staix/agent-hub 0.12.30 → 0.12.32

package/src/hub/board.ts

@@ -8,7 +8,14 @@ import type { SdlcReceipt } from "./sdlc.ts";
 
 export const CLASSES = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] as const;
 export type TaskClass = (typeof CLASSES)[number];
-export type TaskState = "backlog" | "proposed" | "in_progress" | "in_review" | "approved" | "changes_requested";
+export type TaskState = "backlog" | "proposed" | "in_progress" | "in_review" | "approved" | "changes_requested" | "cancelled";
+
+export const isClosedTaskState = (state: string): boolean => state === "approved" || state === "cancelled";
+export interface TaskOffer { envelopeId: string; owner: PeerId; assignmentFlowRevision: number; pullOnly?: boolean }
+export interface TaskCancellation { reason: string; supersededBy?: string; flowRevision: number; withheld?: true }
+export const TASK_STALL_CODES = ["tests", "spec", "roster", "pull-only", "not-attached", "excluded", "owner-admission", "offline", "paused", "failing", "pii", "policy", "cancelled", "unavailable"] as const;
+export type TaskStallCode = (typeof TASK_STALL_CODES)[number];
+export interface TaskStall { task: number; signature: string; replanRevision: number; cause: { kind: "reservation" | "no-eligible-peer" | "cancelled-dependency"; peer?: string; dependency?: number; code: TaskStallCode; refusals?: { peer: string; code: TaskStallCode }[] }; at: number }
 
 export interface TaskRefs {
   repo?: string;
@@ -31,6 +38,7 @@ export interface HistoryEntry {
   by: PeerId;
   event: string; // proposed | assigned | accepted | declined | done | approved | changes_requested | escalated | reassigned
   note?: string;
+  supersededBy?: string;
   /** The owner an event that set it left the task with (#67); absent in rows written before 0.11. */
   owner?: PeerId | null;
   /** On a decline or an escalation: the owner it was declined for or taken from (#207); later reroutes leave it out. */
@@ -46,6 +54,8 @@ export interface HistoryEntry {
   planning?: { revision: number; fields: (keyof PlanningFields)[]; previous: PlanningFields; pull?: true; split?: { children: { id: number; revision: number; history: number }[] } };
 }
 export interface Task extends PlanningFields {
+  offer?: TaskOffer;
+  cancelled?: TaskCancellation;
   external?: GitHubSource;
   planningRevision?: number;
   id: number;
@@ -91,12 +101,13 @@ export function planningUndoEntry(task: Pick<Task, "history">): HistoryEntry | u
 
 /** The moves the state machine allows. `accept` and `done` are transitions, not states: they carried no behaviour of their own. */
 const MOVES: Record<TaskState, TaskState[]> = {
-  backlog: ["proposed"],
-  proposed: ["in_progress", "backlog"],
-  in_progress: ["in_review", "approved", "proposed"], // approved: class without a reviewer; proposed: owner declined or was taken off
-  in_review: ["approved", "changes_requested"],
-  changes_requested: ["in_progress", "proposed"], // proposed: declined redo waits for reassignment
+  backlog: ["proposed", "cancelled"],
+  proposed: ["in_progress", "backlog", "cancelled"],
+  in_progress: ["in_review", "approved", "proposed", "cancelled"], // approved: class without a reviewer; proposed: owner declined or was taken off
+  in_review: ["approved", "changes_requested", "cancelled"],
+  changes_requested: ["in_progress", "proposed", "cancelled"], // proposed: declined redo waits for reassignment
   approved: [],
+  cancelled: [],
 };
 
 const JSON_COLS = ["refs", "plan", "deps", "signals", "history", "sdlc"] as const;
@@ -123,6 +134,19 @@ export class Board {
     return result;
   }
 
+  /** Keep the generation and business write atomic without changing Bun's reported row count. */
+  private taskWrite<T extends { changes: number }>(write: () => T): T {
+    return this.db.transaction(() => {
+      const result = { ...write() };
+      if (result.changes) this.db.run("UPDATE board_status_revision SET revision=revision+1 WHERE id=1");
+      return result;
+    })();
+  }
+
+  statusRevision(): number {
+    return (this.db.query("SELECT revision FROM board_status_revision WHERE id=1").get() as { revision: number }).revision;
+  }
+
   constructor(path: string) {
     this.db = new Database(path, { create: true });
     this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
@@ -145,6 +169,11 @@ export class Board {
       if (!have.has(col)) this.db.run(`ALTER TABLE tasks ADD COLUMN ${col} TEXT NOT NULL DEFAULT '${empty}'`);
     }
     // And from before issue #207: existing rows reserve nobody.
+    for (const col of ["offer", "cancelled"]) if (!have.has(col)) this.db.run(`ALTER TABLE tasks ADD COLUMN ${col} TEXT`);
+    this.db.run("CREATE TABLE IF NOT EXISTS task_stalls (task INTEGER PRIMARY KEY, payload TEXT NOT NULL)");
+    // Derived status-cache generation: only Board task/stall writes advance it, never journal writes.
+    this.db.run("CREATE TABLE IF NOT EXISTS board_status_revision (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL)");
+    this.db.run("INSERT OR IGNORE INTO board_status_revision VALUES (1,0)");
     if (!have.has("reserved")) this.db.run("ALTER TABLE tasks ADD COLUMN reserved TEXT");
     if (!have.has("external_repo")) this.db.run("ALTER TABLE tasks ADD COLUMN external_repo TEXT");
     if (!have.has("external_issue")) this.db.run("ALTER TABLE tasks ADD COLUMN external_issue INTEGER");
@@ -168,9 +197,9 @@ export class Board {
   propose(by: PeerId, t: { title: string; detail?: string; class: TaskClass; profile?: import("./profiles.ts").ProfileName; profileClass?: string; customProfile?: true; role?: string; refs?: TaskRefs; plan?: TaskPlan; deps?: number[]; reserved?: PeerId; signals?: string[]; backlog?: boolean; external?: GitHubSource }): Task {
     const now = Date.now();
     const history: HistoryEntry[] = [{ at: now, by, event: t.backlog ? "backlogged" : "proposed" }];
-    const { lastInsertRowid } = this.db
+    const { lastInsertRowid } = this.taskWrite(() => this.db
       .query("INSERT INTO tasks (title, detail, class, state, refs, plan, deps, reserved, signals, history, created, updated, project_profile, task_role, external_repo, external_issue) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
-      .run(t.title, t.detail ?? "", t.class, t.backlog ? "backlog" : "proposed", JSON.stringify(t.refs ?? {}), JSON.stringify(t.plan ?? {}), JSON.stringify(t.deps ?? []), t.reserved ?? null, JSON.stringify(t.signals ?? []), JSON.stringify(history), now, now, t.profile && (t.profile !== "dev" || t.customProfile || t.profileClass !== undefined && t.profileClass !== t.class) ? JSON.stringify({ profile: t.profile, profileClass: t.profileClass ?? t.class }) : null, t.role ?? null, t.external?.repo.toLowerCase() ?? null, t.external?.issue ?? null);
+      .run(t.title, t.detail ?? "", t.class, t.backlog ? "backlog" : "proposed", JSON.stringify(t.refs ?? {}), JSON.stringify(t.plan ?? {}), JSON.stringify(t.deps ?? []), t.reserved ?? null, JSON.stringify(t.signals ?? []), JSON.stringify(history), now, now, t.profile && (t.profile !== "dev" || t.customProfile || t.profileClass !== undefined && t.profileClass !== t.class) ? JSON.stringify({ profile: t.profile, profileClass: t.profileClass ?? t.class }) : null, t.role ?? null, t.external?.repo.toLowerCase() ?? null, t.external?.issue ?? null));
     const task = this.get(Number(lastInsertRowid))!;
     this.changed(task, history[0]!);
     return task;
@@ -193,18 +222,46 @@ export class Board {
 
   /** Structural status facts only; avoid decoding text, plans and growing history on each status write. */
   statusTasks(): Pick<Task, "id" | "state" | "owner" | "reviewer">[] {
-    return this.db.query("SELECT id, state, owner, reviewer FROM tasks WHERE state != 'approved' ORDER BY id").all() as Pick<Task, "id" | "state" | "owner" | "reviewer">[];
+    return this.db.query("SELECT id, state, owner, reviewer FROM tasks WHERE state NOT IN ('approved','cancelled') ORDER BY id").all() as Pick<Task, "id" | "state" | "owner" | "reviewer">[];
   }
   statusReservations(): string[] {
-    return (this.db.query("SELECT DISTINCT reserved FROM tasks WHERE state NOT IN ('approved', 'backlog') AND reserved IS NOT NULL ORDER BY reserved").all() as { reserved: string }[]).map(row => row.reserved);
+    return (this.db.query("SELECT DISTINCT reserved FROM tasks WHERE state NOT IN ('approved', 'cancelled', 'backlog') AND reserved IS NOT NULL ORDER BY reserved").all() as { reserved: string }[]).map(row => row.reserved);
   }
   plannerWip(peer: string, except?: number): number {
-    const row = this.db.query(`SELECT COUNT(*) AS n FROM tasks WHERE state NOT IN ('approved', 'backlog') AND (? IS NULL OR id != ?) AND
+    const row = this.db.query(`SELECT COUNT(*) AS n FROM tasks WHERE state NOT IN ('approved', 'cancelled', 'backlog') AND (? IS NULL OR id != ?) AND
       (owner = ? OR (owner IS NULL AND state = 'proposed' AND reserved = ? AND
         json_extract((SELECT value FROM json_each(tasks.history) WHERE json_extract(value, '$.event') IN ('backlog pulled', 'backlog returned') ORDER BY CAST(key AS INTEGER) DESC LIMIT 1), '$.planning.pull') = 1))`).get(except ?? null, except ?? null, peer, peer) as { n: number };
     return row.n;
   }
 
+  recordTaskOffer(id: number, offer: TaskOffer, expectedFlowRevision: number): void {
+    const task = this.get(id);
+    if (!task || task.owner !== offer.owner || isClosedTaskState(task.state) || task.history.length !== expectedFlowRevision || offer.assignmentFlowRevision !== expectedFlowRevision) throw new Error("task offer changed");
+    const changed = this.taskWrite(() => this.db.query("UPDATE tasks SET offer=? WHERE id=? AND owner=? AND history=?").run(JSON.stringify(offer), id, offer.owner, JSON.stringify(task.history)));
+    if (!changed.changes) throw new Error("task offer changed");
+  }
+  recordStall(stall: TaskStall): boolean {
+    const old = this.stalls().find(row => row.task === stall.task);
+    if (old?.signature === stall.signature && old.replanRevision === stall.replanRevision) return false;
+    this.taskWrite(() => this.db.query("INSERT INTO task_stalls(task,payload) VALUES(?,?) ON CONFLICT(task) DO UPDATE SET payload=excluded.payload").run(stall.task, JSON.stringify(stall)));
+    return true;
+  }
+  clearStall(task: number): void { this.taskWrite(() => this.db.query("DELETE FROM task_stalls WHERE task=?").run(task)); }
+  stalls(): TaskStall[] {
+    return (this.db.query("SELECT payload FROM task_stalls ORDER BY task").all() as { payload: string }[]).flatMap(row => {
+      try {
+        const value = JSON.parse(row.payload) as TaskStall, cause = value.cause;
+        const peer = (id: unknown) => typeof id === "string" && /^[a-z][a-z0-9_-]{0,63}$/i.test(id);
+        if (Object.keys(value).some(key => !["task", "signature", "replanRevision", "cause", "at"].includes(key)) || !Number.isSafeInteger(value.task) || value.task < 1 || !Number.isSafeInteger(value.replanRevision) || value.replanRevision < 0 || !Number.isFinite(value.at)
+          || !cause || !["reservation", "no-eligible-peer", "cancelled-dependency"].includes(cause.kind) || !TASK_STALL_CODES.includes(cause.code)
+          || cause.peer !== undefined && !peer(cause.peer) || cause.dependency !== undefined && (!Number.isSafeInteger(cause.dependency) || cause.dependency < 1)
+          || cause.refusals !== undefined && (!Array.isArray(cause.refusals) || cause.refusals.length > 64 || cause.refusals.some(row => Object.keys(row).some(key => !["peer", "code"].includes(key)) || !peer(row.peer) || !TASK_STALL_CODES.includes(row.code)))
+          || Object.keys(cause).some(key => !["kind", "peer", "dependency", "code", "refusals"].includes(key)) || value.signature !== JSON.stringify(cause)) return [];
+        return [value];
+      } catch { return []; }
+    });
+  }
+
   /** Tasks per state, without parsing a single row: `status.json` is rewritten on every bus event and the board only grows. */
   counts(): Record<string, number> {
     const rows = this.db.query("SELECT state, COUNT(*) AS n FROM tasks GROUP BY state").all() as { state: string; n: number }[];
@@ -213,7 +270,7 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "withheld"> = {}, expectedFlowRevision?: number): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "withheld"> = {}, expectedFlowRevision?: number): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
@@ -224,10 +281,10 @@ export class Board {
     if (next.state === "backlog" && (next.owner || next.reviewer)) throw new Error(`task #${id}: backlog cannot have an owner or reviewer`);
     if (patch.state === "backlog" && task.owner) throw new Error(`task #${id}: owned work cannot return to backlog`);
     if (patch.state === "backlog" && taskHasStarted(task)) throw new Error(`task #${id}: started work cannot return to backlog`);
-    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.withheld && note ? { withheld: true as const } : {}) }];
-    this.db
-      .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, updated = ? WHERE id = ?")
-      .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, Date.now(), id);
+    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.withheld && note ? { withheld: true as const } : {}) }];
+    this.taskWrite(() => this.db
+      .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ? WHERE id = ?")
+      .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), id));
     const updated = this.get(id)!;
     this.changed(updated, history.at(-1)!);
     return updated;
@@ -243,8 +300,8 @@ export class Board {
     if (next.release != null && !this.release(next.release)) throw new Error("no such release");
     const fields = Object.keys(patch) as (keyof PlanningFields)[], previous = Object.fromEntries(fields.map(key => [key, task[key] ?? (key === "pinned" ? false : key === "deps" ? [] : null)])) as PlanningFields;
     const now = Date.now(), entry: HistoryEntry = { at: now, by, event: "planned", planning: { revision: revision + 1, fields, previous }, ...(note ? { note } : {}), ...(withheld && note ? { withheld: true as const } : {}) };
-    const result = this.db.query(`UPDATE tasks SET rank=?, priority=?, "release"=?, planned_start=?, due=?, pinned=?, deps=?, reserved=?, planning_revision=planning_revision+1, history=?, updated=? WHERE id=? AND planning_revision=?`)
-      .run(next.rank ?? null, next.priority ?? null, next.release ?? null, next.plannedStart ?? null, next.due ?? null, next.pinned ? 1 : 0, JSON.stringify(next.deps ?? []), next.reserved ?? null, JSON.stringify([...task.history, entry]), now, id, revision);
+    const result = this.taskWrite(() => this.db.query(`UPDATE tasks SET rank=?, priority=?, "release"=?, planned_start=?, due=?, pinned=?, deps=?, reserved=?, planning_revision=planning_revision+1, history=?, updated=? WHERE id=? AND planning_revision=?`)
+      .run(next.rank ?? null, next.priority ?? null, next.release ?? null, next.plannedStart ?? null, next.due ?? null, next.pinned ? 1 : 0, JSON.stringify(next.deps ?? []), next.reserved ?? null, JSON.stringify([...task.history, entry]), now, id, revision));
     if (result.changes !== 1) throw new Error("planning revision changed");
     const updated = this.get(id)!; this.changed(updated, entry); return updated;
   }
@@ -254,8 +311,8 @@ export class Board {
     const task = this.get(id);
     if (!task || (task.planningRevision ?? 0) !== revision || task.state !== "backlog" || task.owner || taskHasStarted(task)) throw new Error("planner pull changed or already started");
     const now = Date.now(), entry: HistoryEntry = { at: now, by, event: "backlog pulled", planning: { revision: revision + 1, fields: ["reserved"], previous: { reserved: task.reserved ?? null }, pull: true }, note, ...(withheld ? { withheld: true as const } : {}) };
-    const result = this.db.query("UPDATE tasks SET state='proposed',owner=NULL,reviewer=NULL,reserved=?,planning_revision=planning_revision+1,history=?,updated=? WHERE id=? AND planning_revision=? AND state='backlog' AND owner IS NULL")
-      .run(reserved, JSON.stringify([...task.history, entry]), now, id, revision);
+    const result = this.taskWrite(() => this.db.query("UPDATE tasks SET state='proposed',owner=NULL,reviewer=NULL,reserved=?,planning_revision=planning_revision+1,history=?,updated=? WHERE id=? AND planning_revision=? AND state='backlog' AND owner IS NULL")
+      .run(reserved, JSON.stringify([...task.history, entry]), now, id, revision));
     if (result.changes !== 1) throw new Error("planner pull changed");
     const updated = this.get(id)!; this.changed(updated, entry); return updated;
   }
@@ -265,8 +322,8 @@ export class Board {
     const task = this.get(id), pull = task ? planningUndoEntry(task)?.planning : undefined;
     if (!task || task.state !== "proposed" || task.owner || taskHasStarted(task) || (task.planningRevision ?? 0) !== revision || !pull?.pull || pull.revision !== revision) throw new Error("planner pull undo changed or already offered");
     const now = Date.now(), entry: HistoryEntry = { at: now, by, event: "backlog returned", note: `undo planner pull revision ${revision}` };
-    const result = this.db.query("UPDATE tasks SET state='backlog',owner=NULL,reviewer=NULL,reserved=?,planning_revision=planning_revision+1,history=?,updated=? WHERE id=? AND planning_revision=? AND state='proposed' AND owner IS NULL")
-      .run(pull.previous.reserved ?? null, JSON.stringify([...task.history, entry]), now, id, revision);
+    const result = this.taskWrite(() => this.db.query("UPDATE tasks SET state='backlog',owner=NULL,reviewer=NULL,reserved=?,planning_revision=planning_revision+1,history=?,updated=? WHERE id=? AND planning_revision=? AND state='proposed' AND owner IS NULL")
+      .run(pull.previous.reserved ?? null, JSON.stringify([...task.history, entry]), now, id, revision));
     if (result.changes !== 1) throw new Error("planner pull undo changed");
     const updated = this.get(id)!; this.changed(updated, entry); return updated;
   }
@@ -288,7 +345,7 @@ export class Board {
       const updated = this.plan(id, by, { deps }, revision, note, withheld);
       const entry = updated.history.at(-1)!;
       entry.planning!.split = { children: children.map(child => ({ id: child.id, revision: child.planningRevision ?? 0, history: child.history.length })) };
-      this.db.query("UPDATE tasks SET history=? WHERE id=?").run(JSON.stringify(updated.history), id);
+      this.taskWrite(() => this.db.query("UPDATE tasks SET history=? WHERE id=?").run(JSON.stringify(updated.history), id));
       const notification = this.pendingChanges?.findLast(change => change.task.id === id && change.entry.planning?.revision === revision + 1);
       if (notification) { notification.task = updated; notification.entry = entry; }
       return { parent: this.get(id)!, children };
@@ -306,7 +363,7 @@ export class Board {
       }
       if (this.list().some(task => task.id !== id && !ids.has(task.id) && (task.deps?.some(dep => ids.has(dep)) || task.sdlc?.phase?.tasks.some(ref => ids.has(ref.id) || ref.after.some(dep => ids.has(dep)))))) throw new Error("split children are referenced by other work");
       const restored = this.plan(id, by, { deps: entry!.planning!.previous.deps ?? [] }, revision, `undo split revision ${revision}`);
-      for (const child of ids) this.db.query("DELETE FROM tasks WHERE id=?").run(child);
+      for (const child of ids) this.taskWrite(() => this.db.query("DELETE FROM tasks WHERE id=?").run(child));
       return restored;
     });
   }
@@ -374,6 +431,7 @@ export interface ReviewOutcome {
 
 function parse(row: Record<string, unknown>): Task {
   const out = { ...row } as Record<string, unknown>;
+  for (const key of ["offer", "cancelled"]) if (row[key] == null) delete out[key]; else out[key] = JSON.parse(String(row[key]));
   for (const col of JSON_COLS) {
     if (col === "sdlc" && row[col] == null) delete out[col];
     else out[col] = JSON.parse(String(row[col]));

package/src/hub/bus.ts

@@ -1,6 +1,8 @@
 import { appendNote, DIGEST, HUB, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
 import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
-import { DeliveryJournal, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
+import { DeliveryJournal, MAX_ENVELOPE_BODY, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
+import { DELIVERY_RETRY_WARNING } from "./delivery-hints.ts";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
 
 export type { DeliveryReceipt } from "./peers.ts";
 
@@ -160,6 +162,17 @@ export class Bus {
     }
   }
 
+  /** Apply future batching and admission limits without disturbing queued work or its existing deadline. */
+  configureScheduling(config: Pick<BusOptions, "batchMax" | "batchMs" | "queueCap">): void {
+    const { batchMax, batchMs, queueCap } = config;
+    if (!Number.isSafeInteger(batchMax) || batchMax < 1 || batchMax > 2_147_483_647 ||
+        !Number.isFinite(batchMs) || batchMs < 0 || batchMs > 2_147_483_647 ||
+        !Number.isSafeInteger(queueCap) || queueCap < 1 || queueCap > 2_147_483_647) {
+      throw new Error("invalid bus scheduling configuration");
+    }
+    Object.assign(this.opts, { batchMax, batchMs, queueCap });
+  }
+
   add(peer: PeerAdapter): void {
     this.peers.set(peer.id, peer);
     if (!this.queues.has(peer.id)) this.queues.set(peer.id, []);
@@ -262,6 +275,7 @@ export class Bus {
   /** Stop new deliveries while a coordinator takes a stable snapshot. Existing adapter turns are left alone. */
   setRecoveryHold(held: boolean): void {
     this.recoveryHeld = held;
+    if (!held) this.onQueues?.(); // restored holds need classification even when no peer is attached
     if (!held) for (const id of this.peers.keys()) void this.drain(id);
   }
 
@@ -360,16 +374,41 @@ export class Bus {
 
   queueShow(id: string): JournalDelivery | undefined { return this.journal?.get(id) ?? this.queueList().find((d) => d.id === id); }
 
-  resolveDelivery(id: string, revision: number, action: "completed" | "retry" | "discard", reason: string): void {
+  heldDeliveryHints(peer: string) { return this.storageError ? undefined : this.journal?.heldDeliveryHints(peer); }
+
+  /** Consent is for this peer's held row only, never authority to complete/discard or release a pause. */
+  retryDelivery(peer: string, id: string): void {
+    const refuse = () => { throw new PreEffectToolRefusal("recipient retry unavailable; inspect the held delivery or ask the person"); };
+    if (this.closed || this.recoveryHeld || this.storageError || peer === "user" || peer === HUB) return refuse();
+    const row = this.queueShow(id);
+    if (!row || row.peer !== peer || row.state !== "needs_review" || !this.journal || this.journal.retryEvidence(peer, row.originals) !== "unused") return refuse();
+    this.resolveDelivery(id, row.revision, "retry", "recipient requested one uncertain redelivery", `peer:${peer}`);
+  }
+
+  private retryOut(peer: string, originals: Envelope[], out: Envelope[]): Envelope[] {
+    if (!out.length || !this.journal || !this.journal.retryWarning(peer, originals)) return out;
+    return out.map((env, index) => {
+      if (index !== 0) return env;
+      const prefix = `${DELIVERY_RETRY_WARNING}\n\n`, marker = "\n[cut: rendered body exceeds delivery limit]";
+      if (prefix.length + env.body.length <= MAX_ENVELOPE_BODY) return { ...env, body: prefix + env.body };
+      let end = MAX_ENVELOPE_BODY - prefix.length - marker.length;
+      // The journal cap uses UTF-16 length; never cut between a Unicode surrogate pair.
+      if (Array.from(env.body.slice(end - 1, end + 1))[0]?.length === 2) end--;
+      return { ...env, body: prefix + env.body.slice(0, end) + marker };
+    });
+  }
+
+  resolveDelivery(id: string, revision: number, action: "completed" | "retry" | "discard", reason: string, actor: string = "user"): void {
     if (!this.journal || this.storageError) throw new Error("delivery journal unavailable");
     const record = this.queueShow(id);
     if (!record) throw new Error("unknown delivery");
     const previous = this.journal.resolution(id);
     if (previous) {
-      this.journal.resolve(id, revision, action, reason); // verifies identical request; no second enqueue
+      this.journal.resolve(id, revision, action, reason, revision, actor); // verifies identical request; no second enqueue
       return;
     }
-    if (["dispatching", "accepted"].includes(record.state) || this.peers.get(record.peer)?.state === "busy") throw new Error("active delivery cannot be resolved");
+    const recipientConsent = actor === `peer:${record.peer}` && action === "retry" && record.state === "needs_review";
+    if (["dispatching", "accepted"].includes(record.state) || (this.peers.get(record.peer)?.state === "busy" && !recipientConsent)) throw new Error("active delivery cannot be resolved");
     if (record.revision !== revision) throw new Error("stale delivery revision");
     if (record.state === "queued" && action === "retry") throw new Error("queued delivery is already scheduled");
     if (action === "retry" && (this.queues.get(record.peer)?.length ?? 0) + record.originals.length > this.opts.queueCap) throw new Error("recipient queue is full");
@@ -381,17 +420,17 @@ export class Bus {
       this.journal.transaction(() => {
         if (!this.journal!.get(id)) this.journal!.createDelivery({ ...record });
         const current = this.journal!.get(id)!;
-        this.journal!.resolve(id, current.revision, action, reason, revision);
+        this.journal!.resolve(id, current.revision, action, reason, revision, actor);
         if (record.state === "queued") {
           const ids = new Set(record.originals.map((env) => env.id));
           queue.splice(0, queue.length, ...queue.filter((env) => !ids.has(env.id)));
         }
-        if (action === "retry") {
+        if (action === "retry" || action === "completed" && actor === "hub") {
           for (const env of record.originals) {
             if (env.from === HUB && env.kind === "presence") this.restorePreface(record.peer, env);
-            else if (!queue.some((old) => old.id === env.id)) queue.push(env);
+            else if (action === "retry" && !queue.some((old) => old.id === env.id)) queue.push(env);
           }
-          this.queues.set(record.peer, queue);
+          if (action === "retry") this.queues.set(record.peer, queue);
         }
         this.persist();
       });
@@ -436,7 +475,8 @@ export class Bus {
     const before = this.journal.get(id);
     const state: JournalDeliveryState = receipt.state === "accepted" ? "accepted" : receipt.state === "completed" ? "completed" : receipt.state === "failed_safe" ? "failed" : "needs_review";
     if (state === "failed" || state === "needs_review") this.deliveryFailed(peer);
-    this.journal.transition(id, state, receipt.reason);
+    if (state === "completed") this.journal.completeDelivered(id, peer, "adapter", receipt.reason);
+    else this.journal.transition(id, state, receipt.reason);
     if (before?.state === "dispatching" && (state === "accepted" || state === "completed")) {
       this.memoryDelivery(peer, id, before.out, "delivered", before.originals);
       this.delivered(peer, before.originals);
@@ -463,8 +503,8 @@ export class Bus {
     for (const [id, owner] of this.activeDeliveries) {
       if (owner !== peer) continue;
       const row = this.journal.get(id);
-      if (row?.out.some((e) => e.id === envelopeId)) {
-        this.journal.transition(id, "completed", "correlated reply");
+      if (row?.peer === peer && ["dispatching", "accepted"].includes(row.state) && row.out.some((e) => e.id === envelopeId)) {
+        this.journal.completeDelivered(id, peer, "reply", "correlated reply");
         if (row.state === "dispatching") this.memoryDelivery(peer, id, row.out, "delivered", row.originals);
         this.activeDeliveries.delete(id);
         this.refreshRecoveryHold(peer);
@@ -783,14 +823,20 @@ export class Bus {
     if (index < 0) return;
     this.steering++;
     const deliveryId = crypto.randomUUID();
+    let removed = false, handedOff = false;
     try {
+      const out = this.retryOut(id, [env], [env]);
       queue.splice(index, 1);
-      this.durableHandoff(id, deliveryId, [env], [env]);
+      removed = true;
+      this.durableHandoff(id, deliveryId, [env], out);
+      handedOff = true;
       this.activeDeliveries.set(deliveryId, id);
-      try { await peer.steer([env], deliveryId); }
+      try { await peer.steer(out, deliveryId); }
       catch { this.uncertain(id, deliveryId, "steering outcome is uncertain"); }
-    } catch { this.storageError = "delivery journal unavailable"; }
-    finally { this.steering--; this.onQueues?.(); }
+    } catch {
+      if (removed && !handedOff) queue.splice(index, 0, env);
+      this.storageError = "delivery journal unavailable";
+    } finally { this.steering--; this.onQueues?.(); }
   }
 
   /** Holds on a peer's queue, for a drain and a pull alike: off roster, recovery, an uncertain delivery, a pause (console, budget, conductor). */
@@ -829,14 +875,16 @@ export class Bus {
     if (!preface && !queue.length) return [];
     const queued = [...queue];
     const batch = [...(preface ? [preface] : []), ...this.take(id, queue)];
-    this.prefaces.delete(id);
-    // Before the checkpoint, as in a drain, so the persisted snapshot carries it; on a failure the bus stops anyway.
-    this.remember(batch);
+    let out: Envelope[] = [];
     const deliveryId = crypto.randomUUID();
     try {
+      out = this.retryOut(id, batch, batch);
+      this.prefaces.delete(id);
+      // Before the checkpoint, as in a drain, so the persisted snapshot carries it; a failed policy read rolls back too.
+      this.remember(out);
       this.journal?.transaction(() => {
-        this.durableHandoff(id, deliveryId, batch, batch, false); // observe only after this outer transaction commits
-        this.journal!.transition(deliveryId, "completed", "read through hub_inbox");
+        this.durableHandoff(id, deliveryId, batch, out, false); // observe only after this outer transaction commits
+        this.journal!.completeDelivered(deliveryId, id, "pull", "read through hub_inbox");
       });
     } catch (error) {
       queue.splice(0, queue.length, ...queued);
@@ -845,12 +893,12 @@ export class Bus {
       throw error;
     }
     if (this.journal) {
-      this.memoryDelivery(id, deliveryId, batch, "rendered");
-      this.memoryDelivery(id, deliveryId, batch, "delivered");
+      this.memoryDelivery(id, deliveryId, out, "rendered", batch);
+      this.memoryDelivery(id, deliveryId, out, "delivered", batch);
     }
     this.failureStreak.delete(id); this.lastFailure.delete(id); // read, as a completed push receipt clears them
     this.onQueues?.();
-    return batch;
+    return out;
   }
 
   private async drain(id: PeerId): Promise<void> {
@@ -872,8 +920,11 @@ export class Bus {
         const delivery = preface ? [preface, ...batch] : batch;
         const mayCondense = this.opts.condense && !delivery.some((e) => e.priority === "important");
         this.condensing += mayCondense ? 1 : 0;
-        const out = mayCondense ? await this.opts.condense!(delivery).catch(() => delivery) : delivery;
-        this.condensing -= mayCondense ? 1 : 0;
+        let out: Envelope[];
+        try {
+          const condensed = mayCondense ? await this.opts.condense!(delivery).catch(() => delivery) : delivery;
+          out = this.retryOut(id, delivery, condensed);
+        } finally { this.condensing -= mayCondense ? 1 : 0; }
         // A session that cannot show pushes may have taken the peer while this was condensed (issue #205).
         if (!this.deliverable(id)) {
           if (!this.journal) { if (preface) this.restorePreface(id, preface); queue.unshift(...batch.filter((e) => !this.withdrawn.has(e.id))); }
@@ -885,16 +936,25 @@ export class Bus {
           this.dropIrrelevant(id, queue);
           continue;
         }
+        const deliveryId = crypto.randomUUID();
         if (this.journal) {
           if (this.prefaces.get(id) !== preface || batch.some((e) => !queue.some((item) => item.id === e.id))) continue;
+          const queued = [...queue], seen = [...this.seen];
           for (const env of batch) queue.splice(queue.findIndex((item) => item.id === env.id), 1);
           this.prefaces.delete(id);
-        }
-        this.remember(out);
+          this.remember(out); // the checkpoint must retain rendered reply ids across a restart
+          try { this.durableHandoff(id, deliveryId, delivery, out); }
+          catch (error) {
+            queue.splice(0, queue.length, ...queued);
+            if (preface) this.prefaces.set(id, preface);
+            this.seen.clear();
+            for (const [key, env] of seen) this.seen.set(key, env);
+            throw error;
+          }
+          this.activeDeliveries.set(deliveryId, id);
+        } else this.remember(out);
         this.lastDelivery.set(id, { out, originals: delivery });
         this.preparing.delete(id); // from here on the transport/journal owns settlement
-        const deliveryId = crypto.randomUUID();
-        if (this.journal) { this.durableHandoff(id, deliveryId, delivery, out); this.activeDeliveries.set(deliveryId, id); }
         try {
           try { this.onDeliver?.(id, delivery); } catch { /* observation must never affect delivery */ }
           if (this.journal) await peer.deliver(out, deliveryId);