@staix/agent-hub 0.25.0 → 0.26.0

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/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)");

package/src/hub/invocations.ts

@@ -1,9 +1,9 @@
 // #445 C2: read invocations. A peer asks the hub to have another peer run one capability the person shared; the target runs it in its own turn with its own
 // permissions, and the hub returns a bounded, sanitized, hub-headed result to the caller only. This file is the pure part (the gates, the argument check, the
 // two texts the hub writes) and the ledger (an ids-only `invocations` table in hub.db). It never reads a peer, a socket or the bus.
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import { createHash } from "node:crypto";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { MAX_HOP, sanitize } from "./envelope.ts";
 import type { FlatSchema, ShareState, SideEffect } from "./capabilities.ts";
 
@@ -230,8 +230,7 @@ function validateRelay(row: InvocationRow, relay: Omit<InvocationRelay, "local"
 export class InvocationLedger {
   private readonly db: Database;
   constructor(path: string, private readonly now: () => number = Date.now) {
-    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 invocations (
       id TEXT PRIMARY KEY, trace TEXT NOT NULL, caller TEXT NOT NULL, target TEXT NOT NULL, capability TEXT NOT NULL, digest TEXT NOT NULL,

package/src/hub/lifecycle.ts

@@ -1,15 +1,23 @@
+import { resolveProjectRuntime, recordProjectRuntime, confirmProjectRuntime, readProjectRuntimeForCaller, projectRuntimeRefusal, type ProjectRuntimeSelection } from "./project-runtime.ts";
+import { scheduleRuntimeCapturePrune } from "./runtime-capture-prune.ts";
+import { createProjectRuntimeAccess, type ProjectRuntimeAccess } from "./project-runtime-state.ts";
 import { isDatabaseBusyReply, RecoveryDatabaseBusy } from "./recovery-error.ts";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { createServer, type Server } from "node:net";
-import { ControlClient, PROTOCOL, readControl } from "./control-client.ts";
+import { ControlClient, PROTOCOL, PROTOCOL_MIN, controlProtocolWindow, readControl } from "./control-client.ts";
+import { negotiateProtocol, protocolWindow } from "./protocol-window.ts";
+import { assertHubDbCompatible } from "./db-schema.ts";
+import { verifyPackage, verifyRecoveryTarget } from "../cli/recovery-package.ts";
+import { VERSION } from "../version.ts";
 import { startDaemon } from "./daemon.ts";
 import { terminalOpener } from "./terminal-open.ts";
 import { Registry, type Project } from "./registry.ts";
 import { CODEX_APP, CODEX_PROXY, CONTROL } from "./ports.ts";
-import { assertLifecycleAvailable, recoveryLock } from "./recovery-store.ts";
+import { assertLifecycleAvailable, readOperation, recoveryLock } from "./recovery-store.ts";
+import { realPath } from "./project.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
 export type ProjectInspection = {
@@ -25,7 +33,9 @@ export async function inspectProject(project: Project, timeoutMs = 3000, readerP
   const control = readControl(project.stateDir);
   if (control) {
     if (processLiveness(control.pid, control.pidSignature) === "gone") return { state: "stopped" };
-    if (control.protocol !== undefined && control.protocol !== PROTOCOL) {
+    const advertised = controlProtocolWindow(control);
+    if ((control.protocol !== undefined || control.protocolMin !== undefined || control.protocolMax !== undefined)
+      && (!advertised || negotiateProtocol(protocolWindow(PROTOCOL, PROTOCOL_MIN)!, advertised) === undefined)) {
       return { state: "incompatible", error: `hub protocol ${control.protocol}; stop with its matching CLI before upgrading` };
     }
     if ((control.projectId && control.projectId !== project.id) || control.cwd !== project.root) {
@@ -87,9 +97,24 @@ async function available(base: number): Promise<boolean> {
 /** The signals the project daemon stops on (see `runProjectDaemon`). */
 export const STOP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"] as const;
 
+function startupRuntime(project: Project, env: NodeJS.ProcessEnv, registry: Registry, access: ProjectRuntimeAccess) {
+  const sourceRoot = resolve(import.meta.dir, "../.."), id = env.AGENTHUB_RECOVERY_OPERATION;
+  if (id && recoveryLock(undefined, project.root) === id) {
+    const op = readOperation<{ targetRoot?: string; targetDigest?: string; plan: { kind: "restart" | "upgrade"; version: string; projects: { project: Project }[] } }>(id);
+    if (!op.targetRoot || !op.targetDigest || op.plan.version !== VERSION || realPath(op.targetRoot) !== realPath(sourceRoot)
+      || !op.plan.projects.some(row => row.project.id === project.id && row.project.root === project.root && row.project.stateDir === project.stateDir))
+      throw new Error("recovery startup does not match its retained target runtime");
+    // Authority binds this exact target path. Do not re-stage it at a different, byte-identical path.
+    return { root: sourceRoot, digest: op.targetDigest, version: VERSION, kind: op.plan.kind, check: () => verifyRecoveryTarget(op.plan.kind, sourceRoot, VERSION) };
+  }
+  const retained = resolveProjectRuntime(project, VERSION, sourceRoot, registry, access);
+  return { ...retained, check: () => verifyRecoveryTarget(retained.kind, retained.root, retained.version) };
+}
+
 /** Called only in the detached daemon process. A competing starter exits without touching state. */
 export async function runProjectDaemon(project: Project, unattended = false): Promise<void> {
-  assertLifecycleAvailable();
+  assertLifecycleAvailable(project.root);
+  assertHubDbCompatible(join(project.stateDir, "hub.db"));
   const registry = new Registry();
   const instanceId = randomUUID();
   let claimed = false;
@@ -108,11 +133,19 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
     forcedExit.unref();
   };
   try {
+    const runtimeAccess = createProjectRuntimeAccess(project);
     const before = await inspectProject(registry.get(project.id) ?? project);
     if (before.state === "running" || before.state === "starting") return;
     if (before.state !== "stopped") throw new Error(before.error ?? before.state);
     claimed = registry.claim(project.id, instanceId, process.pid, processSignature(process.pid));
     if (!claimed) return;
+    registry.runtimeCaptureLocked(() => {
+      const runtime = startupRuntime(project, process.env, registry, runtimeAccess);
+      // Direct internal daemon entry must not bypass the selected runtime. Normal up already spawned its verified capture.
+      if (realPath(resolve(import.meta.dir, "../..")) !== runtime.root || verifyPackage(resolve(import.meta.dir, "../.."), VERSION) !== runtime.digest)
+        throw projectRuntimeRefusal(runtime.version, "start with ahub up so the recorded runtime is used");
+      recordProjectRuntime(project, runtime, instanceId, registry, runtimeAccess);
+    });
     let base = registry.get(project.id)!.basePort;
     for (let attempt = 0; attempt < 100; attempt++) {
       if (await available(base)) {
@@ -145,44 +178,69 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
 
 export async function startProject(project: Project, options: { unattended?: boolean; env?: NodeJS.ProcessEnv; liveTest?: boolean; current?: () => void } = {}): Promise<any> {
   options.current?.();
-  assertLifecycleAvailable();
+  assertLifecycleAvailable(project.root);
   const registry = new Registry();
   try {
     const current = registry.get(project.id);
     if (!current || current.root !== project.root || current.stateDir !== project.stateDir) throw new Error("project registration changed; refresh before starting");
+    const runtimeAccess = createProjectRuntimeAccess(current);
+    const admitRunningRuntime = () => {
+      const fresh = registry.get(project.id);
+      if (!fresh || fresh.root !== project.root || fresh.stateDir !== project.stateDir) throw new Error("project registration changed; refresh before starting");
+      readProjectRuntimeForCaller(fresh, VERSION, runtimeAccess);
+    };
     const before = await inspectProject(current);
     options.current?.();
-    if (before.state === "running") return before.status;
+    if (before.state === "running") { admitRunningRuntime(); return before.status; }
     if (before.state !== "stopped" && before.state !== "starting") throw new Error(before.error ?? before.state);
     if (!existsSync(join(project.root, ".agenthub", "config.json"))) throw new Error("project is not initialized; run ahub init there first");
+    let launchedRuntime: ProjectRuntimeSelection | undefined;
     if (before.state === "stopped") {
-      mkdirSync(project.stateDir, { recursive: true });
-      const marker = join(project.stateDir, "project.json");
-      const temporary = `${marker}.${randomUUID()}.tmp`;
-      writeFileSync(temporary, JSON.stringify({ root: project.root, projectId: project.id }), { mode: 0o600 });
-      renameSync(temporary, marker);
-      const log = openSync(join(project.stateDir, "hub.log"), "a");
-      try {
-        const launchEnv = { ...(options.env ?? process.env) };
-        // Native sessions can outlive the operation which launched them. An expired
-        // operation ID must not make a later ordinary startup load a retired snapshot.
-        if (launchEnv.AGENTHUB_RECOVERY_OPERATION !== recoveryLock()) delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
+      const launchEnv = { ...(options.env ?? process.env) };
+      // Expired operation ids must not make an ordinary startup load a retired snapshot.
+      if (launchEnv.AGENTHUB_RECOVERY_OPERATION !== recoveryLock(undefined, project.root)) delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
+      registry.runtimeCaptureLocked(() => {
+        const claim = registry.get(project.id);
+        if (!claim || claim.root !== project.root || claim.stateDir !== project.stateDir) throw new Error("project registration changed; refresh before starting");
+        // A competing starter owns readiness now. Never replace its selection or create a second native start.
+        if (claim.instanceId && processLiveness(claim.pid, claim.pidSignature) !== "gone") return;
+        const runtime = startupRuntime(project, launchEnv, registry, runtimeAccess);
         options.current?.();
-        const child = spawn(process.execPath, [join(import.meta.dir, "../cli/main.ts"), "--project", project.root, ...(options.liveTest ? ["--live-test"] : []), "daemon",
-          ...(options.unattended ? ["--unattended"] : [])], {
-          cwd: project.root, detached: true, stdio: ["ignore", log, log],
-          env: { ...launchEnv, AGENTHUB_STATE_DIR: project.stateDir, AGENTHUB_PROJECT_DIR: project.root,
-            AGENTHUB_UNATTENDED: options.unattended ? "1" : "0" },
-        });
-        child.on("error", () => {}); // bounded readiness below reports failure with the project's log path
-        child.unref();
-      } finally { closeSync(log); }
+        assertLifecycleAvailable(project.root);
+        if (runtime.check() !== runtime.digest) throw new Error("staged startup runtime changed");
+        // The selected runtime's own preflight decides schema compatibility; an older invoking CLI cannot preflight for it.
+        recordProjectRuntime(project, runtime, null, registry, runtimeAccess);
+        launchedRuntime = runtime;
+        mkdirSync(project.stateDir, { recursive: true });
+        const marker = join(project.stateDir, "project.json");
+        const temporary = `${marker}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify({ root: project.root, projectId: project.id }), { mode: 0o600 });
+        renameSync(temporary, marker);
+        const log = openSync(join(project.stateDir, "hub.log"), "a");
+        try {
+          options.current?.();
+          const child = spawn(process.execPath, [join(runtime.root, "src/cli/main.ts"), "--project", project.root, ...(options.liveTest ? ["--live-test"] : []), "daemon",
+            ...(options.unattended ? ["--unattended"] : [])], {
+            cwd: project.root, detached: true, stdio: ["ignore", log, log],
+            env: { ...launchEnv, AGENTHUB_STATE_DIR: project.stateDir, AGENTHUB_PROJECT_DIR: project.root,
+              AGENTHUB_UNATTENDED: options.unattended ? "1" : "0" },
+          });
+          child.on("error", () => {}); // bounded readiness below reports failure with the project's log path
+          child.unref();
+        } finally { closeSync(log); }
+      });
     }
     const deadline = Date.now() + 12_000;
     while (Date.now() < deadline) {
       const observed = await inspectProject(registry.get(project.id) ?? project);
       options.current?.();
-      if (observed.state === "running") return observed.status;
+      if (observed.state === "running") {
+        admitRunningRuntime();
+        if (launchedRuntime) confirmProjectRuntime(project, launchedRuntime, observed.status, registry, runtimeAccess);
+        // Unknown references defer maintenance; cache cleanup never changes a confirmed startup outcome.
+        try { scheduleRuntimeCapturePrune(); } catch { /* retain captures on unreadable inventory or cleanup failure */ }
+        return observed.status;
+      }
       if (observed.state === "incompatible" || observed.state === "missing") throw new Error(observed.error ?? observed.state);
       await Bun.sleep(100);
     }
@@ -200,7 +258,7 @@ function claimHeld(id: string, instanceId: string): boolean {
 }
 
 export async function stopProject(project: Project, expectedInstance?: string): Promise<void> {
-  assertLifecycleAvailable();
+  assertLifecycleAvailable(project.root);
   const inspection = await inspectProject(project);
   if (inspection.state === "stopped") return;
   if (inspection.state !== "running" && inspection.state !== "stopping") throw new Error(inspection.error ?? "hub ownership is not verified; not stopping it");

package/src/hub/manager.ts

@@ -1,13 +1,14 @@
+import { assertExecutableRuntimeRoot } from "./project-runtime-state.ts";
 import { BACKLOG_SPLIT_SCREEN_TIMEOUT_MS } from "./planning.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { Database } from "bun:sqlite";
 import { randomBytes, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { spawn } from "node:child_process";
-import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS } from "./control-client.ts";
+import { ControlClient, PROTOCOL, PROTOCOL_MIN, RECOVERY_SOURCE_PROTOCOLS, controlProtocolWindow } from "./control-client.ts";
 import { Registry, type Project } from "./registry.ts";
-import { hubHome } from "./project.ts";
+import { hubHome, realPath } from "./project.ts";
 import { startDashboard, dashboardView } from "./ui.ts";
 import { projectChain } from "@staix/agent-mem";
 import type { ProjectInspection } from "./lifecycle.ts";
@@ -22,10 +23,12 @@ export type Lifecycle = {
   stopProject(project: Project, expectedInstance?: string): Promise<void>;
 };
 export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string; orphanWatchMs?: number; liveTest?: boolean;
+  /** #608: runs after the dashboard's "start" has the hub ready, as the person's `ahub up` would, never for a live-test session. Its returned lines and any failure go to manager.log, one line each. Never part of a dashboard request. */
+  afterStart?: (project: Project) => Promise<string[]>;
   /** Test clock seam: maps nominal forwarding deadlines, never comes from dashboard input. */
   forwardTimeoutMs?: (action: string, nominalMs: number) => number };
 type ManagerHandle = { stop(): Promise<void>; stopped: Promise<void> };
-type Manifest = { port: number; protocol: number; instanceId: string; pid: number; pidSignature?: string };
+type Manifest = { port: number; protocol: number; protocolMin?: number; protocolMax?: number; instanceId: string; pid: number; pidSignature?: string; runtimeRoot?: string };
 const active = new Map<string, { handle: ManagerHandle; issue(liveTest?: boolean): string }>();
 const CONTROL_TIMEOUT = 3000;
 // A current CLI may authenticate the previous protocol-9 manager while
@@ -80,7 +83,7 @@ function removeManifest(home: string, instanceId: string) {
 }
 
 /** The manager's project listing and forwarding (#935): shared by `ahub ui --all` and the acon plugin, never widened for either. */
-export function projectConsole(options: { registry: Registry; lifecycle: Lifecycle; home: string; stopping?: () => boolean; forwardTimeoutMs?: ManagerOptions["forwardTimeoutMs"] }) {
+export function projectConsole(options: { registry: Registry; lifecycle: Lifecycle; home: string; stopping?: () => boolean; forwardTimeoutMs?: ManagerOptions["forwardTimeoutMs"]; afterStart?: ManagerOptions["afterStart"] }) {
   const { registry, lifecycle, home } = options;
   const aliases = new Map<string, { at: number; names: string[] }>();
   const list = async () => {
@@ -102,7 +105,7 @@ export function projectConsole(options: { registry: Registry; lifecycle: Lifecyc
     }));
     return { ok: true, mode: "all", projects: rows };
   };
-  const act = async (input: Record<string, unknown>) => {
+  const act = async (input: Record<string, unknown>, session?: { liveTest?: true }) => {
     if (options.stopping?.()) return { ok: false, error: "manager is stopping" };
     const project = typeof input.projectId === "string" ? registry.get(input.projectId) : undefined;
     if (!project) return { ok: false, error: "unknown project" };
@@ -110,6 +113,14 @@ export function projectConsole(options: { registry: Registry; lifecycle: Lifecyc
     try {
       if (input.action === "start") {
         const status = await bounded(lifecycle.startProject(project, { unattended: false, env: { ...scrubEnv(process.env), AGENTHUB_HOME: home } }), 20_000);
+        // The agents start in the background: the dashboard's answer is the hub's readiness, and a terminal that is slow to open must not hold it.
+        // A live-test dashboard session is an agent borrowing the person's console: it never opens the person's default agents. The session, not this process, carries that flag.
+        if (options.afterStart && session?.liveTest !== true) {
+          const stamp = (line: string) => `${new Date().toISOString()} default agents for ${project.id}: ${line.replace(/[\x00-\x1f\x7f]+/g, " ").slice(0, 600)}`;
+          void options.afterStart(project).then(
+            lines => { for (const line of lines) console.error(stamp(line)); },
+            error => { console.error(stamp(`not started: ${safeError(error)}`)); });
+        }
         return { ok: true, projectId: project.id, instanceId: status.instanceId };
       }
       if (typeof input.instanceId !== "string" || !input.instanceId) return { ok: false, error: "expected daemon instance is required" };
@@ -181,31 +192,36 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
     cleanup(); resolveStopped();
   };
   try {
-    owner = claimOwner(f.owner, instanceId, pidSignature);
-    const { list, act } = projectConsole({ registry, lifecycle, home, stopping: () => stopping, forwardTimeoutMs: options.forwardTimeoutMs });
-    dashboard = startDashboard({ projects: list, snapshot: (after, input = {}) => act({ ...input, action: "snapshot", after }), action: act });
-    server = Bun.serve({ hostname: "127.0.0.1", port: 0, maxRequestBodySize: 1024,
-      async fetch(req) {
-        if (req.headers.has("origin")) return new Response("forbidden", { status: 403 });
-        if (req.headers.get("authorization") !== `Bearer ${token}`) return new Response("unauthorized", { status: 401 });
-        if (req.method !== "POST") return new Response("POST required", { status: 405 });
-        const expected = req.headers.get("x-agenthub-instance");
-        if (expected && expected !== instanceId) return Response.json({ ok: false, error: "manager instance changed" }, { status: 409 });
-        if (stopping) return Response.json({ ok: false, error: "manager is stopping" }, { status: 409 });
-        const path = new URL(req.url).pathname;
-        if (path === "/open") {
-          const input = await req.json().catch(() => ({})) as { liveTest?: boolean };
-          return Response.json({ ok: true, instanceId, protocol: PROTOCOL, url: dashboard!.issue(false, input.liveTest === true), ...(input.liveTest === true ? { liveTest: true } : {}) });
-        }
-        if (path === "/stop") { setTimeout(() => void stop(), 0); return Response.json({ ok: true, instanceId }); }
-        return new Response("not found", { status: 404 });
-      },
-    });
-    writeFileSync(f.token, token, { mode: 0o600 });
-    chmodSync(f.token, 0o600);
-    const temp = `${f.status}.${instanceId}.tmp`;
-    writeFileSync(temp, JSON.stringify({ port: server.port, protocol: PROTOCOL, instanceId, pid: process.pid, ...(pidSignature ? { pidSignature } : {}) }));
-    renameSync(temp, f.status);
+    const publicationRegistry = typeof registry.runtimeCaptureLocked === "function" && typeof registry.path === "string"
+      && resolve(registry.path) === resolve(join(home, "registry.db")) ? registry : new Registry(join(home, "registry.db"));
+    try { publicationRegistry.runtimeCaptureLocked(() => {
+      assertExecutableRuntimeRoot(realPath(resolve(import.meta.dir, "../..")));
+      owner = claimOwner(f.owner, instanceId, pidSignature);
+      const { list, act } = projectConsole({ registry, lifecycle, home, stopping: () => stopping, forwardTimeoutMs: options.forwardTimeoutMs, ...(options.afterStart && !options.liveTest ? { afterStart: options.afterStart } : {}) });
+      dashboard = startDashboard({ projects: list, snapshot: (after, input = {}) => act({ ...input, action: "snapshot", after }), action: act });
+      server = Bun.serve({ hostname: "127.0.0.1", port: 0, maxRequestBodySize: 1024,
+        async fetch(req) {
+          if (req.headers.has("origin")) return new Response("forbidden", { status: 403 });
+          if (req.headers.get("authorization") !== `Bearer ${token}`) return new Response("unauthorized", { status: 401 });
+          if (req.method !== "POST") return new Response("POST required", { status: 405 });
+          const expected = req.headers.get("x-agenthub-instance");
+          if (expected && expected !== instanceId) return Response.json({ ok: false, error: "manager instance changed" }, { status: 409 });
+          if (stopping) return Response.json({ ok: false, error: "manager is stopping" }, { status: 409 });
+          const path = new URL(req.url).pathname;
+          if (path === "/open") {
+            const input = await req.json().catch(() => ({})) as { liveTest?: boolean };
+            return Response.json({ ok: true, instanceId, protocol: PROTOCOL_MIN, protocolMin: PROTOCOL_MIN, protocolMax: PROTOCOL, url: dashboard!.issue(false, input.liveTest === true), ...(input.liveTest === true ? { liveTest: true } : {}) });
+          }
+          if (path === "/stop") { setTimeout(() => void stop(), 0); return Response.json({ ok: true, instanceId }); }
+          return new Response("not found", { status: 404 });
+        },
+      });
+      writeFileSync(f.token, token, { mode: 0o600 });
+      chmodSync(f.token, 0o600);
+      const temp = `${f.status}.${instanceId}.tmp`;
+      writeFileSync(temp, JSON.stringify({ port: server.port, protocol: PROTOCOL_MIN, protocolMin: PROTOCOL_MIN, protocolMax: PROTOCOL, instanceId, pid: process.pid, ...(pidSignature ? { pidSignature } : {}), runtimeRoot: realPath(resolve(import.meta.dir, "../..")) }), { mode: 0o600 });
+      renameSync(temp, f.status);
+    }); } finally { if (publicationRegistry !== registry) publicationRegistry.close(); }
     // The manager outlives whoever opened it; a deleted AGENTHUB_HOME (a test suite's temp
     // home, issue #56) must not leave it serving a registry that no longer exists.
     orphanWatch = setInterval(() => {
@@ -222,7 +238,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
 async function managerRequest(home: string, path: "/open" | "/stop", liveTest = false): Promise<{ status: Manifest; body: any }> {
   const status = readManifest(home);
   if (!status) throw new Error("manager manifest is unavailable");
-  if (!SUPPORTED_MANAGER_PROTOCOLS.has(status.protocol)) throw new Error("manager protocol is incompatible; use its matching CLI to stop it");
+  if (!SUPPORTED_MANAGER_PROTOCOLS.has(status.protocol) || !controlProtocolWindow(status)) throw new Error("manager protocol is incompatible; use its matching CLI to stop it");
   const token = readFileSync(files(home).token, "utf8").trim();
   if (!token) throw new Error("manager token is unavailable");
   const response = await fetch(`http://127.0.0.1:${status.port}${path}`, {
@@ -275,7 +291,7 @@ export async function openManager(options: ManagerOptions = {}): Promise<string>
 export async function refreshManager(options: ManagerOptions = {}): Promise<string> {
   const home = options.home ?? hubHome();
   const manifest = readManifest(home);
-  if (manifest && manifest.protocol !== PROTOCOL && RECOVERY_SOURCE_PROTOCOLS.includes(manifest.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number])) {
+  if (manifest && (controlProtocolWindow(manifest)?.v ?? Infinity) < PROTOCOL && RECOVERY_SOURCE_PROTOCOLS.includes(manifest.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number])) {
     await managerRequest(home, "/stop");
     const deadline = Date.now() + CONTROL_TIMEOUT;
     while (Date.now() < deadline && readManifest(home)) await Bun.sleep(25);

package/src/hub/orca-env.ts

@@ -0,0 +1,19 @@
+/**
+ * #613 (agent-hub#1048): the one source of truth for the Orca terminal environment. No imports, so every layer can read it
+ * (the launcher, the hub's terminal opener, the test preload and the gate's comment).
+ *
+ * The Orca launcher decides whether to open a terminal in the person's running Orca from these four names, so a process
+ * that inherits them reaches that Orca. A hub or a test run started from an Orca pane inherits them, so tests and the gate
+ * start with the whole `ORCA_` prefix removed and a test that wants one sets it itself.
+ */
+export const ORCA_LAUNCHER_ENV: readonly string[] = Object.freeze(["ORCA_CLI_COMMAND", "ORCA_DEV_REPO_ROOT", "ORCA_TERMINAL_HANDLE", "ORCA_WORKTREE_ID"]);
+
+/** Every variable an Orca terminal exports: the launcher's four and the rest of the pane's environment. */
+export const isOrcaEnvName = (name: string): boolean => name.startsWith("ORCA_");
+
+/** A copy of `env` with every `ORCA_` variable removed. */
+export function withoutOrcaEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const out: NodeJS.ProcessEnv = { ...env };
+  for (const name of Object.keys(out)) if (isOrcaEnvName(name)) delete out[name];
+  return out;
+}