@staix/agent-hub 0.21.0 → 0.23.0

package/src/hub/room-invocations.ts

@@ -0,0 +1,145 @@
+/** Host-owned X6 correlation. The room transport never becomes a task/tool authority. */
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { HUB, MAX_HOP, newEnvelope, type Envelope } from "./envelope.ts";
+import type { Bus } from "./bus.ts";
+import { argsDigest, boundedInvocationBody, isOpenOutcome, type InvocationLedger, type InvocationOutcome, type InvocationRow } from "./invocations.ts";
+import { canonical, type ShareConfig } from "./capabilities.ts";
+import { authorizeRoomInvocation, type RoomInvocationAuthorization } from "../rooms/boundary.ts";
+import { decodeRoomInvocationBody, encodeRoomInvocationBody, type RoomReadInvocationRequest } from "../rooms/application.ts";
+import type { RoomInvocationIdentity, RoomInvocationIngress } from "../rooms/service.ts";
+
+export interface RoomInvocationPorts {
+  bus: Bus; ledger: InvocationLedger; shares: () => ShareConfig;
+  identity: (peer: string, sender?: string) => RoomInvocationIdentity | undefined;
+  target: (input: RoomInvocationIngress, request: RoomReadInvocationRequest) => Promise<void>;
+  safeResult: (body: string, current: () => boolean) => Promise<boolean>;
+  quarantine?: (row: InvocationRow) => void;
+  finish: (row: InvocationRow, outcome: InvocationOutcome, input?: { body?: string; reason?: string }) => void;
+}
+export class RoomInvocations {
+  constructor(private readonly p: RoomInvocationPorts) {}
+  localActor(env: Envelope): string | undefined {
+    const local = env.kind === "invocation" ? env.id : env.refs?.invocation;
+    const row = local && this.p.ledger.get(local), route = local && this.p.ledger.relay(local);
+    if (!row || !route) return undefined;
+    try {
+      const identity = this.p.identity(route.remotePeer);
+      return identity && this.authorization(env, identity) ? route.direction === "outbound" ? row.caller : row.target : undefined;
+    } catch { return undefined; }
+  }
+  authorization(env: Envelope, identity: RoomInvocationIdentity): RoomInvocationAuthorization | undefined {
+    const local = env.kind === "invocation" ? env.id : env.refs?.invocation;
+    const row = local && this.p.ledger.get(local), route = local && this.p.ledger.relay(local);
+    if (!row || !route || row.class !== "read" || env.from !== HUB || env.to?.length !== 1 || env.to[0] !== route.remotePeer
+      || route.room !== identity.room || route.member !== identity.member || route.epoch !== identity.epoch || !identity.current()) return undefined;
+    if (env.kind === "invocation" && (route.direction !== "outbound" || !isOpenOutcome(row.outcome) || env.id !== route.request)) return undefined;
+    if (env.kind === "invocation_result" && (route.direction !== "inbound" || env.id !== route.result || route.state !== "result_queued")) return undefined;
+    if (env.kind !== "invocation" && env.kind !== "invocation_result") return undefined;
+    if (env.trace !== row.trace || env.hop !== route.hop + (env.kind === "invocation_result" ? 1 : 0)) return undefined;
+    if (env.kind === "invocation" && roomInvocationHash({ id: env.id, trace: env.trace, hop: env.hop, from: route.caller, to: route.target,
+      kind: env.kind, priority: "status", body: env.body, ts: env.ts }) !== route.hash) return undefined;
+    const payload = decodeRoomInvocationBody(env.kind, env.body);
+    if (payload.invocation !== route.request || payload.capability !== route.capability || payload.digest !== route.digest) return undefined;
+    if (env.kind === "invocation_result" && (payload as import("../rooms/application.ts").RoomReadInvocationResult).outcome !== row.outcome) return undefined;
+    if (env.kind === "invocation" && argsDigest((payload as RoomReadInvocationRequest).args) !== row.argsSha256) return undefined;
+    const current = () => {
+      const live = this.p.ledger.relay(row.id), candidate = this.p.ledger.get(row.id);
+      const pin = this.p.shares()[route.remotePeer]?.[route.capability];
+      return identity.current() && !!candidate && live?.room === identity.room && live.member === identity.member && live.epoch === identity.epoch
+        && (env.kind === "invocation" ? isOpenOutcome(candidate.outcome) && pin?.digest === row.digest && pin.class === "read" : live.state === "result_queued" && live.result === env.id);
+    };
+    return authorizeRoomInvocation(env, route.direction === "outbound" ? row.caller : row.target, payload, current);
+  }
+  /** Called after target execution settles, before the ordinary caller-offline early return. */
+  result(row: InvocationRow, outcome: InvocationOutcome, input: { body?: string; reason?: string }): boolean {
+    const route = this.p.ledger.relay(row.id);
+    if (!route || route.direction !== "inbound") return false;
+    const result = newEnvelope(HUB, "", { to: [route.remotePeer], kind: "invocation_result", priority: "status", refs: { invocation: row.id } });
+    result.trace = row.trace; result.hop = route.hop + 1;
+    result.body = encodeRoomInvocationBody("invocation_result", { invocation: route.request, capability: row.capability, digest: row.digest, class: "read",
+      outcome: outcome as Exclude<InvocationOutcome, "queued" | "delivered">, body: outcome === "withheld" ? "" : boundedInvocationBody(input.body ?? input.reason ?? "no result") });
+    const identity = this.p.identity(route.remotePeer, row.target);
+    if (!identity || identity.room !== route.room || identity.member !== route.member || identity.epoch !== route.epoch || !identity.current()) {
+      this.p.ledger.updateRelay(row.id, "needs_review"); this.p.bus.holdInvocation(row.id, "remote invocation result route changed", row.target); return true;
+    }
+    this.p.ledger.updateRelay(row.id, "result_queued", result.id);
+    try { this.p.bus.publish(result); }
+    catch { this.p.ledger.updateRelay(row.id, "needs_review"); this.p.bus.holdInvocation(row.id, "remote invocation result publication is uncertain", row.target); }
+    return true;
+  }
+  async receive(input: RoomInvocationIngress): Promise<"admitted" | "refused"> {
+    const env = input.envelope;
+    if (env.kind === "invocation") {
+      const request = decodeRoomInvocationBody("invocation", env.body);
+      if (env.hop >= MAX_HOP || !input.current()) return "refused";
+      const prior = this.p.ledger.relayByRemote(input.room, input.member, request.invocation, "inbound");
+      if (prior) {
+        if (prior.hash !== input.hash || prior.epoch !== input.epoch || prior.remotePeer !== input.remotePeer || prior.caller !== env.from || prior.target !== env.to || prior.capability !== request.capability || prior.digest !== request.digest) return "refused";
+        if (!input.claim()) throw new Error("room: invocation claim unavailable");
+        return "admitted";
+      }
+      try { await this.p.target(input, request); return "admitted"; }
+      catch (error) {
+        // Only a proven pre-effect refusal earns a signed NACK; storage/post-claim failures retain uncertainty.
+        if (error instanceof PreEffectToolRefusal) return "refused";
+        throw error;
+      }
+    }
+    if (env.kind !== "invocation_result") return "refused";
+    const result = decodeRoomInvocationBody("invocation_result", env.body), route = this.p.ledger.relay(result.invocation), row = this.p.ledger.get(result.invocation);
+    if (!route || !row || route.direction !== "outbound" || route.room !== input.room || route.member !== input.member || route.epoch !== input.epoch
+      || route.remotePeer !== input.remotePeer || env.from !== route.target || env.to !== route.caller || env.trace !== row.trace || env.hop !== route.hop + 1
+      || result.capability !== row.capability || result.digest !== row.digest || !input.current()) return "refused";
+    if (!isOpenOutcome(row.outcome)) { if (!input.claim()) throw new Error("room: invocation claim unavailable"); return "admitted"; }
+    const pin = this.p.shares()[route.remotePeer]?.[route.capability];
+    const current = () => input.current() && this.p.shares()[route.remotePeer]?.[route.capability]?.digest === row.digest
+      && this.p.shares()[route.remotePeer]?.[route.capability]?.class === "read";
+    let safe = pin?.digest === row.digest && pin.class === "read" && await this.p.safeResult(result.body, current);
+    if (!input.current()) throw new Error("room: invocation trust changed");
+    safe &&= current();
+    if (!input.claim()) throw new Error("room: invocation claim unavailable");
+    const uncertain = result.outcome === "needs_review" || result.outcome === "timeout";
+    if (uncertain) this.p.bus.holdInvocation(row.id, "target hub reports an uncertain invocation", row.target);
+    this.p.ledger.updateRelay(row.id, route.state, env.id);
+    const outcome = uncertain ? "needs_review" : safe ? result.outcome : result.outcome === "refused" ? "refused" : "withheld";
+    const visible = safe ? result.outcome === "completed" ? { body: result.body } : { reason: boundedInvocationBody(result.body) }
+      : uncertain ? { reason: "the target reports an uncertain outcome; remote details were withheld" }
+      : result.outcome === "refused" ? { reason: "the target declined; the reason was withheld" } : {};
+    this.p.finish(row, outcome, visible);
+    this.p.ledger.updateRelay(row.id, uncertain ? "needs_review" : "completed", env.id);
+    return "admitted";
+  }
+  receipt(id: string, state: "completed" | "failed_safe" | "needs_review"): void {
+    const request = this.p.ledger.relay(id), result = this.p.ledger.relayForResult(id);
+    if (request?.direction === "outbound") {
+      if (state === "completed") { this.p.ledger.markDelivered(id); this.p.ledger.updateRelay(id, "admitted"); }
+      else {
+        this.p.ledger.updateRelay(id, state === "failed_safe" ? "completed" : "needs_review"); const row = this.p.ledger.get(id);
+        if (row) this.p.finish(row, state === "failed_safe" ? "refused" : "needs_review", { reason: state === "failed_safe" ? "the target hub refused read admission" : "remote invocation delivery is uncertain; inspect it by hand" });
+      }
+    }
+    if (result) this.p.ledger.updateRelay(result.local, state === "completed" ? "completed" : "needs_review");
+  }
+  /** Startup only: never resend an outcome whose publication a crash could have interrupted. */
+  reconcile(): void {
+    const pending = this.p.bus.queueList(undefined, true);
+    for (const route of this.p.ledger.pendingRelays()) {
+      if (route.state === "needs_review") continue;
+      const row = this.p.ledger.get(route.local);
+      if (!row) continue;
+      const request = pending.find(delivery => delivery.originals.some(env => env.id === row.id));
+      if (isOpenOutcome(row.outcome) && (!request || request.state !== "queued")) {
+        this.p.bus.holdInvocation(row.id, "remote invocation handoff is unconfirmed after restart", row.target);
+        this.p.ledger.updateRelay(row.id, "needs_review");
+        if (this.p.quarantine) this.p.quarantine(row); else this.p.ledger.settle(row.id, "needs_review");
+        continue;
+      }
+      const result = route.result && pending.find(delivery => delivery.originals.some(env => env.id === route.result));
+      if (route.direction === "inbound" && !isOpenOutcome(row.outcome) && (route.state !== "result_queued" || !result || result.state !== "queued")) {
+        this.p.ledger.updateRelay(row.id, "needs_review");
+        if (!route.result) this.p.bus.holdInvocation(row.id, "remote result publication was interrupted", row.target);
+      } else if (route.direction === "outbound" && !isOpenOutcome(row.outcome)) this.p.ledger.updateRelay(row.id, "needs_review");
+    }
+  }
+}
+export const roomInvocationHash = (value: unknown): string => argsDigest(canonical(value));

package/src/hub/settings.ts

@@ -28,7 +28,9 @@ export interface SettingDef {
   key: string;
   group: "Permissions" | "Start" | "Routing" | "Switches" | "Roster" | "Roles";
   label: string;
-  type: "enum" | "boolean" | "peers" | "roles" | "integer" | "number";
+  type: "enum" | "boolean" | "peers" | "roles" | "integer" | "number" | "lines";
+  /** Written only by the named hub command, never by `settings set`, a dashboard session or a conductor (#514b). */
+  managed?: "learn";
   min?: number; max?: number;
   /** The closed values of an enum; a route setting takes the project's own route ids instead. */
   values?: readonly string[];
@@ -85,7 +87,16 @@ export const SETTINGS: readonly SettingDef[] = [
  * Never editable from settings, whatever the session: these choose what the hub executes or where secrets and task
  * text go. A key equal to an entry, or below it, is refused by name.
  */
-export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "schedules", "folder_triggers", "corpus", "rooms", "instances", "adapters", "adapter_modules", "local.doc_read", "local.web_fetch"] as const;
+export const NEVER_EDITABLE = ["invocation", "kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "schedules", "folder_triggers", "corpus", "rooms", "instances", "adapters", "adapter_modules", "local.doc_read", "local.web_fetch"] as const;
+
+/**
+ * The one key `ahub learn accept` writes (#514b): the active profile's review checklist, which replaces as a unit. It is NOT a row of `SETTINGS` and `settingDef` does NOT resolve it, so
+ * `settings set|get|list`, the dashboard, a settings session and a conductor all see an unknown setting and nothing about them changed. Only the daemon's learn operation passes this
+ * definition to `settingsSet` itself (a function argument no request field can reach), so the write still goes through the same writer, loader check, reload and undo as every other setting.
+ */
+export const LEARN_CHECKLIST: SettingDef = Object.freeze({ key: "profile_overrides.review_checklist", group: "Routing", label: "Profile review checklist (written by ahub learn accept)", type: "lines", managed: "learn",
+  store: "config", applies: "restart", restartReason: "Session tool schemas and profile contracts are bound at startup", risk: "raises", path: Object.freeze(["profile_overrides", "review_checklist"]) });
+const LEARN_LINES_MAX = 16, LEARN_LINE_MAX = 500;
 
 /** Derive project-bound rows from the same builtin templates used by lookup, without registering aliases globally. */
 export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): readonly SettingDef[] {
@@ -143,6 +154,11 @@ export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAda
   return extra.length ? Object.freeze([...settings, ...extra]) : settings;
 }
 
+/** What undo may put back: a registry key, or the one managed key `ahub learn accept` writes. Never used to set anything. The CLI passes its project scope; the daemon has its own wrapper over its project-scoped lookup. */
+export function undoableDef(key: unknown, instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): SettingDef | string {
+  return key === LEARN_CHECKLIST.key ? LEARN_CHECKLIST : settingDef(key, instances, adapterCatalog);
+}
+
 /** The definition of a key, or why there is none. */
 export function settingDef(key: unknown, instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): SettingDef | string {
   if (typeof key !== "string" || key.length > 80) return "unknown setting";
@@ -163,6 +179,10 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
     if (typeof raw !== "number" || !(def.type === "integer" ? Number.isSafeInteger(raw) : Number.isFinite(raw)) || raw < (def.min ?? 0) || raw > (def.max ?? Number.MAX_SAFE_INTEGER)) throw new Error(`${def.key} takes ${def.type === "integer" ? "an integer" : "a number"} from ${def.min ?? 0} to ${def.max ?? Number.MAX_SAFE_INTEGER}`);
     return raw;
   }
+  if (def.type === "lines") {
+    if (!Array.isArray(raw) || !raw.length || raw.length > LEARN_LINES_MAX || raw.some(line => typeof line !== "string" || !line.trim() || line.length > LEARN_LINE_MAX || /[\x00-\x1f\x7f]/.test(line))) throw new Error(`${def.key} takes one to ${LEARN_LINES_MAX} lines of plain text, each at most ${LEARN_LINE_MAX} characters`);
+    return raw.map(line => line.trim());
+  }
   if (def.type === "boolean") {
     if (typeof raw !== "boolean") throw new Error(`${def.key} takes true or false`);
     return raw;

package/src/hub/shipped-packs.ts

@@ -1,8 +1,11 @@
 import example from "../../templates/packs/example.pack.json" with { type: "text" };
+import writing from "../../templates/packs/writing-pack.pack.json" with { type: "text" };
+import analysis from "../../templates/packs/analysis.pack.json" with { type: "text" };
+import ops from "../../templates/packs/ops.pack.json" with { type: "text" };
 
 /**
  * The packs the hub ships (#513a), by file name without `.pack.json`. Imported as text so the bundle carries them, as `shipped-roles.ts` carries the role catalog.
- * Only the format example is here: the writing, analysis and ops packs are #513b, which adds a file to `templates/packs/` and a line here.
+ * The format example and the writing, analysis and ops domain packs are advisory data; checks never execute from this registry.
  */
 // TypeScript types a `.json` import as its parsed shape even with `type: "text"`; Bun hands over the file text, which `parsePack` parses and bounds itself.
-export const SHIPPED_PACKS: Readonly<Record<string, string>> = { example: example as unknown as string };
+export const SHIPPED_PACKS: Readonly<Record<string, string>> = { example: example as unknown as string, "writing-pack": writing as unknown as string, analysis: analysis as unknown as string, ops: ops as unknown as string };

package/src/hub/shipped-roles.ts

@@ -10,6 +10,13 @@ import role8 from "../../templates/roles/research/analyst.md" with { type: "text
 import role9 from "../../templates/roles/research/statistician.md" with { type: "text" };
 import role10 from "../../templates/roles/research/fact-checker.md" with { type: "text" };
 
+import role11 from "../../templates/roles/writing/editor.md" with { type: "text" };
+import role12 from "../../templates/roles/writing/translator.md" with { type: "text" };
+import role13 from "../../templates/roles/writing/style-checker.md" with { type: "text" };
+import role14 from "../../templates/roles/writing/terminology-checker.md" with { type: "text" };
+import role15 from "../../templates/roles/ops/project-manager.md" with { type: "text" };
+import role16 from "../../templates/roles/ops/meeting-actions-owner.md" with { type: "text" };
+
 export const SHIPPED_ROLES: Readonly<Record<string, string>> = {
   "software-architect": role0,
   "backend-engineer": role1,
@@ -22,4 +29,10 @@ export const SHIPPED_ROLES: Readonly<Record<string, string>> = {
   "analyst": role8,
   "statistician": role9,
   "fact-checker": role10,
+  "editor": role11,
+  "translator": role12,
+  "style-checker": role13,
+  "terminology-checker": role14,
+  "project-manager": role15,
+  "meeting-actions-owner": role16,
 };

package/src/hub/tasks.ts

@@ -1,3 +1,4 @@
+import type { InvocationRow } from "./invocations.ts";
 import type { ContextAdmission } from "./context-window.ts";
 import { queueBackpressure, queueBackpressurePolicy, type QueueBackpressureCode, type QueueBackpressurePolicy, type QueueBackpressureStatus, type QueuePressure } from "./queue-backpressure.ts";
 import { canonicalMemorySymbolNode, normalizeMemorySymbolInput, MEMORY_SYMBOL_LIMIT, type MemorySymbolNodes } from "./memory-symbols.ts";
@@ -35,7 +36,16 @@ import type { MemoryScreen } from "./read-tools.ts";
 import { withoutPii, mentionsPrivatePath } from "./memory-policy.ts";
 import { profileClass, profileData, profileTaskLabel, projectProfile, type ProfileName, type ProfileSelection, type ProjectProfile } from "./profiles.ts";
 import { criteriaView, unmetCriteriaIds, workflowHash } from "./workflow.ts";
-import { candidateCard, criterionKey, groupUnmetCriteria, LEARNING_DEFAULTS, selectGroups, type CriterionGroup } from "./learning.ts";
+import { candidateCard, criterionKey, groupUnmetCriteria, LEARNING_DEFAULTS, overridesDiff, parseCandidateCard, selectGroups, type CriterionGroup } from "./learning.ts";
+/** #514b: how a closed candidate card says what the person decided; `learnCandidates` reads them back. */
+const LEARN_ACCEPTED = "candidate accepted", LEARN_REJECTED = "candidate rejected";
+/** What the person decided on a candidate card, read from its cancellation: only an entry the person wrote counts, so no other note can pass for a verdict. Undefined while it is open or closed for another reason. */
+const learnVerdict = (card: Pick<Task, "state" | "history">): "accepted" | "rejected" | undefined => {
+  if (card.state !== "cancelled") return undefined;
+  const closed = card.history.findLast(entry => entry.event === "cancelled");
+  if (!closed || closed.by !== USER) return undefined;
+  return closed.note?.startsWith(LEARN_ACCEPTED) ? "accepted" : closed.note?.startsWith(LEARN_REJECTED) ? "rejected" : undefined;
+};
 import { approvedDeliverables, latestDeliverables, parseDeliverableClaims, publicDeliverables, type DeliverableRecord, type DeliverableStatus } from "./deliverables.ts";
 import { checkDeliverables, DeliverableRefusal, hashDeliverables, vetDeliverables, type DeliverablePorts } from "./deliverable-files.ts";
 import { isAbsolute, relative } from "node:path";
@@ -253,6 +263,7 @@ QUIET_EVENTS.add("ready held"); // #655: the hub's note that a ready task waits
 QUIET_EVENTS.add("plan observed"); // Host observation does not move the task or replace completion intent.
 QUIET_EVENTS.add("planner changed"); // Planning authority does not move the execution owner or revoke its handoff.
 QUIET_EVENTS.add("claim verdict"); // #901: a person's bookkeeping on a plan claim moves nothing, so it must not turn a running check into "check finished late".
+QUIET_EVENTS.add("invocation");
 QUIET_EVENTS.add("shell branch bound"); // #880: the hub's host-observed branch binding (#845) is bookkeeping; it neither moves nor settles the task.
 /** The records of the `done (checking)` entry a passed check now completes: what the owner delivered then (#509a). */
 const latestPendingDeliverables = (task: Task): DeliverableRecord[] | undefined => {
@@ -600,6 +611,17 @@ export class Tasks {
     });
   }
 
+  /** Host-only audit: no tool accepts this record and no task state or notification changes. */
+  recordInvocation(id: number, row: InvocationRow): void {
+    const task = this.d.board.get(id);
+    if (!task) throw new Error("invocation audit task is unavailable");
+    if (row.task !== id) throw new Error("invocation audit task mismatch");
+    if (row.outcome === "queued" && (this.isPii(task) || this.d.privateTurn?.(row.caller) || isClosedTaskState(task.state) || task.state === "backlog" || task.owner !== row.caller && task.reviewer !== row.caller)) throw new Error("invocation audit task scope changed");
+    if (task.history.some(entry => entry.invocation?.id === row.id && entry.invocation.outcome === row.outcome)) return;
+    const { id: invocationId, caller, target, capability, digest, class: sideEffect, approval, argsSha256, outcome } = row;
+    this.d.board.update(id, HUB, "invocation", {}, undefined, { invocation: { id: invocationId, caller, target, capability, digest, class: sideEffect, approval, argsSha256, outcome } });
+  }
+
   recordOwnerTurn(peer: PeerId, bindings: readonly { id: number; acceptance: number }[], changed: boolean | undefined, effect: boolean): void {
     requireLocalTaskPeer(peer);
     this.noWriteTurns.retain(this.d.board.list("in_progress").filter(task => ["implement", "bulk_edit"].includes(task.class)).map(task => task.id));
@@ -706,6 +728,74 @@ export class Tasks {
     }
     return new Set(rows.map(row => find(row.id))).size;
   }
+  /**
+   * #514b: the person's view of the recurring-criterion candidates (`ahub learn list`). The person only: a conductor or an agent gets a refusal, never a list. A card that does not parse as the
+   * hub's own is not listed. Ids, counts and the key parts only: the card's text is never echoed, and a PII row is never reached because the cards are already screened when filed.
+   */
+  learnCandidates(by: PeerId, opts: { all?: boolean } = {}): Record<string, unknown>[] {
+    if (by !== USER) throw new PreEffectToolRefusal("ahub learn is a person's command");
+    const rows: Record<string, unknown>[] = [];
+    for (const card of this.d.board.list()) {
+      const parsed = parseCandidateCard(card);
+      if ("refused" in parsed) continue;
+      const open = card.state === "backlog" || card.state === "proposed";
+      const closed = card.history.findLast(entry => entry.event === "cancelled");
+      const verdict = learnVerdict(card) ?? (closed ? "closed" : undefined);
+      if (!open && !opts.all) continue;
+      if (!open && !closed) continue;
+      rows.push({ id: card.id, state: card.state, ...parsed, status: open ? "open" : verdict, tasks: this.learnEvidence(parsed).tasks, line: overridesDiff({ ...parsed, tasks: this.learnEvidence(parsed).tasks }).profile_overrides.review_checklist[0] });
+    }
+    return rows;
+  }
+  /** The distinct tasks that name this criterion unmet on this profile and class in the window, from the board as it is now: the count the written line states is recomputed, never read from the card. */
+  private learnEvidence(card: { profile: string; class: string; criterion: string }): { tasks: number[] } {
+    const eligible = this.d.board.list().filter(row => this.candidateTextAllowed(`${row.profile ?? ""} ${row.profileClass ?? ""} ${row.class}`, row));
+    const group = groupUnmetCriteria(eligible, { windowMs: LEARNING_DEFAULTS.windowMs, now: Date.now() }).find(g => g.profile === card.profile && g.class === card.class && g.criterion === card.criterion);
+    return { tasks: group?.tasks ?? [] };
+  }
+  /**
+   * #514b: what `ahub learn accept` would write for card `id`, or why not. Person only. It reads ONLY the card's key line (`parseCandidateCard`), requires the card to be open, and builds the
+   * line from the board's own evidence with `overridesDiff`: nothing of the card's text is parsed as a value. The daemon adds the line to the stored checklist and writes it through the settings path.
+   */
+  learnAcceptPlan(by: PeerId, id: unknown): { id: number; profile: string; class: string; criterion: string; line: string; tasks: number } {
+    if (by !== USER) throw new PreEffectToolRefusal("ahub learn accept is a person's command");
+    const card = this.learnCard(id);
+    const evidence = this.learnEvidence(card);
+    if (!evidence.tasks.length) throw new PreEffectToolRefusal(`no task in the window still names ${card.criterion} unmet on ${card.profile}/${card.class}: nothing to accept; reject the card to close it`);
+    const line = overridesDiff({ ...card, tasks: evidence.tasks }).profile_overrides.review_checklist[0]!;
+    return { id: card.id, profile: card.profile, class: card.class, criterion: card.criterion, line, tasks: evidence.tasks.length };
+  }
+  /**
+   * #514b: whether `ahub learn accept` already decided this card. Person only. A card the person accepted answers `"accepted"`, so a repeat accept is a no-write success (the plan's idempotency);
+   * a rejected card, a card closed some other way and an open one answer undefined and take the normal path, which refuses the closed ones.
+   */
+  learnAccepted(by: PeerId, id: unknown): { id: number; profile: string; class: string; criterion: string } | undefined {
+    if (by !== USER) throw new PreEffectToolRefusal("ahub learn accept is a person's command");
+    if (typeof id !== "number" || !Number.isSafeInteger(id) || id <= 0) return undefined;
+    const task = this.d.board.get(id);
+    if (!task || learnVerdict(task) !== "accepted") return undefined;
+    const parsed = parseCandidateCard(task);
+    return "refused" in parsed ? undefined : { id, ...parsed };
+  }
+  /** The card, which must be an open candidate the hub filed. */
+  private learnCard(id: unknown): { id: number; profile: string; class: string; criterion: string } {
+    if (typeof id !== "number" || !Number.isSafeInteger(id) || id <= 0) throw new PreEffectToolRefusal("id must be a positive task number");
+    const task = this.d.board.get(id);
+    if (!task) throw new PreEffectToolRefusal(`no task #${id}`);
+    const parsed = parseCandidateCard(task);
+    if ("refused" in parsed) throw new PreEffectToolRefusal(`task #${id}: ${parsed.refused}`);
+    if (task.state !== "backlog" && task.state !== "proposed") throw new PreEffectToolRefusal(`task #${id} is already ${task.state === "cancelled" ? "closed" : task.state}`);
+    return { id, ...parsed };
+  }
+  /**
+   * #514b: closes a candidate card after the person's verdict, through `cancel` (never a direct board write): the row stays, the verdict is in its history, and because the dedupe key is the card's
+   * detail the same criterion is never filed again. `accepted` is recorded only after the write succeeded (the daemon calls this last); a repeat of either verdict is refused by `learnCard`.
+   */
+  async learnClose(by: PeerId, id: unknown, verdict: "accepted" | "rejected"): Promise<Task> {
+    if (by !== USER) throw new PreEffectToolRefusal("ahub learn is a person's command");
+    const card = this.learnCard(id);
+    return this.cancel(card.id, USER, { reason: verdict === "accepted" ? `${LEARN_ACCEPTED} by the person: its review checklist line was written to config.local.json` : `${LEARN_REJECTED} by the person` });
+  }
   /**
    * #514a: the same recurrence path for recurring UNMET CRITERIA. A criterion id that reviews keep naming unmet on the same profile and class, on at least
    * `threshold` tasks that are at least two separate pieces of work (`workUnits`), files one backlog card for a person to review, with the `profile_overrides`
@@ -788,6 +878,7 @@ export class Tasks {
       ...(h.reviewFindings ? { reviewFindings: !h.withheld && this.findingTextAllowed(task, h.reviewFindings.items) ? h.reviewFindings
         : { ...(h.reviewFindings.head ? { head: h.reviewFindings.head } : {}), tally: findingTally(h.reviewFindings.items), withheld: true } } : {}),
       ...(h.supersededBy === undefined ? {} : { supersededBy: screenHistoryText(h.supersededBy, "supersession", h.withheld) }),
+      ...(h.invocation ? { invocation: h.invocation } : {}),
       ...(h.profile === undefined ? {} : { profile: screenHistoryText(h.profile, "profile") }),
       ...(h.owner === undefined ? {} : { owner: h.owner }),
       ...(h.planner === undefined ? {} : { planner: h.planner }),

package/src/memory/capture.ts

@@ -1,6 +1,6 @@
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { defaultCapturePeer } from "../adapters/definitions/native-identity-defaults.ts";
-import { BOUNDED_TASK_TOOLS } from "../hub/hub-tools.ts";
+import { BOUNDED_TASK_TOOLS, CAPABILITY_TOOLS } from "../hub/hub-tools.ts";
 import { MEMORY_READ_TOOLS } from "../hub/read-tools.ts";
 import { isDenied } from "../local/deny.ts";
 import type { MemoryClient } from "./client.ts";
@@ -38,7 +38,7 @@ export class Capture {
   }
 
   observe(call: { tool: string; args: string; output: string; id: string; paths: string[]; sourceId?: string }): void {
-    if (!this.sessionId || ((MEMORY_READ_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || BOUNDED_TASK_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_memory_correct") || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_source_read" || this.opts.skip?.includes(call.tool)) return;
+    if (!this.sessionId || ((MEMORY_READ_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || BOUNDED_TASK_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || CAPABILITY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_memory_correct") || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_source_read" || this.opts.skip?.includes(call.tool)) return;
     // Anything that names a denylisted path is kept out of memory entirely, input and output alike.
     if (call.paths.some((p) => isDenied(p, this.opts.deny) || p.split(/\s+/).some((word) => isDenied(word, this.opts.deny)))) return;
     // ponytail: legacy callers without a host sourceId dedupe native ids within a summary interval; all live LocalPeer calls supply invocation identity. Require that port for other hosts.

package/src/models/relay.ts

@@ -167,6 +167,11 @@ export interface ModelRelayOptions {
   efficientWaitMs?: number;
   /** A backend alias's cooldown starts or ends. */
   onCooldown?: (event: RelayCooldownEvent) => void;
+  /** Host-validated policy captured when this relay is constructed. */
+  cooldownFailures?: number;
+  cooldownMs?: number;
+  cooldownCapMs?: number;
+  terminalHistoryLimit?: number;
   /** Cooldown clock; tests inject one. */
   now?: () => number;
   /** How long a dispatch waits for a busy MLX slot before it gives up and falls back (default 120 s); tests shorten it. */
@@ -207,8 +212,9 @@ export interface ModelRelay {
 
 export interface RelayCooldownEvent { alias: string; event: "start" | "end"; failures: number; ms?: number }
 
-// ponytail: fixed policy, 3 failures and 30 s doubling up to 5 min; routing.toml keys if a backend needs other values.
-const COOLDOWN_FAILURES = 3, COOLDOWN_MS = 30_000, COOLDOWN_CAP_MS = 300_000;
+/** Legacy defaults, independently pinned by the operational-settings tests. */
+export const COOLDOWN_FAILURES = 3, COOLDOWN_MS = 30_000, COOLDOWN_CAP_MS = 300_000;
+export const RELAY_TERMINAL_HISTORY_LIMIT = 1000;
 /** The longest one upstream request may take. */
 const REQUEST_DEADLINE_MS = 180_000;
 // ponytail: a moved attempt (a load move or an enforced pin, both only optimizations) gets 15 s to its response headers
@@ -222,7 +228,12 @@ const MOVE_FIRST_BYTE_MS = 15_000;
  */
 export class BackendCooldowns {
   private readonly entries = new Map<string, { failures: number; until?: number; failedAt?: number; countedAt?: number }>();
-  constructor(private readonly now: () => number = Date.now, private readonly notify: (event: RelayCooldownEvent) => void = () => {}) {}
+  private readonly policy: { failures: number; cooldownMs: number; capMs: number };
+  constructor(
+    private readonly now: () => number = Date.now,
+    private readonly notify: (event: RelayCooldownEvent) => void = () => {},
+    policy: { failures: number; cooldownMs: number; capMs: number } = { failures: COOLDOWN_FAILURES, cooldownMs: COOLDOWN_MS, capMs: COOLDOWN_CAP_MS },
+  ) { this.policy = { ...policy }; }
 
   /** The alias's cooldown while it lasts. Its end is recorded when it is first seen to have passed, or at an answer. */
   cooling(alias: string): { until: number; failures: number } | undefined {
@@ -244,11 +255,11 @@ export class BackendCooldowns {
     const entry = this.entry(alias);
     entry.failedAt = this.now();
     if (cooling || !streak) return;
-    if (entry.countedAt !== undefined && this.now() - entry.countedAt > 2 * COOLDOWN_CAP_MS) entry.failures = 0;
+    if (entry.countedAt !== undefined && this.now() - entry.countedAt > 2 * this.policy.capMs) entry.failures = 0;
     entry.countedAt = this.now();
     entry.failures++;
-    if (entry.failures < COOLDOWN_FAILURES) return;
-    const ms = Math.min(COOLDOWN_CAP_MS, COOLDOWN_MS * 2 ** (entry.failures - COOLDOWN_FAILURES));
+    if (entry.failures < this.policy.failures) return;
+    const ms = Math.min(this.policy.capMs, this.policy.cooldownMs * 2 ** (entry.failures - this.policy.failures));
     entry.until = this.now() + ms;
     this.notify({ alias, event: "start", failures: entry.failures, ms });
   }
@@ -265,7 +276,7 @@ export class BackendCooldowns {
   /** Until when the alias's last dispatch counts as failed for a load move, while it does. */
   failing(alias: string): number | undefined {
     const at = this.entries.get(alias)?.failedAt;
-    return at !== undefined && this.now() < at + COOLDOWN_MS ? at + COOLDOWN_MS : undefined;
+    return at !== undefined && this.now() < at + this.policy.cooldownMs ? at + this.policy.cooldownMs : undefined;
   }
 
   private entry(alias: string) {
@@ -430,7 +441,7 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
   const models = relayModelIds(options);
   const efficientWaitMs = options.efficientWaitMs;
   const moveFirstByteMs = options.moveFirstByteMs ?? MOVE_FIRST_BYTE_MS;
-  const cooldowns = new BackendCooldowns(options.now, (event) => { try { options.onCooldown?.(event); } catch { /* observation cannot fail routing */ } });
+  const cooldowns = new BackendCooldowns(options.now, (event) => { try { options.onCooldown?.(event); } catch { /* observation cannot fail routing */ } }, { failures: options.cooldownFailures ?? COOLDOWN_FAILURES, cooldownMs: options.cooldownMs ?? COOLDOWN_MS, capMs: options.cooldownCapMs ?? COOLDOWN_CAP_MS });
   const autoRoute = options.enableHubAuto ? new AutoRouteSelector({ ...options, dgxMaxInputTokens }, defaultBackend, mlxAlias, estimateInputTokens) : undefined;
   let mlx: MlxHandle | undefined;
   let mlxStarting: Promise<MlxHandle> | undefined;
@@ -438,7 +449,7 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
   const activeRequests = new Set<ActiveRequest>();
   const activeByAlias = new Map<string, number>();
   const journal: RelayRequestRecord[] = [];
-  const JOURNAL_LIMIT = 1000;
+  const JOURNAL_LIMIT = options.terminalHistoryLimit ?? RELAY_TERMINAL_HISTORY_LIMIT;
 
   // The record object is the generation fence: every update goes through this entry's own closure,
   // so interleaved requests for the same alias never write into each other's evidence.

package/src/rooms/application.ts

@@ -6,7 +6,7 @@ import { canonicalBytes, ROOM_WIRE_LIMITS } from "./wire.ts";
 export const ROOM_APPLICATION_MAX_BYTES = ROOM_WIRE_LIMITS.plaintext;
 export interface RoomChatEnvelope {
   id: string; trace: string; hop: number; from: string; to: string;
-  kind: "chat" | "status"; priority: Priority; body: string; ts: number;
+  kind: "chat" | "status" | "invocation" | "invocation_result"; priority: Priority; body: string; ts: number;
 }
 export type RoomReceiptReason = "admitted" | "inbox_admitted" | "inbox_full" | "inbox_oversize" | "inbox_expired" | "inbox_age_unavailable" | "not_exposed" | "boundary_refused" | "invalid_message" | "rate_limited" | "hop" | "person_inbox_unsupported";
 export type RoomMessage =
@@ -64,10 +64,75 @@ function text(value: unknown): string {
   if (encoder.encode(value).length > ROOM_APPLICATION_MAX_BYTES) fail("limit");
   return value;
 }
+export type RoomInvocationKind = "invocation" | "invocation_result";
+export interface RoomReadInvocationRequest {
+  invocation: string; capability: string; digest: string; class: "read"; depth: 1;
+  args: Record<string, string | number | boolean>;
+}
+export interface RoomReadInvocationResult {
+  invocation: string; capability: string; digest: string; class: "read";
+  outcome: "completed" | "refused" | "failed" | "expired" | "timeout" | "needs_review" | "withheld";
+  body: string;
+}
+export type RoomInvocationPayload = RoomReadInvocationRequest | RoomReadInvocationResult;
+/** Wire contract bounds; the target still validates the capability's actual schema. */
+const INVOCATION_ARGS_MAX = 4096, INVOCATION_STRING_MAX = 2000, INVOCATION_RESULT_MAX = 8192;
+const CAPABILITY_ID = /^(command|skill|mcp_tool):[A-Za-z0-9_.:-]{1,64}$/;
+const CAPABILITY_DIGEST = /^sha256:[0-9a-f]{64}$/;
+export function roomInvocationArgs(value: unknown): Record<string, string | number | boolean> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail();
+  const keys = Object.keys(value).sort();
+  if (keys.length > 16) fail("limit");
+  const raw = object(value, keys), args = Object.create(null) as Record<string, string | number | boolean>;
+  for (const key of keys) {
+    if (/^[A-Za-z0-9_.:-]{1,64}$/.exec(key)?.[0] !== key) fail();
+    const arg = raw[key];
+    if (typeof arg === "string") { if (!arg.isWellFormed() || arg.length > INVOCATION_STRING_MAX) fail("limit"); }
+    else if (typeof arg !== "boolean" && (typeof arg !== "number" || !Number.isFinite(arg))) fail();
+    Object.defineProperty(args, key, { value: arg, enumerable: true });
+  }
+  if (JSON.stringify(args).length > INVOCATION_ARGS_MAX) fail("limit");
+  return Object.fromEntries(Object.entries(args));
+}
+function invocationPayload(kind: RoomInvocationKind, value: unknown): RoomInvocationPayload {
+  const row = object(value, kind === "invocation" ? ["invocation", "capability", "digest", "class", "depth", "args"] : ["invocation", "capability", "digest", "class", "outcome", "body"]);
+  if (row.class !== "read" || typeof row.capability !== "string" || CAPABILITY_ID.exec(row.capability)?.[0] !== row.capability
+    || typeof row.digest !== "string" || CAPABILITY_DIGEST.exec(row.digest)?.[0] !== row.digest) fail();
+  const common = { invocation: uuid(row.invocation), capability: row.capability, digest: row.digest, class: "read" as const };
+  if (kind === "invocation") {
+    if (row.depth !== 1) fail();
+    return { ...common, depth: 1, args: roomInvocationArgs(row.args) };
+  }
+  if (typeof row.outcome !== "string" || !["completed", "refused", "failed", "expired", "timeout", "needs_review", "withheld"].includes(row.outcome)) fail();
+  const body = text(row.body);
+  if (encoder.encode(body).length > INVOCATION_RESULT_MAX) fail("limit");
+  if (row.outcome === "withheld" && body !== "") fail();
+  return { ...common, outcome: row.outcome as RoomReadInvocationResult["outcome"], body };
+}
+/** Closed canonical JSON inside the encrypted envelope: no refs, approvals or extra authority fields. */
+export function encodeRoomInvocationBody(kind: RoomInvocationKind, value: RoomInvocationPayload): string {
+  try { return decoder.decode(canonicalBytes(invocationPayload(kind, value))); }
+  catch (error) { return applicationError(error); }
+}
+export function decodeRoomInvocationBody(kind: "invocation", body: string): RoomReadInvocationRequest;
+export function decodeRoomInvocationBody(kind: "invocation_result", body: string): RoomReadInvocationResult;
+export function decodeRoomInvocationBody(kind: RoomInvocationKind, body: string): RoomInvocationPayload;
+export function decodeRoomInvocationBody(kind: RoomInvocationKind, body: string): RoomInvocationPayload {
+  try {
+    const parsed = invocationPayload(kind, JSON.parse(text(body)));
+    if (decoder.decode(canonicalBytes(parsed)) !== body) fail();
+    return parsed;
+  } catch (error) { return applicationError(error); }
+}
+
 function parseEnvelope(value: unknown): RoomChatEnvelope {
   const row = object(value, ["id", "trace", "hop", "from", "to", "kind", "priority", "body", "ts"]);
-  if (row.kind !== "chat" && row.kind !== "status") fail();
+  if (row.kind !== "chat" && row.kind !== "status" && row.kind !== "invocation" && row.kind !== "invocation_result") fail();
   if (row.priority !== "important" && row.priority !== "status" && row.priority !== "fyi") fail();
+  if (row.kind === "invocation" || row.kind === "invocation_result") {
+    const payload = decodeRoomInvocationBody(row.kind, text(row.body));
+    if (row.from === "user" || row.to === "user" || row.priority !== "status" || row.kind === "invocation" && payload.invocation !== row.id) fail();
+  }
   return { id: uuid(row.id), trace: uuid(row.trace), hop: integer(row.hop, 0, MAX_HOP), from: localPeer(row.from), to: localPeer(row.to), kind: row.kind, priority: row.priority, body: text(row.body), ts: integer(row.ts, 0) };
 }
 function frameDigest(value: unknown): string {