@staix/agent-hub 0.20.0 → 0.22.0

package/src/hub/research.ts

@@ -58,8 +58,8 @@ export interface TaskRecord {
   /** #258 AC11: task briefs handed over for it, and how many of them carried a hub-memory fail note; absent without briefs. */
   briefs?: { delivered: number; withFail: number };
 }
-/** A person's later verdict on one task record: `createdAt` binds it to that task, not a later one with the same id. */
-export interface LabelRecord { schema: typeof RESEARCH_SCHEMA; kind: "label"; project: string; task: number; createdAt: string; label: Label; at: string }
+/** A person's later verdict on one task record: `createdAt` binds it to that task, not a later one with the same id. `by`: the agent that labelled its own task (#933); absent for the person. */
+export interface LabelRecord { schema: typeof RESEARCH_SCHEMA; kind: "label"; project: string; task: number; createdAt: string; label: Label; at: string; by?: string }
 export type ResearchRecord = TaskRecord | LabelRecord;
 
 /** The store name for a project: a hash of its id, never its path. */
@@ -293,15 +293,26 @@ export function formatResearch(r: ResearchReport): string[] {
   return [head, row("all approved tasks", r.overall), ...section("by class", r.byClass), ...section("by owner", r.byOwner), ...section("by model", r.byModel), ...section("by project", r.byProject), ...(Object.keys(r.byMemoryBrief).some((k) => k !== "no brief recorded") ? section("by memory brief", r.byMemoryBrief) : [])];
 }
 
-/** Each approved task once, its last record, and every task's latest label: what both reports count. */
-function latestRecords(records: ResearchRecord[], since: number): { all: TaskRecord[]; labels: Map<string, Label> } {
-  const latest = new Map<string, TaskRecord>(), labels = new Map<string, Label>();
+/**
+ * The label each record counts with: the person's latest label, whatever came after it; an agent's (#933, `by` set) only when the person
+ * never labelled that record, the latest of them then. An agent's verdict on its own task never replaces the person's.
+ */
+function effectiveLabels(records: readonly ResearchRecord[]): Map<string, LabelRecord> {
+  const labels = new Map<string, LabelRecord>();
   for (const r of records) {
-    const key = recordKey(r);
-    if (r.kind === "label") { labels.set(key, r.label); continue; }
-    if (Date.parse(r.approvedAt) >= since) latest.set(key, r);
+    if (r.kind !== "label") continue;
+    const key = recordKey(r), held = labels.get(key);
+    if (r.by === undefined || held === undefined || held.by !== undefined) labels.set(key, r);
   }
-  return { all: [...latest.values()], labels };
+  return labels;
+}
+const labelValues = (labels: Map<string, LabelRecord>): Map<string, Label> => new Map([...labels].map(([key, r]) => [key, r.label]));
+
+/** Each approved task once, its last record, and every task's effective label: what both reports count. */
+function latestRecords(records: ResearchRecord[], since: number): { all: TaskRecord[]; labels: Map<string, Label> } {
+  const latest = new Map<string, TaskRecord>();
+  for (const r of records) if (r.kind === "task" && Date.parse(r.approvedAt) >= since) latest.set(recordKey(r), r);
+  return { all: [...latest.values()], labels: labelValues(effectiveLabels(records)) };
 }
 
 /** The peers that worked on a task: every peer with an attributed event, else (older records) owners, reviewer and token peers. */
@@ -364,15 +375,14 @@ export function formatAddons(rows: AddonComparison[]): string[] {
 
 export const CSV_COLUMNS = ["project", "task", "class", "pii", "outcome", "createdAt", "startedAt", "approvedAt", "wallMs", "activeMs", "owners",
   "reviewer", "reviewRounds", "changesRequested", "checkPassed", "checkFailed", "dones", "reassignments", "firstPass", "stuck", "overlaps", "conflicts",
-  "testsPass", "testsFail", "tokens", "turns", "filesChanged", "models", "label", "writerVersion", "writerSource"] as const;
-/** Task records as CSV with a header row, one row per record, each with the task's latest label; JSONL has every field. */
+  "testsPass", "testsFail", "tokens", "turns", "filesChanged", "models", "label", "labelBy", "writerVersion", "writerSource"] as const;
+/** Task records as CSV with a header row, one row per record, each with its effective label and who gave it (empty: the person); JSONL has every field. */
 export function toCsv(records: ResearchRecord[]): string {
-  const labels = new Map<string, Label>();
-  for (const r of records) if (r.kind === "label") labels.set(recordKey(r), r.label);
+  const labels = effectiveLabels(records);
   const cell = (v: unknown) => { const s = v === null || v === undefined ? "" : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
   const rows = records.filter((r): r is TaskRecord => r.kind === "task").map((r) => [r.project, r.task, r.class, r.pii, r.outcome, r.createdAt, r.startedAt,
     r.approvedAt, r.wallMs, r.activeMs, r.owners.join(" "), r.reviewer, r.reviewRounds, r.changesRequested, r.checkPassed, r.checkFailed, r.dones,
     r.reassignments, r.firstPass, r.stuck, r.overlaps, r.conflicts, r.tests.pass, r.tests.fail, r.tokens.total, r.turns, r.filesChanged, r.models.join(" "),
-    labels.get(recordKey(r)) ?? "", r.writer.version, r.writer.source].map(cell).join(","));
+    labels.get(recordKey(r))?.label ?? "", labels.get(recordKey(r))?.by ?? "", r.writer.version, r.writer.source].map(cell).join(","));
   return [CSV_COLUMNS.join(","), ...rows].join("\n") + "\n";
 }

package/src/hub/restart.ts

@@ -7,6 +7,7 @@ import { MAX_HOP } from "./envelope.ts";
 import { validateJournalSnapshot } from "./delivery-journal.ts";
 import { atomicPrivateJSON } from "./recovery-store.ts";
 import { RecoveryDeferredHubError, validateDeferredHub } from "./deferred-hub.ts";
+import { validExternalInstanceBinding, type ExternalInstanceBinding } from "./external-instance.ts";
 
 export const RESTART_SCHEMA_VERSION = 1;
 
@@ -24,6 +25,8 @@ export interface RestartPeerSnapshot {
    * cannot be resumed and a fresh session is accepted instead. Absent in snapshots written
    * before this flag; those are re-derived from disk (#64). */
   sessionPersisted?: boolean;
+  /** Retained stable identity for an explicitly stopped module instance; never authorizes automatic resume. */
+  externalInstance?: ExternalInstanceBinding;
 }
 
 export interface RestartSnapshot {
@@ -41,6 +44,8 @@ export interface RestartSnapshot {
     manualPaused: PeerId[];
     boardDigest: string;
     budgetDigest: string;
+    /** Whole captured binding set; portable identities are covered alongside queue/board integrity. */
+    externalBindingsDigest?: string;
   };
 }
 
@@ -87,7 +92,9 @@ export function readRestartSnapshot(stateDir: string, expected: RestartReadExpec
     }, occupied);
   } catch (error) { if (error instanceof RecoveryDeferredHubError) throw error; return undefined; }
   if (!Array.isArray(s.manualPaused) || !s.manualPaused.every((id) => typeof id === "string") || !Array.isArray(s.peers) || !s.peers.every((peer) => peer && typeof peer === "object" && typeof peer.id === "string" && ["idle", "busy", "paused", "offline"].includes(peer.state as string) && Array.isArray(peer.queueIds) && peer.queueIds.every((id) => typeof id === "string"))) return undefined;
+  if (s.peers.some(peer => Object.hasOwn(peer, "externalInstance") && (peer.state !== "offline" || !validExternalInstanceBinding(peer.externalInstance, expected.projectRoot, peer.id)))) return undefined;
   if (s.integrity !== undefined && (!s.integrity || typeof s.integrity !== "object" || typeof s.integrity.boardDigest !== "string" || typeof s.integrity.budgetDigest !== "string" || !Array.isArray(s.integrity.manualPaused) || !s.integrity.manualPaused.every((id) => typeof id === "string") || !s.integrity.queues || typeof s.integrity.queues !== "object" || !Object.values(s.integrity.queues).every((ids) => Array.isArray(ids) && ids.every((id) => typeof id === "string")))) return undefined;
+  if (s.integrity && Object.hasOwn(s.integrity, "externalBindingsDigest") && (typeof s.integrity.externalBindingsDigest !== "string" || !/^[a-f0-9]{64}$/.test(s.integrity.externalBindingsDigest))) return undefined;
   if (bus.journal !== undefined) { try { validateJournalSnapshot(bus.journal); } catch { return undefined; } }
   return s as RestartSnapshot;
 }

package/src/hub/routing.ts

@@ -1,3 +1,5 @@
+import { contextHeadroom, type ContextAdmission } from "./context-window.ts";
+import { queueBackpressure, type QueueBackpressureCode, type QueueBackpressurePolicy, type QueuePressure } from "./queue-backpressure.ts";
 import { selectReviewerPool, type ReviewerPoolSelection } from "./reviewer-pool.ts";
 import { ADAPTERS, definitionOf, kindOf, familyOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { readFileSync, statSync } from "node:fs";
@@ -119,6 +121,17 @@ export interface InstanceRoutingOptions {
   instances?: Readonly<Record<string, { kind: string }>>;
   wip?: Record<string, number>;
   load?: Record<string, number>;
+  /** Separate from WIP and sibling load: bounded pending delivery metadata for new automatic offers. */
+  queues?: Readonly<Record<string, QueuePressure>>;
+  queueBackpressure?: QueueBackpressurePolicy;
+  /** Host-only explicit person/conductor nomination; a name or reservation alone grants no bypass. */
+  queueOverride?: "owner" | "reviewer" | "both";
+  /** Fresh native session evidence supplied by the host; never read telemetry inside assign(). */
+  contextAdmission?: ContextAdmission;
+  /** Host-authorized explicit nomination or self-claim, never inferred from namedOwner or a reservation. */
+  contextOverride?: boolean;
+  /** Host-proven person reservation: queue pressure holds this exact target instead of rerouting it. No bypass is granted. */
+  queueReservedHold?: PeerId;
   /** Positive host verification of the live extra runtime's noncanonical execution root. */
   ownerIsolation?: Readonly<Record<string, boolean>>;
 }
@@ -297,7 +310,7 @@ export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, rou
 /** A peer's entry in a peer-indexed map: own keys only, so a peer named `constructor` is never an inherited Object member. */
 export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer: string): T | undefined => (map && Object.hasOwn(map, peer) ? map[peer] : undefined);
 
-export type RoutingRefusalCode = "instance" | "family" | "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
+export type RoutingRefusalCode = QueueBackpressureCode | "context-headroom" | "instance" | "family" | "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
 export interface RoutingRefusal { peer: PeerId; role: "owner" | "reviewer"; code: RoutingRefusalCode; reason: string }
 export interface Assignment {
   reviewSelection?: ReviewerPoolSelection;
@@ -333,6 +346,9 @@ export function ownerRoleOfClass(cls: TaskClass): "planner" | "implementer" | "r
 /** Why a planner was chosen: the person named it, rotation reached it, the task's recorded planner is kept, or there is none (PII, no holder). */
 export type PlannerReason = "rotation" | "named" | "kept" | "none";
 
+/** The remote namespace has no local task, reviewer or planner authority, even for malformed remote ids. */
+export function isRemotePeerId(peer: unknown): boolean { return typeof peer === "string" && peer.includes("@"); }
+
 /**
  * I-2 (#525-3): the peers that implemented a task, read from its own history: any peer with an `accepted` or `done` entry. A reviewer is
  * never one of them, so a multi-role holder (implementer and reviewer) never reviews a change it made, even after the task changed hands.
@@ -367,10 +383,11 @@ export interface PlannerWalk { planner?: PeerId; reason: PlannerReason; walk: {
  *   holder, availability never renumbers it (the #519 seed rule). When all are skipped, the seed holder is taken, "rotation (none available)".
  */
 export function plannerWalk(input: PlannerWalkInput): PlannerWalk {
-  const holders = [...new Set(input.planners)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const holders = [...new Set(input.planners)].filter(peer => !isRemotePeerId(peer)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   const walk: { peer: PeerId; note: string }[] = [];
   const finish = (reason: PlannerReason, planner: PeerId | undefined, detail: string): PlannerWalk => ({ ...(planner ? { planner } : {}), reason, walk, line: planner ? `planner: ${planner} (${detail})` : `planner: none (${detail})` });
   if (input.pii) return finish("none", undefined, "pii: planning stays with the person");
+  if (isRemotePeerId(input.named)) return finish("none", undefined, "remote peers cannot hold local roles");
   if (!holders.length) return finish("none", undefined, "no planner holder");
   if (input.named !== undefined) {
     if (!holders.includes(input.named)) { walk.push({ peer: input.named, note: "skipped, not a planner holder" }); return finish("none", undefined, `named ${input.named} is not a planner holder`); }
@@ -463,6 +480,7 @@ export function assign(
   const former = implementers(task.history);
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
     const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
+    if (isRemotePeerId(peer)) return deny("policy", "remote peers cannot hold local roles");
     const ceiling = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.allowedRoles;
     const requiredRole = role === "reviewer" ? "reviewer" : ownerRoleOfClass(task.class);
     if (ceiling && !ceiling.includes(requiredRole)) return deny("policy", "adapter role ceiling excludes this assignment");
@@ -498,10 +516,20 @@ export function assign(
       if (routing.signals.long_context_tokens > limit) return deny("policy", `${nativeRouting.backendLabel} ${backend} capability limit ${limit} tokens`);
     }
     if (nativeRouting?.longContext === "skip-owner" && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return deny("policy", "long_context: skip local");
-    // I-2 (#525-3): a peer that implemented this task never reviews it, whoever holds it now, a named reviewer included. It is the LAST check,
-    // so it only ever removes a candidate that was otherwise eligible: a former implementer that is offline, paused, failing or off roster is
-    // refused for that real reason and leaves the outcome exactly as it was before I-2 (a task with no other reviewer still approves directly).
+    // I-2 (#525-3) is the last capability/independence gate, before queue-capacity admission. A former implementer never reviews its task,
+    // including a named reviewer. Earlier offline, paused, failing and roster refusals retain their existing reason and outcome.
     if (role === "reviewer" && former.has(peer)) return deny("policy", "implemented this task");
+    if (role === "owner" && requiredRole !== "reviewer" && opts.contextAdmission) {
+      const decision = contextHeadroom(opts.contextAdmission.policy, adapter?.budget?.context ? peerEntry(opts.contextAdmission.peers, peer) : undefined, opts.now ?? NaN);
+      if (decision) {
+        trace.push(`  owner context ${peer}: ${decision.note}${opts.contextOverride ? "; explicit override" : ""}`);
+        if (decision.blocked && !opts.contextOverride) return deny("context-headroom", decision.note);
+      }
+    }
+    if (opts.queueOverride !== role && opts.queueOverride !== "both") {
+      const pressure = queueBackpressure(peer, opts.queueBackpressure, peerEntry(opts.queues, peer), opts.now ?? NaN);
+      if (pressure) return deny(pressure.code, pressure.reason);
+    }
     return undefined;
   };
   /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
@@ -556,12 +584,15 @@ export function assign(
     return ranked.find((p) => states[p] === "idle") ?? ranked[0];
   };
 
-  // The PII constraint, capability limits, exclusions and peer states still apply: when they pass it over, routing proceeds.
+  // Safety/state refusals still permit the existing reservation fallback. Queue pressure holds a host-proven person reservation instead.
   const unreserved = reserved ? blocked(reserved, "owner") : undefined;
-  if (reserved) trace.push(`reserved owner ${reserved}: ${unreserved ? `not honored, ${unreserved}; routing proceeds` : "honored"}`);
+  const reservedRefusal = reserved ? refusals.get(`owner:${reserved}`) : undefined;
+  const queueReservedHeld = reserved === opts.queueReservedHold && reservedRefusal !== undefined
+    && ["queue-count", "queue-age", "queue-age-unknown"].includes(reservedRefusal.code);
+  if (reserved) trace.push(`reserved owner ${reserved}: ${queueReservedHeld ? `held, ${unreserved}; reservation retained` : unreserved ? `not honored, ${unreserved}; routing proceeds` : "honored"}`);
   // Never the task's current owner by default: a decline or an escalation has to reach the next peer in the list.
   const automaticOwner = !(reserved && !unreserved) && opts.candidates === undefined && !(instanceMode && opts.namedOwner !== undefined);
-  const wanted = reserved && !unreserved ? [reserved] : opts.candidates ?? (instanceMode && opts.namedOwner !== undefined ? [opts.namedOwner] : expandClassPeers(policy?.peers ?? [], states, opts));
+  const wanted = queueReservedHeld ? [] : reserved && !unreserved ? [reserved] : opts.candidates ?? (instanceMode && opts.namedOwner !== undefined ? [opts.namedOwner] : expandClassPeers(policy?.peers ?? [], states, opts));
   const owner = pick(wanted, "owner", undefined, automaticOwner);
   trace.push(owner ? `owner: ${owner}` : "owner: none available, task stays proposed (ahub task assign <id> <peer>)");
   const ownerHold = owner ? peerEntry(opts.held, owner) : undefined;
@@ -680,6 +711,12 @@ export function assign(
         reviewBlocked = true;
         trace.push("  every eligible reviewer implemented this task: the person reviews");
       }
+      // Queue pressure holds a new review offer; it must never turn review exhaustion into direct approval.
+      if (!reviewer && [...refusals.values()].some(row => row.role === "reviewer" && (row.code === "queue-count" || row.code === "queue-age" || row.code === "queue-age-unknown"))) {
+        reviewer = "user";
+        reviewBlocked = true;
+        trace.push("  reviewer queue backpressure: automatic review held; the person may override");
+      }
       trace.push(reviewer ? `reviewer: ${reviewer}` : "reviewer: none, done will approve directly");
       const reviewerHold = reviewer ? peerEntry(opts.held, reviewer) : undefined;
       if (reviewerHold) trace.push(`  hold: ${reviewer}'s queue is held: ${reviewerHold} (it receives the review once the hold is resolved)`);
@@ -719,6 +756,10 @@ export interface SplitInput {
   /** Other open work each peer has: a busy owner does not start from orientation plus two whole units. */
   backlog: Record<PeerId, number>;
   available: Record<PeerId, boolean>;
+  /** #489 H2: `tasks.split_min_observations`; absent is `SPLIT_MIN`. */
+  minObservations?: number;
+  /** #489 H2: `tasks.split_max_failure_share`; absent is `SPLIT_FAILURE_SHARE`. */
+  maxFailureShare?: number;
 }
 
 export interface SplitPrediction {
@@ -733,7 +774,7 @@ export interface SplitPrediction {
 
 /** Observations a peer needs, and the share of failures a history may hold, before a prediction is made. */
 export const SPLIT_MIN = 5;
-const SPLIT_FAILURE_SHARE = 0.3;
+export const SPLIT_FAILURE_SHARE = 0.3;
 
 /**
  * Shadow split prediction (issue #109): never changes assignment. For two similar units of overlapping work, a split
@@ -744,6 +785,8 @@ const SPLIT_FAILURE_SHARE = 0.3;
  * comparable. A difference under a tenth of the single time is inconclusive.
  */
 export function predictSplit(input: SplitInput): SplitPrediction {
+  // #489 H2: `tasks.split_min_observations` and `tasks.split_max_failure_share`; absent, the constants above.
+  const minObservations = input.minObservations ?? SPLIT_MIN, maxFailureShare = input.maxFailureShare ?? SPLIT_FAILURE_SHARE;
   const trace: string[] = ["shadow split prediction (it never changes assignment):"];
   const unknown = (why: string): SplitPrediction => ({ verdict: "unknown", trace: [...trace, `  unknown: ${why}`] });
   const [a, b] = input.peers;
@@ -767,8 +810,8 @@ export function predictSplit(input: SplitInput): SplitPrediction {
     const all = input.observations[p] ?? [];
     const failed = all.filter((o) => o.outcome !== "approved").length;
     const ok = all.filter((o): o is Required<SplitObservation> => o.outcome === "approved" && o.orient !== undefined && o.work !== undefined);
-    if (ok.length < SPLIT_MIN) return unknown(`${p} has ${ok.length} measured task(s) with this profile; ${SPLIT_MIN} are needed`);
-    if (failed / all.length > SPLIT_FAILURE_SHARE) return unknown(`${failed} of ${all.length} of ${p}'s recorded tasks failed: its successes alone would understate its time`);
+    if (ok.length < minObservations) return unknown(`${p} has ${ok.length} measured task(s) with this profile; ${minObservations} are needed`);
+    if (failed / all.length > maxFailureShare) return unknown(`${failed} of ${all.length} of ${p}'s recorded tasks failed: its successes alone would understate its time`);
     const works = ok.map((o) => o.work).sort((x, y) => x - y);
     const u = median(works);
     const iqr = works[Math.floor((works.length * 3) / 4)]! - works[Math.floor(works.length / 4)]!;

package/src/hub/schedules.ts

@@ -0,0 +1,266 @@
+import { Database } from "bun:sqlite";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { corpusPathProblem } from "./corpus-config.ts";
+
+// agent-hub #512 (hub task #330): machine-local schedules. Spec: "Schedules and folder triggers (#512)".
+
+export const MIN_EVERY_MS = 15 * 60_000;
+export const MAX_EVERY_MS = 365 * 86_400_000;
+export const MAX_SCHEDULES = 64;
+export const MAX_SCHEDULE_SOURCES = 16;
+/** Under the board's 8000-character detail cap with the fixed lines and 16 source lines around it, so the marker line is never cut off. */
+export const MAX_SCHEDULE_DETAIL = 7000;
+/** The first line of a scheduled task's detail: how the board finds the task a schedule made, whatever hub.db remembers. */
+export const SCHEDULE_MARKER = "Schedule key: ";
+
+export interface ScheduleEntry {
+  id: string;
+  every: string;
+  class: string;
+  title: string;
+  detail?: string;
+  sources?: string[];
+  owner?: string;
+  queue: "backlog" | "ready";
+}
+
+/** The source id form of `src/hub/sources.ts` (`validSourceId`), repeated here because that module reaches the file system and the converters and this one is bundled into the Claude channel server through the config schema; `test/schedules.test.ts` pins that the two agree. */
+export const SOURCE_ID = /^src:[0-9a-f]{16}$/;
+const ID = /^[a-z0-9][a-z0-9_-]{0,47}$/, PEER = /^[a-z][a-z0-9-]{0,31}$/, CLASS = /^[a-z][a-z0-9_]{0,47}$/, KEYS = new Set(["id", "every", "cron", "class", "title", "detail", "sources", "owner", "queue"]);
+const control = /[\x00-\x1f\x7f]/;
+
+/** `<n>m|h|d` to milliseconds; a thrown reason otherwise. The 15-minute floor keeps a typo from flooding the board. */
+export function parseEvery(value: unknown): number {
+  const match = typeof value === "string" ? /^([1-9][0-9]{0,5})([mhd])$/.exec(value) : null;
+  if (!match) throw new Error("every must be <n>m, <n>h or <n>d, such as 90m, 6h or 1d");
+  const ms = Number(match[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2] as "m" | "h" | "d"];
+  if (ms < MIN_EVERY_MS) throw new Error("every must be at least 15m");
+  if (ms > MAX_EVERY_MS) throw new Error("every must be at most 365d");
+  return ms;
+}
+
+/** The checked `schedules` list. Every refusal names the entry; nothing here reads the board, a clock or a file. */
+export function schedulesConfig(input: unknown): ScheduleEntry[] {
+  if (input === undefined) return [];
+  if (!Array.isArray(input)) throw new Error("schedules must be a list");
+  if (input.length > MAX_SCHEDULES) throw new Error(`schedules holds at most ${MAX_SCHEDULES} entries`);
+  const seen = new Set<string>(), out: ScheduleEntry[] = [];
+  input.forEach((raw, index) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`schedules[${index}] must be an object`);
+    const row = raw as Record<string, unknown>;
+    const name = typeof row.id === "string" && ID.test(row.id) ? `schedules.${row.id}` : `schedules[${index}]`;
+    const bad = (reason: string): never => { throw new Error(`${name}: ${reason}`); };
+    for (const key of Object.keys(row)) if (!KEYS.has(key)) bad(`unknown key ${key}`);
+    if (typeof row.id !== "string" || !ID.test(row.id)) bad("id is 1 to 48 lower-case letters, digits, - or _");
+    if (seen.has(row.id as string)) bad("duplicate id");
+    seen.add(row.id as string);
+    if (row.cron !== undefined) bad("cron not supported yet; use every");
+    try { parseEvery(row.every); } catch (error) { bad((error as Error).message); }
+    if (typeof row.class !== "string" || !CLASS.test(row.class)) bad("class is required");
+    if (typeof row.title !== "string" || !row.title.trim() || row.title.length > 300 || control.test(row.title)) bad("title is 1 to 300 printable characters on one line");
+    if (row.detail !== undefined && (typeof row.detail !== "string" || row.detail.length > MAX_SCHEDULE_DETAIL || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(row.detail))) bad(`detail is text of at most ${MAX_SCHEDULE_DETAIL} characters`);
+    if (row.owner !== undefined && (typeof row.owner !== "string" || !PEER.test(row.owner))) bad("owner is a peer id");
+    if (row.queue !== undefined && row.queue !== "backlog" && row.queue !== "ready") bad('queue is "backlog" or "ready"');
+    if (row.sources !== undefined) {
+      if (!Array.isArray(row.sources) || row.sources.length > MAX_SCHEDULE_SOURCES || !row.sources.every(id => typeof id === "string" && SOURCE_ID.test(id))) bad(`sources is a list of at most ${MAX_SCHEDULE_SOURCES} source ids (src:<16 hex>)`);
+    }
+    out.push({
+      id: row.id as string, every: row.every as string, class: row.class as string, title: (row.title as string).replace(/\s+/g, " ").trim(),
+      ...(row.detail !== undefined ? { detail: row.detail as string } : {}), ...(row.sources !== undefined ? { sources: [...(row.sources as string[])] } : {}),
+      ...(row.owner !== undefined ? { owner: row.owner as string } : {}), queue: (row.queue as "backlog" | "ready" | undefined) ?? "backlog",
+    });
+  });
+  return out;
+}
+
+// agent-hub #512c (hub task #336): machine-local folder triggers. The pure config only; the scan, the store and the registration are in `folder-trigger.ts`, which reaches the disk.
+export const MAX_FOLDER_TRIGGERS = 16;
+export const MAX_FOLDER_GLOB = 100;
+/** The first line of a folder-triggered task's detail: which trigger made it. A task per file, so unlike a schedule's marker it blocks nothing. */
+export const FOLDER_MARKER = "Folder trigger: ";
+
+export interface FolderEntry {
+  id: string;
+  folder: string;
+  glob?: string;
+  class: string;
+  title: string;
+  detail?: string;
+  owner?: string;
+  queue: "backlog" | "ready";
+}
+const FOLDER_KEYS = new Set(["id", "folder", "glob", "class", "title", "detail", "owner", "queue"]);
+
+/** A file-name pattern: letters, digits, `.`, `_`, `-`, space, `*` and `?`. Never a path, so it cannot reach outside the folder. */
+export const folderGlobProblem = (value: unknown): string | undefined =>
+  typeof value !== "string" || !value || value.length > MAX_FOLDER_GLOB || !/^[A-Za-z0-9._ *?-]+$/.test(value) || value === "." || value === ".."
+    ? `glob is a file-name pattern of at most ${MAX_FOLDER_GLOB} characters (letters, digits, . _ - space, * and ?), never a path` : undefined;
+
+/** Whether a file name matches a trigger's glob. Dot files never match: a hidden file is not something a person dropped in. */
+export function folderGlobMatches(glob: string | undefined, name: string): boolean {
+  if (name.startsWith(".")) return false;
+  if (glob === undefined) return true;
+  return new RegExp(`^${glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`).test(name);
+}
+
+/** The checked `folder_triggers` list. Every refusal names the entry; nothing here reads the disk (the folder check does, at each poll). */
+export function foldersConfig(input: unknown): FolderEntry[] {
+  if (input === undefined) return [];
+  if (!Array.isArray(input)) throw new Error("folder_triggers must be a list");
+  if (input.length > MAX_FOLDER_TRIGGERS) throw new Error(`folder_triggers holds at most ${MAX_FOLDER_TRIGGERS} entries`);
+  const seen = new Set<string>(), out: FolderEntry[] = [];
+  input.forEach((raw, index) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`folder_triggers[${index}] must be an object`);
+    const row = raw as Record<string, unknown>;
+    const name = typeof row.id === "string" && ID.test(row.id) ? `folder_triggers.${row.id}` : `folder_triggers[${index}]`;
+    const bad = (reason: string): never => { throw new Error(`${name}: ${reason}`); };
+    for (const key of Object.keys(row)) if (!FOLDER_KEYS.has(key)) bad(`unknown key ${key}`);
+    if (typeof row.id !== "string" || !ID.test(row.id)) bad("id is 1 to 48 lower-case letters, digits, - or _");
+    if (seen.has(row.id as string)) bad("duplicate id");
+    seen.add(row.id as string);
+    const folderProblem = corpusPathProblem(row.folder);
+    if (folderProblem) bad(folderProblem.replace("a corpus path", "folder"));
+    if (row.glob !== undefined) { const problem = folderGlobProblem(row.glob); if (problem) bad(problem); }
+    if (typeof row.class !== "string" || !CLASS.test(row.class)) bad("class is required");
+    if (typeof row.title !== "string" || !row.title.trim() || row.title.length > 300 || control.test(row.title)) bad("title is 1 to 300 printable characters on one line");
+    if (row.detail !== undefined && (typeof row.detail !== "string" || row.detail.length > MAX_SCHEDULE_DETAIL || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(row.detail))) bad(`detail is text of at most ${MAX_SCHEDULE_DETAIL} characters`);
+    if (row.owner !== undefined && (typeof row.owner !== "string" || !PEER.test(row.owner))) bad("owner is a peer id");
+    if (row.queue !== undefined && row.queue !== "backlog" && row.queue !== "ready") bad('queue is "backlog" or "ready"');
+    out.push({
+      id: row.id as string, folder: row.folder as string, ...(row.glob !== undefined ? { glob: row.glob as string } : {}), class: row.class as string,
+      title: (row.title as string).replace(/\s+/g, " ").trim(), ...(row.detail !== undefined ? { detail: row.detail as string } : {}),
+      ...(row.owner !== undefined ? { owner: row.owner as string } : {}), queue: (row.queue as "backlog" | "ready" | undefined) ?? "backlog",
+    });
+  });
+  return out;
+}
+
+/** What one poll of a trigger did: `baseline` (first poll, recorded only), `ran`, `none`, `held`, `refused` (the folder may not be read, with the reason) or `failed`. */
+export interface FolderRunResult { id: string; outcome: "baseline" | "ran" | "none" | "held" | "refused" | "failed"; tasks: number[]; files: number; reason?: string; more?: true }
+/**
+ * One file a poll found: its real path, name, size, mtime and SHA-256, and never its bytes (a scan of a big inbox would hold them all). `seen` marks a file the trigger
+ * already recorded at this path, size and mtime: its hash is the recorded one and the file was not read again.
+ */
+export interface ScannedFile { real: string; name: string; size: number; mtime: number; sha256: string; seen?: true }
+/** What a read of a trigger's folder gave. `refused` is the reason the folder may not be read; `truncated` says the hash budget ran out and some files wait for the next poll. */
+export interface FolderScan { folder?: string; files: ScannedFile[]; skipped: { name: string; reason: string }[]; refused?: string; truncated: boolean }
+/** The part of the folder state `Tasks` needs. The scan, the disk and the table are in `folder-trigger.ts`, which the Claude channel bundle must not reach. */
+export interface FolderStorePort {
+  baselined(trigger: string): boolean;
+  begin(trigger: string, now: number): void;
+  markBaselined(trigger: string, now: number): void;
+  polled(trigger: string, now: number, error?: string): void;
+  isNew(trigger: string, sha256: string): boolean;
+  record(trigger: string, file: Pick<ScannedFile, "real" | "size" | "mtime" | "sha256">, task: number | null, now: number): void;
+  observe(trigger: string, file: Pick<ScannedFile, "real" | "size" | "mtime" | "sha256">, now: number): void;
+  prune(keep: readonly string[]): void;
+}
+/** New files one poll registers per trigger: a drop of a whole archive becomes a handful of tasks per tick, never a burst. */
+export const MAX_NEW_PER_POLL = 20;
+
+/** The detail of a folder-triggered task: the marker first, then the person's text, then the one source it names. Never the file's name or path: both can be private. */
+export function folderDetail(entry: FolderEntry, source: string): string {
+  return [`${FOLDER_MARKER}${entry.id}`, `Made by the machine-local folder trigger "${entry.id}" for a new file, registered as the source below.`, ...(entry.detail ? ["", entry.detail] : []), "", `Source: ${source}`].join("\n");
+}
+
+export interface ScheduleRow {
+  id: string;
+  /** The start of the current period: the first time the schedule was seen, then the last run. The next run is this plus `every`. */
+  anchor: number;
+  last_run: number | null;
+  last_task: number | null;
+  /** Ticks that were due and skipped (held, or the previous task still open) since the last run: coalesced into the one run that follows. */
+  coalesced: number;
+  last_error: string | null;
+  /** #335: 1 while a person has paused it. */
+  paused?: number;
+}
+
+/** `schedule_runs` in hub.db: when each schedule last ran and what it made. The board stays the record of the tasks themselves. */
+export class ScheduleStore {
+  private readonly db: Database;
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db.run("CREATE TABLE IF NOT EXISTS schedule_runs (id TEXT PRIMARY KEY, anchor INTEGER NOT NULL, last_run INTEGER, last_task INTEGER, coalesced INTEGER NOT NULL DEFAULT 0, last_error TEXT)");
+    // #335: a person's pause. A column on the existing table, so an older database gains it and every older row reads as not paused.
+    if (!(this.db.query("PRAGMA table_info(schedule_runs)").all() as { name: string }[]).some(column => column.name === "paused")) this.db.run("ALTER TABLE schedule_runs ADD COLUMN paused INTEGER NOT NULL DEFAULT 0");
+  }
+  get(id: string): ScheduleRow | undefined { return (this.db.query("SELECT * FROM schedule_runs WHERE id = ?").get(id) as ScheduleRow | null) ?? undefined; }
+  rows(): ScheduleRow[] { return this.db.query("SELECT * FROM schedule_runs ORDER BY id").all() as ScheduleRow[]; }
+  /** A schedule seen for the first time starts its period now: it never runs at once, and a restart never replays a missed one. */
+  ensure(id: string, now: number): ScheduleRow {
+    this.db.query("INSERT OR IGNORE INTO schedule_runs(id, anchor) VALUES(?, ?)").run(id, now);
+    return this.get(id)!;
+  }
+  /**
+   * A schedule's pause generation, in memory: `setPaused` bumps it. A run captures it when it is admitted and its write fence asks again, so a pause or a resume that
+   * lands while the run awaits its PII screen cancels that run instead of being overtaken by it. A restart ends every run in flight, so memory is enough.
+   */
+  private readonly epochs = new Map<string, number>();
+  epoch(id: string): number { return this.epochs.get(id) ?? 0; }
+  /**
+   * #335: pause or resume one schedule. A pause stops the timer from proposing it and counts no skipped tick. Resuming starts a fresh period at `now`, so a long
+   * pause is never replayed as a run the moment it ends, as a restart is never replayed either.
+   */
+  setPaused(id: string, paused: boolean, now: number): void {
+    this.epochs.set(id, this.epoch(id) + 1);
+    this.db.query("INSERT OR IGNORE INTO schedule_runs(id, anchor) VALUES(?, ?)").run(id, now);
+    if (paused) this.db.query("UPDATE schedule_runs SET paused = 1 WHERE id = ?").run(id);
+    else this.db.query("UPDATE schedule_runs SET paused = 0, anchor = ?, coalesced = 0 WHERE id = ?").run(now, id);
+  }
+  skipped(id: string): void { this.db.query("UPDATE schedule_runs SET coalesced = coalesced + 1 WHERE id = ?").run(id); }
+  ran(id: string, now: number, task: number): void {
+    // The anchor never moves back: a resume that landed after the task was written already started a later period, and an older pass timestamp must not shorten it.
+    this.db.query("UPDATE schedule_runs SET anchor = MAX(anchor, ?), last_run = ?, last_task = ?, coalesced = 0, last_error = NULL WHERE id = ?").run(now, now, task, id);
+  }
+  failed(id: string, reason: string): void { this.db.query("UPDATE schedule_runs SET last_error = ? WHERE id = ?").run(reason.slice(0, 200), id); }
+  /** A schedule removed from the config keeps no row. */
+  prune(keep: readonly string[]): void {
+    for (const row of this.rows()) if (!keep.includes(row.id)) this.db.query("DELETE FROM schedule_runs WHERE id = ?").run(row.id);
+  }
+  close(): void { try { this.db.close(); } catch { /* already closed */ } }
+}
+
+/** What one run of a schedule did. `changed`: the person paused or resumed it after the run was admitted, so it wrote nothing (#335). */
+export type ScheduleOutcome = "ran" | "held" | "waiting" | "failed" | "changed";
+export interface ScheduleRunResult { id: string; outcome: ScheduleOutcome; task?: number }
+
+export type ScheduleState = "scheduled" | "due" | "waiting" | "held" | "paused";
+export interface ScheduleView {
+  id: string;
+  every: string;
+  class: string;
+  queue: "backlog" | "ready";
+  next: number;
+  last?: number;
+  task?: number;
+  state: ScheduleState;
+  coalesced?: number;
+  error?: string;
+}
+
+/**
+ * What status shows for each schedule. `open` maps a schedule id to the open task it made. A due schedule that is held or whose task is open says so;
+ * one that is simply due (before its next tick) reads `due`. Titles and details are never shown: they are task text.
+ */
+export function scheduleViews(entries: readonly ScheduleEntry[], rows: readonly ScheduleRow[], now: number, open: ReadonlyMap<string, number>, held: boolean): ScheduleView[] {
+  const byId = new Map(rows.map(row => [row.id, row]));
+  return entries.map(entry => {
+    const row = byId.get(entry.id), anchor = row?.anchor ?? now, next = anchor + parseEvery(entry.every), openTask = open.get(entry.id);
+    const state: ScheduleState = row?.paused ? "paused" : now < next ? "scheduled" : held ? "held" : openTask !== undefined ? "waiting" : "due";
+    return {
+      id: entry.id, every: entry.every, class: entry.class, queue: entry.queue, next, state,
+      ...(row?.last_run != null ? { last: row.last_run } : {}), ...(openTask !== undefined ? { task: openTask } : row?.last_task != null ? { task: row.last_task } : {}),
+      ...(row?.coalesced ? { coalesced: row.coalesced } : {}), ...(row?.last_error ? { error: row.last_error } : {}),
+    };
+  });
+}
+
+/** The detail of a scheduled task: the marker line first, then the person's text and the sources it names, all fixed words around config text. */
+export function scheduledDetail(entry: ScheduleEntry): string {
+  return [`${SCHEDULE_MARKER}${entry.id}`, `Scheduled every ${entry.every} by the machine-local schedule "${entry.id}".`, ...(entry.detail ? ["", entry.detail] : []),
+    ...(entry.sources?.length ? ["", ...entry.sources.map(id => `Source: ${id}`)] : [])].join("\n");
+}
+
+export const scheduleKeyOf = (detail: string | undefined): string | undefined => detail?.startsWith(SCHEDULE_MARKER) ? detail.slice(SCHEDULE_MARKER.length).split("\n")[0] : undefined;