@staix/agent-hub 0.12.29 → 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;
@@ -133,6 +133,36 @@ export function keepNotes(body: string, max: number): string {
   return extra > 0 ? lines.filter((l) => !(NOTE_LINE.test(l) && extra-- > 0)).join("\n") : body;
 }
 
+/** The same rendered memory reference rides only once in a recipient's preface, including shared note lines. */
+export function uniqueMemoryLines(body: string): string {
+  const reference = (line: string) => /^(?:note from \S+ \[(?:decision|finding|contract|fail)\]: )?mem:([a-f0-9]{8,64})(?=\s|:|$)/i.exec(line)?.[1]?.toLowerCase();
+  const references = [...new Set(body.split("\n").flatMap(line => reference(line) ?? []))];
+  const identity = (id: string) => {
+    const extensions = references.filter(other => other.length > id.length && other.startsWith(id));
+    const terminals = extensions.filter(other => !extensions.some(longer => longer.length > other.length && longer.startsWith(other)));
+    // An ambiguous prefix cannot identify either full entry; keep both full references.
+    return terminals.length === 1 ? terminals[0]! : id;
+  };
+  const ids = new Set<string>(), headers = new Set<string>();
+  let removed = false;
+  const lines = body.split("\n").filter((line) => {
+    const memory = reference(line);
+    const seen = memory ? ids : line.startsWith("Hub memory:") ? headers : undefined;
+    const key = memory ? identity(memory) : line;
+    if (!seen) return true;
+    if (seen.has(key)) { removed = true; return false; }
+    seen.add(key);
+    return true;
+  });
+  return removed ? lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() : body;
+}
+
+/** Recovery and a new session can regenerate the same context. Keep distinct context and every new note. */
+export function mergePrefaces(older: string, newer: string): string {
+  const contains = (whole: string, part: string) => `\n\n${whole}\n\n`.includes(`\n\n${part}\n\n`);
+  return uniqueMemoryLines(contains(older, newer) ? older : contains(newer, older) ? newer : `${older}\n\n${newer}`);
+}
+
 /** Notes follow each other line by line; the first one after other text starts a paragraph. */
 export function appendNote(body: string, line: string): string {
   return `${body}${NOTE_LINE.test(body.slice(body.lastIndexOf("\n") + 1)) ? "\n" : "\n\n"}${line}`;

package/src/hub/git.ts

@@ -1,38 +1,2 @@
-import { spawnSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process";
-
-/**
- * The one helper for every git call the hub makes outside the sandbox (#281): the repository's own configuration
- * must not name a program the hub then runs with its own rights (defense in depth behind the seatbelt profile,
- * which refuses a sandboxed command the writes that would plant one). Every call gets:
- * - core.fsmonitor=false: the file-system monitor is an arbitrary command read from the repo config.
- * - core.hooksPath=/dev/null: hooks come from a non-directory, so every hook lookup fails closed.
- * - diff.external= (empty): no external diff driver.
- * - core.pager=cat and --no-pager: no pager, whatever the config says (stdout is a pipe everywhere anyway).
- * - credential.helper= (empty resets the list) and core.askpass= (empty fails closed), with GIT_TERMINAL_PROMPT=0:
- *   no hub command authenticates, so any prompt is a bug and must fail instead of running a configured helper.
- * git has no global switch for filter drivers or textconv: both are per-driver config keys. Of the hub's commands
- * only the snapshot's `add`/`restore` would run a filter driver, and only a content diff would run textconv — the
- * hub's one content diff is `diff --no-index`, which DOES read the repository's config (verified: a planted
- * diff.external runs for it), so that call passes `--no-ext-diff` and `--no-textconv` on top of the config here,
- * and the driver command of a filter lives in the `.git/config` the seatbelt profile refuses to a sandboxed
- * command. GIT_CONFIG_NOSYSTEM/global are left alone: those files are the user's own.
- */
-const SAFE_CONFIG = ["core.fsmonitor=false", "core.hooksPath=/dev/null", "diff.external=", "core.pager=cat", "credential.helper=", "core.askpass="];
-/** Hub memory sync (#258) pushes to the person's own remote: their global credential helper stays, the rest does not. */
-const CREDENTIAL_KEYS = new Set(["credential.helper=", "core.askpass="]);
-
-/**
- * `["git", ...safe options, ...args]`: use instead of a literal "git" argv anywhere under src/. `credentials` keeps the
- * person's credential helper, for a repository the hub created itself (the memory store), never a project's.
- */
-export const hubGitArgv = (args: string[], opts: { credentials?: boolean } = {}): string[] =>
-  ["git", "--no-pager", ...SAFE_CONFIG.filter((c) => !opts.credentials || !CREDENTIAL_KEYS.has(c)).flatMap((c) => ["-c", c]), ...args];
-
-/** The caller's env plus the no-prompt switch; existing keys (childEnv, GIT_OPTIONAL_LOCKS=0) pass through. */
-export const hubGitEnv = (env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv => ({ ...env, GIT_TERMINAL_PROMPT: "0" });
-
-/** spawnSync form of the same call: the env option is merged with hubGitEnv, everything else passes through. */
-export function hubGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
-  const argv = hubGitArgv(args);
-  return spawnSync(argv[0]!, argv.slice(1), { ...options, env: hubGitEnv(options.env ?? process.env) });
-}
+// The portable core owns hardened git invocation; retain the hub names as identical exports.
+export { memoryGitArgv as hubGitArgv, memoryGitEnv as hubGitEnv, memoryGitSync as hubGitSync } from "@staix/agent-mem/platform";

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,13 +58,18 @@ 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_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }, ["text"]),
+  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"]),
+  tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
+  tool("hub_memory_graph", "Read screened memory neighbourhoods, fails first. Up to 8 starts (<=200 UTF-8 bytes each), 1 or 2 hops; default 60/max 120 nodes, max 240 edges, whole output <=6 KB. No project argument.", { starts: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 200, description: "At most 200 UTF-8 bytes" } }, hops: { type: "integer", enum: [1, 2] }, limit: { type: "integer", minimum: 1, maximum: 120 } }, ["starts"]),
+  tool("hub_memory_correct", "Propose a correction to a visible memory entry. This creates a machine-local candidate only; a person accepts or rejects it with amem review. It never edits a note. id is an exact id or unique visible prefix; text and reason must each fit 4000 UTF-8 bytes.", { id: str, text: str, reason: str }, ["id", "text", "reason"]),
+  tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
 ];
 
 export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));

package/src/hub/manager.ts

@@ -9,7 +9,7 @@ import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS } from "./control-cl
 import { Registry, type Project } from "./registry.ts";
 import { hubHome } from "./project.ts";
 import { startDashboard } from "./ui.ts";
-import { projectChain } from "../memory/recall.ts";
+import { projectChain } from "@staix/agent-mem";
 import type { ProjectInspection } from "./lifecycle.ts";
 import { MAX_COMMAND_MS } from "../cli/terminal-recovery.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";