@staix/agent-hub 0.12.30 → 0.12.32

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/events.ts

@@ -14,9 +14,9 @@ export const EVENTS_SCHEMA = 1;
  */
 export type HubEvent =
   | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
-  /** A settings change (#269): the registry key, the value in force before and after (closed words, ids or booleans, never free text) and where it came from. */
   | { type: "role"; peer?: string; task?: number; actor: string; stage: "prepared" | "assigned"; roles: { id: string; layer: "shipped" | "project"; hash: string }[] }
-  | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal"; undo?: boolean }
+  /** A settings change (#269): the registry key, the bounded registry values before/after and their source; an optional person reason is sanitized and capped at 400 UTF-8 bytes. */
+  | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal"; undo?: boolean; reason?: string }
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }

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/manager.ts

@@ -155,7 +155,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
           return { ok: true };
         }
         // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
-        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
         client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
         const deliveryRead = input.action === "sdlc_queue" || input.action === "sdlc_release";
         let nominalMs = 10_000;

package/src/hub/peer-catalog.ts

@@ -1,4 +1,8 @@
-/** Native peers the hub knows; membership checks share this list. */
+import { definitionOf } from "../adapters/registry.ts";
+
+// ponytail: older staged coordinators read these literal declarations to probe target support.
+// A2 replaces that source probe with a published capability before deleting the compatibility exports.
+/** Native peers the hub knows; membership checks share the registry. */
 export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
 /** Optional production peers are added explicitly; legacy defaults remain stable. */
 export const OPTIONAL_PEERS = ["qwen", "jcode"] as const;
@@ -6,23 +10,19 @@ export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
 export type KnownPeer = typeof SUPPORTED_PEERS[number];
 
 export const isKnownPeer = (value: unknown): value is KnownPeer =>
-  typeof value === "string" && (KNOWN_PEERS as readonly string[]).includes(value);
+  typeof value === "string" && !!definitionOf(value) && !definitionOf(value)!.optional;
 
 export const isSupportedPeer = (value: unknown): value is KnownPeer =>
-  typeof value === "string" && (SUPPORTED_PEERS as readonly string[]).includes(value);
+  typeof value === "string" && !!definitionOf(value);
 
 // Policy metadata, not a membership list. Preserve DEFAULT_ROLES' existing key order.
-const PEER_ROLES: Record<KnownPeer, readonly string[]> = {
-  claude: ["planner", "reviewer"],
-  codex: ["implementer"],
-  kimi: ["implementer", "verifier"],
-  local: ["implementer", "verifier"],
-  pi: ["implementer", "verifier"],
-  qwen: ["implementer", "verifier"],
-  jcode: ["implementer", "verifier"],
-};
+const ROLE_ORDER: readonly KnownPeer[] = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode"];
 
 /** Each caller owns its role arrays; changing a project's defaults cannot change another's. */
 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]]));
+  return Object.fromEntries(ROLE_ORDER.filter(peer => includeOptional || !definitionOf(peer)!.optional)
+    .map(peer => [peer, [...definitionOf(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/peers.ts

@@ -44,18 +44,28 @@ export abstract class BasePeer implements PeerAdapter {
   onDelivery?: (receipt: DeliveryReceipt) => void;
   private _state: PeerState = "offline";
   private timer: ReturnType<typeof setTimeout> | undefined;
+  private nextWatchdogMs: number | undefined;
 
   constructor(
     readonly id: PeerId,
-    protected readonly watchdogMs = DEFAULT_WATCHDOG_MS,
+    protected watchdogMs = DEFAULT_WATCHDOG_MS,
   ) {}
 
   get state(): PeerState {
     return this._state;
   }
 
+  /** Keep the active turn's inactivity bound; a changed setting belongs to the next busy turn. */
+  configureWatchdog(ms: number): void {
+    if (!Number.isFinite(ms) || ms <= 0 || ms > 2_147_483_647) throw new Error("invalid watchdog interval");
+    this.nextWatchdogMs = ms;
+  }
+
   protected setState(next: PeerState): void {
-    if (next === "busy") this.touch();
+    if (next === "busy") {
+      if (this._state !== "busy" && this.nextWatchdogMs !== undefined) this.watchdogMs = this.nextWatchdogMs;
+      this.touch();
+    }
     else this.clearWatchdog();
     if (next === this._state) return;
     this._state = next;

package/src/hub/permission-mode.ts

@@ -1,12 +1,13 @@
 import { isSupportedPeer } from "./peer-catalog.ts";
+import { definitionOf } from "../adapters/registry.ts";
 import { lstatSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
 /** Operator-selected approval frequency; agent sandboxes remain separate. */
 export const PERMISSION_MODES = ["ask", "ask-when-needed", "never-ask"] as const;
 export type PermissionMode = typeof PERMISSION_MODES[number];
-export const KIMI_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "yolo", "never-ask": "auto" };
-export const QWEN_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "auto-edit", "never-ask": "yolo" };
+export { KIMI_MODE_IDS } from "../adapters/definitions/kimi-native.ts";
+export { QWEN_MODE_IDS } from "../adapters/definitions/qwen-native.ts";
 export const isPermissionMode = (value: unknown): value is PermissionMode => typeof value === "string" && (PERMISSION_MODES as readonly string[]).includes(value);
 export function permissionDefaults(value: unknown): Record<string, PermissionMode> {
   if (value === undefined) return {};
@@ -29,9 +30,10 @@ export function permissionBoundary(peer: string): string {
 }
 /** What a mode lets a peer do without asking, in one line a person reads before choosing it (#269). */
 export function permissionGrant(peer: string, mode: PermissionMode): string {
+  const grant = definitionOf(peer)?.permission.grants?.[mode];
+  if (grant !== undefined) return grant;
   if (peer === "jcode") return "no verified hub mode mapping; native policy only";
   if (mode === "ask") return peer === "codex" ? "the session's own approval policy applies again" : peer === "kimi" ? "Kimi asks as it does on its own" : peer === "claude" ? "Claude's own permission rules decide" : "every write, edit and shell command asks";
-  if (peer === "qwen") return mode === "never-ask" ? "Qwen yolo approves every tool; NO hub sandbox" : "Qwen auto-edit approves file edits; shell commands ask; NO hub sandbox";
   if (peer === "kimi") return mode === "never-ask" ? "Kimi's auto mode: nothing asks" : "Kimi's yolo mode: it asks only where it judges it must";
   if (peer === "codex") return mode === "never-ask" ? "approval policy never on every turn: nothing asks" : "approval policy on-request on every turn";
   if (peer === "claude") return mode === "never-ask" ? "every tool runs without asking" : "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules";