@staix/agent-hub 0.25.0 → 0.27.0

package/src/hub/hub-tools.ts

@@ -8,7 +8,7 @@ import { NOTE_KINDS } from "./envelope.ts";
 
 /** Restricted to the fixed current-child tools server, never an ordinary peer tool. */
 /** The fixed MCP surface of a current owned implementer child; independent of broader project roles. */
-export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_study_handoff"]);
+export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_experiment_show", "hub_experiment_record", "hub_study_handoff"]);
 
 export const IMPLEMENTER_PERMISSION_TOOL = {
   name: "hub_permission_request",
@@ -82,7 +82,7 @@ const tool = (name: string, description: string, properties: Record<string, unkn
 });
 
 /** #601: a campaign's contract and handoff are model-written text about its sources. The write tools' arguments and every study result stay out of memory capture. */
-export const STUDY_TOOLS = new Set(["hub_study_draft", "hub_study_revise", "hub_study_show", "hub_study_handoff"]);
+export const STUDY_TOOLS = new Set(["hub_study_draft", "hub_study_revise", "hub_study_show", "hub_experiment_show", "hub_experiment_record", "hub_study_handoff"]);
 /** #604: a handoff's arguments cross to another project, so neither tool's arguments nor result are captured to memory. */
 export const HANDOFF_TOOLS = new Set(["hub_task_handoff", "hub_task_handoffs"]);
 export const BOUNDED_TASK_TOOLS = new Set(["hub_task_spec", "hub_check_start", "hub_check_result", "hub_check_cancel"]);
@@ -103,6 +103,8 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_study_draft", "Store a research campaign contract as a DRAFT revision 1 on an approved parent task. Configured planners only; it creates no task, dispatches nothing and never approves (only the person approves, with ahub study approve). The contract is data: question, scope, exclusions, sourceIds, units, deliverableSections, stopPolicy and an optional budget.", { parentTaskId: id, contract: { type: "object" } }, ["parentTaskId", "contract"]),
   tool("hub_study_revise", "Store the next DRAFT revision of a research campaign with the revision you read. Configured planners only; a stale revision refuses, and a draft holds older bound work until the person approves it. Never approves.", { id: str, revision: { type: "integer", minimum: 1 }, contract: { type: "object" } }, ["id", "revision", "contract"]),
   tool("hub_study_show", "Read a research campaign's coverage and stop projection: per unit round, state, handoff completeness and budget support, and why dispatch is held. Read-only. A private campaign, task or source shows ids, counts and states only, never its question, scope, path or excerpt. Give no id to list this project's campaigns, at most 50 per call: when the reply carries `next`, pass it as `after` for the following page.", { id: str, after: str }),
+  tool("hub_experiment_record", "Record experiment metadata for your current in-progress campaign unit: protocol, attempt, event or comparison plan, or relay a signed runner receipt. The hub validates ownership, sources, campaign and signatures. It runs no command, starts no experiment and contacts no runner. Refused during a PII turn.", { kind: { type: "string", enum: ["protocol", "attempt", "event", "plan", "receipt"] }, taskId: id, protocol: { type: "object" }, attempt: { type: "object" }, attemptId: str, idempotencyKey: str, event: { type: "object" }, plan: { type: "object" }, receipt: { type: "object" }, signature: str }, ["kind"]),
+  tool("hub_experiment_show", "Read the experiment attempts of a research campaign, one attempt, or one baseline/variant comparison under a recorded plan. Read-only: it runs no command and reads no file. Every metric, hash and setting says where it came from (declared by an agent, host-observed, runner-attested or person-attested); a declared value is never shown as observed, failed, cancelled and unknown attempts stay in the counts, and a repeat is never an independent reproduction. A private campaign, task or source shows ids, counts and states only. Give campaignId (with after to page, at most 50 rows), or attemptId, or planHash with baselineAttemptId and variantAttemptId.", { campaignId: str, attemptId: str, after: { type: "integer", minimum: 0 }, eventAfter: { type: "integer", minimum: 0 }, limit: { type: "integer", minimum: 1, maximum: 50 }, planHash: str, baselineAttemptId: str, variantAttemptId: str }),
   tool("hub_task_handoff", "Hand work that belongs to ANOTHER project that runs agent-hub to that project's board. Use it instead of implementing it from this session: a feature or behavior change first needs a spec issue in that project (pass its number as issue); a mechanical chore (an exact version pin, a regenerated file) goes straight to a task. The target is a registered project (its root or id) whose hub is running; it is not queued. Planner, conductor or person only. Never for a [pii] task or during a private turn. You learn the task's state changes as kind task messages.", { project: str, title: str, class: { type: "string", description: "task class, default implement" }, detail: str, paths: { type: "array", items: str, description: "repository-relative paths in the TARGET project" }, issue: { type: "integer", minimum: 1, description: "the target repository's issue number" }, task: { type: "integer", minimum: 1, description: "your own task in THIS project that this work comes from; a [pii] task is refused" } }, ["project", "title"]),
   tool("hub_task_handoffs", "List what this project handed to other projects, with the last state each target reported. Read-only.", {}),
   tool("hub_study_handoff", "Record the handoff for the research unit you currently own and have in progress: evidence per source, unresolved questions, contradictions and limitations, or insufficientEvidence. Only the bound owner; every required field must be present. Not a task completion.", { handoff: { type: "object" } }, ["handoff"]),
@@ -194,7 +196,7 @@ export function configuredToolContext(status: unknown, peer: string): ProjectToo
   return { startPeers, readOnly: readOnlyPeers.includes(peer) };
 }
 
-const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "hub_send", "hub_inbox", "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_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "hub_send", "hub_inbox", "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"]);
 /** Publication restricts exposure only; server-side authority remains mandatory for every call. */
 export function projectToolList<T extends { name: string }>(tools: T[], readOnly = false): T[] {
   return readOnly ? tools.filter(tool => READ_ONLY_PROJECT_TOOLS.includes(tool.name)) : tools;
@@ -240,7 +242,7 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       properties.receipt = { ...receipt, properties: fields };
     }
     if (customProfile && tool.name === "hub_task_propose") properties.class = { type: "string", enum: [...new Set([...Object.keys(data.classes), ...PROFILE_CLASS_NAMES.filter(v => projectProfile("dev").classes[v])])] };
-    if (customProfile && properties.plan && tool.name !== "hub_task_accept") properties.plan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
+    if (customProfile && properties.plan && tool.name !== "hub_task_accept" && tool.name !== "hub_experiment_record") properties.plan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
     if (customProfile && tool.name === "hub_task_done" && data.name !== "dev") {
       const summaryProp = properties.summary as { type: string; description: string };
       properties.summary = {
@@ -255,7 +257,7 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       const selectedPlan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
     }
-    if (criteria && properties.plan) {
+    if (criteria && properties.plan && tool.name !== "hub_experiment_record") {
       const current = properties.plan as { properties: Record<string, unknown> };
       properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties, ...evidencePlanProperties } };
     }

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/no-writes.ts

@@ -37,7 +37,7 @@ export class NoWriteTurns {
 }
 
 
-const OWNER_TOOL_EFFECTS = new Set(["hub_task_propose", "hub_task_decline", "hub_task_done", "hub_task_cancel", "hub_task_assign", "hub_task_escalate", "hub_review", "hub_checkpoint", "hub_remember", "hub_memory_correct", "hub_check_start", "hub_check_cancel", "hub_sdlc_record", "hub_plan_review", "hub_backlog_plan", "hub_backlog_pull", "hub_backlog_undo", "hub_backlog_split", "hub_backlog_return_untouched", "hub_release_new", "hub_release_configure", "hub_release_assign", "hub_release_cut", "hub_study_handoff"]);
+const OWNER_TOOL_EFFECTS = new Set(["hub_task_propose", "hub_task_decline", "hub_task_done", "hub_task_cancel", "hub_task_assign", "hub_task_escalate", "hub_review", "hub_checkpoint", "hub_remember", "hub_memory_correct", "hub_check_start", "hub_check_cancel", "hub_sdlc_record", "hub_plan_review", "hub_backlog_plan", "hub_backlog_pull", "hub_backlog_undo", "hub_backlog_split", "hub_backlog_return_untouched", "hub_release_new", "hub_release_configure", "hub_release_assign", "hub_release_cut", "hub_study_handoff", "hub_experiment_record"]);
 /** A read does not prove progress; failed/pending mutations are handled conservatively by the host. */
 export function ownerToolEffect(op: string, input: Record<string, unknown> | undefined): boolean {
   return OWNER_TOOL_EFFECTS.has(op) || op === "hub_task_accept" && !!input?.plan && typeof input.plan === "object" && Object.keys(input.plan).length > 0;

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;
+}