@staix/agent-hub 0.12.30 → 0.12.31

package/src/hub/delivery-hints.ts

@@ -0,0 +1,30 @@
+import { sanitize, type Kind } from "./envelope.ts";
+
+export const DELIVERY_RETRY_WARNING = sanitize("Hub redelivery warning: An earlier attempt of this delivery is uncertain; check for its effects before acting.");
+export interface HeldDeliveryHints {
+  count: number;
+  rows: { id: string; senders: string[]; kinds: Kind[]; createdAt: number }[];
+  truncated: boolean;
+}
+export function heldDeliveryHints(rows: readonly HeldDeliveryHints["rows"][number][], count = rows.length): HeldDeliveryHints {
+  const result: HeldDeliveryHints = { count, rows: [], truncated: count > rows.length };
+  for (const row of rows) {
+    const value = { ...row, senders: row.senders.map(sanitize) };
+    if (result.rows.length >= 32 || Buffer.byteLength(JSON.stringify({ ...result, rows: [...result.rows, value] }), "utf8") > 3500) { result.truncated = true; break; }
+    result.rows.push(value);
+  }
+  return result;
+}
+export function renderHeldHint(value: unknown, now = Date.now(), recipientRetry = true): string {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "";
+  const held = value as HeldDeliveryHints;
+  const kinds = new Set(["chat", "task", "review", "status", "budget", "presence"]);
+  try {
+    if (!Number.isSafeInteger(held.count) || held.count < 1 || !Array.isArray(held.rows) || held.rows.length > 32 || held.rows.length > held.count || typeof held.truncated !== "boolean" || Buffer.byteLength(JSON.stringify(held), "utf8") > 4096) return "";
+    if (held.rows.some(row => !row || typeof row !== "object" || typeof row.id !== "string" || !row.id.length || row.id.length > 256 || !Number.isFinite(row.createdAt) || !Array.isArray(row.senders) || !Array.isArray(row.kinds) || row.senders.some(sender => typeof sender !== "string" || sender.length > 256) || row.kinds.some(kind => !kinds.has(kind)))) return "";
+  } catch { return ""; }
+  const rows = held.rows.map(row => `${sanitize(row.id)} from ${row.senders.map(sanitize).join(",")} kind ${row.kinds.join(",")} age ${Math.max(0, Math.floor((now - row.createdAt) / 1000))}s`);
+  const action = recipientRetry ? "Use hub_delivery_retry {delivery_id} for one retry of your own uncertain row; check for earlier effects. A repeated uncertain retry needs the person." : "Ask the person to resolve these held deliveries; this delivery-only peer cannot initiate recipient retry.";
+  const out = `Held hub deliveries: ${held.count}${held.truncated ? " (metadata truncated)" : ""}\n${rows.join("\n")}\n${action}`;
+  return Buffer.byteLength(out, "utf8") <= 4096 ? out : `Held hub deliveries: ${held.count} (metadata truncated; ask the person to inspect the queue).`;
+}

package/src/hub/delivery-journal.ts

@@ -2,7 +2,8 @@ import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { Database } from "bun:sqlite";
 import type { BusSnapshot } from "./bus.ts";
-import type { Envelope } from "./envelope.ts";
+import { HUB, USER, type Envelope, type Kind } from "./envelope.ts";
+import { heldDeliveryHints } from "./delivery-hints.ts";
 import { processLiveness } from "../pi/process-signature.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
@@ -15,6 +16,7 @@ export type JournalDeliveryState =
   | "failed"
   | "discarded";
 export type JournalResolution = "completed" | "retry" | "discard";
+export const MAX_ENVELOPE_BODY = 1_000_000;
 const SCHEMA_VERSION = 1,
   TERMINAL_CAP = 2048,
   MAX_ROWS = 100_000,
@@ -29,6 +31,8 @@ const STATES = new Set<JournalDeliveryState>([
   "discarded",
 ]);
 const ACTIONS = new Set<JournalResolution>(["completed", "retry", "discard"]);
+// Hub presence ids survive context merges; they are not immutable attempted work.
+const retryOriginals = (originals: readonly Envelope[]): Envelope[] => originals.filter(env => env.from !== HUB || env.kind !== "presence");
 
 export interface JournalDelivery {
   id: string;
@@ -108,7 +112,7 @@ function validateEnvelope(value: unknown, name: string, seen = false): Envelope
   text(e.trace, `${name}.trace`, 256);
   text(e.from, `${name}.from`, 256);
   integer(e.hop, `${name}.hop`, 0, seen ? Number.MAX_SAFE_INTEGER : 3);
-  if (typeof e.body !== "string" || e.body.length > 1_000_000) fail(`${name}.body is invalid`);
+  if (typeof e.body !== "string" || e.body.length > MAX_ENVELOPE_BODY) fail(`${name}.body is invalid`);
   integer(e.ts, `${name}.ts`);
   if (
     !new Set(["chat", "task", "review", "status", "budget", "presence"]).has(
@@ -249,7 +253,7 @@ export class DeliveryJournal {
     if (!meta)
       this.db
         .query(
-          "INSERT INTO delivery_meta (project_id, project_root, revision, instance_id, operation_id) VALUES (?, ?, 0, ?, ?)",
+          "INSERT INTO delivery_meta (project_id, project_root, revision, instance_id, operation_id, retry_history_cursor) VALUES (?, ?, 0, ?, ?, 0)",
         )
         .run(
           this.projectId,
@@ -273,6 +277,9 @@ export class DeliveryJournal {
           );
         // A new daemon cannot infer completion of an old process's handoffs, including
         // controlled restarts with silent native/bridge receipts still outstanding.
+        for (const row of this.db.query("SELECT * FROM task_offer_reads WHERE project_id = ?").all(this.projectId) as Record<string, unknown>[]) this.validateOfferRead(row);
+        this.recoverRetryHistory(meta);
+        this.recoverRetryEvidence();
         this.recoverInterrupted();
       })();
     }
@@ -296,6 +303,8 @@ export class DeliveryJournal {
       ["project_root", "TEXT"],
       ["schema_version", "INTEGER NOT NULL DEFAULT 1"],
       ["operation_id", "TEXT"],
+      ["retry_unknown_ids", "TEXT NOT NULL DEFAULT '{}'"],
+      ["retry_history_cursor", "INTEGER NOT NULL DEFAULT 0"],
     ] as const) {
       const columns = this.db
         .query("PRAGMA table_info(delivery_meta)")
@@ -308,9 +317,58 @@ export class DeliveryJournal {
     this.db.run(
       `CREATE TABLE IF NOT EXISTS deliveries (id TEXT PRIMARY KEY, project_id TEXT NOT NULL, peer TEXT NOT NULL, state TEXT NOT NULL, revision INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, originals TEXT NOT NULL, out_json TEXT NOT NULL, reason TEXT, attempt INTEGER, previous_id TEXT)`,
     );
+    this.db.run("CREATE TABLE IF NOT EXISTS task_offer_reads (project_id TEXT NOT NULL, peer TEXT NOT NULL, envelope_id TEXT NOT NULL, delivery_id TEXT NOT NULL, source TEXT NOT NULL CHECK(source IN ('adapter','reply','pull')), offer_revision INTEGER NOT NULL CHECK(offer_revision >= 1), PRIMARY KEY(project_id,peer,envelope_id))");
     this.db.run(
       `CREATE TABLE IF NOT EXISTS resolution_history (id INTEGER PRIMARY KEY AUTOINCREMENT, project_id TEXT NOT NULL, delivery_id TEXT NOT NULL, observed_revision INTEGER NOT NULL, action TEXT NOT NULL, reason TEXT NOT NULL, result_revision INTEGER NOT NULL, result_state TEXT NOT NULL, UNIQUE(project_id, delivery_id, observed_revision, action, reason))`,
     );
+    this.db.run("CREATE TABLE IF NOT EXISTS delivery_retry_evidence (project_id TEXT NOT NULL, peer TEXT NOT NULL, original_id TEXT NOT NULL, proof_id TEXT NOT NULL, warning INTEGER NOT NULL CHECK(warning IN (0,1)), PRIMARY KEY(project_id, peer, original_id))");
+    this.db.transaction(() => {
+      const resolutionColumns = this.db.query("PRAGMA table_info(resolution_history)").all() as { name: string }[];
+      if (!resolutionColumns.some((column) => column.name === "actor")) this.db.run("ALTER TABLE resolution_history ADD COLUMN actor TEXT NOT NULL DEFAULT 'user'");
+      if (!resolutionColumns.some((column) => column.name === "peer")) this.db.run("ALTER TABLE resolution_history ADD COLUMN peer TEXT NOT NULL DEFAULT ''");
+      if (!resolutionColumns.some((column) => column.name === "original_ids")) this.db.run("ALTER TABLE resolution_history ADD COLUMN original_ids TEXT NOT NULL DEFAULT '[]'");
+      this.db.run("CREATE INDEX IF NOT EXISTS resolution_retry_peer ON resolution_history(project_id, peer, action)");
+      this.db.run("CREATE INDEX IF NOT EXISTS deliveries_peer ON deliveries(project_id, peer, state)");
+    })();
+  }
+  private recoverRetryHistory(meta: Record<string, unknown>): void {
+    const cursor = Number(meta.retry_history_cursor ?? 0);
+    const latest = Number((this.db.query("SELECT COALESCE(MAX(id), 0) AS n FROM resolution_history WHERE project_id = ?").get(this.projectId) as { n: number }).n);
+    if (latest > cursor) {
+      const legacy = this.db.query("SELECT r.id,d.peer,d.originals FROM resolution_history r LEFT JOIN deliveries d ON d.id = r.delivery_id AND d.project_id = r.project_id WHERE r.project_id = ? AND r.peer = '' AND r.id > ?").all(this.projectId, cursor) as { id: number; peer: string | null; originals: string | null }[];
+      for (const row of legacy) if (row.peer && row.originals) this.db.query("UPDATE resolution_history SET peer = ?, original_ids = ? WHERE project_id = ? AND id = ?").run(row.peer, JSON.stringify(retryOriginals(JSON.parse(row.originals) as Envelope[]).map(env => env.id)), this.projectId, row.id);
+      // A pruned pre-feature retry cannot be mapped back to its originals. Fence current legacy work only.
+      if (this.db.query("SELECT 1 FROM resolution_history WHERE project_id = ? AND action = 'retry' AND peer = '' AND id > ? LIMIT 1").get(this.projectId, cursor)) {
+        this.markRetryUnknown(this.list(), JSON.parse(String(meta.bus_snapshot || '{}')));
+      }
+      this.db.query("UPDATE delivery_meta SET retry_history_cursor = ? WHERE project_id = ?").run(latest, this.projectId);
+    }
+  }
+  private validateRetryProof(row: Record<string, unknown>): void {
+    text(row.peer, "retry proof peer", 256); text(row.original_id, "retry proof original", 256); text(row.proof_id, "retry proof id", 256);
+    integer(row.warning, "retry proof warning", 0, 1);
+  }
+  private retryProof(peer: string, originals: readonly Envelope[]): { proof: string; warning: boolean } | undefined {
+    originals = retryOriginals(originals);
+    if (!originals.length) return undefined;
+    const rows = this.db.query("SELECT peer,original_id,proof_id,warning FROM delivery_retry_evidence WHERE project_id = ? AND peer = ? AND original_id IN (SELECT value FROM json_each(?))").all(this.projectId, peer, JSON.stringify(originals.map(env => env.id))) as Record<string, unknown>[];
+    for (const row of rows) this.validateRetryProof(row);
+    return rows.length ? { proof: String(rows[0]!.proof_id), warning: rows.some(row => row.warning === 1) } : undefined;
+  }
+  private recordRetryEvidence(peer: string, originals: readonly Envelope[], proof: string, warning: boolean): void {
+    const put = this.db.query("INSERT INTO delivery_retry_evidence (project_id,peer,original_id,proof_id,warning) VALUES (?,?,?,?,?) ON CONFLICT(project_id,peer,original_id) DO UPDATE SET warning = MAX(warning,excluded.warning)");
+    for (const id of new Set(retryOriginals(originals).map(env => env.id))) put.run(this.projectId, peer, id, proof, warning ? 1 : 0);
+  }
+  private recoverRetryEvidence(): void {
+    for (const row of this.db.query("SELECT peer,original_id,proof_id,warning FROM delivery_retry_evidence WHERE project_id = ?").all(this.projectId) as Record<string, unknown>[]) this.validateRetryProof(row);
+    // An older writer can append attempt-bearing rows while this writer is absent.
+    const rows = this.db.query("SELECT d.id,d.peer,d.originals FROM deliveries d WHERE d.project_id = ? AND d.attempt > 0 AND EXISTS (SELECT 1 FROM json_each(d.originals) env WHERE NOT EXISTS (SELECT 1 FROM delivery_retry_evidence e WHERE e.project_id = d.project_id AND e.peer = d.peer AND e.original_id = json_extract(env.value,'$.id')))").all(this.projectId) as { id: string; peer: string; originals: string }[];
+    for (const row of rows) {
+      const originals = retryOriginals(JSON.parse(row.originals) as Envelope[]);
+      if (!originals.length) continue;
+      const known = this.retryProof(row.peer, originals) || this.db.query("SELECT 1 FROM resolution_history r, json_each(r.original_ids) old, json_each(?) current WHERE r.project_id = ? AND r.peer = ? AND r.action = 'retry' AND old.value = current.value LIMIT 1").get(JSON.stringify(originals.map(env => env.id)), this.projectId, row.peer);
+      this.recordRetryEvidence(row.peer, originals, row.id, this.retryWarning(row.peer, originals) || !known);
+    }
   }
   private readMeta(): Record<string, unknown> | null {
     return this.db
@@ -536,11 +594,20 @@ export class DeliveryJournal {
       updatedAt: delivery.createdAt,
     });
     return this.db.transaction(() => {
-      const ids = new Set(delivery.originals.map((env) => env.id));
+      const evidence = this.retryEvidence(delivery.peer, delivery.originals);
+      if (evidence === "used") {
+        // Inheritance commits with the handoff, before safe failure or pruning can erase a grouped parent.
+        this.recordRetryEvidence(delivery.peer, delivery.originals, delivery.id, this.retryWarning(delivery.peer, delivery.originals));
+        delivery = { ...delivery, attempt: Math.max(1, delivery.attempt ?? 0) };
+      } else if (evidence === "unknown") this.markRetryUnknown([{ ...delivery, revision: 0, updatedAt: delivery.createdAt }], {});
+      const ids = new Set(delivery.originals.map((env) => env.id)), immutableIds = new Set(retryOriginals(delivery.originals).map(env => env.id));
       for (const row of this.list(delivery.peer)) {
         if (row.state !== "queued" || !row.originals.some((env) => ids.has(env.id))) continue;
         this.transition(row.id, "discarded", `grouped into delivery ${delivery.id}`);
-        delivery = { ...delivery, previousId: delivery.previousId ?? row.id };
+        if (retryOriginals(row.originals).some(env => immutableIds.has(env.id))) {
+          delivery = { ...delivery, previousId: delivery.previousId ?? row.id };
+          if ((row.attempt ?? 0) > 0) delivery = { ...delivery, attempt: Math.max(delivery.attempt ?? 0, row.attempt!) };
+        }
       }
       const revision = this.bump();
       const now = Date.now();
@@ -611,6 +678,32 @@ export class DeliveryJournal {
       return { ...input, revision, updatedAt };
     })();
   }
+  private validateOfferRead(row: Record<string, unknown>): void {
+    text(row.peer, "offer read peer", 256); text(row.envelope_id, "offer read envelope", 256); text(row.delivery_id, "offer read delivery", 256);
+    integer(row.offer_revision, "offer read revision", 1);
+    if (!["adapter", "reply", "pull"].includes(String(row.source))) fail("offer read source is invalid");
+  }
+  /** Positive delivery provenance only; generic transitions and operator resolutions never call this. */
+  completeDelivered(deliveryId: string, peer: string, source: "adapter" | "reply" | "pull", reason?: string): JournalDelivery {
+    this.ensureOpen(); text(deliveryId, "delivery id", 256); text(peer, "delivery peer", 256);
+    if (peer === HUB || peer === USER || !["adapter", "reply", "pull"].includes(source)) throw new Error("invalid delivered completion source");
+    if (reason !== undefined) text(reason, "delivery completion reason", 1_000_000);
+    return this.db.transaction((): JournalDelivery => {
+      const row = this.get(deliveryId);
+      if (!row || row.peer !== peer || !["dispatching", "accepted"].includes(row.state)) throw new Error("delivery is not active for this peer");
+      const completed = this.transition(deliveryId, "completed", reason, row.revision);
+      const put = this.db.query("INSERT OR IGNORE INTO task_offer_reads (project_id,peer,envelope_id,delivery_id,source,offer_revision) VALUES (?,?,?,?,?,?)");
+      for (const env of row.originals) if (env.from === HUB && env.kind === "task" && Number.isSafeInteger(env.refs?.taskOffer) && env.refs!.taskOffer! >= 1) put.run(this.projectId, peer, env.id, deliveryId, source, env.refs!.taskOffer!);
+      return completed;
+    })();
+  }
+  /** Exact immutable offer id, independent of queue snapshots or generic completed rows. */
+  offerRead(peer: string, envelopeId: string): boolean {
+    this.ensureOpen(); text(peer, "offer read peer", 256); text(envelopeId, "offer read envelope", 256);
+    const row = this.db.query("SELECT * FROM task_offer_reads WHERE project_id = ? AND peer = ? AND envelope_id = ?").get(this.projectId, peer, envelopeId) as Record<string, unknown> | null;
+    if (!row) return false;
+    this.validateOfferRead(row); return true;
+  }
   transition(
     id: string,
     state: JournalDeliveryState,
@@ -663,12 +756,85 @@ export class DeliveryJournal {
     const rows = this.db.query("SELECT * FROM deliveries WHERE project_id = ? AND peer = ? AND state IN ('queued', 'dispatching', 'accepted', 'needs_review') ORDER BY created_at, id").all(this.projectId, peer) as Record<string, unknown>[];
     return rows.map(parseDelivery);
   }
+  heldDeliveryHints(peer: string) {
+    this.ensureOpen();
+    const count = Number((this.db.query("SELECT COUNT(*) AS n FROM deliveries WHERE project_id = ? AND peer = ? AND state = 'needs_review'").get(this.projectId, peer) as { n: number }).n);
+    const rows = this.db.query("SELECT d.id, d.created_at, (SELECT json_group_array(DISTINCT json_extract(env.value, '$.from')) FROM json_each(d.originals) env) AS senders, (SELECT json_group_array(DISTINCT json_extract(env.value, '$.kind')) FROM json_each(d.originals) env) AS kinds FROM deliveries d WHERE d.project_id = ? AND d.peer = ? AND d.state = 'needs_review' ORDER BY d.created_at, d.id LIMIT 33").all(this.projectId, peer) as { id: string; created_at: number; senders: string; kinds: string }[];
+    return heldDeliveryHints(rows.map(row => ({ id: row.id, createdAt: row.created_at, senders: JSON.parse(row.senders) as string[], kinds: JSON.parse(row.kinds) as Kind[] })), count);
+  }
+  /** Explicit resolutions, not automatic safe failures, consume the immutable originals' retry lineage. */
+  retryEvidence(peer: string, originals: readonly Envelope[]): "unused" | "used" | "unknown" {
+    this.ensureOpen();
+    originals = retryOriginals(originals);
+    if (!originals.length) return "unused";
+    const ids = JSON.stringify([...new Set(originals.map(env => env.id))]);
+    const proof = this.retryProof(peer, originals);
+    if (this.retryUnknown(peer, new Set(originals.map(env => env.id)))) return "unknown";
+    if (proof) return "used";
+    if (this.db.query("SELECT 1 FROM resolution_history r, json_each(r.original_ids) old, json_each(?) current WHERE r.project_id = ? AND r.peer = ? AND r.action = 'retry' AND old.value = current.value LIMIT 1").get(ids, this.projectId, peer)) return "used";
+    const wanted = new Set(originals.map(env => env.id));
+    type Ancestor = { id: string; peer: string; attempt: number | null; previous_id: string | null; originals: string };
+    const related = this.db.query("SELECT d.id, d.peer, d.attempt, d.previous_id, d.originals FROM deliveries d WHERE d.project_id = ? AND d.peer = ? AND d.state IN ('queued','dispatching','accepted','needs_review') AND EXISTS (SELECT 1 FROM json_each(d.originals) env, json_each(?) ids WHERE json_extract(env.value, '$.id') = ids.value)").all(this.projectId, peer, ids) as Ancestor[];
+    const retried = (id: string) => !!this.db.query("SELECT 1 FROM resolution_history WHERE project_id = ? AND delivery_id = ? AND action = 'retry' LIMIT 1").get(this.projectId, id);
+    const inspected = new Set<string>();
+    let unknown = false;
+    for (const row of related) {
+      const chain = new Set<string>();
+      let current: Ancestor | undefined = row;
+      while (current) {
+        if (!retryOriginals(JSON.parse(current.originals) as Envelope[]).some(env => wanted.has(env.id))) break;
+        if (chain.has(current.id)) { unknown = true; break; }
+        if (inspected.has(current.id)) break;
+        chain.add(current.id); inspected.add(current.id);
+        if ((current.attempt ?? 0) > 0 || retried(current.id)) return "used";
+        if (!current.previous_id) break;
+        const parent = current.previous_id;
+        current = this.db.query("SELECT id, peer, attempt, previous_id, originals FROM deliveries WHERE project_id = ? AND id = ?").get(this.projectId, parent) as Ancestor | undefined;
+        if (!current || current.peer !== peer) { unknown = true; break; }
+      }
+    }
+    return unknown || this.retryUnknown(peer, wanted) ? "unknown" : "unused";
+  }
+  /** Console retries consume the allowance too, but only recipient-requested/unknown lineage adds a warning. */
+  retryWarning(peer: string, originals: readonly Envelope[]): boolean {
+    this.ensureOpen();
+    originals = retryOriginals(originals);
+    if (!originals.length) return false;
+    const wanted = new Set(originals.map(env => env.id));
+    const ids = JSON.stringify([...wanted]);
+    if (this.retryProof(peer, originals)?.warning) return true;
+    if (this.db.query("SELECT 1 FROM resolution_history r, json_each(r.original_ids) old, json_each(?) current WHERE r.project_id = ? AND r.peer = ? AND r.action = 'retry' AND r.actor = ? AND old.value = current.value LIMIT 1").get(ids, this.projectId, peer, `peer:${peer}`)) return true;
+    return this.retryUnknown(peer, wanted) || this.retryEvidence(peer, originals) === "unknown";
+  }
+  private retryUnknown(peer: string, wanted: ReadonlySet<string>): boolean {
+    try {
+      const map = JSON.parse(String(this.readMeta()?.retry_unknown_ids ?? '{}')) as Record<string, string[]>;
+      if (!map || typeof map !== "object" || Array.isArray(map)) return true;
+      const own = Object.hasOwn(map, peer) ? map[peer] : [];
+      return !Array.isArray(own) || own.some(id => wanted.has(id));
+    } catch { return true; }
+  }
+  private markRetryUnknown(deliveries: readonly JournalDelivery[], bus: Partial<BusSnapshot>): void {
+    const map: Record<string, Set<string>> = Object.create(null);
+    const existing = JSON.parse(String(this.readMeta()?.retry_unknown_ids ?? '{}')) as Record<string, unknown>;
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) throw new Error("retry lineage metadata unavailable");
+    for (const [peer, ids] of Object.entries(existing)) {
+      if (!Array.isArray(ids) || ids.some(id => typeof id !== "string")) throw new Error("retry lineage metadata unavailable");
+      map[peer] = new Set(ids as string[]);
+    }
+    const add = (peer: string, envs: readonly Envelope[]) => { for (const env of retryOriginals(envs)) (map[peer] ??= new Set()).add(env.id); };
+    for (const row of deliveries) add(row.peer, row.originals);
+    for (const [peer, envs] of Object.entries(bus.queues ?? {})) add(peer, envs);
+    for (const [peer, env] of Object.entries(bus.prefaces ?? {})) add(peer, [env]);
+    this.db.query("UPDATE delivery_meta SET retry_unknown_ids = ? WHERE project_id = ?").run(JSON.stringify(Object.fromEntries(Object.entries(map).map(([peer, ids]) => [peer, [...ids]]))), this.projectId);
+  }
   resolve(
     id: string,
     revision: number,
     action: JournalResolution,
     reason: string,
     requestRevision = revision,
+    actor: string = "user",
   ): JournalDelivery {
     this.ensureOpen();
     text(reason, "resolution reason", 1_000_000);
@@ -678,19 +844,20 @@ export class DeliveryJournal {
       const resolved = this.resolution(id);
       if (resolved) {
         const current = this.get(id);
-        if (current && resolved.action === action && resolved.reason === reason && (requestRevision === resolved.observedRevision || requestRevision === current.revision)) return current;
+        if (current && resolved.action === action && resolved.reason === reason && resolved.actor === actor && (requestRevision === resolved.observedRevision || requestRevision === current.revision)) return current;
         throw new Error("stale delivery revision or conflicting operator resolution");
       }
       const prior = this.db
         .query(
-          "SELECT result_revision FROM resolution_history WHERE project_id = ? AND delivery_id = ? AND observed_revision = ? AND action = ? AND reason = ?",
+          "SELECT result_revision FROM resolution_history WHERE project_id = ? AND delivery_id = ? AND observed_revision = ? AND action = ? AND reason = ? AND actor = ?",
         )
-        .get(this.projectId, id, requestRevision, action, reason) as {
+        .get(this.projectId, id, requestRevision, action, reason, actor) as {
         result_revision: number;
       } | null;
       if (prior) return this.get(id)!;
       const current = this.get(id);
       if (!current) throw new Error(`unknown delivery ${id}`);
+      if (actor.startsWith("peer:") && (action !== "retry" || current.peer !== actor.slice(5) || current.state !== "needs_review" || this.retryEvidence(current.peer, current.originals) !== "unused")) throw new Error("recipient retry unavailable; inspect the held delivery or ask the person");
       if (current.revision !== revision)
         throw new Error(`stale delivery revision for ${id}`);
       if (
@@ -715,7 +882,7 @@ export class DeliveryJournal {
       }
       this.db
         .query(
-          "INSERT INTO resolution_history (project_id, delivery_id, observed_revision, action, reason, result_revision, result_state) VALUES (?, ?, ?, ?, ?, ?, ?)",
+          "INSERT INTO resolution_history (project_id, delivery_id, observed_revision, action, reason, result_revision, result_state, actor, peer, original_ids) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
         )
         .run(
           this.projectId,
@@ -725,14 +892,18 @@ export class DeliveryJournal {
           reason,
           result.revision,
           result.state,
+          actor,
+          current.peer,
+          JSON.stringify(retryOriginals(current.originals).map(env => env.id)),
         );
+      if (action === "retry") this.recordRetryEvidence(current.peer, current.originals, id, actor === `peer:${current.peer}`);
       this.pruneTerminal();
       return result;
     })();
   }
-  resolution(id: string): { action: JournalResolution; reason: string; observedRevision: number } | undefined {
-    const row = this.db.query("SELECT action,reason,observed_revision FROM resolution_history WHERE project_id=? AND delivery_id=? ORDER BY id DESC LIMIT 1").get(this.projectId, id) as { action: JournalResolution; reason: string; observed_revision: number } | null;
-    return row ? { action: row.action, reason: row.reason, observedRevision: row.observed_revision } : undefined;
+  resolution(id: string): { action: JournalResolution; reason: string; observedRevision: number; actor: string } | undefined {
+    const row = this.db.query("SELECT action,reason,observed_revision,actor FROM resolution_history WHERE project_id=? AND delivery_id=? ORDER BY id DESC LIMIT 1").get(this.projectId, id) as { action: JournalResolution; reason: string; observed_revision: number; actor: string } | null;
+    return row ? { action: row.action, reason: row.reason, observedRevision: row.observed_revision, actor: row.actor } : undefined;
   }
   private pruneTerminal(): void {
     const count = Number(
@@ -801,6 +972,8 @@ export class DeliveryJournal {
             row.attempt ?? null,
             row.previousId ?? null,
           );
+      // Snapshots deliberately omit resolution history; only these imported originals have unknown retry rights.
+      this.markRetryUnknown(snapshot.deliveries, snapshot.bus);
       return true;
     })();
   }

package/src/hub/delivery-superseded.ts

@@ -0,0 +1,52 @@
+import type { Envelope } from "./envelope.ts";
+import type { Task } from "./board.ts";
+
+/** Evidence only, never task text: a mixed/unknown/live row requires a person's decision. */
+export function supersededDeliveryReason(
+  originals: readonly Envelope[],
+  board: { get(id: number): Pick<Task, "id" | "state" | "owner" | "reviewer" | "cancelled"> | undefined },
+  recipient: string,
+): string | undefined {
+  if (!originals.length) return undefined;
+  const reasons = new Set<string>();
+  for (const env of originals) {
+    if (env.from !== "hub") return undefined;
+    if (env.kind === "presence") { reasons.add("presence"); continue; }
+    if (env.kind !== "task" && env.kind !== "review") return undefined;
+    if (!env.refs?.task || !/^[1-9][0-9]*$/.test(env.refs.task)) return undefined;
+    const id = Number(env.refs.task);
+    if (!Number.isSafeInteger(id)) return undefined;
+    const task = board.get(id);
+    if (!task) return undefined;
+    if (task.state === "cancelled") {
+      if (typeof env.refs.taskCancelled === "number" && env.refs.taskCancelled === task.cancelled?.flowRevision) return undefined;
+      reasons.add(`task #${task.id} cancelled`);
+    } else if (task.state === "approved") reasons.add(`task #${task.id} approved`);
+    else if ((env.kind === "review" || env.refs.taskRecipient === "reviewer") && (task.state !== "in_review" || task.reviewer !== recipient)) reasons.add(`task #${task.id} review moved`);
+    else if (env.kind === "task" && env.refs.taskRecipient === "owner" && task.owner !== recipient) reasons.add(`task #${task.id} owner moved`);
+    else return undefined; // Untagged legacy task notices and planner coordination carry no proof of supersession.
+  }
+  return `superseded: ${[...reasons].join("; ")}`;
+}
+
+
+/** Informational context for every referenced task, including peer/user and mixed rows. Never authorizes settlement. */
+export function deliveryTaskContext(
+  originals: readonly Envelope[],
+  board: { get(id: number): Pick<Task, "id" | "state" | "owner" | "reviewer" | "cancelled"> | undefined },
+  recipient: string,
+): string | undefined {
+  const context = new Set<string>();
+  for (const env of originals) {
+    if (!env.refs?.task || !/^[1-9][0-9]*$/.test(env.refs.task)) continue;
+    const id = Number(env.refs.task);
+    if (!Number.isSafeInteger(id)) continue;
+    const task = board.get(id);
+    if (!task) continue;
+    if (task.state === "cancelled") context.add(`task #${task.id} cancelled`);
+    else if (task.state === "approved") context.add(`task #${task.id} approved`);
+    else if (task.owner !== recipient && task.reviewer !== recipient) context.add(`task #${task.id} moved`);
+    else if ((env.kind === "review" || env.refs.taskRecipient === "reviewer") && (task.state !== "in_review" || task.reviewer !== recipient)) context.add(`task #${task.id} review moved`);
+  }
+  return context.size ? [...context].join("; ") : undefined;
+}

package/src/hub/envelope.ts

@@ -14,7 +14,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; backlog?: number[]; supervision?: boolean; supervisionKey?: string; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;

package/src/hub/host-executable.ts

@@ -0,0 +1,11 @@
+import { isAbsolute, relative } from "node:path";
+import { realPath } from "./project.ts";
+
+/** A repo-writable PATH shim is not a host-owned authenticated capability. No caller-selected binary. */
+export function hostExecutable(name: "gh" | "container" | "git", projectDir: string, path = process.env.PATH ?? ""): string {
+  const found = Bun.which(name, { PATH: path });
+  if (!found || !isAbsolute(found)) throw new Error(`${name} unavailable`);
+  const target = realPath(found), inside = relative(realPath(projectDir), target);
+  if (!inside || inside !== ".." && !inside.startsWith("../") && !isAbsolute(inside)) throw new Error(`${name} unavailable`);
+  return target;
+}

package/src/hub/hub-tools.ts

@@ -41,7 +41,14 @@ const tool = (name: string, description: string, properties: Record<string, unkn
   inputSchema: { type: "object", properties, required, additionalProperties: false },
 });
 
+export const BOUNDED_TASK_TOOLS = new Set(["hub_task_spec", "hub_check_start", "hub_check_result", "hub_check_cancel"]);
+
 export const TASK_TOOLS: HubTool[] = [
+  tool("hub_task_spec", "Read complete assigned GitHub issue contracts through the bounded hub boundary. Owner/reviewer only; no repository or URL input. Refuses withheld or oversized specs.", { id }, ["id"]),
+  tool("hub_check_start", "Run an exact-head isolated Linux check for your in-progress task. Trusted opt-in runner only; no host shell or credentials. Tests require one to 32 test/*.test.ts paths. Receipt is Linux evidence.", { id, check: { type: "string", enum: ["test", "typecheck"] }, files: { type: "array", minItems: 1, maxItems: 32, items: str } }, ["id", "check"]),
+  tool("hub_check_result", "Read your current task-bound isolated check receipt. Stale ownership/generation refuses; output is policy screened.", { run: str }, ["run"]),
+  tool("hub_check_cancel", "Cancel your task-bound isolated check; only its owner or the person may cancel.", { run: str }, ["run"]),
+  tool("hub_delivery_retry", "Request one redelivery of your own needs_review delivery. An earlier attempt may have effects: inspect those effects before acting. Refuses another peer's row or any lineage already explicitly retried; a repeated uncertain row needs the person. Never completes/discards a delivery or changes task state.", { delivery_id: { type: "string", minLength: 1, maxLength: 256 } }, ["delivery_id"]),
   tool("hub_backlog_list", "Read public backlog cards with planning revisions. Configured planners only; PII remains a stub.", {}),
   tool("hub_backlog_plan", "Plan an unpinned backlog item outside frozen releases with the revision you read and a bounded reason. A person's rank is retained. Actual dates cannot be set.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", maxLength: 1000 }, fields: { type: "object", properties: { rank: { type: ["integer", "null"], minimum: 0 }, priority: { type: ["integer", "null"], minimum: 0, maximum: 3 }, release: { type: ["integer", "null"], minimum: 1 }, plannedStart: { type: ["integer", "null"], minimum: 1 }, due: { type: ["integer", "null"], minimum: 1 }, deps: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, reserved: { type: ["string", "null"], minLength: 1, maxLength: 32 } }, additionalProperties: false } }, ["id", "revision", "reason", "fields"]),
   tool("hub_backlog_pull", "Reserve a WIP slot and pull ready unpinned backlog work into To Do at its current revision. Preserves person order/reservations and frozen scope; pending unowned work can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "reason"]),
@@ -51,10 +58,11 @@ export const TASK_TOOLS: HubTool[] = [
 
   tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, role: { type: "string", description: "catalog role id for this task class; guidance only, no routing or authority change" }, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it. With after, the owner is reserved: offered the task first once it is ready" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, backlog: { type: "boolean", description: "stage unoffered work; owner is only a reservation, even when naming yourself" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" }, goal: { type: "string", description: "id of this project's long-term task (ahub goal list) the work is part of" } }, ["title"]),
   tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan: acceptPlan }, ["id"]),
+  tool("hub_task_cancel", "Cancel unaccepted proposed/backlog work you proposed as its configured planner; accepted work is person-only. Keeps history and does not stop a native turn or delete files.", { id, reason: str, superseded_by: str, revision: { type: "integer", minimum: 0 } }, ["id", "reason"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
-  tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
+  tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
   tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. Two changes_requested in a row move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),

package/src/hub/peer-catalog.ts

@@ -26,3 +26,6 @@ const PEER_ROLES: Record<KnownPeer, readonly string[]> = {
 export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
   return Object.fromEntries(Object.entries(PEER_ROLES).filter(([peer]) => includeOptional || !(OPTIONAL_PEERS as readonly string[]).includes(peer)).map(([peer, roles]) => [peer, [...roles]]));
 }
+
+/** #455: who may hold the planner role, in the order automatic assignment tries them; the hub-sandboxed pi and local never plan. */
+export const PLANNER_PEERS = ["claude", "codex", "kimi", "qwen", "jcode"] as const;

package/src/hub/routing.ts

@@ -1,6 +1,9 @@
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CLASSES, type Task, type TaskClass } from "./board.ts";
+import { isGitHubRepository, specRefs } from "./spec-read.ts";
+
+export interface PeerCapabilities { tests: boolean; spec: boolean; testsReason?: string; specReason?: string; }
 import type { PeerId, PeerState } from "./envelope.ts";
 
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
@@ -231,7 +234,10 @@ export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, rou
 /** A peer's entry in a peer-indexed map: own keys only, so a peer named `constructor` is never an inherited Object member. */
 export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer: string): T | undefined => (map && Object.hasOwn(map, peer) ? map[peer] : undefined);
 
+export type RoutingRefusalCode = "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
+export interface RoutingRefusal { peer: PeerId; role: "owner" | "reviewer"; code: RoutingRefusalCode; reason: string }
 export interface Assignment {
+  refusals?: RoutingRefusal[];
   owner?: PeerId;
   reviewer?: PeerId;
   /** what `local` should ask for on this task: a Switchyard route id and the model to fall back to */
@@ -248,10 +254,12 @@ export interface Assignment {
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
  */
 export function assign(
-  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state">>,
+  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external">>,
   states: Record<PeerId, PeerState>,
   routing: Routing,
   opts: {
+    capabilities?: Record<PeerId, PeerCapabilities>;
+    repository?: string;
     exclude?: PeerId[];
     /** Owner admission limits do not remove otherwise eligible reviewers. */
     excludeOwners?: PeerId[];
@@ -280,6 +288,7 @@ export function assign(
     roles?: Record<string, string[]>;
   } = {},
 ): Assignment {
+  if (task.state === "cancelled" || task.state === "approved") return { trace: [`${task.state}: closed; not routed`] };
   if (task.state === "backlog") return { trace: ["backlog: not routed; pull into To Do first"] };
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];
@@ -292,29 +301,39 @@ export function assign(
   if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`, ...(reserved ? [`reserved owner ${reserved}: offered first once it is ready`] : [])] };
   const pii = task.signals.includes("pii_path") || (task.signals.includes("pii") && routing.constraints.pii === "local_only");
 
+  let needsSpec = false;
+  if (!pii) try { needsSpec = specRefs({ title: task.title ?? "", detail: task.detail ?? "", refs: task.refs ?? {}, external: task.external }, opts.repository ?? "", { bareTitle: isGitHubRepository(opts.repository) }).length > 0; }
+  catch { needsSpec = true; } // an invalid/foreign reference never grants a sandboxed peer spec access
+  const needsTests = ["implement", "test", "bulk_edit"].includes(task.class);
+  const refusals = new Map<string, RoutingRefusal>();
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
-    if (opts.offRoster?.includes(peer)) return "off roster";
+    const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
+    if (role === "owner" && opts.capabilities && !pii) {
+      const caps = peerEntry(opts.capabilities, peer);
+      if (needsTests && !caps?.tests) return deny("tests", `missing tests: ${caps?.testsReason ?? "capability unavailable"}`);
+      if (needsSpec && !caps?.spec) return deny("spec", `missing spec: ${caps?.specReason ?? "capability unavailable"}`);
+    }
+    if (opts.offRoster?.includes(peer)) return deny("roster", "off roster");
     const named = role === "owner" ? opts.namedOwner ?? reserved : opts.namedReviewer;
-    if (opts.pullOnly?.includes(peer) && named !== peer) return "pull-only: takes work when named or when it claims it";
-    if (!Object.hasOwn(states, peer)) return "not attached";
-    if (opts.exclude?.includes(peer)) return "excluded (declined or replaced)";
-    if (role === "owner" && opts.excludeOwners?.includes(peer)) return "owner admission: WIP or delivery hold";
-    if (states[peer] === "offline") return "offline";
-    if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return "paused";
+    if (opts.pullOnly?.includes(peer) && named !== peer) return deny("pull-only", "pull-only: takes work when named or when it claims it");
+    if (!Object.hasOwn(states, peer)) return deny("not-attached", "not attached");
+    if (opts.exclude?.includes(peer)) return deny("excluded", "excluded (declined or replaced)");
+    if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
+    if (states[peer] === "offline") return deny("offline", "offline");
+    if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return deny("paused", "paused");
     const failing = peerEntry(opts.failing, peer);
-    if (failing) return `failing: ${failing}`;
-    if (pii && peer !== LOCAL) return "pii: on-prem peers only";
-    if (peer === LOCAL && policy?.local_allowed === false) return "local_allowed = false for this class";
-    if (peer === PI && policy?.local_allowed === false) return "local_allowed = false also excludes pi for this class";
+    if (failing) return deny("failing", `failing: ${failing}`);
+    if (pii && peer !== LOCAL) return deny("pii", "pii: on-prem peers only");
+    if (peer === LOCAL && policy?.local_allowed === false) return deny("policy", "local_allowed = false for this class");
+    if (peer === PI && policy?.local_allowed === false) return deny("policy", "local_allowed = false also excludes pi for this class");
     if (peer === PI && task.signals.includes("long_context")) {
       const backend = policy?.pi_backend ?? "dgx";
       const limit = backend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens;
-      if (routing.signals.long_context_tokens > limit) return `pi ${backend} capability limit ${limit} tokens`;
+      if (routing.signals.long_context_tokens > limit) return deny("policy", `pi ${backend} capability limit ${limit} tokens`);
     }
-    if (peer === LOCAL && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return "long_context: skip local";
+    if (peer === LOCAL && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return deny("policy", "long_context: skip local");
     return undefined;
   };
-
   /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
   const drain = (p: PeerId): number | undefined => {
     const q = peerEntry(opts.quota, p);
@@ -396,7 +415,7 @@ export function assign(
   const piBackend = policy?.pi_backend;
   if (owner === LOCAL) trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
   if (owner === PI) trace.push(`pi decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
-  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), trace };
+  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }
 
 /**

package/src/hub/settings.ts

@@ -1,4 +1,4 @@
-import { SUPPORTED_PEERS } from "./peer-catalog.ts";
+import { PLANNER_PEERS, SUPPORTED_PEERS } from "./peer-catalog.ts";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -46,6 +46,7 @@ const perClass = (name: TaskClass): SettingDef[] => [
 ];
 export const SETTINGS: readonly SettingDef[] = [
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "hub start", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
+  { key: "planner", group: "Roles", label: "Planner (the one peer that plans)", type: "enum", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "peer start", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `roster.${peer}`, group: "Roster", label: `${peer}: participates`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", peer] })),