@staix/agent-hub 0.24.0 → 0.26.0

package/src/hub/schedules.ts

@@ -1,5 +1,5 @@
-import { Database } from "bun:sqlite";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import { corpusPathProblem } from "./corpus-config.ts";
 
 // agent-hub #512 (hub task #330): machine-local schedules. Spec: "Schedules and folder triggers (#512)".
@@ -15,7 +15,12 @@ export const SCHEDULE_MARKER = "Schedule key: ";
 
 export interface ScheduleEntry {
   id: string;
-  every: string;
+  /** Exactly one of `every` and `cron` (#1017). */
+  every?: string;
+  /** The five cron fields, single-spaced (`parseCron` checked them). */
+  cron?: string;
+  /** An IANA zone for `cron`; without it the machine's own zone (`scheduleZone`). */
+  tz?: string;
   class: string;
   title: string;
   detail?: string;
@@ -26,7 +31,7 @@ export interface ScheduleEntry {
 
 /** 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 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", "tz", "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. */
@@ -39,6 +44,185 @@ export function parseEvery(value: unknown): number {
   return ms;
 }
 
+// agent-hub #1017: calendar-anchored schedules. Spec: "Calendar-anchored schedules (#1017)". Pure: a cron expression and a zone in, instants out, on `Intl` and `Date` only (zero runtime
+// dependencies). Every function takes the time it works from, so a test pins a fixed clock.
+
+/** The five fields, each as the sorted values it allows. `domStar` and `dowStar`: the field began with `*`, which the day rule below reads. */
+export interface CronSpec { minutes: number[]; hours: number[]; doms: number[]; months: number[]; dows: number[]; domStar: boolean; dowStar: boolean }
+const CRON_FIELDS = [{ name: "minute", min: 0, max: 59 }, { name: "hour", min: 0, max: 23 }, { name: "day of month", min: 1, max: 31 }, { name: "month", min: 1, max: 12 }, { name: "day of week", min: 0, max: 7 }] as const;
+export const MAX_CRON_LENGTH = 100;
+/**
+ * One Gregorian cycle: the calendar, and so every day-of-month, month and weekday pattern, repeats exactly every 146097 days (400 years, a whole number of weeks). Scanning that far makes
+ * both questions complete: an expression that never fires has no matching day in it, and one that fires at all fires inside it from any start (a Feb 29 that is a Sunday recurs
+ * 28 to 40 years apart). The cost is only paid by a sparse expression: a common one stops at its first match.
+ */
+const CRON_HORIZON_DAYS = 146_097;
+const DAY_MS = 86_400_000, MIN_MS = 60_000;
+
+function cronField(text: string, name: string, min: number, max: number): number[] {
+  const values = new Set<number>();
+  for (const part of text.split(",")) {
+    const match = /^(?:(\*)|(\d{1,2})(?:-(\d{1,2}))?)(?:\/(\d{1,2}))?$/.exec(part);
+    if (!match || (match[2] !== undefined && match[3] === undefined && match[4] !== undefined)) throw new Error(`cron ${name} must be numbers, ranges (a-b), lists (a,b) and steps (*/n or a-b/n)`);
+    const from = match[1] ? min : Number(match[2]), to = match[1] ? max : match[3] !== undefined ? Number(match[3]) : from, step = match[4] === undefined ? 1 : Number(match[4]);
+    if (from < min || to > max || from > to) throw new Error(`cron ${name} is ${min} to ${max}, and a range runs upward`);
+    if (step < 1) throw new Error(`cron ${name} step must be at least 1`);
+    for (let value = from; value <= to; value += step) values.add(name === "day of week" && value === 7 ? 0 : value);
+  }
+  return [...values].sort((a, b) => a - b);
+}
+
+/**
+ * The standard five fields (minute, hour, day of month, month, day of week): numbers, lists, ranges and steps; day of week 0 and 7 are Sunday. No seconds, no year, no `@` macro, no names.
+ * A day matches when both day fields are restricted and EITHER matches, or when one of them begins with `*` and BOTH match (the classic cron rule); month always has to match.
+ */
+export function parseCron(expression: unknown): CronSpec {
+  if (typeof expression !== "string" || !expression.trim()) throw new Error("cron is five fields: minute hour day-of-month month day-of-week");
+  if (expression.length > MAX_CRON_LENGTH || /[^\x20-\x7e]/.test(expression)) throw new Error(`cron is at most ${MAX_CRON_LENGTH} printable characters`);
+  if (expression.trim().startsWith("@")) throw new Error("cron takes the five fields, not an @ macro");
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error(`cron is exactly five fields (minute hour day-of-month month day-of-week), not ${fields.length}; seconds and a year are not supported`);
+  const [minutes, hours, doms, months, dows] = CRON_FIELDS.map((field, index) => cronField(fields[index]!, field.name, field.min, field.max)) as [number[], number[], number[], number[], number[]];
+  return { minutes, hours, doms, months, dows, domStar: fields[2]!.startsWith("*"), dowStar: fields[4]!.startsWith("*") };
+}
+/** The expression as stored: the same five fields, single-spaced. */
+export const cronText = (expression: string): string => expression.trim().split(/\s+/).join(" ");
+
+function dayMatches(spec: CronSpec, dayMs: number): boolean {
+  const date = new Date(dayMs);
+  if (!spec.months.includes(date.getUTCMonth() + 1)) return false;
+  const dom = spec.doms.includes(date.getUTCDate()), dow = spec.dows.includes(date.getUTCDay());
+  return spec.domStar || spec.dowStar ? dom && dow : dom || dow;
+}
+
+/**
+ * The smallest gap, in minutes, between two fires of the expression on the calendar itself (a wall clock with no zone), or undefined when no day of a full 400-year Gregorian cycle matches (`0 0 31 2 *`).
+ * Daylight saving can still move two fires closer on its one change day (a skipped time runs at the first valid minute); a schedule proposes at most one task per pass and none while its
+ * previous task is open, so that costs no flood.
+ */
+export function cronMinGapMinutes(spec: CronSpec): number | undefined {
+  const times = spec.hours.flatMap(hour => spec.minutes.map(minute => hour * 60 + minute));
+  let gap = Infinity;
+  for (let i = 1; i < times.length; i++) gap = Math.min(gap, times[i]! - times[i - 1]!);
+  const start = Date.UTC(2024, 0, 1);
+  let any = false, consecutive = false, before = false;
+  for (let day = 0; day < CRON_HORIZON_DAYS; day++) {
+    const now = dayMatches(spec, start + day * DAY_MS);
+    any ||= now;
+    if (now && before) consecutive = true;
+    before = now;
+  }
+  if (!any) return undefined;
+  return Math.min(gap, consecutive ? 1440 - times[times.length - 1]! + times[0]! : Infinity);
+}
+
+const zoneFormats = new Map<string, Intl.DateTimeFormat>();
+function zoneFormat(zone: string): Intl.DateTimeFormat {
+  let format = zoneFormats.get(zone);
+  if (!format) {
+    format = new Intl.DateTimeFormat("en-US", { timeZone: zone, hourCycle: "h23", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" });
+    if (zoneFormats.size >= 64) zoneFormats.clear();
+    zoneFormats.set(zone, format);
+  }
+  return format;
+}
+/** An IANA zone name the runtime knows, as it spells it (`utc` is `UTC`), or a thrown reason. */
+export function checkZone(value: unknown): string {
+  if (typeof value !== "string" || value.length > 64 || !/^[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)*$/.test(value)) throw new Error("tz is an IANA zone name such as Asia/Seoul or America/New_York");
+  try { return zoneFormat(value).resolvedOptions().timeZone; } catch { throw new Error("tz is not a zone this machine knows; use an IANA name such as Asia/Seoul or America/New_York"); }
+}
+/** The zone a schedule's `cron` is read in: its `tz`, else this machine's own. */
+export function scheduleZone(entry: Pick<ScheduleEntry, "tz">): string {
+  if (entry.tz) return entry.tz;
+  try { return new Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC"; } catch { return "UTC"; }
+}
+
+/** The wall clock of an instant in a zone, as milliseconds on a zone-less calendar (the calendar read as UTC). */
+function wallOf(zone: string, instant: number): number {
+  const parts: Record<string, number> = {};
+  for (const part of zoneFormat(zone).formatToParts(instant)) if (part.type !== "literal") parts[part.type] = Number(part.value);
+  return Date.UTC(parts.year!, parts.month! - 1, parts.day!, parts.hour! % 24, parts.minute!, parts.second!);
+}
+/**
+ * The instant a wall-clock minute happens in a zone. A time that happens twice (the clock went back) is its first occurrence, so a repeated time runs once; a time that never happens
+ * (the clock jumped forward) is the first minute that does, so a skipped time still runs.
+ */
+function instantOf(zone: string, wall: number): number {
+  const offset = (instant: number) => wallOf(zone, instant) - Math.floor(instant / 1000) * 1000;
+  const tried = new Set<number>(), found: number[] = [];
+  for (const guess of [offset(wall - DAY_MS), offset(wall + DAY_MS), offset(wall)]) {
+    if (tried.has(guess)) continue;
+    tried.add(guess);
+    if (wallOf(zone, wall - guess) === wall) found.push(wall - guess);
+  }
+  if (found.length) return Math.min(...found);
+  // A gap: the first minute whose wall clock has reached the skipped time. No zone's offset moves by 30 hours, so this window holds the one change.
+  let low = Math.floor((wall - 30 * 3_600_000) / MIN_MS), high = Math.ceil((wall + 30 * 3_600_000) / MIN_MS);
+  while (high - low > 1) {
+    const middle = Math.floor((low + high) / 2);
+    if (wallOf(zone, middle * MIN_MS) >= wall) high = middle; else low = middle;
+  }
+  return high * MIN_MS;
+}
+
+/** The first wall-clock minute strictly after `wall` that the expression allows, or undefined when no day of a full cycle matches. */
+function nextWall(spec: CronSpec, wall: number): number | undefined {
+  const from = wall - (wall % MIN_MS) + MIN_MS, firstDay = from - (from % DAY_MS), floor = (from - firstDay) / MIN_MS;
+  for (let day = 0; day < CRON_HORIZON_DAYS; day++) {
+    const dayMs = firstDay + day * DAY_MS;
+    if (!dayMatches(spec, dayMs)) continue;
+    for (const hour of spec.hours) for (const minute of spec.minutes) if (hour * 60 + minute >= (day === 0 ? floor : 0)) return dayMs + (hour * 60 + minute) * MIN_MS;
+  }
+  return undefined;
+}
+
+/**
+ * The next fire strictly after `after` (epoch ms), or undefined when none exists (no day of a full 400-year cycle matches). Fires are found on the zone's wall clock and then placed on the timeline by
+ * `instantOf`: a repeated wall time fires once, and a fire the clock skipped fires at the first valid minute.
+ */
+export function cronNext(spec: CronSpec, zone: string, after: number): number | undefined {
+  let wall = wallOf(zone, after);
+  wall -= wall % MIN_MS;
+  for (let guard = 0; guard < 2000; guard++) {
+    const next = nextWall(spec, wall);
+    if (next === undefined) return undefined;
+    const instant = instantOf(zone, next);
+    if (instant > after) return instant;
+    wall = next;
+  }
+  return undefined;
+}
+
+/** `YYYY-MM-DD HH:mm` in a zone: how a person reads the next run of a calendar schedule. */
+export function formatInZone(instant: number, zone: string): string {
+  const iso = new Date(wallOf(zone, instant)).toISOString();
+  return `${iso.slice(0, 10)} ${iso.slice(11, 16)}`;
+}
+
+/** How a view's period reads: `every 6h`, or `cron 30 7 * * 1-5 (Asia/Seoul)`. */
+export const schedulePeriodText = (view: { every?: string; cron?: string; zone?: string }): string => view.cron !== undefined ? `cron ${view.cron}${view.zone ? ` (${view.zone})` : ""}` : `every ${view.every ?? "?"}`;
+/** An instant as a person reads a schedule's next run: in the zone of a `cron` (`2026-11-02 07:30 Asia/Seoul`), else UTC like every other time in the CLI. */
+export function scheduleWhen(view: { zone?: string }, instant: number): string {
+  if (view.zone) { try { return `${formatInZone(instant, view.zone)} ${view.zone}`; } catch { /* an unknown zone falls through to UTC */ } }
+  return `${new Date(instant).toISOString().replace("T", " ").slice(0, 16)} UTC`;
+}
+
+const parsedCrons = new Map<string, CronSpec>();
+function cronSpec(expression: string): CronSpec {
+  let spec = parsedCrons.get(expression);
+  if (!spec) {
+    spec = parseCron(expression);
+    if (parsedCrons.size >= 256) parsedCrons.clear();
+    parsedCrons.set(expression, spec);
+  }
+  return spec;
+}
+/** The next time a schedule is due, given the start of its period: `every` after the anchor, or the next calendar fire of its `cron` after it. Far in the future when a cron has none. */
+export function scheduleNext(entry: Pick<ScheduleEntry, "every" | "cron" | "tz">, anchor: number): number {
+  if (entry.cron !== undefined) return cronNext(cronSpec(entry.cron), scheduleZone(entry), anchor) ?? Number.MAX_SAFE_INTEGER;
+  return anchor + parseEvery(entry.every);
+}
+
 /** 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 [];
@@ -54,8 +238,21 @@ export function schedulesConfig(input: unknown): ScheduleEntry[] {
     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 (row.every !== undefined && row.cron !== undefined) bad("give every or cron, not both");
+    if (row.every === undefined && row.cron === undefined) bad("every must be <n>m, <n>h or <n>d, or give cron (five fields)");
+    if (row.tz !== undefined && row.cron === undefined) bad("tz applies to cron only");
+    let cron: string | undefined, tz: string | undefined;
+    if (row.cron !== undefined) {
+      try {
+        const spec = parseCron(row.cron), gap = cronMinGapMinutes(spec);
+        if (gap === undefined) bad("cron never fires: no calendar day matches it");
+        if (gap! < MIN_EVERY_MS / MIN_MS) bad(`cron can fire every ${gap} minute${gap === 1 ? "" : "s"}; the minimum is ${MIN_EVERY_MS / MIN_MS} minutes`);
+        cron = cronText(row.cron as string);
+        if (row.tz !== undefined) tz = checkZone(row.tz);
+      } catch (error) { bad((error as Error).message.replace(/^schedules[.[][^:]*: /, "")); }
+    } else {
+      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`);
@@ -65,7 +262,7 @@ export function schedulesConfig(input: unknown): ScheduleEntry[] {
       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(),
+      id: row.id as string, ...(cron !== undefined ? { cron, ...(tz !== undefined ? { tz } : {}) } : { 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",
     });
@@ -180,8 +377,7 @@ export interface ScheduleRow {
 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 = openHubDatabase(dbPath, { create: true });
     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");
@@ -229,7 +425,10 @@ export interface ScheduleRunResult { id: string; outcome: ScheduleOutcome; task?
 export type ScheduleState = "scheduled" | "due" | "waiting" | "held" | "paused";
 export interface ScheduleView {
   id: string;
-  every: string;
+  /** `every` or `cron`, never both; `zone` is the zone a `cron` is read in (its `tz`, else the machine's), so a person reads the next run with it (#1017). */
+  every?: string;
+  cron?: string;
+  zone?: string;
   class: string;
   queue: "backlog" | "ready";
   next: number;
@@ -247,10 +446,10 @@ export interface ScheduleView {
 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 row = byId.get(entry.id), anchor = row?.anchor ?? now, next = scheduleNext(entry, anchor), 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,
+      id: entry.id, ...(entry.cron !== undefined ? { cron: entry.cron, zone: scheduleZone(entry) } : { 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 } : {}),
     };
@@ -259,7 +458,8 @@ export function scheduleViews(entries: readonly ScheduleEntry[], rows: readonly
 
 /** 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] : []),
+  const when = entry.cron !== undefined ? `on the calendar "${entry.cron}" (${scheduleZone(entry)})` : `every ${entry.every}`;
+  return [`${SCHEDULE_MARKER}${entry.id}`, `Scheduled ${when} by the machine-local schedule "${entry.id}".`, ...(entry.detail ? ["", entry.detail] : []),
     ...(entry.sources?.length ? ["", ...entry.sources.map(id => `Source: ${id}`)] : [])].join("\n");
 }
 

package/src/hub/sdlc-merge.ts

@@ -144,6 +144,12 @@ export function localGates(input: { subject: DeliveryTask; state: string; taskSt
   const { subject, config } = input, gates: string[] = [];
   if (subject.private) return ["private task: a person merges"];
   if (input.state !== "approved") gates.push(`task not approved (state ${input.state})`);
+  const approved = subject.receipt?.reviewedHead;
+  if (subject.latestHead !== undefined && subject.latestHead !== approved) gates.push("latest reported head differs from approved head");
+  const binding = subject.approval;
+  if (binding && (!binding.current || binding.mismatch || !binding.head || binding.head !== approved
+    || subject.latestHead !== undefined && binding.head !== subject.latestHead
+    || binding.latestHead !== undefined && binding.head !== binding.latestHead)) gates.push("approval is not current at the latest reported head");
   for (const id of subject.after) {
     const state = input.taskState(id);
     if (state !== "approved") gates.push(`dependency task #${id} is not approved (${state ?? "unknown"})`);
@@ -206,6 +212,7 @@ export function dispatchGates(input: Pick<MergeInput, "subject" | "taskState"> &
   if (!now) return moved;
   const receipt = now.subject.receipt;
   if (receipt?.repo !== decision.repo || receipt?.pr !== decision.pr || receipt?.reviewedHead !== decision.head) return moved;
+  if (now.subject.latestHead !== input.subject.latestHead || JSON.stringify(now.subject.approval) !== JSON.stringify(input.subject.approval)) return moved;
   if (now.mode !== input.mode) return ["merge mode changed during the merge check: nothing was run"];
   if (JSON.stringify(requiredChecksFor(now.config, decision.repo)) !== JSON.stringify(requiredChecksFor(input.config, decision.repo))) return ["required checks changed during the merge check: nothing was run"];
   if (!now.allowed) return ["authority or hub availability changed during the merge check: nothing was run"];

package/src/hub/sdlc-queue.ts

@@ -4,7 +4,14 @@ import { evalGapBlockers, evalGateView, readEvalFor, type EvalGate } from "./eva
 import { findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CriteriaView } from "./workflow.ts";
 import { parsePrEvidence, readSdlcPr, sdlcGh, sdlcStatus, type PrEvidence, type SdlcConfig, type SdlcGh, type SdlcReceipt } from "./sdlc.ts";
-export interface DeliveryTask { plan?: { paths?: string[]; revision: number; fingerprint: string; accepted: { repo: string; pr: number; head: string; revision: number; fingerprint: string; paths: string[] }[] }; findings?: readonly ReviewFindingSet[]; id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
+export interface DeliveryTask {
+  /** Latest owner-reported artifact head; omitted by older library callers. */
+  latestHead?: string;
+  /** Host-derived verdict binding, never inferred from a mutable lifecycle receipt. */
+  approval?: { head?: string; latestHead?: string; mismatch: boolean; current: boolean };
+  plan?: { paths?: string[]; revision: number; fingerprint: string; accepted: { repo: string; pr: number; head: string; revision: number; fingerprint: string; paths: string[] }[] };
+  findings?: readonly ReviewFindingSet[]; id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView;
+}
 export interface MergeQueueRow { evalGate?: EvalGate; testIntegrity?: (TestIntegrity & { task?: number })[]; planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
 export interface MergeConflict { left: number; right: number; files: number; order: "dependency" | "person_required"; }
 export interface MergeQueue { repo: string; rows: MergeQueueRow[]; order: number[]; unordered?: number[]; conflicts: MergeConflict[]; complete: boolean; truncated: boolean; }
@@ -94,6 +101,11 @@ export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: De
       const integrity = rawIntegrity ? publicTestIntegrity(rawIntegrity, readableMetadata) : undefined;
       if (integrity) (row.testIntegrity ??= []).push({ task: holder!.id, ...integrity });
       row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+      const approved = holder?.receipt?.reviewedHead, binding = holder?.approval;
+      if (holder?.latestHead !== undefined && holder.latestHead !== approved) row.blockers.push("latest reported head differs from approved head");
+      if (binding && (!binding.current || binding.mismatch || !binding.head || binding.head !== approved
+        || holder?.latestHead !== undefined && binding.head !== holder.latestHead
+        || binding.latestHead !== undefined && binding.head !== binding.latestHead)) row.blockers.push("approval is not current at the latest reported head");
       // #481 S5: the eval check itself is a required check inside sdlcStatus; its recorded pass rate and suite are read once per PR here.
       if (!row.evalGate) {
         const gate = evalGateView(config, read, await readEvalFor(config, read, repo, bounded));

package/src/hub/session-identity.ts

@@ -0,0 +1,49 @@
+// Distinguishable sessions, not authentication (agent-hub#1036, board #606). A connection that names a peer id but is not that id's current session is bound to an id the DAEMON mints,
+// `<peer>~<origin>` (for example `claude~agent-console`), instead of becoming that peer. The id has no `@`, so it never reaches the remote-room paths (`isRemotePeerId`,
+// `membershipAllowed`, `remoteEnvelope`), and `PEER_ID` is not widened: only the daemon makes these ids, and it keeps them in its own Set.
+//
+// What such a session may do: send, and read through the tools below. It is never a WsPeer, never receives a delivery or a push, and holds none of the peer's board roles.
+//
+// Limit, stated plainly: this makes sessions distinguishable and traceable. It does not authenticate them. A same-user process can always act as the user; the point is that a mix-up
+// between two sessions of one person is visible in the header a recipient reads and in events.jsonl.
+
+/** The task ops a distinct session may run: reads that need no role. Everything else is refused with `sessionRefusal`. */
+export const SESSION_READ_OPS: ReadonlySet<string> = new Set([
+  "hub_task_show", "hub_task_list", "hub_status", "hub_capabilities", "hub_study_show", "hub_backlog_list", "hub_release_list",
+]);
+
+/** The control messages a distinct session may send besides task ops. `task` is gated again by `SESSION_READ_OPS`. */
+export const SESSION_MESSAGES: ReadonlySet<string> = new Set(["send", "status", "task"]);
+
+const LABEL = /^[a-z][a-z0-9-]{0,23}$/;
+
+/**
+ * A label is the other project's name or a short session id, and it ends up in a header another agent reads. It is kept only when it already IS a plain lowercase token: nothing is cleaned up into
+ * one, so a path, a sentence or an instruction cannot leave a fragment of itself in a sender name. Anything else is dropped, and the hub mints a random short id instead.
+ */
+export function sessionLabel(value: unknown): string | undefined {
+  return typeof value === "string" && LABEL.test(value) && !value.endsWith("-") ? value : undefined;
+}
+
+/** `taken(id)` says whether a live session already has the id. A second session from the same origin gets a short suffix, so no two live sessions share an id. */
+export function mintSessionId(peer: string, label: unknown, taken: (id: string) => boolean, random: () => string): string {
+  const base = `${peer.slice(0, 32)}~${sessionLabel(label) ?? random()}`;
+  let id = base;
+  for (let n = 0; taken(id) && n < 8; n++) id = `${base}-${random().slice(0, 4)}`;
+  return id;
+}
+
+export const isSessionId = (id: unknown): id is string => typeof id === "string" && id.includes("~");
+
+/** The one refusal a distinct session meets, so a person reading it learns which session it is and which one holds the role. */
+export function sessionRefusal(id: string): string {
+  const peer = id.slice(0, id.indexOf("~"));
+  return `this session is ${id}, not this project's ${peer}: it can send and read, and holds none of ${peer}'s board roles`;
+}
+
+/** The gate the daemon applies to every message of a distinct session. Returns the refusal text, or undefined when the message may proceed. */
+export function sessionGate(id: string, msg: { t?: unknown; op?: unknown }): string | undefined {
+  if (typeof msg.t !== "string" || !SESSION_MESSAGES.has(msg.t)) return sessionRefusal(id);
+  if (msg.t === "task" && !(typeof msg.op === "string" && SESSION_READ_OPS.has(msg.op))) return sessionRefusal(id);
+  return undefined;
+}

package/src/hub/settings.ts

@@ -12,6 +12,7 @@ import { CLASSES, type TaskClass } from "./board.ts";
 import { configTracked, configRepositoryPresent } from "./config-trust.ts";
 import { PERMISSION_MODES, permissionBoundary } from "./permission-mode.ts";
 import { START_MODES } from "./start-mode.ts";
+import { checkStartAgents } from "./start-agents.ts";
 import { OVERLAY_FILE, overlayToml, parseOverlay, parseRouting, routingText, type Routing, type RoutingOverlay } from "./routing.ts";
 
 /**
@@ -74,6 +75,7 @@ export const SETTINGS: readonly SettingDef[] = [
   ...ACTION_CLASSES.map((kind): SettingDef => ({ key: `action_policy.budgets.${kind}`, group: "Permissions", label: `${kind}: approved session budget`, type: "integer", min: 0, max: 1000, store: "config", applies: "live", risk: "raises", floor: 0, path: ["action_policy", "budgets", kind] })),
   ...SETTING_PEERS.filter(peer => !definitionOf(peer)?.permission.unmanaged).map((peer): SettingDef => ({ key: `permission.${peer}`, group: "Permissions", label: `${peer}: mode now`, type: "enum", values: PERMISSION_MODES, store: "runtime", applies: "live", risk: "raises", floor: "ask", path: [peer] })),
   ...SETTING_PEERS.filter(peer => !definitionOf(peer)?.permission.unmanaged).map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at next peer start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "next use", risk: "raises", floor: "ask", path: ["permission_modes", peer] })),
+  { key: "start.agents", group: "Start", label: "Agents ahub up starts (none for an empty list)", type: "peers", store: "config", applies: "next use", risk: "raises", path: ["start", "agents"] },
   ...START_MODE_PEERS.map((peer): SettingDef => ({ key: `peers.${peer}.start_mode`, group: "Start", label: `${peer}: start mode (tui unless set)`, type: "enum", values: START_MODES, store: "config", applies: "next use", risk: "raises", floor: "tui", path: ["peers", peer, "start_mode"] })),
   ...ADAPTERS.flatMap(adapter => adapter.configuration?.settings ?? []),
   { key: "routing.stay_switch", group: "Routing", label: "Stay or switch (hub/auto and stage routes)", type: "enum", values: ["off", "shadow", "enforce"], store: "routing", applies: "live", risk: "raises", path: ["stay_switch"] },
@@ -203,6 +205,7 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
       }
       return peers.length === 1 ? peers[0] as string : [...peers] as string[];
     }
+    if (def.key === "start.agents") return checkStartAgents(raw, def.key);
     if (!Array.isArray(raw) || raw.length > PEERS_MAX || raw.some((p) => typeof p !== "string" || !PEER.test(p)) || new Set(raw).size !== raw.length) throw new Error(`${def.key} takes up to ${PEERS_MAX} distinct peer ids`);
     return [...(raw as string[])];
   }
@@ -217,6 +220,7 @@ export function parseSettingText(def: SettingDef, text: string): unknown {
   if (def.type === "number") return text.trim() && Number.isFinite(Number(text)) ? Number(text) : text;
   if (def.type === "integer") return /^(0|[1-9]\d*)$/.test(text) ? Number(text) : text;
   if (def.type === "boolean") return text === "true" ? true : text === "false" ? false : text;
+  if (def.key === "start.agents" && text.trim() === "none") return [];
   if (def.type === "peers" || def.type === "roles") return text.split(",").map((p) => p.trim()).filter(Boolean);
   return text;
 }

package/src/hub/snapshots.ts

@@ -1,4 +1,5 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import { closeSync, constants, copyFileSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync, type Stats } from "node:fs";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
@@ -7,7 +8,6 @@ import { childEnv } from "./child-process.ts";
 import type { Touch } from "./conflicts.ts";
 import { hubGitSync } from "./git.ts";
 import { realPath } from "./project.ts";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 /**
  * Per-turn workspace snapshots (issue #33): git tree objects written through a copy of the index, so the user's index
@@ -657,8 +657,7 @@ export function submodulePaths(repo: Repo): string[] {
 export class Turns {
   private readonly db: Database;
   constructor(path: string, readonly?: boolean) {
-    this.db = new Database(path, readonly ? { readonly: true } : { create: true });
-    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db = openHubDatabase(path, readonly ? { readonly: true } : { create: true });
     if (readonly) return;
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`CREATE TABLE IF NOT EXISTS turns (id TEXT PRIMARY KEY, peer TEXT NOT NULL, started INTEGER NOT NULL, ended INTEGER,

package/src/hub/start-agents.ts

@@ -0,0 +1,44 @@
+import { SUPPORTED_PEERS, definitionOf } from "../adapters/registry.ts";
+
+/**
+ * #608 (agent-hub#1040): the agents `ahub up` asks the hub to start, `start.agents`. Pure and free of file-system
+ * imports: the config schema (`config-apply.ts`) reaches the Claude channel bundle. The list is read by the CLI at a
+ * person's `ahub up` and by the dashboard manager's start; the daemon never reads it, so a restart, a crash recovery,
+ * a reload or an upgrade relaunch starts nothing from it.
+ *
+ * Which kinds may be listed, which are in the default set and why a kind is refused all come from the kind's own
+ * `AdapterDefinition.start.upStart` (#451): nothing here names a peer.
+ */
+const upStart = (id: string) => definitionOf(id)?.start.upStart;
+
+/** The kinds in the default set, in the registry's order. */
+export const START_AGENTS_DEFAULT: readonly string[] = Object.freeze(SUPPORTED_PEERS.filter(peer => { const s = upStart(peer); return s?.allowed === true && s.default === true; }));
+export const START_AGENTS_MAX = 8;
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** The kinds `ahub up` may start. A declared instance, a channel extra and an unknown id are never in it. */
+export const START_AGENTS_ALLOWED: readonly string[] = Object.freeze(SUPPORTED_PEERS.filter(peer => definitionOf(peer)?.start.conductorStartable === true && upStart(peer)?.allowed === true));
+
+/** Why `id` cannot be in the start set, or undefined. The reason never repeats the id unless it is a well-formed peer id. */
+export function startAgentRefusal(id: unknown): string | undefined {
+  if (typeof id !== "string" || !PEER.test(id)) return "an entry is not a peer id (lowercase letters, digits and dashes)";
+  if (START_AGENTS_ALLOWED.includes(id)) return undefined;
+  const own = upStart(id);
+  if (own?.allowed === false) return `${id} cannot be started by ahub up: ${own.refusal}`;
+  if (SUPPORTED_PEERS.includes(id)) return `${id} cannot be started by ahub up: the hub does not start it; run ahub ${id} in a terminal`;
+  return `${id} cannot be started by ahub up: it is a declared instance, a channel extra or unknown, and only ${START_AGENTS_ALLOWED.join(", ")} are started by the hub`;
+}
+
+/** The checked list (a copy), or a thrown reason. An empty list is allowed and starts nothing. */
+export function checkStartAgents(raw: unknown, key = "start.agents"): string[] {
+  if (!Array.isArray(raw) || raw.length > START_AGENTS_MAX) throw new Error(`${key} takes a list of up to ${START_AGENTS_MAX} peer ids (an empty list starts none)`);
+  for (const id of raw) { const why = startAgentRefusal(id); if (why) throw new Error(`${key}: ${why}`); }
+  if (new Set(raw).size !== raw.length) throw new Error(`${key} takes distinct peer ids`);
+  return [...raw] as string[];
+}
+
+/** A person's text for the list: commas or spaces between ids, `none` for an empty list. */
+export function parseStartAgents(text: string): string[] {
+  const words = text.split(/[\s,]+/).filter(Boolean);
+  return checkStartAgents(words.length === 1 && words[0] === "none" ? [] : words);
+}

package/src/hub/task-approval.ts

@@ -0,0 +1,23 @@
+import type { Task } from "./board.ts";
+
+export interface ApprovalBinding { head?: string; latestHead?: string; mismatch: boolean; current: boolean }
+const fullHead = (value: unknown): string | undefined => typeof value === "string" && /^[a-f0-9]{40}$/.test(value) ? value : undefined;
+
+/** The last approval remains historical evidence after a new delivery or a withdrawal. Unknown legacy heads stay unknown. */
+export function approvalBinding(task: Task): ApprovalBinding | undefined {
+  const verdict = task.history.findLast(entry => entry.event === "approved");
+  if (!verdict) return undefined;
+  const head = fullHead(verdict.reviewedHead) ?? fullHead(verdict.reviewFindings?.head)
+    ?? (task.state === "approved" ? fullHead(task.sdlc?.reviewedHead) : undefined);
+  const latestHead = fullHead(task.refs.commit ?? task.sdlc?.head ?? task.sdlc?.localHead);
+  const mismatch = !!head && !!latestHead && head !== latestHead;
+  return { ...(head ? { head } : {}), ...(latestHead ? { latestHead } : {}), mismatch,
+    current: task.state === "approved" && !!head && head === latestHead };
+}
+
+export function approvalText(binding: ApprovalBinding | undefined): string {
+  if (!binding) return "";
+  return `Approval bound to head ${binding.head ?? "unknown"}; latest reported head ${binding.latestHead ?? "unknown"}. ${binding.mismatch
+    ? "HEAD MISMATCH: earlier approval does not approve the latest reported head."
+    : binding.current ? "Approval is current at this head." : "Earlier approval is not current; review is required."}`;
+}