@staix/agent-hub 0.25.0 → 0.27.0

package/src/hub/runtime-prune-health.ts

@@ -0,0 +1,112 @@
+import { Database } from "bun:sqlite";
+import { lstatSync, opendirSync, type Dirent, type Stats } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+import { processLiveness } from "../pi/process-signature.ts";
+import { hubHome } from "./project.ts";
+import { REGISTRY_DB_BUSY_TIMEOUT_MS } from "./registry.ts";
+import { RUNTIME_PRUNE_INTERVAL_MS } from "./runtime-capture-prune.ts";
+
+export interface RuntimePruneHealthCheck { ok: boolean | undefined; name: string; detail: string }
+const MAX_LEDGER_BYTES = 1024 * 1024, MAX_OUTCOME_BYTES = 16 * 1024;
+const MAX_SCAN_ENTRIES = 1024, MAX_QUARANTINES = 64, SCAN_MS = 250;
+const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
+const columns = "slot,id,admitted_at,phase,pid,outcome";
+const issue = (detail: string, ok: boolean | undefined = undefined): RuntimePruneHealthCheck => ({ ok, name: "runtime pruning", detail });
+const info = (file: string): Stats | undefined => {
+  try { return lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+};
+const safeFile = (file: string, stat: Stats, limit: number): void => {
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || stat.size > limit) throw new Error(`unsafe metadata: ${file}`);
+};
+interface Admission { slot: number; id: string; admitted_at: number; phase: string; pid: number | null; outcome: string | null; signature: string | null; outcome_ok: number; signature_ok: number }
+interface LedgerHealth { checks: RuntimePruneHealthCheck[]; active: boolean | undefined }
+function admissionHealth(file: string): LedgerHealth {
+  let db: Database | undefined;
+  try {
+    const before = info(file); if (!before) return { checks: [], active: false };
+    safeFile(file, before, MAX_LEDGER_BYTES);
+    for (const suffix of ["-wal", "-shm", "-journal"]) { const sidecar = info(`${file}${suffix}`); if (sidecar) safeFile(`${file}${suffix}`, sidecar, MAX_LEDGER_BYTES); }
+    db = new Database(file, { readonly: true, create: false });
+    db.run(`PRAGMA busy_timeout = ${REGISTRY_DB_BUSY_TIMEOUT_MS}`);
+    const tables = db.query("SELECT name,type FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' LIMIT 2").all() as { name: string; type: string }[];
+    const shape = (db.query("PRAGMA table_info(admission)").all() as { name: string }[]).map(column => column.name).join(",");
+    if (tables.length !== 1 || tables[0]?.name !== "admission" || tables[0]?.type !== "table" || ![columns, `${columns},signature`].includes(shape)) throw new Error("unknown admission schema");
+    const signed = shape.endsWith(",signature");
+    const rows = db.query(`SELECT slot,id,admitted_at,phase,pid,CASE WHEN typeof(outcome)='text' AND length(CAST(outcome AS BLOB))<=${MAX_OUTCOME_BYTES} THEN outcome END AS outcome,
+      CASE WHEN outcome IS NULL OR (typeof(outcome)='text' AND length(CAST(outcome AS BLOB))<=${MAX_OUTCOME_BYTES}) THEN 1 ELSE 0 END AS outcome_ok,
+      ${signed ? "CASE WHEN typeof(signature)='text' AND length(CAST(signature AS BLOB))<=1024 THEN signature END" : "NULL"} AS signature,
+      ${signed ? "CASE WHEN signature IS NULL OR (typeof(signature)='text' AND length(CAST(signature AS BLOB))<=1024) THEN 1 ELSE 0 END" : "1"} AS signature_ok FROM admission LIMIT 2`).all() as Admission[];
+    const row = rows[0], after = info(file);
+    if (!after || after.dev !== before.dev || after.ino !== before.ino || after.size > MAX_LEDGER_BYTES) throw new Error("admission identity changed");
+    if (!rows.length) return { checks: [], active: false };
+    if (rows.length !== 1 || row?.slot !== 1 || row.outcome_ok !== 1 || row.signature_ok !== 1 || typeof row.id !== "string" || row.id.length !== 36 || !/^[a-f0-9-]{36}$/.test(row.id)
+      || !Number.isSafeInteger(row.admitted_at) || row.admitted_at < 0 || !["scheduled", "running", "complete"].includes(row.phase)
+      || row.pid !== null && (!Number.isSafeInteger(row.pid) || row.pid < 1)
+      || row.signature !== null && (!row.signature.trim() || Buffer.byteLength(row.signature) > 1024)) throw new Error("invalid admission row");
+    if (row.phase === "running") {
+      if (row.pid === null) throw new Error("running admission has no pid");
+      const liveness = processLiveness(row.pid, row.signature);
+      if (row.signature === null) return { active: undefined, checks: [issue(`legacy running admission has no signed worker identity${liveness === "gone" ? "; its PID is gone" : "; ownership is unknown"}; inspect ${file}`, liveness === "gone" ? false : undefined)] };
+      if (liveness === "live") return { active: true, checks: [issue(`signed maintenance worker ${row.pid} is running; ledger ${file}`, true)] };
+      return { active: liveness === "gone" ? false : undefined, checks: [issue(`maintenance worker is ${liveness === "gone" ? "gone; admission needs recovery" : "uncertain; ownership needs inspection"}; inspect ${file}`, liveness === "gone" ? false : undefined)] };
+    }
+    if (row.phase === "scheduled") {
+      if (row.pid !== null || row.signature !== null || row.outcome !== null) throw new Error("scheduled admission identity is inconsistent");
+      const age = Date.now() - row.admitted_at;
+      return { active: false, checks: age < 0 ? [issue(`scheduled admission timestamp is in the future; inspect ${file}`)]
+        : age >= RUNTIME_PRUNE_INTERVAL_MS ? [issue(`scheduled maintenance has not started within its admission interval; inspect ${file}`, false)] : [] };
+    }
+    if (typeof row.outcome !== "string") throw new Error("completed admission has no bounded outcome");
+    const outcome = JSON.parse(row.outcome) as { removed?: unknown; quarantined?: unknown; deferred?: unknown };
+    if (!outcome || typeof outcome !== "object" || Array.isArray(outcome) || Object.keys(outcome).some(key => !["removed", "quarantined", "deferred"].includes(key))
+      || !Number.isSafeInteger(outcome.removed) || (outcome.removed as number) < 0 || !Array.isArray(outcome.quarantined) || outcome.quarantined.length > MAX_QUARANTINES
+      || outcome.quarantined.some(value => typeof value !== "string" || value.length > 4096 || isAbsolute(value) || normalize(value) !== value || value.split(/[\\/]/).some(part => part === ".."))
+      || outcome.deferred !== undefined && (typeof outcome.deferred !== "string" || Buffer.byteLength(outcome.deferred) > 512)) throw new Error("invalid completed outcome");
+    if (outcome.deferred !== undefined || outcome.quarantined.length) {
+      const detail = typeof outcome.deferred === "string" ? `maintenance deferred: ${outcome.deferred.replace(/[\x00-\x1f\x7f]/g, " ")}; inspect ${file}` : `maintenance retained quarantine paths; inspect ${file}`;
+      return { active: false, checks: [issue(detail, false)] };
+    }
+    return { checks: [], active: false };
+  } catch { return { active: undefined, checks: [issue(`runtime maintenance admission is unreadable, unsafe or unknown; inspect ${file}`)] }; }
+  finally { try { db?.close(); } catch { /* Inspection never repairs or alters admission state. */ } }
+}
+
+/** Scan only the two release directory levels, never capture contents or a referenced/symlinked directory. */
+function quarantineHealth(home: string, active: boolean | undefined): RuntimePruneHealthCheck[] {
+  const releases = join(home, "releases"), checks: RuntimePruneHealthCheck[] = [];
+  let remaining = MAX_SCAN_ENTRIES, found = 0;
+  const deadline = performance.now() + SCAN_MS;
+  const scan = (directory: string, visit: (entry: Dirent) => void) => {
+    const stat = info(directory); if (!stat) return;
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("unsafe release directory");
+    const stream = opendirSync(directory);
+    try { for (;;) { const entry = stream.readSync(); if (!entry) break; if (--remaining < 0 || performance.now() > deadline) throw new Error("release inventory bound exceeded"); visit(entry); } }
+    finally { stream.closeSync(); }
+  };
+  try {
+    scan(releases, version => {
+      if (VERSION.exec(version.name)?.[0] !== version.name) return;
+      const directory = join(releases, version.name);
+      if (!version.isDirectory() || version.isSymbolicLink()) throw new Error(`unsafe version directory: ${directory}`);
+      scan(directory, entry => {
+        if (!entry.name.startsWith(".runtime-prune-")) return;
+        if (++found > MAX_QUARANTINES) throw new Error("quarantine result bound exceeded");
+        const path = join(directory, entry.name), stat = info(path); if (!stat) return;
+        const unsafe = stat.isSymbolicLink() || !stat.isDirectory();
+        checks.push({ ok: undefined, name: "runtime quarantine", detail: `${unsafe ? "unsafe reserved quarantine path" : active === true ? "maintenance quarantine is in use" : "runtime quarantine remains"}; inspect ${path}` });
+      });
+    });
+  } catch { checks.push(issue(`runtime quarantine inventory is unreadable, unsafe or exceeds its bound; inspect ${releases}`)); }
+  return checks;
+}
+
+/** Read-only doctor diagnostics. An absent ledger and quarantine inventory preserves the previous empty result. */
+export function runtimePruneHealth(home?: string): RuntimePruneHealthCheck[] {
+  try {
+    const target = home ?? hubHome(), stat = info(target);
+    if (!stat) return [];
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return [issue(`runtime maintenance home is unsafe; inspect ${target}`)];
+    const ledger = admissionHealth(join(target, "runtime-prune.db"));
+    return [...ledger.checks, ...quarantineHealth(target, ledger.active)];
+  } catch { return [issue(`runtime maintenance diagnostics are unavailable; inspect ${home ?? "the agent-hub home"}`)]; }
+}

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)".
@@ -377,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");

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/sdlc-release-authorization.ts

@@ -1,6 +1,6 @@
 import { releaseTrackedClean } from "./release-worktree.ts";
 import { createHash, randomUUID } from "node:crypto";
-import { USER } from "./envelope.ts";
+import { USER, type PeerId } from "./envelope.ts";
 import { hubGitEnv, hubGitSync } from "./git.ts";
 import { readDocEvidence, type DocEvidence, type ReleaseGit, type ReleaseReadiness } from "./sdlc-release.ts";
 import type { SdlcGh } from "./sdlc.ts";
@@ -13,13 +13,15 @@ const SHA = /^[0-9a-f]{40}$/;
 const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 export const validReleaseVersion = (value: unknown): value is string => typeof value === "string" && value.length <= 128 && VERSION.test(value);
 export interface ReleaseDocsVerdict { fresh: true; errors: 0; documents: number; digest: string }
-export interface ReleaseAuthorization { schemaVersion: 1; id: string; by: typeof USER; commit: string; version: string; at: number; docs: ReleaseDocsVerdict }
+export interface ReleaseAuthorization { schemaVersion: 1; id: string; by: PeerId; commit: string; version: string; at: number; docs: ReleaseDocsVerdict }
 export interface ReleaseAuthorizationPorts {
   git?: ReleaseGit;
   docs?: (root: string) => Promise<DocEvidence | undefined>;
   gh?: SdlcGh;
   now?: () => number;
   current?: () => boolean;
+  /** Host-only current eligible conductor; absent keeps non-person authorization refused. */
+  conductor?: () => PeerId | undefined;
   record: (receipt: ReleaseAuthorization) => boolean;
 }
 export type ReleaseGuardVerdict = { ok: true; receipts: ReleaseAuthorization[] } | { ok: false; error: string };
@@ -44,6 +46,9 @@ export class ReleaseAuthorizations {
   private latest?: Entry;
   constructor(private readonly root: string, private readonly ports: ReleaseAuthorizationPorts) {}
   private current(): void { if (this.ports.current?.() === false) throw new ReleaseAuthorizationError("release authorization unavailable during lifecycle transition"); }
+  private actor(by: PeerId): void {
+    if (by !== USER && (typeof by !== "string" || !by.trim() || this.ports.conductor?.() !== by)) throw new ReleaseAuthorizationError("only the person or the configured conductor may authorize a release");
+  }
   private git(): ReleaseGit {
     let remaining = 5000;
     return args => {
@@ -85,16 +90,17 @@ export class ReleaseAuthorizations {
     return value;
   }
   async authorize(by: string, version: unknown, expectedCommit: unknown): Promise<ReleaseAuthorization> {
-    if (by !== USER) throw new ReleaseAuthorizationError("only the person may authorize a release");
+    this.actor(by);
     if (!validReleaseVersion(version) || typeof expectedCommit !== "string" || !SHA.test(expectedCommit)) throw new ReleaseAuthorizationError("authorization needs an exact version and candidate commit");
     this.current();
     const git = this.git(), commit = this.commit(git, "HEAD"), origin = this.origin(git);
     if (commit !== expectedCommit || this.version(git, commit) !== version) throw new ReleaseAuthorizationError("candidate commit or version differs from the person's request");
     const docs = docsVerdict(await (this.ports.docs ?? readDocEvidence)(this.root), commit, version);
     if (!docs) throw new ReleaseAuthorizationError("release authorization requires fresh committed documentation evidence");
-    this.current();
+    this.current(); this.actor(by);
     if (this.commit(git, "HEAD") !== commit || this.version(git, commit) !== version || this.origin(git).hash !== origin.hash) throw new ReleaseAuthorizationError("release candidate changed during authorization");
-    const receipt: ReleaseAuthorization = { schemaVersion: 1, id: randomUUID(), by: USER, commit, version, at: (this.ports.now ?? Date.now)(), docs };
+    this.current(); this.actor(by);
+    const receipt: ReleaseAuthorization = { schemaVersion: 1, id: randomUUID(), by, commit, version, at: (this.ports.now ?? Date.now)(), docs };
     if (!this.ports.record(structuredClone(receipt))) throw new ReleaseAuthorizationError("release approval audit could not be recorded");
     const entry = { receipt, origin };
     this.entries.set(`${version}:${commit}`, entry); this.latest = entry;

package/src/hub/session-identity.ts

@@ -9,7 +9,7 @@
 
 /** 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",
+  "hub_task_show", "hub_task_list", "hub_status", "hub_capabilities", "hub_study_show", "hub_experiment_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`. */

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."}`;
+}