@staix/agent-hub 0.25.0 → 0.27.0

package/src/hub/daemon.ts

@@ -174,9 +174,11 @@ import { githubOriginRepository, githubRemoteRepository } from "./task-repositor
 import { Bus } from "./bus.ts";
 import { attribute, deliveryTask, type TaskAttribution } from "./attribution.ts";
 import { DeliveryJournal } from "./delivery-journal.ts";
+import { assertHubDbCompatible } from "./db-schema.ts";
 import { startDashboard, dashboardView, type DashboardSession } from "./ui.ts";
 import { codeGroup } from "./task-code-group.ts";
-import { ControlClient, DAEMON_FEATURES, PROTOCOL, readControl, stateDirFor } from "./control-client.ts";
+import { ControlClient, DAEMON_FEATURES, PROTOCOL, PROTOCOL_MIN, readControl, stateDirFor } from "./control-client.ts";
+import { negotiateProtocol, protocolWindow } from "./protocol-window.ts";
 import { attachEvent, originOf, type Origin } from "./provenance.ts";
 import { mintSessionId, sessionGate } from "./session-identity.ts";
 import { MAX_HOP, newEnvelope, parseMarker, replyParent, sanitize, USER, type Envelope, type PeerId, type Priority } from "./envelope.ts";
@@ -185,6 +187,7 @@ import { ClaudeTodoSource, DoingTracker, readAiTitle, type DoingKind, type PeerD
 import { MemoryClient } from "../memory/client.ts";
 import { VERSION } from "../version.ts";
 import { appendRecords, taskRecords } from "./research.ts";
+import { parseResearchRunners, type RegisteredRunnerV1 } from "./research-runner.ts";
 import { benchReport, MIN_ATTEMPTS, readRuns, runSummary, type Measures, type RunSummary } from "./bench.ts";
 import { projectChain } from "@staix/agent-mem";
 import { recallFor } from "../memory/recall.ts";
@@ -199,6 +202,7 @@ import { consumeRecoveryContinuity, readRecoveryContinuity, retireRecoveryContin
 import { shellQuote, publishTerminalLaunch, terminalLaunchCandidate, launcherOf } from "../cli/terminal-recovery.ts";
 import { TerminalLaunches, terminalOwnerReads } from "./terminal-launch.ts";
 
+import { START_AGENTS_DEFAULT, checkStartAgents } from "./start-agents.ts";
 import { peerStartConfig, PEER_START_RETRY_MS, startModeOf, terminalTemplate, type PeerStartConfig, type StartMode } from "./start-mode.ts";
 import { hasKimiHubMcp } from "../cli/kimi-mcp.ts";
 import type { TerminalOpener } from "./terminal-open.ts";
@@ -281,13 +285,15 @@ export interface HubConfig {
   /** A git tree at each turn boundary for `ahub turns` and `ahub undo`, the last `keep` per peer (issue #33). */
   snapshots: { enabled: boolean; keep: number };
   /** #247: opt-in research records of each approved task in ~/.agenthub/research (ids, counts and tokens only). */
-  research: { enabled: boolean };
+  research: { enabled: boolean; runners?: Record<string, RegisteredRunnerV1> };
   /** #251: a project kept for benchmarks: `ahub bench run` resets its work tree between attempts. */
   bench: { enabled: boolean };
   /** #269: per peer, how a start comes up when nothing more specific was asked: `tui` (the default) or `headless`. Pi and Codex only. */
   peers: PeerStartConfig;
   /** #269: a machine-local argv that opens a terminal for a hub-made TUI start; `{command}` in one element is the command to run. */
   terminal: { open: string[] };
+  /** #608: the peers `ahub up` asks the hub to start, machine-local. Read by the CLI at a person's `ahub up` and by the dashboard manager's start; the daemon itself never starts one from it. */
+  start: { agents: string[] };
   /** Per-sender rate limits and repeat suppression for what agents send (issue #38). */
   limits: LimitsConfig;
   /** Reviewer choice from recorded review outcomes, once a reviewer has `min_reviews` of an implementer (issue #35). */
@@ -353,6 +359,7 @@ export const DEFAULT_CONFIG: HubConfig = {
   bench: { enabled: false },
   peers: {},
   terminal: { open: [] },
+  start: { agents: [...START_AGENTS_DEFAULT] },
   limits: DEFAULT_LIMITS,
   review: { adaptive: false, min_reviews: 5 },
   recovery: { auto_resume_after_crash: false, reconnect_wait_s: RECOVERY_RECONNECT_WAIT_SETTING.defaultValue, unmanaged_reconnect_wait_s: RECOVERY_UNMANAGED_RECONNECT_WAIT_SETTING.defaultValue, control_timeout_s: RECOVERY_CONTROL_TIMEOUT_SETTING.defaultValue, shutdown_wait_s: RECOVERY_SHUTDOWN_WAIT_SETTING.defaultValue, terminal_idle_wait_s: RECOVERY_TERMINAL_IDLE_WAIT_SETTING.defaultValue },
@@ -363,14 +370,29 @@ export const DEFAULT_CONFIG: HubConfig = {
 export { stateDirFor };
 
 /** Ids an external process may not claim: the console user and the adapters the daemon runs itself. */
-const READ_ONLY_HUB_TOOLS = new Set(["hub_capabilities", "hub_inbox", "hub_send", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
+const READ_ONLY_HUB_TOOLS = new Set(["hub_capabilities", "hub_inbox", "hub_send", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_experiment_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
 const BASE_RESERVED_IDS = new Set<string>([USER, ...SUPPORTED_PEERS.filter(peer => definitionOf(peer)?.attach?.externalHello !== true), HUB, DIGEST]);
 const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 
 /** The shared project config, then the machine's own file, which overrides it block by block (issue #17). */
 const CONFIG_FILES = INSTANCE_CONFIG_FILES;
 export interface ConfigLayer { name: typeof CONFIG_FILES[number]; raw: Record<string, any> }
-const CONFIG_BLOCKS = ["action_policy", "memory", "roster", "roles", "catalog_roles", "pii", "data", "conductor", "budget", "context", "inference", "omniroute", ...NATIVE_CONFIG_BLOCKS, "approvals", "tasks", "task_sweep", "bus", "adapter_timing", "model_relay", "console", "corpus", "checks", "snapshots", "research", "bench", "limits", "review", "recovery", "capabilities", "mlx", "permission_modes", "peers", "terminal", "pet"];
+const CONFIG_BLOCKS = ["action_policy", "memory", "roster", "roles", "catalog_roles", "pii", "data", "conductor", "budget", "context", "inference", "omniroute", ...NATIVE_CONFIG_BLOCKS, "approvals", "tasks", "task_sweep", "bus", "adapter_timing", "model_relay", "console", "corpus", "checks", "snapshots", "research", "bench", "limits", "review", "recovery", "capabilities", "mlx", "permission_modes", "peers", "terminal", "start", "pet"];
+
+/** Older targets parse raw keys before placement/trust checks, so even an empty or refused declaration needs the floor. */
+function rawResearchRunnersPresent(cwd: string): boolean {
+  const texts = configSourceTexts(cwd);
+  let present = false;
+  for (const name of CONFIG_FILES) {
+    if (texts[name] === null) continue;
+    const raw: unknown = JSON.parse(texts[name]!);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("invalid configuration");
+    const research = (raw as Record<string, unknown>).research;
+    if (research !== undefined && (!research || typeof research !== "object" || Array.isArray(research))) throw new Error("invalid research configuration");
+    present ||= research !== undefined && Object.hasOwn(research, "runners");
+  }
+  return present;
+}
 
 /** Connection-time policy refresh reads role/feed fields only, never launches or machine-local configuration. */
 export function loadConductorPolicy(cwd: string, layers?: readonly ConfigLayer[], scope: Pick<ReturnType<typeof readInstanceConfig>, "instances" | "catalog"> = readInstanceConfig(cwd, layers)): { roles: Record<string, string[]>; conductor: HubConfig["conductor"]; planner?: string | string[]; notices?: string[] } {
@@ -478,6 +500,8 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
     peerStartConfig(file.peers, instances, adapterCatalog);
     if (file.terminal != null && (typeof file.terminal !== "object" || Array.isArray(file.terminal))) throw new Error("terminal must be an object");
     terminalTemplate(file.terminal?.open);
+    if (file.start != null && (typeof file.start !== "object" || Array.isArray(file.start) || Object.keys(file.start).some((key: string) => key !== "agents"))) throw new Error("start must be an object with an agents list");
+    if (file.start?.agents !== undefined) checkStartAgents(file.start.agents);
     if (file.pet !== undefined) validatePetConfig(file.pet, "config.pet");
     if (file.pet && typeof file.pet === "object" && !Object.keys(file.pet).length) delete file.pet;
     delete file.declaredExternalInstances; // host-derived refusal rows, never a file claim
@@ -487,8 +511,11 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
       if (name !== "config.local.json" || configTracked(cwd, name) !== false) throw new Error("remote checks require untracked config.local.json");
       if (file.checks.remote !== undefined) remoteRunnerConfig(file.checks.remote);
     }
+    if (file.research !== undefined && (!file.research || typeof file.research !== "object" || Array.isArray(file.research))) throw new Error("research must be an object");
+    const hasRunners = file.research && Object.hasOwn(file.research, "runners"), runnerDeclarations: unknown = hasRunners ? file.research.runners : undefined;
     const why = stripUntrusted(file, DEFAULT_CONFIG, cwd, name);
     if (why) ignored.push(why);
+    if (hasRunners) file.research.runners = parseResearchRunners(runnerDeclarations);
     for (const [peer, mode] of Object.entries(permissionDefaults(file.permission_modes, instances, adapterCatalog))) appliedPermissionSources[peer] = { mode, source: `.agenthub/${name}` };
     return [file];
   });
@@ -575,10 +602,11 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
     checks: { ...DEFAULT_CONFIG.checks, ...file.checks, runner: file.checks?.runner === "remote" ? "remote" : file.checks?.runner === "container" ? "container" : undefined,
       ...(file.checks?.remote !== undefined || file.checks?.runner === "remote" ? { remote: remoteRunnerConfig(file.checks?.remote) } : {}) },
     snapshots: { ...DEFAULT_CONFIG.snapshots, enabled: true, ...file.snapshots },
-    research: { enabled: file.research?.enabled === true }, // opt-in: anything but true is off
+    research: { enabled: file.research?.enabled === true, ...(file.research?.runners !== undefined ? { runners: parseResearchRunners(file.research.runners) } : {}) }, // opt-in: anything but true is off
     bench: { enabled: file.bench?.enabled === true }, // opt-in: a run resets this project's work tree
     peers: { ...instanceModes, ...peerStartConfig(file.peers, instances, adapterCatalog) },
     terminal: { open: terminalTemplate(file.terminal?.open) },
+    start: { agents: file.start?.agents === undefined ? [...START_AGENTS_DEFAULT] : checkStartAgents(file.start.agents) },
     limits: { ...PROJECT_LIMITS, ...file.limits }, // on with any project config (issue #38)
     review: { ...DEFAULT_CONFIG.review, ...file.review },
     recovery: { ...DEFAULT_CONFIG.recovery, ...file.recovery },
@@ -698,6 +726,7 @@ export interface DaemonOptions {
 
 interface Client {
   authed: boolean;
+  protocol?: number;
   role?: "peer" | "console" | "tools";
   peer?: PeerId;
   /** agent-hub#1036: this connection is a distinct session; `peer` is the id the daemon minted for it (`<peer>~<origin>`), never a bus peer. */
@@ -747,6 +776,8 @@ function capturedRecoverySourceDigest(): string | undefined {
 }
 
 export async function startDaemon(opts: DaemonOptions) {
+  // Refuse unknown formats before logs, session cleanup, module factories or any writable store is opened.
+  assertHubDbCompatible(join(opts.stateDir, "hub.db"));
   const resolveExecutionCwd = (peer: string, currentDeclarations: InstancesConfig | undefined, currentRoles: readonly string[], catalog: ReturnType<typeof createProjectAdapterCatalog>): string =>
     resolveInstanceExecutionCwd(opts.cwd, peer, currentDeclarations, currentRoles, catalog, undefined, undefined, opts.instanceExecutionGit);
   const projectId = opts.projectId ?? randomUUID();
@@ -2048,6 +2079,12 @@ export async function startDaemon(opts: DaemonOptions) {
   };
   const tasks: Tasks = new Tasks({
     releaseWindow,
+    researchRunners: () => {
+      if (config.research.runners === undefined) return {};
+      const why = configRefusal(opts.cwd, "config.local.json");
+      if (why || configSourceTexts(opts.cwd)["config.local.json"] === null) throw new Error(`research.runners source trust unavailable${why ? `: ${why}` : ""}`);
+      return parseResearchRunners(config.research.runners);
+    },
     capabilities: peerCapabilities, repository: memoryRepo,
     contextAdmission: () => ({
       policy: { max_used: config.context.max_assignment_used ?? 0, stale_min: config.context.stale_min },
@@ -3483,6 +3520,7 @@ export async function startDaemon(opts: DaemonOptions) {
     }
     // Inside a PII turn the worker's words may carry the PII whatever they are attached to: a note would go to
     // shared memory and a new task could be routed to a cloud peer without matching any pattern.
+    if (op === "hub_experiment_record" && (piiTurn || turns.get(by)?.private || contextPii(by))) throw new PreEffectToolRefusal(`${op} is not available while working on a PII task: its text must not leave this machine`);
     if (piiTurn && (MEMORY_READ_TOOLS.has(op) || op === "hub_memory_correct" || op === "hub_remember" || op === "hub_task_propose" || op === "hub_sdlc_record" || op === "hub_plan_review" || op === "hub_sdlc_costs" || op === "hub_sdlc_metrics" || op.startsWith("hub_release_") || op === "hub_backlog_return_untouched" || op === "hub_backlog_plan" || op === "hub_backlog_undo" || op === "hub_backlog_pull" || op === "hub_backlog_split" || op === "release_new" || op === "hub_study_draft" || op === "hub_study_revise")) throw new PreEffectToolRefusal(`${op} is not available while working on a PII task: its text must not leave this machine`);
     // The same words attached to an ordinary task would reach its reviewer, its owner, overlapping owners (a plan, the
     // completed-change notice) and shared memory. A turn that holds a PII task acts on ordinary tasks in a turn of its own.
@@ -3697,6 +3735,11 @@ export async function startDaemon(opts: DaemonOptions) {
         return JSON.stringify(await tasks.studyRevise(by, a));
       case "hub_study_show":
         return JSON.stringify(a.id === undefined ? tasks.studyList(by, a) : tasks.studyShow(by, a));
+      // #602 (issue 932 T3): the read of the experiment records Tasks already keeps; it runs nothing and reads no file, and a private record is blanked inside the view.
+      case "hub_experiment_show":
+        return JSON.stringify(await tasks.experimentShow(by, a));
+      case "hub_experiment_record":
+        return JSON.stringify(await tasks.experimentRecord(by, a));
       case "hub_study_handoff":
         if (!a || typeof a !== "object" || Array.isArray(a) || Object.keys(a).some(key => key !== "handoff")) throw new PreEffectToolRefusal("study handoff takes only a handoff object");
         return JSON.stringify(await tasks.studyHandoff(by, a.handoff));
@@ -4217,7 +4260,11 @@ export async function startDaemon(opts: DaemonOptions) {
     docs: opts.releaseDocEvidence,
     gh: (args, timeout) => sdlcGh(args, timeout, opts.cwd),
     current: () => !stopping && !recoveryActive() && !bus.isRecoveryHeld,
-    record: receipt => event({ type: "release_authorization", by: "user", authorization: receipt.id, commit: receipt.commit, version: receipt.version, docsDigest: receipt.docs.digest, documents: receipt.docs.documents }),
+    conductor: () => {
+      const peer = conductorPeer(config.roles);
+      return peer && !turns.get(peer)?.private && !contextPii(peer) ? peer : undefined;
+    },
+    record: receipt => event({ type: "release_authorization", by: receipt.by, authorization: receipt.id, commit: receipt.commit, version: receipt.version, docsDigest: receipt.docs.digest, documents: receipt.docs.documents }),
   });
   const terminalReads = terminalOwnerReads();
   const terminalLaunches = new TerminalLaunches({
@@ -4400,6 +4447,7 @@ export async function startDaemon(opts: DaemonOptions) {
     const metadata = peer.recoveryMetadata?.() ?? {};
     const row: RestartPeerSnapshot = { id, state: peer.state, queueIds: bus.queueIds(id), ...(metadata.launch ? { launch: metadata.launch as Record<string, unknown> } : {}) };
     if (typeof metadata.threadId === "string") row.threadId = metadata.threadId;
+    if (typeof metadata.controlProtocol === "number" && Number.isSafeInteger(metadata.controlProtocol) && metadata.controlProtocol > 0) row.controlProtocol = metadata.controlProtocol;
     const sessionId = definitionOf(id)?.transport === "claude-channel" ? claudeSession(id).sessionId : metadata.sessionId;
     if (typeof sessionId === "string" && sessionId) row.sessionId = sessionId;
     return [id, row];
@@ -4422,7 +4470,8 @@ export async function startDaemon(opts: DaemonOptions) {
     const researchDispatch = board.researchDispatchIntegrity();
     const researchExperiments = board.researchExperimentsIntegrity();
     const researchComparisons = board.researchComparisonIntegrity();
-    return { queues, manualPaused: [...manualPaused].sort(), boardDigest: digest(boardState), budgetDigest: digest(budgetState), ...(research.campaigns || research.units ? { research } : {}), ...(researchDispatch.activations || researchDispatch.handoffs ? { researchDispatch } : {}), ...(researchExperiments.protocols || researchExperiments.attempts || researchExperiments.events || researchExperiments.observations ? { researchExperiments } : {}), ...(researchComparisons.plans || researchComparisons.approvals || researchComparisons.contexts ? { researchComparisons } : {}), ...(allExternalInstanceIds().length ? { externalBindingsDigest: digest(allExternalInstanceIds().sort().map(id => [id, (externalRefusedRows.has(id) ? externalBindings.get(id) : retainedExternalBinding(id)) ?? null])) } : {}) };
+    const researchRunners = board.runnerReceiptIntegrity();
+    return { queues, manualPaused: [...manualPaused].sort(), boardDigest: digest(boardState), budgetDigest: digest(budgetState), ...(research.campaigns || research.units ? { research } : {}), ...(researchDispatch.activations || researchDispatch.handoffs ? { researchDispatch } : {}), ...(researchExperiments.protocols || researchExperiments.attempts || researchExperiments.events || researchExperiments.observations ? { researchExperiments } : {}), ...(researchComparisons.plans || researchComparisons.approvals || researchComparisons.contexts ? { researchComparisons } : {}), ...(researchRunners.count ? { researchRunners } : {}), ...(allExternalInstanceIds().length ? { externalBindingsDigest: digest(allExternalInstanceIds().sort().map(id => [id, (externalRefusedRows.has(id) ? externalBindings.get(id) : retainedExternalBinding(id)) ?? null])) } : {}) };
   };
   /** The integrity in the shape `expected` was recorded in: the current one unless only an older shape matches. */
   const integrityAs = (expected: unknown) => {
@@ -4512,7 +4561,7 @@ export async function startDaemon(opts: DaemonOptions) {
     ...(lifecycleConfig.mode !== "off" ? { lifecycleCriteria: true } : {}),
     // Every supported peer's membership, for launchers that run outside the console role (#484).
     roster: [...KNOWN_PEERS, ...OPTIONAL_PEERS].map(peer => ({ peer, on: onRoster(peer) })),
-    protocol: PROTOCOL,
+    protocol: PROTOCOL_MIN, protocolMin: PROTOCOL_MIN, protocolMax: PROTOCOL,
     features: DAEMON_FEATURES,
     configuredAdapters: configuredIds,
     ...(externalAdapters.length ? { externalAdapters } : {}),
@@ -6708,6 +6757,7 @@ export async function startDaemon(opts: DaemonOptions) {
     // Retired dictionaries never enter active publication; hub ids remain opaque keys.
     if (prefix === "routing.targets" || prefix === "routing.routes") return [];
     if (prefix === "routing.hub_routes") return [prefix];
+    if (prefix === "research.runners") return [prefix];
     if (value && typeof value === "object" && !Array.isArray(value)) return Object.entries(value).flatMap(([key, child]) => declaredPaths(child, prefix ? `${prefix}.${key}` : key));
     return prefix ? [prefix] : [];
   }
@@ -7586,6 +7636,12 @@ export async function startDaemon(opts: DaemonOptions) {
         // Raw presence matters even for a disabled or ignored shared declaration: an older target parses the unknown key first.
         if (namesRunners) return "target lacks research_records; the project's research.runners cannot be loaded by that daemon";
       }
+      if (!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("research_runners")) {
+        if (board.hasRunnerReceipts()) return "target lacks research_runners; persisted runner attestations require a supporting daemon";
+        try {
+          if (config.research.runners !== undefined || rawResearchRunnersPresent(opts.cwd)) return "target lacks research_runners; the project's research.runners requires a supporting daemon";
+        } catch { return "research_runners compatibility is unknown; configuration could not be read"; }
+      }
       if ((!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("research_dispatch")) && board.hasResearchDispatchState())
         return "target lacks research_dispatch; persisted campaign stop policies and handoffs require a supporting daemon";
       if ((!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("research_dropped_offers")) && board.hasResearchDroppedOffers())
@@ -7637,8 +7693,16 @@ export async function startDaemon(opts: DaemonOptions) {
         } catch { return "calendar_schedules compatibility is unknown; configuration could not be read"; }
         if (namesCalendar) return "target lacks calendar_schedules; the project's schedules use cron or tz, which that daemon cannot load";
       }
+      if (!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("schema_guard"))
+        return "target lacks schema_guard; controlled recovery requires a guard-aware runtime";
       return undefined;
     };
+    // Preserve lifecycle fences before capability probes; the prepare branch rechecks them after resume capture awaits.
+    if (msg.op === "prepare") {
+      if (rosterChanging) return recoveryError("roster change is in progress; wait for ahub status before preparing recovery");
+      if (requestedPeerStops.size) return recoveryError("peer stop is in progress; wait for ahub status before preparing recovery");
+      if (recoveryCommitted) return recoveryError("recovery commit is already in progress");
+    }
     const checkTarget = msg.op === "prepare" || msg.op === "commit" || msg.op === "inspect" && msg.targetFeatures !== undefined;
     if (checkTarget) {
       const error = incompatibleRecoveryTarget(); if (error) return recoveryError(error);
@@ -7906,7 +7970,8 @@ export async function startDaemon(opts: DaemonOptions) {
     if (!c.authed) {
       if (msg.t !== "hello" || msg.token !== token) return sock.close(4401, "bad token");
       if (typeof msg.peer === "string" && msg.peer.includes("@")) return sock.close(4403, "remote identities have no control connection");
-      if (msg.v !== PROTOCOL) {
+      const offered = protocolWindow(msg.v, msg.vMin), selectedProtocol = offered && negotiateProtocol({ v: PROTOCOL, vMin: PROTOCOL_MIN }, offered);
+      if (selectedProtocol === undefined) {
         // An outdated plugin would drop every digest without a trace. Refuse it loudly instead.
         log(`refused ${msg.role} ${msg.peer ?? ""}: wire version ${msg.v ?? 1}, hub speaks ${PROTOCOL} (claude plugin update agent-hub@agent-hub)`);
         return sock.close(4426, `wire version mismatch: hub speaks ${PROTOCOL}; update the agent-hub plugin`);
@@ -7917,6 +7982,7 @@ export async function startDaemon(opts: DaemonOptions) {
       try { refreshConductorPolicy(); } catch { return sock.close(4403, "invalid conductor role/feed configuration"); }
       if (stopping && msg.role !== "console") return sock.close(1013, "hub is stopping");
       c.authed = true;
+      c.protocol = selectedProtocol;
       c.role = msg.role;
       if (c.role === "console") consoles.add(sock);
       else if (c.role === "tools" && sessionHello(msg)) {
@@ -8003,7 +8069,7 @@ export async function startDaemon(opts: DaemonOptions) {
       }
       // #604 PR B: one attach event per admitted peer or tools hello, with the same fields an envelope's `origin` carries. A refused hello returned above and writes none.
       if (c.role === "peer" || c.role === "tools") event(attachEvent({ role: c.role, peer: c.peer, launchId: c.launchId, ...(c.session ? { session: true } : {}) }));
-      return void reply({ t: "welcome", projectId, instanceId, cwd: opts.cwd, protocol: PROTOCOL, features: DAEMON_FEATURES, ...(c.session ? { session: c.peer } : {}) });
+      return void reply({ t: "welcome", projectId, instanceId, cwd: opts.cwd, protocol: c.protocol, protocolMin: PROTOCOL_MIN, protocolMax: PROTOCOL, features: DAEMON_FEATURES, ...(c.session ? { session: c.peer } : {}) });
     }
     const committedSourceProof = c.role === "tools" && msg.t === "recovery_authority" && msg.op === "verify" && recoveryCommitted
       && msg.binding?.operationId === recoveryOperationId && msg.binding?.sourceInstanceId === instanceId;
@@ -8272,11 +8338,15 @@ export async function startDaemon(opts: DaemonOptions) {
             const plan = msg.plan as UpgradePlan;
             const { fingerprint, ...body } = plan ?? {} as UpgradePlan;
             if (!plan || !["restart", "upgrade"].includes(plan.kind) || plan.projects.some(row => row.terminals.length > 0) || planFingerprint(body) !== fingerprint || fingerprint !== raw.planFingerprint || plan.kind !== raw.kind || existsSync(operationPath(raw.operationId))
-              || raw.sourceInstanceId !== instanceId || recoveryActive() || recoveryLock() || !plan.projects.some(row => row.project.id === projectId && row.project.root === opts.cwd && row.project.stateDir === opts.stateDir && row.source.instanceId === instanceId)) throw new RecoveryAuthorityError();
+              || raw.sourceInstanceId !== instanceId || recoveryActive() || recoveryLock(undefined, opts.cwd) || !plan.projects.some(row => row.project.id === projectId && row.project.root === opts.cwd && row.project.stateDir === opts.stateDir && row.source.instanceId === instanceId)) throw new RecoveryAuthorityError();
+            const { recoveryScope } = await import("../cli/upgrade.ts"); current();
+            const scope = recoveryScope(plan);
+            if (scope !== undefined && scope !== opts.cwd) throw new RecoveryAuthorityError();
             if (plan.kind === "restart" && plan.projects.length !== 1) throw new RecoveryAuthorityError();
             if (plan.kind === "upgrade") {
-              // Shared package/plugin effects cover every running or uncertain registered project, not a caller-selected subset.
+              // Scoped upgrades bind the source's one registered project; retained shared upgrades still cover every affected project.
               const affected = registeredProjects().filter(project => {
+                if (scope !== undefined) return project.root === scope;
                 const control = readControl(project.stateDir);
                 return control ? processLiveness(control.pid, control.pidSignature) !== "gone" : project.pid !== null && processLiveness(project.pid, project.pidSignature) !== "gone";
               });
@@ -8289,23 +8359,26 @@ export async function startDaemon(opts: DaemonOptions) {
               if (!Array.isArray(selected.reconnectOnly) || new Set(selected.reconnectOnly).size !== selected.reconnectOnly.length) throw new RecoveryAuthorityError();
               for (const id of selected.reconnectOnly) {
                 const row = selected.source.peers.find(peer => peer.id === id), owner = bus.peers.get(id), definition = definitionOf(id);
-                if (!row || selected.freshStart?.includes(id) || Object.keys(row).some(key => !["id", "state", "observation"].includes(key)) || !row.observation
+                if (!row || selected.freshStart?.includes(id) || Object.keys(row).some(key => !["id", "state", "observation", "controlProtocol"].includes(key)) || !row.observation
                   || Object.keys(row.observation).some(key => !["kind", "attached", "sessionDigest"].includes(key))
                   || !isWsPeer(owner) || definition?.transport !== "claude-channel" || !owner.attached || owner.managedLaunchId || claudeLaunchProof.verified(id)
+                  || !protocolWindow(row.controlProtocol) || owner.recoveryMetadata().controlProtocol !== row.controlProtocol
                   || row.observation.kind !== definition.kind || row.observation.attached !== owner.attached || row.observation.sessionDigest !== recoverySessionDigest(claudeSession(id).sessionId)) throw new RecoveryAuthorityError();
                 const generation = owner.sessionGeneration;
                 const launcher = await launcherOf(id, opts.cwd, { stateDir: opts.stateDir, instanceId }); current();
-                if (launcher && launcher.state !== "gone" || bus.peers.get(id) !== owner || owner.sessionGeneration !== generation || !owner.attached || owner.managedLaunchId || claudeLaunchProof.verified(id)) throw new RecoveryAuthorityError();
+                if (launcher && launcher.state !== "gone" || bus.peers.get(id) !== owner || owner.sessionGeneration !== generation || !owner.attached || owner.managedLaunchId || claudeLaunchProof.verified(id)
+                  || owner.recoveryMetadata().controlProtocol !== row.controlProtocol) throw new RecoveryAuthorityError();
                 reconnectCurrent.push(() => bus.peers.get(id) === owner && owner.sessionGeneration === generation && owner.attached && !owner.managedLaunchId && !claudeLaunchProof.verified(id)
+                  && owner.recoveryMetadata().controlProtocol === row.controlProtocol
                   && definitionOf(id)?.kind === row.observation!.kind && owner.attached === row.observation!.attached && recoverySessionDigest(claudeSession(id).sessionId) === row.observation!.sessionDigest);
                 reconnect.set(id, row.observation);
               }
             }
             if (reconnectCurrent.some(check => !check())) throw new RecoveryAuthorityError();
-            const normalize = (row: { id: string; state: string; observation?: { kind: string; attached: boolean; sessionDigest?: string }; threadId?: string; sessionId?: string; sessionFile?: string; args?: Record<string, string>; launch?: Record<string, unknown> }) => {
+            const normalize = (row: { id: string; state: string; controlProtocol?: number; observation?: { kind: string; attached: boolean; sessionDigest?: string }; threadId?: string; sessionId?: string; sessionFile?: string; args?: Record<string, string>; launch?: Record<string, unknown> }) => {
               const launch = row.args ?? row.launch ?? {};
               const observed = reconnect.get(row.id);
-              return { id: row.id, active: row.state !== "offline", threadId: row.threadId, sessionId: observed ? undefined : row.sessionId,
+              return { id: row.id, active: row.state !== "offline", controlProtocol: row.controlProtocol, threadId: row.threadId, sessionId: observed ? undefined : row.sessionId,
                 ...(observed ? { sessionDigest: row.observation?.sessionDigest ?? recoverySessionDigest(row.sessionId) } : {}),
                 ...(observed ? { kind: row.observation?.kind ?? definitionOf(row.id)?.kind, attached: row.observation?.attached ?? (isWsPeer(bus.peers.get(row.id)) && (bus.peers.get(row.id) as import("../adapters/channel-peer.ts").WsPeer).attached) } : {}),
                 sessionFile: row.sessionFile ?? (typeof launch.sessionFile === "string" ? launch.sessionFile : undefined),
@@ -8319,9 +8392,11 @@ export async function startDaemon(opts: DaemonOptions) {
             if (raw.kind === "restart") {
               if (!sourcePackageDigest || raw.targetDigest !== sourcePackageDigest) throw new RecoveryAuthorityError();
             } else {
-              const staged = join(hubHome(), "releases", plan.version);
-              if (raw.targetRoot !== join(staged, "node_modules/@staix/agent-hub")) throw new RecoveryAuthorityError();
-              const verified = JSON.parse(readFileSync(join(staged, "verified.json"), "utf8"));
+              const staged = join(scope === undefined ? hubHome() : realPath(hubHome()), "releases", plan.version);
+              const expectedTarget = scope === undefined ? join(staged, "node_modules/@staix/agent-hub") : join(staged, `source-${raw.targetDigest}`);
+              if (raw.targetRoot !== expectedTarget) throw new RecoveryAuthorityError();
+              // A new/expired grant still needs registry proof; verification of an already issued grant below uses only retained target bytes.
+              const verified = JSON.parse(readFileSync(join(scope === undefined ? staged : join(staged, "registry"), "verified.json"), "utf8"));
               if (verified.digest !== raw.targetDigest || verified.integrity !== plan.integrity) throw new RecoveryAuthorityError();
             }
             if (!sourcePackageDigest || plan.sourceDigest !== sourcePackageDigest && (plan.kind !== "upgrade" || plan.sourceDigest !== raw.targetDigest)) throw new RecoveryAuthorityError();
@@ -8726,6 +8801,15 @@ export async function startDaemon(opts: DaemonOptions) {
           );
           return;
         }
+        if (msg.op === "authorize-release") {
+          const asker = c.role === "console" ? USER : c.role === "tools" && c.peer && conductorPeer(config.roles) === c.peer && !c.toolsOwner && !turns.get(c.peer)?.private && !contextPii(c.peer) ? c.peer : undefined;
+          if (!asker) return void reply({ ok: false, error: "only the console user or the configured conductor may authorize a release" });
+          void releaseAuthorizations.authorize(asker, msg.version, msg.commit).then(
+            authorization => reply({ ok: true, authorization }),
+            error => reply({ ok: false, error: releaseAuthorizationError(error) }),
+          );
+          return;
+        }
         if (c.role !== "console" && ["status", "explain", "queue", "release"].includes(msg.op)) {
           let current: () => void;
           try { current = publicReadCurrent(sock); current(); } catch { return void reply({ ok: false, error: "public lifecycle read unavailable for this caller" }); }
@@ -8766,13 +8850,6 @@ export async function startDaemon(opts: DaemonOptions) {
           return;
         }
         if (c.role !== "console") return void reply({ ok: false, error: "SDLC readback is console only; task owners record ids through hub_sdlc_record" });
-        if (msg.op === "authorize-release") {
-          void releaseAuthorizations.authorize(USER, msg.version, msg.commit).then(
-            authorization => reply({ ok: true, authorization }),
-            error => reply({ ok: false, error: releaseAuthorizationError(error) }),
-          );
-          return;
-        }
         if (msg.op === "queue" || msg.op === "release") {
           if (typeof msg.repo !== "string" || !Array.isArray(msg.liveIssues ?? []) || (msg.liveIssues ?? []).length > 32) return void reply({ ok: false, error: "invalid delivery readback arguments" });
           const read = msg.op === "queue" ? tasks.deliveryQueue(msg.repo) : tasks.releaseReadiness(msg.repo, msg.liveIssues ?? []);

package/src/hub/db-schema.ts

@@ -0,0 +1,143 @@
+import { constants, Database } from "bun:sqlite";
+export type { Database } from "bun:sqlite";
+import { closeSync, lstatSync, openSync, readSync, statSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { VERSION } from "../version.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+
+/** Bump only for an incompatible hub.db format; compatible releases keep the introducing version. */
+export const HUB_DB_SCHEMA = 2;
+/** New/legacy databases keep format 1 until an incompatible record is committed. */
+export const HUB_DB_BASE_SCHEMA = 1;
+/** schema is the maximum supported format, never a request to migrate an existing compatible database. */
+export interface HubDbSchemaReader { schema: number; version: string }
+export interface HubDatabaseOptions {
+  readonly?: boolean;
+  create?: boolean;
+  reader?: HubDbSchemaReader;
+}
+export class HubDbSchemaError extends Error {
+  readonly code = "HUB_DB_SCHEMA";
+  constructor(message: string, readonly requiredVersion?: string) { super(message); this.name = "HubDbSchemaError"; }
+}
+interface HubDbSchema { schema: number; requiredVersion: string }
+const VERSION_TEXT = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+const safeVersion = (value: unknown): value is string => typeof value === "string" && value.length <= 64 && VERSION_TEXT.exec(value)?.[0] === value;
+const defaultReader = (): HubDbSchemaReader => ({ schema: HUB_DB_SCHEMA, version: VERSION });
+const invalidSchema = () => new HubDbSchemaError("this project's hub.db schema metadata is invalid; inspect or restore the database before starting agent-hub");
+const busy = (error: unknown): boolean => {
+  const value = error as { code?: unknown; message?: unknown } | null;
+  return typeof value?.code === "string" && /^SQLITE_(BUSY|LOCKED)(?:_|$)/.test(value.code)
+    || typeof value?.message === "string" && /database (?:is )?(?:locked|busy)|database table is locked/i.test(value.message);
+};
+function readerValue(reader: HubDbSchemaReader): HubDbSchemaReader {
+  if (!reader || !Number.isSafeInteger(reader.schema) || reader.schema < 1 || !safeVersion(reader.version)) throw invalidSchema();
+  return { schema: reader.schema, version: reader.version };
+}
+
+/** No persistent PRAGMA or schema/data write runs while reading the marker. */
+function schemaOn(db: Database): HubDbSchema | undefined {
+  try {
+    const entries = db.query("SELECT type FROM sqlite_master WHERE name='hub_schema' COLLATE NOCASE LIMIT 2").all() as { type: string }[];
+    if (!entries.length) return undefined;
+    if (entries.length !== 1 || entries[0]!.type !== "table") throw invalidSchema();
+    const rows = db.query("SELECT id,schema,CASE WHEN typeof(required_version)='text' AND length(CAST(required_version AS BLOB))<=64 THEN required_version END AS required_version FROM hub_schema LIMIT 2")
+      .all() as { id: number; schema: number; required_version: string | null }[];
+    const row = rows[0];
+    if (rows.length !== 1 || !row || row.id !== 1 || !Number.isSafeInteger(row.schema) || row.schema < 1 || !safeVersion(row.required_version)) throw invalidSchema();
+    return { schema: row.schema, requiredVersion: row.required_version };
+  } catch (error) {
+    // Native corruption is unreadable storage, not a parsed schema claim; reset may archive it intact.
+    const code = (error as { code?: unknown } | null)?.code;
+    if (error instanceof HubDbSchemaError || busy(error) || typeof code === "string" && /^(?:SQLITE_NOTADB|SQLITE_CORRUPT)(?:_|$)/.test(code)) throw error;
+    throw invalidSchema();
+  }
+}
+function checkOn(db: Database, reader: HubDbSchemaReader): HubDbSchema | undefined {
+  const stored = schemaOn(db);
+  if (stored && stored.schema > reader.schema) throw new HubDbSchemaError(`this project was opened by agent-hub ${stored.requiredVersion}; use ${stored.requiredVersion} or later`, stored.requiredVersion);
+  return stored;
+}
+function existingFile(file: string): boolean {
+  if (file === ":memory:") return false;
+  let info;
+  try { info = lstatSync(file); }
+  catch (error) { if ((error as { code?: string }).code === "ENOENT") return false; throw error; }
+  // A dangling link or non-file is unknown storage, never a missing legacy database.
+  if (info.isSymbolicLink()) { try { info = statSync(file); } catch { throw invalidSchema(); } }
+  if (!info.isFile()) throw invalidSchema();
+  return true;
+}
+
+/** Closed, checkpointed WAL files need a quiet metadata probe on macOS; unknown file/mode state never qualifies. */
+function checkpointedWal(file: string): boolean {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, "r");
+    const header = Buffer.alloc(20);
+    return readSync(fd, header, 0, header.length, 0) === header.length && header.toString("ascii", 0, 15) === "SQLite format 3"
+      && header[15] === 0 && header[18] === 2 && header[19] === 2;
+  } catch { return false; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+function noSidecars(file: string): boolean {
+  for (const suffix of ["-wal", "-shm", "-journal"]) {
+    try { lstatSync(`${file}${suffix}`); return false; }
+    catch (error) { if ((error as { code?: string }).code !== "ENOENT") return false; }
+  }
+  return true;
+}
+function probeCompatible(file: string, reader: HubDbSchemaReader, quiet: boolean): void {
+  const uri = pathToFileURL(file); uri.searchParams.set("immutable", "1");
+  const db = quiet ? new Database(uri.href, constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI) : new Database(file, { readonly: true, create: false });
+  try {
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`); // connection-local, not persisted
+    checkOn(db, reader);
+  } finally { db.close(); }
+}
+
+/** Live WAL reads may take SHM read locks. Refusal performs no SQL/schema/data or DB/WAL write; SHM locks are SQLite's ceiling. */
+export function assertHubDbCompatible(file: string, reader: HubDbSchemaReader = defaultReader()): void {
+  const supported = readerValue(reader);
+  if (!existingFile(file)) return;
+  if (checkpointedWal(file) && noSidecars(file)) {
+    // This handle is short-lived and never escapes. A live returned handle must continue observing later WAL commits.
+    let failure: unknown, failed = false;
+    try { probeCompatible(file, supported, true); } catch (error) { failure = error; failed = true; }
+    if (!noSidecars(file)) { probeCompatible(file, supported, false); return; }
+    if (failed) throw failure;
+    return;
+  }
+  probeCompatible(file, supported, false);
+}
+
+/** Every hub.db writer enters here before its own persistent PRAGMAs, migrations or maintenance writes. */
+export function openHubDatabase(file: string, options: HubDatabaseOptions = {}): Database {
+  const reader = readerValue(options.reader ?? defaultReader());
+  // Refuse a future file without opening a writable connection, which can perform SQLite recovery work itself.
+  assertHubDbCompatible(file, reader);
+  const db = new Database(file, options.readonly ? { readonly: true, create: false } : { readwrite: true, create: options.create ?? true });
+  try {
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    if (options.readonly) { checkOn(db, reader); return db; }
+    // The second read and legacy baseline stamp share the writer lock, without filesystem work in SQL.
+    // Existing compatible markers never advance here; an incompatible migration must advance its marker with its actual DDL/data transaction.
+    db.transaction(() => {
+      const stored = checkOn(db, reader);
+      if (!stored) {
+        db.run("CREATE TABLE hub_schema (id INTEGER PRIMARY KEY CHECK(id=1),schema INTEGER NOT NULL,required_version TEXT NOT NULL)");
+        db.query("INSERT INTO hub_schema(id,schema,required_version) VALUES(1,?,?)").run(HUB_DB_BASE_SCHEMA, VERSION);
+      }
+    }).immediate();
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+
+/** The format marker advances only in the same transaction as the incompatible data it protects. */
+export function advanceHubDbSchema(db: Database, schema: number, requiredVersion: string): void {
+  if (!db.inTransaction || !Number.isSafeInteger(schema) || schema < HUB_DB_BASE_SCHEMA || schema > HUB_DB_SCHEMA || !safeVersion(requiredVersion))
+    throw new HubDbSchemaError("hub.db schema advance requires an active data transaction and a supported format");
+  const stored = checkOn(db, defaultReader());
+  if (!stored) throw invalidSchema();
+  if (stored.schema < schema) db.query("UPDATE hub_schema SET schema=?,required_version=? WHERE id=1").run(schema, requiredVersion);
+}

package/src/hub/delivery-journal.ts

@@ -1,12 +1,12 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import type { BusSnapshot } from "./bus.ts";
 import type { QueuePressure } from "./queue-backpressure.ts";
 import { HUB, KINDS, USER, type Envelope, type Kind } from "./envelope.ts";
 import { heldDeliveryHints } from "./delivery-hints.ts";
 import { processLiveness } from "../pi/process-signature.ts";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { parseRemotePeerId } from "../rooms/application.ts";
 import { validateDeferredHub } from "./deferred-hub.ts";
 
@@ -282,8 +282,7 @@ export class DeliveryJournal {
     this.operationId = options.operationId;
     this.terminalHistoryLimit = options.terminalHistoryLimit;
     mkdirSync(dirname(options.file), { recursive: true, mode: 0o700 });
-    this.db = new Database(options.file, { create: true });
-    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db = openHubDatabase(options.file, { create: true });
     this.harden();
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run("PRAGMA synchronous = FULL");

package/src/hub/events.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
 import type { TaskAttribution } from "./attribution.ts";
+import type { PeerId } from "./envelope.ts";
 import type { SwitchTrace } from "../models/route/stage.ts";
 import type { ScreenRecord } from "./inference.ts";
 
@@ -13,7 +14,7 @@ export const EVENTS_SCHEMA = 1;
  * ids, routing and sizes, tasks carry ids and states, so the file can be exported without leaking what agents wrote.
  */
 export type HubEvent =
-  | { type: "release_authorization"; by: "user"; authorization: string; commit: string; version: string; docsDigest: string; documents: number }
+  | { type: "release_authorization"; by: PeerId; authorization: string; commit: string; version: string; docsDigest: string; documents: number }
   | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
   | { type: "role"; peer?: string; task?: number; actor: string; stage: "prepared" | "assigned"; roles: { id: string; layer: "shipped" | "project"; hash: string }[] }
   /** A settings change (#269): the registry key, the bounded registry values before/after and their source; an optional person reason is sanitized and capped at 400 UTF-8 bytes. */

package/src/hub/execution-budget.ts

@@ -1,6 +1,6 @@
 import { definitionOf, type KindMap } from "../adapters/registry.ts";
-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";
 
 export type ExecutionUnit = "model_calls" | "tool_calls" | "elapsed_ms" | "tokens";
 export type ExecutionBudgetLimits = Partial<Record<ExecutionUnit, number>>;
@@ -43,8 +43,7 @@ const validLimits = (raw: ExecutionBudgetLimits): ExecutionBudgetLimits => {
 export class ExecutionBudget {
   private readonly db: Database;
   constructor(path: string, private readonly instances?: KindMap) {
-    this.db = new Database(path, { create: true });
-    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db = openHubDatabase(path, { create: true });
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`CREATE TABLE IF NOT EXISTS execution_budgets (
       id TEXT PRIMARY KEY, kind TEXT NOT NULL, task_id INTEGER, peers TEXT NOT NULL,

package/src/hub/folder-trigger.ts

@@ -1,10 +1,10 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { isDenied } from "../local/deny.ts";
 import { checkCorpusRoot } from "./corpus.ts";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { realPath } from "./project.ts";
 import { folderGlobMatches, MAX_NEW_PER_POLL, type FolderEntry, type FolderRunResult, type FolderScan, type ScannedFile } from "./schedules.ts";
 import { MAX_SOURCE_BYTES, screenRegistration, type SourceRegistry } from "./sources.ts";
@@ -169,8 +169,7 @@ export interface FolderSeenRow { trigger: string; real_path: string; size: numbe
 export class FolderStore {
   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 folder_seen (trigger TEXT NOT NULL, real_path TEXT NOT NULL, size INTEGER NOT NULL, mtime INTEGER NOT NULL, sha256 TEXT NOT NULL, task INTEGER, at INTEGER NOT NULL, PRIMARY KEY (trigger, real_path, sha256))");
     this.db.run("CREATE INDEX IF NOT EXISTS folder_seen_hash ON folder_seen (trigger, sha256)");
     this.db.run("CREATE TABLE IF NOT EXISTS folder_poll (trigger TEXT PRIMARY KEY, started INTEGER NOT NULL, baselined INTEGER NOT NULL DEFAULT 0, last_poll INTEGER, last_error TEXT)");