@staix/agent-hub 0.21.0 → 0.22.0

package/src/hub/bus.ts

@@ -41,6 +41,11 @@ export interface BusOptions {
   /** How long a status envelope may wait for company before it is delivered on its own. */
   batchMs: number;
   queueCap: number;
+  /** Accepted live operational settings; read only at the next matching delivery/note operation. */
+  maxAttempts?: () => number;
+  digestMax?: () => number;
+  pullBudgetBytes?: () => number;
+  notesKept?: () => number;
   /** Optional: rewrite a delivery before it goes out (M6 digest condensation). Must return its input on any failure. */
   condense?: (envs: Envelope[]) => Promise<Envelope[]>;
   journal?: DeliveryJournal;
@@ -118,7 +123,7 @@ function resolveTo(to: PeerId[], originals: Envelope[] | undefined): PeerId[] {
 }
 
 const SEEN_CAP = 2048;
-const MAX_ATTEMPTS = 3;
+export const MAX_ATTEMPTS = 3;
 // ponytail: provenance is capped at 2048 ids/peer, 4096 peers, 100000 ids total and 256 KiB per snapshot.
 // Omitted metadata means unknown age only; use a measured per-envelope store if larger queues need provenance.
 const QUEUE_TIME_CAP = 2048, QUEUE_TIME_PEERS_CAP = 4096, QUEUE_TIME_TOTAL_CAP = 100_000, QUEUE_TIME_SNAPSHOT_BYTES = 256 * 1024;
@@ -127,11 +132,11 @@ const remoteId = (id: string): boolean => id.includes("@");
 const remoteFingerprint = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
 // ponytail: one digest carries at most ten originals; larger supervision windows split into bounded deliveries.
 // Revisit this ceiling after measuring native supervision cost, rather than bypassing the delivery limit.
-const DIGEST_MAX = 10;
+export const DIGEST_MAX = 10;
 // #713: a pull-only peer reads between steps, often minutes apart, so one pull drains its queue up to this many bytes of rendered text instead of ten items.
 // Bounded, not unbounded: a queue larger than the budget takes more than one pull, and the reply says how many are still waiting. Push peers keep DIGEST_MAX.
-const PULL_BUDGET_BYTES = 64 * 1024;
-const NOTES_KEPT = 10;
+export const PULL_BUDGET_BYTES = 64 * 1024;
+export const NOTES_KEPT = 10;
 
 /**
  * N-peer fan-out. Never delivers back to `from`, caps hops, dedupes by id. Each peer has one queue,
@@ -797,7 +802,7 @@ export class Bus {
   note(id: PeerId, line: string): void {
     if (remoteId(id)) return;
     const existing = this.prefaces.get(id);
-    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(uniqueMemoryLines(appendNote(existing.body, line)), NOTES_KEPT) } : newEnvelope(HUB, uniqueMemoryLines(line), { to: [id], kind: "presence" }));
+    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(uniqueMemoryLines(appendNote(existing.body, line)), this.opts.notesKept?.() ?? NOTES_KEPT) } : newEnvelope(HUB, uniqueMemoryLines(line), { to: [id], kind: "presence" }));
     this.persist();
   }
 
@@ -805,7 +810,7 @@ export class Bus {
   private restorePreface(id: PeerId, env: Envelope): void {
     if (remoteId(id)) return;
     const now = this.prefaces.get(id);
-    this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), NOTES_KEPT) });
+    this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), this.opts.notesKept?.() ?? NOTES_KEPT) });
   }
 
   /**
@@ -1505,13 +1510,14 @@ export class Bus {
    * An envelope that already failed once goes alone, so a poison one cannot take a digest down with it.
    */
   private take(id: PeerId, queue: Envelope[], remove = true): Envelope[] {
+    const digestMax = this.opts.digestMax?.() ?? DIGEST_MAX;
     const ordered = [...queue.filter((e) => e.priority === "important"), ...queue.filter((e) => e.priority !== "important")];
     const batch: Envelope[] = [];
     for (const env of ordered) {
       const failedBefore = this.attempts.has(`${id}:${env.id}`);
       if (failedBefore && batch.length) break;
       batch.push(env);
-      if (failedBefore || remoteId(id) || batch.length === DIGEST_MAX) break;
+      if (failedBefore || remoteId(id) || batch.length === digestMax) break;
     }
     if (remove) for (const env of batch) queue.splice(queue.indexOf(env), 1);
     return batch;
@@ -1523,13 +1529,14 @@ export class Bus {
    * envelope cannot stall the queue. An envelope that already failed once still goes alone, as in `take`.
    */
   private takeBudget(id: PeerId, queue: Envelope[]): Envelope[] {
+    const pullBudgetBytes = this.opts.pullBudgetBytes?.() ?? PULL_BUDGET_BYTES;
     const batch: Envelope[] = [];
     let bytes = 0;
     for (const env of queue) {
       const failedBefore = this.attempts.has(`${id}:${env.id}`);
       if (failedBefore && batch.length) break;
       const size = Buffer.byteLength(frame(env)) + 2;
-      if (batch.length && bytes + size > PULL_BUDGET_BYTES) break;
+      if (batch.length && bytes + size > pullBudgetBytes) break;
       batch.push(env); bytes += size;
       if (failedBefore) break;
     }
@@ -1555,11 +1562,12 @@ export class Bus {
   }
 
   private failed(id: PeerId, envs: Envelope[], reason = "delivery failed without an error detail", quota = false): void {
+    const maxAttempts = this.opts.maxAttempts?.() ?? MAX_ATTEMPTS;
     if (!this.journal) this.deliveryFailed(id);
     // A quota refusal ran no work. The budget pause fences retries until reset; it is not a poison attempt.
     const quotaPaused = quota && this.paused.has(id);
     this.lastFailure.set(id, reason.replace(/\s+/g, " ").slice(0, 300));
-    if (!quotaPaused && envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= MAX_ATTEMPTS)) {
+    if (!quotaPaused && envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= maxAttempts)) {
       this.failureStreak.set(id, (this.failureStreak.get(id) ?? 0) + 1);
     }
     const keep = envs.filter((env) => {
@@ -1571,7 +1579,7 @@ export class Bus {
       if (quotaPaused) return true;
       const key = `${id}:${env.id}`;
       const n = (this.attempts.get(key) ?? 0) + 1;
-      if (n < MAX_ATTEMPTS) return this.attempts.set(key, n);
+      if (n < maxAttempts) return this.attempts.set(key, n);
       this.attempts.delete(key);
       this.emit({ t: "undeliverable", env, peer: id, reason: this.lastFailure.get(id) });
       return false;

package/src/hub/config-apply.ts

@@ -194,6 +194,7 @@ const schema: Record<string, Check> = {
   conductor: block({ feed: words(["own", "all", "off"]), approval_wait_s: number(0, 2_147_483_647 / 1000) }),
   budget: block({ gate: number(0, 1), stale_min: timerMinutes, poll_min: timerMinutes, checkpoint_timeout_s: timerSeconds, kimi_tokens_5h: number(0), wait_max_min: number(0) }),
   context: block({ gate: number(0, 1), stale_min: timerMinutes, max_assignment_used: number(0, 1) }),
+  bus: block({ max_attempts: operationalNumberCheck("bus.max_attempts"), digest_max: operationalNumberCheck("bus.digest_max"), pull_budget_bytes: operationalNumberCheck("bus.pull_budget_bytes"), notes_kept: operationalNumberCheck("bus.notes_kept"), terminal_history_limit: operationalNumberCheck("bus.terminal_history_limit") }),
   inference: block({ enabled: bool, digest_min_items: number(1, 100_000, true), digest_min_chars: number(1, 10_000_000, true), triage: bool }),
   omniroute: block({ urls: strings, api_key_file: text, access_hosts: strings, cf_client_id_file: text, cf_client_secret_file: text }),
   mlx: block({ enabled: bool, provider: words(["legacy", "ollama"]), host: text, runtimeDir: text, modelPath: text, bin: text, port: number(1, 65535, true), model: text, sourceModel: text,
@@ -213,7 +214,7 @@ const schema: Record<string, Check> = {
   peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), START_MODE_PEERS)(v, k); peerStartConfig(v); },
   terminal: (v, k) => { block({ open: strings })(v, k); terminalTemplate(object(v, k).open); },
   limits: block({ sender_per_min: number(0), pair_per_min: number(0), important_per_hour: number(0), repeat_window_s: number(0) }),
-  review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true), pool: v => { reviewerPoolConfig({ pool: v }, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS); }, rerotate: bool, same_family: words(["fallback", "never"]) }), recovery: block({ auto_resume_after_crash: bool }),
+  review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true), pool: v => { reviewerPoolConfig({ pool: v }, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS); }, rerotate: bool, same_family: words(["fallback", "never"]) }), recovery: block({ auto_resume_after_crash: bool, reconnect_wait_s: operationalNumberCheck("recovery.reconnect_wait_s"), unmanaged_reconnect_wait_s: operationalNumberCheck("recovery.unmanaged_reconnect_wait_s"), control_timeout_s: operationalNumberCheck("recovery.control_timeout_s"), shutdown_wait_s: operationalNumberCheck("recovery.shutdown_wait_s"), terminal_idle_wait_s: operationalNumberCheck("recovery.terminal_idle_wait_s") }),
   capabilities: map(strings), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
 };
 export const SCHEMA_KEYS: readonly string[] = Object.freeze(Object.keys(schema));

package/src/hub/daemon.ts

@@ -81,6 +81,7 @@ import { childEnv } from "./child-process.ts";
 import { runCheck } from "./checks.ts";
 import { DEFAULT_TASK_SWEEP, taskSweepConfig, type TaskSweepConfig } from "./task-sweep.ts";
 import { CONTRADICTION_WINDOW_SETTING, DEMOTE_AT_SETTING, DEMOTION_HALF_LIFE_SETTING, GROOM_FYI_WINDOW_SETTING, RESCREEN_MAX_SETTING, SPLIT_FAILURE_SHARE_SETTING, SPLIT_MIN_SETTING, taskOperationalReaders } from "./operational-settings.ts";
+import { BUS_DIGEST_MAX_SETTING, BUS_MAX_ATTEMPTS_SETTING, BUS_NOTES_KEPT_SETTING, BUS_PULL_BUDGET_BYTES_SETTING, BUS_TERMINAL_HISTORY_LIMIT_SETTING, busOperationalReaders, RECOVERY_CONTROL_TIMEOUT_SETTING, RECOVERY_RECONNECT_WAIT_SETTING, RECOVERY_SHUTDOWN_WAIT_SETTING, RECOVERY_TERMINAL_IDLE_WAIT_SETTING, RECOVERY_UNMANAGED_RECONNECT_WAIT_SETTING } from "./operational-settings.ts";
 import { foldersConfig, scheduleViews, schedulesConfig, ScheduleStore, type FolderEntry, type ScheduleEntry } from "./schedules.ts";
 import { FolderStore, registerScanned, scanFolder, type FolderPolicy } from "./folder-trigger.ts";
 import type { ScannedFile } from "./schedules.ts";
@@ -155,7 +156,8 @@ import { AssignmentUndeliveredError, ESCALATE_AFTER, Tasks } from "./tasks.ts";
 import { DEFAULT_INFERENCE, DIGEST, Inference, screenPii, type InferenceConfig, type PiiVerdict } from "./inference.ts";
 import { taskEvidencePrivacy, type TaskEvidencePrivacy, ask, ASK_NOTE_TITLE, RUN_START } from "./ask.ts";
 import { currentRouting, loadRouting, detectSignals, OVERLAY_FILE, overlayToml, parseRouting, routingText, type Routing } from "./routing.ts";
-import { NEVER_EDITABLE, projectSettings, checkSettingValue, ignoredLine, pendingUndo, pendingUndoIdentity, readOverlay, restoredValue, routingCandidate, storedLocally, sharedValue, settingDef as instanceSettingDef, settingRefusal, settingRows, settingText, undoSetting, valueAt, writeConfigSetting, writeRoutingSetting, type SettingAuthority, type SettingSource, type SettingDef, type SettingRow, type SettingValue, type UndoIdentity } from "./settings.ts";
+import { withChecklistLine } from "./learning.ts";
+import { LEARN_CHECKLIST, NEVER_EDITABLE, projectSettings, checkSettingValue, ignoredLine, pendingUndo, pendingUndoIdentity, readOverlay, restoredValue, routingCandidate, storedLocally, sharedValue, settingDef as instanceSettingDef, settingRefusal, settingRows, settingText, undoSetting, valueAt, writeConfigSetting, writeRoutingSetting, type SettingAuthority, type SettingSource, type SettingDef, type SettingRow, type SettingValue, type UndoIdentity } from "./settings.ts";
 import { githubOriginRepository } from "./task-repository.ts";
 import { Bus } from "./bus.ts";
 import { attribute, deliveryTask, type TaskAttribution } from "./attribution.ts";
@@ -219,6 +221,8 @@ export interface HubConfig {
   batch_max: number;
   batch_ms: number;
   queue_cap: number;
+  /** #489 H3: accepted delivery policy, read at the next delivery operation without rewriting queued work. */
+  bus?: { max_attempts?: number; digest_max?: number; pull_budget_bytes?: number; notes_kept?: number; terminal_history_limit?: number };
   /** `native` (#258): the hub's own store in ~/.agenthub/memory, on with any project config; `short_ttl_days`: short-term lifetime after approval; `sync_interval_min`: machine sync while a remote is set (default 10, 0 off). */
   memory: { enabled: boolean; worker_url?: string; inject_tokens: number; brief_items: number; native?: boolean; short_ttl_days?: number; sync_interval_min?: number; suggest_edges?: boolean };
   roster: PeerRoster;
@@ -269,7 +273,8 @@ export interface HubConfig {
   /** Reviewer choice from recorded review outcomes, once a reviewer has `min_reviews` of an implementer (issue #35). */
   review: { adaptive: boolean; min_reviews: number; pool?: string[]; rerotate?: boolean; same_family?: "fallback" | "never" };
   /** After an unplanned stop, start Kimi, Pi and the local worker again with their recorded sessions (issue #37). */
-  recovery: { auto_resume_after_crash: boolean };
+  /** #489 H4: the five waits the upgrade coordinator reads from this project's config at the start of each wait; the daemon itself only validates and carries them. */
+  recovery: { auto_resume_after_crash: boolean; reconnect_wait_s?: number; unmanaged_reconnect_wait_s?: number; control_timeout_s?: number; shutdown_wait_s?: number; terminal_idle_wait_s?: number };
   /** Per peer, the hub-tool capabilities it has (issue #39); a peer not listed has all of them. */
   capabilities: Record<string, string[]>;
   /**
@@ -297,6 +302,7 @@ export const DEFAULT_CONFIG: HubConfig = {
   batch_max: 3,
   batch_ms: 15_000,
   queue_cap: 200,
+  bus: { max_attempts: BUS_MAX_ATTEMPTS_SETTING.defaultValue, digest_max: BUS_DIGEST_MAX_SETTING.defaultValue, pull_budget_bytes: BUS_PULL_BUDGET_BYTES_SETTING.defaultValue, notes_kept: BUS_NOTES_KEPT_SETTING.defaultValue, terminal_history_limit: BUS_TERMINAL_HISTORY_LIMIT_SETTING.defaultValue },
   memory: { enabled: true, inject_tokens: 2000, brief_items: 8 },
   roster: {},
   roles: DEFAULT_ROLES,
@@ -324,7 +330,7 @@ export const DEFAULT_CONFIG: HubConfig = {
   terminal: { open: [] },
   limits: DEFAULT_LIMITS,
   review: { adaptive: false, min_reviews: 5 },
-  recovery: { auto_resume_after_crash: false },
+  recovery: { auto_resume_after_crash: false, reconnect_wait_s: RECOVERY_RECONNECT_WAIT_SETTING.defaultValue, unmanaged_reconnect_wait_s: RECOVERY_UNMANAGED_RECONNECT_WAIT_SETTING.defaultValue, control_timeout_s: RECOVERY_CONTROL_TIMEOUT_SETTING.defaultValue, shutdown_wait_s: RECOVERY_SHUTDOWN_WAIT_SETTING.defaultValue, terminal_idle_wait_s: RECOVERY_TERMINAL_IDLE_WAIT_SETTING.defaultValue },
   capabilities: {},
   coordination: "advisory",
 };
@@ -339,7 +345,7 @@ const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 /** The shared project config, then the machine's own file, which overrides it block by block (issue #17). */
 const CONFIG_FILES = INSTANCE_CONFIG_FILES;
 export interface ConfigLayer { name: typeof CONFIG_FILES[number]; raw: Record<string, any> }
-const CONFIG_BLOCKS = ["action_policy", "memory", "roster", "roles", "catalog_roles", "pii", "data", "conductor", "budget", "context", "inference", "omniroute", ...NATIVE_CONFIG_BLOCKS, "approvals", "tasks", "task_sweep", "corpus", "checks", "snapshots", "research", "bench", "limits", "review", "recovery", "capabilities", "mlx", "permission_modes", "peers", "terminal", "pet"];
+const CONFIG_BLOCKS = ["action_policy", "memory", "roster", "roles", "catalog_roles", "pii", "data", "conductor", "budget", "context", "inference", "omniroute", ...NATIVE_CONFIG_BLOCKS, "approvals", "tasks", "task_sweep", "bus", "corpus", "checks", "snapshots", "research", "bench", "limits", "review", "recovery", "capabilities", "mlx", "permission_modes", "peers", "terminal", "pet"];
 
 /** Connection-time policy refresh reads role/feed fields only, never launches or machine-local configuration. */
 export function loadConductorPolicy(cwd: string, layers?: readonly ConfigLayer[], scope: Pick<ReturnType<typeof readInstanceConfig>, "instances" | "catalog"> = readInstanceConfig(cwd, layers)): { roles: Record<string, string[]>; conductor: HubConfig["conductor"]; planner?: string | string[]; notices?: string[] } {
@@ -532,6 +538,7 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
       notify: typeof file.approvals?.notify === "boolean" ? file.approvals.notify : process.platform === "darwin",
     },
     tasks: { ...DEFAULT_CONFIG.tasks, ...file.tasks, ...(file.tasks?.wip_limits !== undefined ? { wip_limits: planningWipLimits(file.tasks.wip_limits) } : {}) },
+    bus: { ...DEFAULT_CONFIG.bus, ...file.bus },
     task_sweep: taskSweepConfig(file.task_sweep),
     schedules: schedulesConfig(file.schedules),
     folder_triggers: foldersConfig(file.folder_triggers),
@@ -911,6 +918,8 @@ export async function startDaemon(opts: DaemonOptions) {
     const found = instanceSettingDef(key, declarations, adapterCatalog), stale = staleRosterKey(key);
     return typeof found === "string" && stale ? { key: `roster.${stale}`, group: "Roster", label: `${stale}: stale roster key (instance no longer declared)`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", stale] } : found;
   };
+  // #514b: undo resolves the managed checklist key, which is not a settings row, and every other key through the project-scoped lookup above (declared instances, the adapter catalog, a stale roster key).
+  const undoableDef = (key: unknown): SettingDef | string => key === LEARN_CHECKLIST.key ? LEARN_CHECKLIST : settingDef(key);
   const accountOf = (peer: string) => definitionOf(peer)?.budget?.account ?? peer;
   const accountMembers = (account: string) => SUPPORTED_PEERS.filter(peer => accountOf(peer) === account);
   let rosterChanging: string | undefined;
@@ -1172,7 +1181,8 @@ export async function startDaemon(opts: DaemonOptions) {
 
   // The hub's own model calls (digest condensation, task triage) are wired below, once the gateway client exists.
   let inference: Inference | undefined;
-  const journal = new DeliveryJournal({ file: join(opts.stateDir, "hub.db"), projectRoot: opts.cwd, projectId, instanceId, operationId: recoveryOperation });
+  const { terminalHistoryLimit, ...busReaders } = busOperationalReaders(() => config);
+  const journal = new DeliveryJournal({ file: join(opts.stateDir, "hub.db"), projectRoot: opts.cwd, projectId, instanceId, operationId: recoveryOperation, terminalHistoryLimit });
   // What the crash left in flight, per recipient: opening the journal just marked these needs_review.
   const lost = new Map<PeerId, JournalDelivery[]>();
   if (crashed) for (const d of journal.list()) if (d.state === "needs_review" && d.reason === "daemon stopped during delivery" && d.updatedAt >= startedAt) lost.set(d.peer, [...(lost.get(d.peer) ?? []), d]);
@@ -1292,7 +1302,7 @@ export async function startDaemon(opts: DaemonOptions) {
   const queuePolicy = () => queueBackpressurePolicy(config.tasks.queue_backpressure);
   let remotePending = (_room: string): readonly string[] => [];
   let remoteQueueChanged = () => {};
-  const bus: Bus = new Bus({ rostered: membershipAllowed, trackQueuePressure: () => { const policy = queuePolicy(); return policy.max_queued > 0 || policy.max_oldest_s > 0; }, deliveryHeld: peer => requestedPeerStops.has(peer) || rosterChanging === peer, journal, batchMax: config.batch_max, batchMs: config.batch_ms, queueCap: config.queue_cap, condense: (envs) => inference?.condense(envs) ?? Promise.resolve(envs), admit, relevant: (peer, env) => reviewOnlyPeer(peer) && !reviewOnlyItem(peer, env) ? `not for ${peer}: a review-only instance receives review requests only` : env.refs?.boundedCheck || env.refs?.supervision || env.refs?.backlog ? relevantNotice(peer, env) : staleOff() || relevantNotice(peer, env), silence,
+  const bus: Bus = new Bus({ rostered: membershipAllowed, ...busReaders, trackQueuePressure: () => { const policy = queuePolicy(); return policy.max_queued > 0 || policy.max_oldest_s > 0; }, deliveryHeld: peer => requestedPeerStops.has(peer) || rosterChanging === peer, journal, batchMax: config.batch_max, batchMs: config.batch_ms, queueCap: config.queue_cap, condense: (envs) => inference?.condense(envs) ?? Promise.resolve(envs), admit, relevant: (peer, env) => reviewOnlyPeer(peer) && !reviewOnlyItem(peer, env) ? `not for ${peer}: a review-only instance receives review requests only` : env.refs?.boundedCheck || env.refs?.supervision || env.refs?.backlog ? relevantNotice(peer, env) : staleOff() || relevantNotice(peer, env), silence,
     remotePending: room => remotePending(room),
     remotePrivate: (env): boolean => {
       const task = env.refs?.task;
@@ -3432,6 +3442,33 @@ export async function startDaemon(opts: DaemonOptions) {
         return JSON.stringify((await tasks.approveIntake(by, a.id)).map(task => tasks.publicView(task)));
       case "intake_discard":
         return JSON.stringify((await tasks.discardIntake(by, a.id)).map(task => tasks.publicView(task)));
+      // #514b: the person's verdict on a recurring-criterion candidate. Person only (Tasks refuses any other `by`, and the generic gate above already refuses every non-person caller, the configured
+      // conductor included: none of these is in CONDUCTOR_TASK_OPS). Accept writes ONE key, derived from the card's key line, through the settings writer.
+      case "learn_list":
+        return JSON.stringify(tasks.learnCandidates(by, { all: a.all === true }));
+      case "learn_reject":
+        return JSON.stringify(tasks.publicView(await tasks.learnClose(by, a.id, "rejected")));
+      case "learn_accept": {
+        // A card the person already accepted answers with a success that writes nothing: no config, no undo record, no event. A rejected or otherwise closed card falls through and is refused.
+        const decided = tasks.learnAccepted(by, a.id);
+        if (decided) return JSON.stringify({ card: tasks.publicView(board.get(decided.id)!), accepted: { profile: decided.profile, class: decided.class, criterion: decided.criterion, alreadyAccepted: true, file: ".agenthub/config.local.json" } });
+        const plan = tasks.learnAcceptPlan(by, a.id);
+        const stored = storedConfig();
+        if (!stored) throw new PreEffectToolRefusal("the config files do not load; fix them in your editor first: nothing was written");
+        const active = profileName(stored.profile);
+        if (plan.profile !== active) throw new PreEffectToolRefusal(`this card is for the ${plan.profile} profile and the project's profile is ${active}: nothing was written; reject the card, or switch profile first`);
+        // review_checklist replaces as a unit: extend the checklist the profile uses now (the person's, else the shipped one), never start from one line.
+        const current = resolveProfile(stored.profile, stored.profile_overrides).review_checklist ?? [];
+        const next = withChecklistLine(current, plan.line);
+        if ("refused" in next) throw new PreEffectToolRefusal(next.refused);
+        const already = next.list.length === current.length;
+        if (!already) {
+          const written = await settingsSet(LEARN_CHECKLIST.key, next.list, "terminal", undefined, undefined, `ahub learn accept #${plan.id}`, LEARN_CHECKLIST);
+          if (written.ok !== true) throw new PreEffectToolRefusal(String(written.error ?? "the checklist could not be written") + "; the candidate stays open");
+        }
+        const closed = await tasks.learnClose(by, a.id, "accepted");
+        return JSON.stringify({ card: tasks.publicView(closed), accepted: { profile: plan.profile, class: plan.class, criterion: plan.criterion, line: plan.line, tasks: plan.tasks, lines: next.list.length, alreadyPresent: already, file: ".agenthub/config.local.json", applies: "after a restart (profile contracts are bound at startup)", undo: already ? undefined : "ahub settings undo" } });
+      }
       case "review_brief": {
         const task = board.get(Number(a.id));
         return task ? tasks.briefText(task) || `task #${task.id} names no commit, or is private: no brief` : `no task #${a.id}`;
@@ -6475,13 +6512,17 @@ export async function startDaemon(opts: DaemonOptions) {
     if (typeof reason !== "string" || !reason.trim() || Buffer.byteLength(reason) > 400) throw new Error("setting reason must contain 1..400 UTF-8 bytes");
     return sanitize(reason.trim());
   };
-  async function settingsSet(key: unknown, raw: unknown, authority: SettingAuthority, confirm?: unknown, now?: unknown, rawReason?: unknown): Promise<Record<string, unknown>> {
+  /** `managed` (#514b) is the learn command's own definition: a function argument, never read from a request, so no other key or caller can reach the managed row. */
+  async function settingsSet(key: unknown, raw: unknown, authority: SettingAuthority, confirm?: unknown, now?: unknown, rawReason?: unknown, managed?: SettingDef): Promise<Record<string, unknown>> {
     checkOperational(authority);
     if (stopping || recoveryActive()) return { ok: false, error: "recovery or shutdown is holding settings" };
     let reason: string | undefined;
     try { reason = settingReason(rawReason); } catch (error) { return { ok: false, error: (error as Error).message }; }
     if(authority==="conductor" && reason && !tasks.publicMetadataText(reason))return {ok:false,error:"setting reason withheld by privacy policy"};
-    const input = settingInput(key, raw);
+    if (managed && (managed !== LEARN_CHECKLIST || authority !== "terminal")) return { ok: false, error: "a managed setting is written only by its own command, as the person" };
+    let input: ReturnType<typeof settingInput>;
+    if (managed) { try { input = { def: managed, value: checkSettingValue(managed, raw) }; } catch (error) { return { ok: false, error: (error as Error).message }; } }
+    else input = settingInput(key, raw);
     if ("error" in input) return { ok: false, error: input.error };
     const { def, value } = input;
     const refusal = settingRefusal(def, value, authority);
@@ -6520,11 +6561,13 @@ export async function startDaemon(opts: DaemonOptions) {
       const result = await reloadConfig(authority, def.path.join("."));
       if (result.ok !== true) return { ...result, saved: true };
       const to = settingScalar(valueAt(storedConfig(), def.path));
-      recordSetting(def.key, from, to, source, false, reason);
+      // A managed checklist is the person's own profile text: the event and the notice carry line counts, never the lines.
+      const shown = (v: SettingValue): SettingValue => managed ? (Array.isArray(v) ? `${v.length} line(s)` : v === null ? "(not set)" : v) : v;
+      recordSetting(def.key, shown(from), shown(to), source, false, reason);
       if (def.type === "roles") { prepareRoleSelection(def.path[1]!); event({ type: "role", peer: def.path[1]!, actor: "user", stage: "assigned", roles: selectedRoles(def.path[1]!, config.roles, roleAssignments, catalog).map(roleIdentity) }); }
       const timing = def.applies === "live" ? "in force now" : def.applies === "restart" ? "pending restart"
         : ["permission_modes", "catalog_roles", "peers"].includes(def.path[0]!) ? "applies at the peer's next start" : def.key === "coordination" ? "applies to new tasks" : "applies at next use";
-      return { ok: true, text: `${def.key}: ${settingText(to)} (${timing})` };
+      return { ok: true, text: `${def.key}: ${settingText(shown(to))} (${timing})` };
     } catch (error) {
       return { ok: false, error: sanitize((error as Error).message), ...(error instanceof OperationalAuthorityError ? { authorityRefused: true, authorityScope: error.scope } : {}), ...(saved ? { saved: true } : {}) };
     }
@@ -6541,8 +6584,9 @@ export async function startDaemon(opts: DaemonOptions) {
       if (typeof expectedKey !== "string" || !expectedKey || typeof expectedDigest !== "string" || !/^[a-f0-9]{64}$/.test(expectedDigest)) return { ok: false, error: "invalid undo preview identity; preview again; nothing was undone" };
       if (!identity || identity.key !== expectedKey || identity.undoDigest !== expectedDigest) return { ok: false, error: "undo record changed since preview; preview again; nothing was undone" };
     }
-    const def = settingDef(identity?.key);
+    const def = undoableDef(identity?.key);
     if (typeof def === "string" || !identity) return { ok: false, error: "nothing to undo" };
+    if (def.managed && authority !== "terminal") return { ok: false, error: `${def.key} was written by ahub learn accept: put it back with ahub settings undo in a terminal` };
     if (def.group === "Roster") return changeRosterSetting(def, null, settingSource(authority), confirm, now === true, true, authority, reason, identity);
     if (rosterChanging) return { ok: false, error: `roster change for ${rosterChanging} is in progress` };
     const read = (): SettingValue => def.store === "routing" ? routingValue(activeRouting(), def) : settingScalar(valueAt(storedConfig(), def.path));
@@ -6553,9 +6597,11 @@ export async function startDaemon(opts: DaemonOptions) {
       undoSetting(opts.cwd, opts.stateDir, scratch => configWriteCheck(scratch, authority, def.path.join(".")), (_routing, overlay) => routingWriteCheck(authority, overlay, def.key), identity);
       const result = await reloadConfig(authority, def.store === "routing" ? def.key : def.path.join("."));
       if (result.ok !== true) return { ...result, saved: true };
-      recordSetting(def.key, from, read(), settingSource(authority), true, reason);
+      // A managed checklist is the person's own profile text: the event, the notice and the reply carry its line count, never the lines (the same form as the write).
+      const shown = (v: SettingValue): SettingValue => def.managed ? (Array.isArray(v) ? `${v.length} line(s)` : v === null ? "(not set)" : v) : v;
+      recordSetting(def.key, shown(from), shown(read()), settingSource(authority), true, reason);
       if (def.type === "roles") { prepareRoleSelection(def.path[1]!); event({ type: "role", peer: def.path[1]!, actor: "user", stage: "assigned", roles: selectedRoles(def.path[1]!, config.roles, roleAssignments, catalog).map(roleIdentity) }); }
-      return { ok: true, text: `${def.key}: put back to ${settingText(read())}` };
+      return { ok: true, text: `${def.key}: put back to ${settingText(shown(read()))}` };
     } catch (error) {
       return { ok: false, error: (error as Error).message };
     }
@@ -6594,8 +6640,9 @@ export async function startDaemon(opts: DaemonOptions) {
   }
 
   function settingsUndoPreview(): Record<string, unknown> {
-    const identity = pendingUndoIdentity(opts.stateDir), def = settingDef(identity?.key);
+    const identity = pendingUndoIdentity(opts.stateDir), def = undoableDef(identity?.key);
     if (typeof def === "string" || !identity) return { ok: false, error: "nothing to undo" };
+    if (def.managed) return { ok: true, ...identity, lines: [`Undo ${def.key}: put back the previous machine-local file (the review checklist ahub learn accept changed; its lines are not shown here)`, "The saved previous machine-local file is revalidated before writing."] };
     const value = restoredValue(opts.cwd, opts.stateDir, def), preview = settingsPreview(def.key, value ?? null);
     if (pendingUndoIdentity(opts.stateDir)?.undoDigest !== identity.undoDigest) return { ok: false, error: "undo record changed during preview; preview again" };
     return { ...preview, ...identity, lines: [`Undo ${def.key}: put back ${settingText(value)}`, ...(Array.isArray(preview.lines) ? preview.lines : []), "The saved previous machine-local file is revalidated before writing."] };

package/src/hub/delivery-journal.ts

@@ -20,8 +20,8 @@ export type JournalDeliveryState =
   | "discarded";
 export type JournalResolution = "completed" | "retry" | "discard";
 export const MAX_ENVELOPE_BODY = 1_000_000;
+export const TERMINAL_CAP = 2048;
 const SCHEMA_VERSION = 1,
-  TERMINAL_CAP = 2048,
   MAX_ROWS = 100_000,
   MAX_JSON = 20 * 1024 * 1024;
 const STATES = new Set<JournalDeliveryState>([
@@ -56,6 +56,8 @@ export interface DeliveryJournalOptions {
   projectId: string;
   instanceId: string;
   operationId?: string;
+  /** Accepted live history target; only terminal mutations apply it, other pruning keeps the legacy cap. */
+  terminalHistoryLimit?: () => number;
 }
 export interface JournalSnapshot {
   schemaVersion: number;
@@ -271,13 +273,16 @@ export class DeliveryJournal {
   private closed = false;
   private queueMetadataTracking = false;
   private queueMetadataInvalidated = false;
+  private pruningDeferred = 0;
   private readonly operationId?: string;
+  private readonly terminalHistoryLimit?: () => number;
   constructor(options: DeliveryJournalOptions) {
     this.file = options.file;
     this.projectRoot = text(options.projectRoot, "projectRoot", 4096);
     this.projectId = text(options.projectId, "projectId", 256);
     this.instanceId = text(options.instanceId, "instanceId", 256);
     this.operationId = options.operationId;
+    this.terminalHistoryLimit = options.terminalHistoryLimit;
     mkdirSync(dirname(options.file), { recursive: true, mode: 0o700 });
     this.db = new Database(options.file, { create: true });
     this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
@@ -704,53 +709,56 @@ export class DeliveryJournal {
       updatedAt: delivery.createdAt,
     });
     return this.queueMetadataTransaction(trackQueuePressure, () => {
-      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}`);
-        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!) };
+      // Grouped parents are not linked until the handoff INSERT.
+      return this.withPruningDeferred(() => {
+        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}`);
+          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();
-      this.db
-        .query(
-          "UPDATE delivery_meta SET bus_snapshot = ?, manual_paused = ? WHERE project_id = ?",
-        )
-        .run(
-          JSON.stringify(bus),
-          JSON.stringify(bus.manualPaused ?? []),
-          this.projectId,
-        );
-      this.writeQueueMetadata(bus, revision, trackQueuePressure);
-      this.db
-        .query(
-          "INSERT INTO deliveries (id, project_id, peer, state, revision, created_at, updated_at, originals, out_json, reason, attempt, previous_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-        )
-        .run(
-          delivery.id,
-          this.projectId,
-          delivery.peer,
-          delivery.state,
-          revision,
-          delivery.createdAt,
-          now,
-          JSON.stringify(delivery.originals),
-          JSON.stringify(delivery.out),
-          delivery.reason ?? null,
-          delivery.attempt ?? null,
-          delivery.previousId ?? null,
-        );
-      this.harden();
-      return { ...delivery, revision, updatedAt: now };
+        const revision = this.bump();
+        const now = Date.now();
+        this.db
+          .query(
+            "UPDATE delivery_meta SET bus_snapshot = ?, manual_paused = ? WHERE project_id = ?",
+          )
+          .run(
+            JSON.stringify(bus),
+            JSON.stringify(bus.manualPaused ?? []),
+            this.projectId,
+          );
+        this.writeQueueMetadata(bus, revision, trackQueuePressure);
+        this.db
+          .query(
+            "INSERT INTO deliveries (id, project_id, peer, state, revision, created_at, updated_at, originals, out_json, reason, attempt, previous_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+          )
+          .run(
+            delivery.id,
+            this.projectId,
+            delivery.peer,
+            delivery.state,
+            revision,
+            delivery.createdAt,
+            now,
+            JSON.stringify(delivery.originals),
+            JSON.stringify(delivery.out),
+            delivery.reason ?? null,
+            delivery.attempt ?? null,
+            delivery.previousId ?? null,
+          );
+        this.harden();
+        return { ...delivery, revision, updatedAt: now };
+      });
     });
   }
   createDelivery(
@@ -785,7 +793,7 @@ export class DeliveryJournal {
           input.attempt ?? null,
           input.previousId ?? null,
         );
-      this.pruneTerminal();
+      this.pruneTerminal(input.state, input.id);
       return { ...input, revision, updatedAt };
     })();
   }
@@ -802,9 +810,14 @@ export class DeliveryJournal {
     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!);
+      const completed = this.withPruningDeferred(() => {
+        const result = 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 result;
+      });
+      // Proof is now durable in this transaction, and the return receipt is captured.
+      this.pruneTerminal("completed", "");
       return completed;
     })();
   }
@@ -834,7 +847,7 @@ export class DeliveryJournal {
           "UPDATE deliveries SET state = ?, revision = ?, updated_at = ?, reason = ? WHERE id = ? AND project_id = ?",
         )
         .run(state, revision, Date.now(), reason ?? null, id, this.projectId);
-      this.pruneTerminal();
+      this.pruneTerminal(state, id);
       return this.get(id)!;
     })();
   }
@@ -1023,7 +1036,7 @@ export class DeliveryJournal {
           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();
+      this.pruneTerminal(result.state, result.id);
       return result;
     })();
   }
@@ -1031,7 +1044,15 @@ export class DeliveryJournal {
     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 {
+  private withPruningDeferred<T>(body: () => T): T {
+    this.pruningDeferred++;
+    try { return body(); } finally { this.pruningDeferred--; }
+  }
+  private pruneTerminal(state: JournalDeliveryState, currentId: string): void {
+    if (this.pruningDeferred) return;
+    const terminal = state === "completed" || state === "discarded" || state === "failed";
+    const terminalCap = terminal ? this.terminalHistoryLimit?.() ?? TERMINAL_CAP : TERMINAL_CAP;
+    // Never delete the receipt this mutation/resolve is still using, at any target.
     const count = Number(
       (
         this.db
@@ -1041,12 +1062,12 @@ export class DeliveryJournal {
           .get(this.projectId) as { n: number }
       ).n,
     );
-    if (count <= TERMINAL_CAP) return;
+    if (count <= terminalCap) return;
     this.db
       .query(
-        "DELETE FROM deliveries WHERE id IN (SELECT d.id FROM deliveries d WHERE d.project_id = ? AND d.state IN ('completed','discarded','failed') AND NOT EXISTS (SELECT 1 FROM deliveries c WHERE c.project_id = d.project_id AND c.previous_id = d.id) ORDER BY d.updated_at, d.id LIMIT ?)",
+        "DELETE FROM deliveries WHERE id IN (SELECT d.id FROM deliveries d WHERE d.project_id = ? AND d.state IN ('completed','discarded','failed') AND d.id != ? AND NOT EXISTS (SELECT 1 FROM deliveries c WHERE c.project_id = d.project_id AND c.previous_id = d.id) ORDER BY d.updated_at, d.id LIMIT ?)",
       )
-      .run(this.projectId, count - TERMINAL_CAP);
+      .run(this.projectId, currentId, count - terminalCap);
   }
   importSnapshot(snapshot: JournalSnapshot, operationId: string, trackQueuePressure = false): boolean {
     this.ensureOpen();

package/src/hub/learning.ts

@@ -78,8 +78,40 @@ export function candidateCard(group: CriterionGroup, windowDays: number, workUni
     detail: [
       criterionKey(group),
       `Criterion ${group.criterion} was named unmet ${group.count} time(s) on ${group.tasks.length} ${group.profile}/${group.class} task(s) in the last ${windowDays} days (${workUnits} separate piece(s) of work): ${group.tasks.slice(0, 8).map(id => `#${id}`).join(", ")}.`,
-      "This is a candidate for a person to review. Nothing was applied, and nothing in the hub writes it. profile_overrides is not machine-local: it is read from the shared .agenthub/config.json (tracked, so a change there reaches every checkout) and from .agenthub/config.local.json (this machine only), and the layers merge. Put it where you want it to apply. If you agree, add the line below to profile_overrides.review_checklist; that list replaces as a unit, so add it to your current checklist, do not paste it over it:",
+      "This is a candidate for a person to review. Nothing was applied: the hub writes it only when the person runs ahub learn accept <id> (to .agenthub/config.local.json, this machine only, added to your current checklist; ahub settings undo puts it back), or ahub learn reject <id> to close this card. By hand: profile_overrides is not machine-local: it is read from the shared .agenthub/config.json (tracked, so a change there reaches every checkout) and from .agenthub/config.local.json (this machine only), and the layers merge. Put it where you want it to apply. If you agree, add the line below to profile_overrides.review_checklist; that list replaces as a unit, so add it to your current checklist, do not paste it over it:",
       JSON.stringify(diff, null, 2),
     ].join("\n"),
   };
 }
+
+/** The cap `resolveProfile` puts on a review checklist (`profiles.ts`): the learn writer never builds a list the loader would refuse. */
+export const CHECKLIST_MAX_LINES = 16;
+const PROFILE = /^[a-z][a-z0-9_-]{0,31}$/, CLASS = /^[a-z][a-z0-9_]{0,47}$/, CRITERION = /^[A-Za-z][A-Za-z0-9-]{0,47}$/;
+
+/**
+ * What `ahub learn accept` may act on (#514b), read from a card the hub itself filed. ONLY the key line is read: `Criterion candidate key: <profile>:<class>:<criterion>`, as the
+ * FIRST line of the detail, on a backlog card the hub filed in the `plan` class. The three parts are re-checked against the shapes the loaders accept, and the line to write is
+ * REGENERATED from them by `overridesDiff` with a count the caller recomputes from the board, so no text of the card (the diff it prints, a count it states, a title) is ever
+ * parsed as a value or written. A card that does not match is refused with a reason, never half read.
+ */
+export type CandidateCard = { profile: string; class: string; criterion: string } | { refused: string };
+export function parseCandidateCard(task: Pick<Task, "class" | "detail" | "history" | "title">): CandidateCard {
+  if (task.class !== "plan" || task.history[0]?.by !== "hub") return { refused: "not a candidate the hub filed" };
+  const first = task.detail.split("\n", 1)[0] ?? "";
+  const match = /^Criterion candidate key: ([^:\s]+):([^:\s]+):([^:\s]+)$/.exec(first);
+  if (!match) return { refused: "not a recurring-criterion candidate (no key line first)" };
+  const [, profile, cls, criterion] = match as unknown as [string, string, string, string];
+  if (!PROFILE.test(profile) || !CLASS.test(cls) || !CRITERION.test(criterion)) return { refused: "the key line names a profile, class or criterion the loaders would not accept" };
+  if (task.title !== `Review checklist candidate for ${profile}/${cls} criterion ${criterion}`) return { refused: "the card's title does not match its key line" };
+  return { profile, class: cls, criterion };
+}
+
+/**
+ * The checklist to store after accepting: the person's CURRENT checklist (what the profile uses now) with the one regenerated line added, because `review_checklist` replaces as a
+ * unit. The line is skipped when it is already there, so a repeated accept writes nothing new. Refused, not trimmed, when the list would pass `CHECKLIST_MAX_LINES`.
+ */
+export function withChecklistLine(current: readonly string[], line: string): { list: string[] } | { refused: string } {
+  if (current.includes(line)) return { list: [...current] };
+  if (current.length + 1 > CHECKLIST_MAX_LINES) return { refused: `the checklist already has ${current.length} lines and the profile allows ${CHECKLIST_MAX_LINES}; remove one in .agenthub/config.local.json first` };
+  return { list: [...current, line] };
+}