@staix/agent-hub 0.24.0 → 0.26.0

package/src/hub/budget.ts

@@ -1,7 +1,7 @@
 import { definitionOf, type AdapterDefinition } from "../adapters/registry.ts";
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import type { PeerId } from "./envelope.ts";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { windowKind, type WindowKind } from "./window-kind.ts";
 export { windowKind, type WindowKind };
 
@@ -136,8 +136,7 @@ export class Budget {
     private readonly hooks: BudgetHooks,
     private readonly now: () => number = Date.now,
   ) {
-    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 budget_pauses (peer TEXT PRIMARY KEY, since INTEGER NOT NULL, resets_at INTEGER NOT NULL,
       reason TEXT NOT NULL, summary TEXT, handed_off INTEGER NOT NULL DEFAULT 0, moved TEXT NOT NULL DEFAULT '[]')`);
     try { this.normalizeStoredPauses(); } catch (error) { this.db.close(); throw error; }

package/src/hub/channel-project.ts

@@ -0,0 +1,61 @@
+// Which project and state directory the Claude channel plugin joins (#604 PR B, agent-hub#1030 item 10). It applies the same decision the CLI makes at startup: `projectContext` for an
+// ordinary process, plus the one exception the CLI has for a declared extra instance, whose cwd is its own managed worktree and whose state directory is the main project's by design.
+// Without this the plugin trusted an inherited AGENTHUB_STATE_DIR as is, so a Claude process started in `<repo>/.worktrees/<name>` that inherited the main checkout's variables joined the
+// main repository's hub.
+//
+// Limit, stated plainly: this stops accidental and inherited-environment joins. It is not a defence against a same-user process that sets the variables and the launch evidence itself.
+import { definitionOf } from "../adapters/registry.ts";
+import { readInstanceConfig } from "./instance-config.ts";
+import { effectiveInstanceRoles } from "./instances.ts";
+import { resolveInstanceExecutionCwd } from "./instance-execution.ts";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalPath, inheritedStateDir, projectContext, projectRoot, realPath } from "./project.ts";
+
+export interface ChannelProject {
+  root: string; stateDir: string;
+  /** True when the state directory came from the inherited environment, proven. */
+  inherited: boolean;
+  /**
+   * Set when this process has no project of its own and an inherited state directory that records another project (agent-hub#1036): it joins that hub as a distinct session, never as the
+   * peer id it names. `label` is the origin part of the id the hub mints (`<peer>~<label>`), or empty to let the hub choose a short one.
+   */
+  session?: { label: string };
+}
+
+/**
+ * `cwd` is the plugin process's working directory, `env` its environment, `policyRoles(root)` the configured roles of a project (the same merge the plugin and the CLI use).
+ * Returns `undefined` only when there is nothing to join at all: no project of its own and no inherited state directory. Everything else joins something (agent-hub#1036: nothing that
+ * works today is refused): the proven project, the cwd's own project, or, when the process cannot prove it belongs to the hub its environment names, that hub as a distinct session.
+ */
+export function channelProject(cwd: string, env: NodeJS.ProcessEnv, policyRoles: (root: string) => Record<string, string[]>): ChannelProject | undefined {
+  const override = env.AGENTHUB_STATE_DIR?.trim(), declared = env.AGENTHUB_PROJECT_DIR?.trim();
+  // A tools-mode helper (`AGENTHUB_MODE=tools`) is started by the hub or by an agent the hub started, with the state dir and project dir set for exactly that purpose: the Claude implementer child and
+  // an external-module instance run in their own managed worktree and must reach the owning hub, as they always did. The daemon checks their launch id itself at the hello. The root check below is
+  // for a channel session, a person's `claude` that may merely have inherited a pair (review thread on #1037; agent-hub#1036 AC4).
+  if (env.AGENTHUB_MODE === "tools" && override && declared) return { root: canonicalPath(declared), stateDir: canonicalPath(override), inherited: true };
+  // The origin label is left empty on purpose: the hub mints a short id, so no directory name reaches a header another agent reads.
+  const asSession = (): ChannelProject | undefined => override
+    ? { root: declared ? canonicalPath(declared) : "", stateDir: canonicalPath(override), inherited: false, session: { label: "" } } : undefined;
+  let own: ReturnType<typeof projectContext>;
+  try { own = projectContext(cwd, {}); } catch { return asSession(); }
+  const peer = env.AGENTHUB_PEER_ID;
+  if (peer && declared && !definitionOf(peer)) {
+    // A declared extra instance: its workspace is the exact managed worktree the project declares for it, and its hub is the project that declares it.
+    try {
+      const root = realPath(declared), config = readInstanceConfig(root);
+      if (config.instances && Object.hasOwn(config.instances, peer)) {
+        const workspace = resolveInstanceExecutionCwd(root, peer, config.instances, effectiveInstanceRoles(peer, config.instances, policyRoles(root), config.catalog), config.catalog);
+        if (realPath(projectRoot(cwd)) !== realPath(workspace)) return asSession();
+        const stateDir = inheritedStateDir(root, env);
+        return stateDir ? { root, stateDir, inherited: true } : asSession();
+      }
+    } catch { return asSession(); }
+  }
+  const inherited = inheritedStateDir(own.root, env);
+  if (inherited) return { root: own.root, stateDir: inherited, inherited: true };
+  // No project of its own (no .agenthub/config.json up to the git boundary) and an inherited state directory that is not proven to belong here: it joins that hub as a distinct session.
+  // With a project of its own (a linked worktree, say) it keeps that project's own hub, as before.
+  if (override && !existsSync(join(own.root, ".agenthub", "config.json"))) return asSession();
+  return { root: own.root, stateDir: own.stateDir, inherited: false };
+}

package/src/hub/child-process.ts

@@ -1,4 +1,5 @@
 import type { ChildProcess } from "node:child_process";
+import { withoutOrcaEnv } from "./orca-env.ts";
 
 /**
  * Recovery authority belongs to the short-lived ahub wrapper/launcher. Native
@@ -19,9 +20,9 @@ export function childEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.Proces
  * typed or started there has the console's identity, whatever started the hub.
  */
 export function personEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  const env = childEnv(source);
-  // The Orca terminal the hub itself was started in is not this new terminal: a launch there must not record it as its own.
-  for (const name of ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "AGENTHUB_CHANNEL", "AGENTHUB_PEER_ID", "AGENTHUB_UNATTENDED", "ORCA_TERMINAL_HANDLE", "ORCA_WORKTREE_ID"]) delete env[name];
+  // The Orca terminal the hub itself was started in is not this new terminal: a launch there must not record it as its own, so every ORCA_ variable goes (#613).
+  const env = withoutOrcaEnv(childEnv(source));
+  for (const name of ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "AGENTHUB_CHANNEL", "AGENTHUB_PEER_ID", "AGENTHUB_UNATTENDED"]) delete env[name];
   return env;
 }
 

package/src/hub/conductor.ts

@@ -1,5 +1,6 @@
 import { definitionOf, type KindMap, type ProjectAdapterCatalog } from "../adapters/registry.ts";
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import type { Task } from "./board.ts";
 import { CONDUCTOR_TOOL_NAMES } from "./hub-tools.ts";
 import { HUB, sanitize, USER } from "./envelope.ts";
@@ -11,7 +12,6 @@ import type { SupervisionFeed } from "./supervision.ts";
 import { DOING_STUB, type PeerDoing } from "./peer-doing.ts";
 import type { Budget } from "./budget.ts";
 import { windowKind, type WindowKind } from "./window-kind.ts";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { supportsHeadlessInstances } from "./instances.ts";
 
 /** The production ProgressObserver sink forwards structured verdicts, never its observations/reasoning. */
@@ -72,8 +72,7 @@ export interface ConductorHold { peer: string; actor: string; since: number }
 export class ConductorHolds {
   private readonly db: Database;
   constructor(dbPath: string, private readonly now: () => number = Date.now) {
-    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 conductor_holds (peer TEXT PRIMARY KEY, actor TEXT NOT NULL, since INTEGER NOT NULL)");
     this.db.run("CREATE TABLE IF NOT EXISTS supervision_rounds (peer TEXT PRIMARY KEY, signature TEXT NOT NULL)");
   }

package/src/hub/config-apply.ts

@@ -1,4 +1,5 @@
 import { operationalNumber, OPERATIONAL_NUMBERS } from "./operational-settings.ts";
+import { parseResearchRunners } from "./research-runner.ts";
 import { QUEUE_BACKPRESSURE_LIMITS } from "./queue-backpressure.ts";
 import { operationalSettingKey } from "./operational-authority.ts";
 import { remoteRunnerConfig } from "./check-runner.ts";
@@ -14,6 +15,7 @@ import { createProjectAdapterCatalog, type ProjectAdapterCatalog, ADAPTERS, DEFA
 import { CLASSES } from "./board.ts";
 import { permissionDefaults } from "./permission-mode.ts";
 import { peerStartConfig, terminalTemplate } from "./start-mode.ts";
+import { checkStartAgents } from "./start-agents.ts";
 import { catalogAssignments } from "./roles.ts";
 import { resolveProfile } from "./profiles.ts";
 import { foldersConfig, schedulesConfig } from "./schedules.ts";
@@ -62,6 +64,12 @@ export interface ConfigAuthorizationDecision { key: string; allowed: boolean; gu
 export function authorizeConfigLeaf(input: ConfigAuthorizationInput): ConfigAuthorizationDecision {
   const { key, before, after } = input;
   const result = (allowed: boolean, guarded: boolean, reason: string): ConfigAuthorizationDecision => ({ key, allowed, guarded, reason });
+  const runners = key === "research.runners" || key.startsWith("research.runners.") || key === "research"
+    && [before, after].some(value => !!value && typeof value === "object" && Object.hasOwn(value, "runners"));
+  if (runners) {
+    if (input.source !== "config" || input.sourceFile !== "config.local.json" || input.tracked !== false) return result(false, true, "research.runners requires untracked config.local.json");
+    if (input.authority === "conductor") return result(false, true, "runner registration is person only");
+  }
   if (key === "action_policy" || key.startsWith("action_policy.")) {
     if (input.sourceFile !== "config.local.json") return result(false, true, "action policy requires .agenthub/config.local.json");
     if (input.tracked !== false) return result(false, true, "action policy requires an untracked machine-local source");
@@ -175,6 +183,8 @@ export const validatePetConfig: Check = (v, k) => {
 };
 shapes.set(validatePetConfig, { fields: petFields });
 const nativeValidators = { bool, text, strings, argv, number, words, block };
+const researchRunners: Check = value => { parseResearchRunners(value); };
+shapes.set(researchRunners, { item: block({ publicKey: text, projects: strings, revoked: bool }) });
 const schema: Record<string, Check> = {
   _autonomy: v => { autonomyOwnership(v); },
   ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.schema?.(nativeValidators) ?? {})),
@@ -214,9 +224,10 @@ const schema: Record<string, Check> = {
     else if (key === "remote") remoteRunnerConfig(value);
     else if (/^[a-z][a-z0-9_]{0,47}$/.test(key)) text(value, `${k}.${key}`); else fail(`${k}.${key}`, "unknown key");
   } },
-  snapshots: block({ enabled: bool, keep: number(1, 1_000_000, true) }), research: block({ enabled: bool }), bench: block({ enabled: bool }),
+  snapshots: block({ enabled: bool, keep: number(1, 1_000_000, true) }), research: block({ enabled: bool, runners: researchRunners }), bench: block({ enabled: bool }),
   peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), START_MODE_PEERS)(v, k); peerStartConfig(v); },
   terminal: (v, k) => { block({ open: strings })(v, k); terminalTemplate(object(v, k).open); },
+  start: (v, k) => { block({ agents: strings })(v, k); if (object(v, k).agents !== undefined) checkStartAgents(object(v, k).agents, `${k}.agents`); },
   limits: block({ sender_per_min: number(0), pair_per_min: number(0), important_per_hour: number(0), repeat_window_s: number(0) }),
   review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true), pool: v => { reviewerPoolConfig({ pool: v }, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS); }, rerotate: bool, same_family: words(["fallback", "never"]) }), recovery: block({ auto_resume_after_crash: bool, reconnect_wait_s: operationalNumberCheck("recovery.reconnect_wait_s"), unmanaged_reconnect_wait_s: operationalNumberCheck("recovery.unmanaged_reconnect_wait_s"), control_timeout_s: operationalNumberCheck("recovery.control_timeout_s"), shutdown_wait_s: operationalNumberCheck("recovery.shutdown_wait_s"), terminal_idle_wait_s: operationalNumberCheck("recovery.terminal_idle_wait_s") }),
   capabilities: map(strings), invocation: block({ share: map(map(() => {})), timeout_s: number(10, 86_400, true) }), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
@@ -269,7 +280,7 @@ export function configApply(key: string, scopes: readonly ConfigIdentityScope[]
   if (top !== "routing" && top !== "permission" && key.includes(".")) {
     const special: Record<string, readonly string[]> = {
       task_sweep: ["enabled", "auto_reassign", "no_writes_turns", "interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"],
-      checks: ["timeout_s", "runner", "remote", ...CLASSES], terminal: ["open"],
+      checks: ["timeout_s", "runner", "remote", ...CLASSES], terminal: ["open"], start: ["agents"],
     };
     let check = schema[top];
     for (const [index, part] of key.split(".").slice(1).entries()) {

package/src/hub/config-edit-host.ts

@@ -160,6 +160,7 @@ export function createConfigEditor(host: ConfigEditHost) {
 function leafKeys(plan: Extract<ConfigEditPlan, { ok: true }>): string[] {
   const out = new Set<string>();
   const walk = (prefix: string, before: unknown, after: unknown): void => {
+    if (prefix === "research.runners") { out.add(prefix); return; }
     const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
     if (object(before) || object(after)) {
       const old = object(before) ? before : {}, next = object(after) ? after : {};

package/src/hub/config-tier.ts

@@ -41,6 +41,9 @@ export function configTier(file: ConfigEditFile, path: readonly string[], value?
   const key = path.join(".");
   if (file === "sdlc.toml") return path.length === 1 && (SDLC_KEYS as readonly string[]).includes(path[0]!) ? { tier: 2 } : refuse(`sdlc.${key} is not editable here: only mode and required_checks are; edit .agenthub/sdlc.toml in your editor`);
   if (registryKey(key)) return { refused: `${key} is already editable with ahub settings set ${key}; nothing was written` };
+  if (path[0] === "research" && path[1] === "runners") {
+    return path.length === 2 ? { tier: 2 } : refuse("research.runners: edit the whole registration block");
+  }
   if (path[0] === "instances") {
     if (path.length === 1) return refuse("instances: name one instance (instances.<id>)");
     if (!PEER.test(path[1]!)) return refuse(`instances.${path[1]}: an instance id is lower-case letters, digits and hyphens`);

package/src/hub/config-trust.ts

@@ -36,7 +36,9 @@ export const MACHINE_LOCAL = [
   "invocation", // #445 C1: what another agent may be offered from this machine's agents (a digest-pinned allowlist); a committed config may not share a person's agents' commands with someone else's peers
 ] as const;
 /** Legacy exported field list stays compatible; new policies use the complete list below. */
-export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "rooms", "tasks.queue_backpressure", "context.max_assignment_used", "action_policy", "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "adapters", "adapter_modules", "text_projection", "instances"] as const;
+export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "research.runners", "rooms", "tasks.queue_backpressure", "context.max_assignment_used", "action_policy", "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "start.agents", "adapters", "adapter_modules", "text_projection", "instances"] as const;
+/** An empty list of these is a value (`start.agents` empty starts no agent), not "the default", so the empty-value drop below skips them. */
+const EMPTY_IS_VALUE: readonly string[] = ["start.agents"];
 
 /** A known repository, including an unreadable marker, must never be mistaken for a plain directory. */
 export function configRepositoryPresent(cwd: string): boolean {
@@ -102,11 +104,17 @@ const drop = (file: Record<string, unknown>, path: string) => {
  * once resolved to the project root). A committed copy of the template sets them to defaults and asks git nothing.
  */
 export function stripUntrusted(file: Record<string, unknown>, defaults: object, cwd: string, name: string): string | undefined {
+  const research = file.research;
+  if (research && typeof research === "object" && Object.hasOwn(research, "runners")) {
+    if (name !== "config.local.json") throw new Error("research.runners requires untracked config.local.json");
+    const why = configRefusal(cwd, name);
+    if (why) throw new Error(`research.runners requires untracked config.local.json: ${why}`);
+  }
   if (name !== "config.local.json") delete file.rooms;
   const localOnly = name !== "config.local.json" && file.action_policy !== undefined;
   if (localOnly) delete file.action_policy;
   const originNotice = localOnly ? "action_policy ignored: only .agenthub/config.local.json may set it" : undefined;
-  for (const p of ALL_MACHINE_LOCAL) if (valueAt(file, p) !== undefined && !chooses(valueAt(file, p))) drop(file, p);
+  for (const p of ALL_MACHINE_LOCAL) if (!EMPTY_IS_VALUE.includes(p) && valueAt(file, p) !== undefined && !chooses(valueAt(file, p))) drop(file, p);
   const set = ALL_MACHINE_LOCAL.filter((p) => {
     const v = valueAt(file, p);
     return v !== undefined && JSON.stringify(v) !== JSON.stringify(valueAt(defaults, p));

package/src/hub/control-client.ts

@@ -2,16 +2,27 @@ import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { projectContext } from "./project.ts";
 import { externalAdapterMetadata, externalInstanceCatalog, type ExternalInstanceCatalog, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
+import { negotiateProtocol, protocolWindow, type ProtocolWindow } from "./protocol-window.ts";
 
 export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
 }
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
-export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor"] as const;
+export const PROTOCOL = 17;
+/** The descriptor's legacy protocol field remains this floor for previous published clients. */
+export const PROTOCOL_MIN = 16;
+export const DAEMON_FEATURES = ["project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor", "calendar_schedules", "research_records", "research_dispatch", "research_dropped_offers", "research_experiments", "research_comparisons", "research_runners", "task_handoff", "session_identity", "schema_guard"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
-export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
+export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, 16, PROTOCOL] as const;
+
+/** Modern descriptors advertise their maximum separately; old descriptors represent singleton windows. */
+export function controlProtocolWindow(descriptor: { protocol?: unknown; protocolMin?: unknown; protocolMax?: unknown }): ProtocolWindow | undefined {
+  const legacy = protocolWindow(descriptor.protocol);
+  const window = protocolWindow(descriptor.protocolMax ?? descriptor.protocol, descriptor.protocolMin ?? descriptor.protocol);
+  if (!legacy || !window || legacy.v < window.vMin || legacy.v > window.v) return undefined;
+  return window;
+}
 
 /** Only a launch retries transient transport failures. Refusals and identity mismatches
  * remain terminal; every attempt rereads the descriptor and applies the instance pin. */
@@ -42,6 +53,12 @@ export interface Hello {
   launchId?: string;
   /** Optional canonical native execution cwd; ownership requires independent host proof. */
   cwd?: string;
+  /**
+   * agent-hub#1036: the plugin has no project of its own and its inherited state directory belongs to another project. It asks to join as a distinct session; the value is the origin label
+   * (possibly empty). The daemon mints `<peer>~<label>` for it and never binds the peer id it names. A daemon without the `session_identity` feature ignores the field, so a client checks
+   * `features` in `status.json` before sending it.
+   */
+  session?: string;
   /** Reclaim after replacement, never an intentional initial takeover. */
   standby?: boolean;
   projectId?: string;
@@ -56,6 +73,8 @@ export interface ControlDescriptor {
   instanceId?: string;
   cwd?: string;
   protocol?: number;
+  protocolMin?: number;
+  protocolMax?: number;
   pid?: number;
   features?: readonly string[];
   /** The daemon's accepted native start modes, used by launchers when the file value is retained. */
@@ -75,7 +94,7 @@ export function readControl(stateDir: string): ControlDescriptor | undefined {
       ? Object.fromEntries(Object.entries(status.startModes).filter((entry): entry is [string, "tui" | "headless"] => entry[1] === "tui" || entry[1] === "headless"))
       : undefined;
     return { url: `ws://127.0.0.1:${status.controlPort}`, token, projectId: status.projectId,
-      instanceId: status.instanceId, cwd: status.cwd, protocol: status.protocol, pid: status.pid, features: Array.isArray(status.features) ? status.features.filter((feature: unknown): feature is string => typeof feature === "string") : [],
+      instanceId: status.instanceId, cwd: status.cwd, protocol: status.protocol, protocolMin: status.protocolMin, protocolMax: status.protocolMax, pid: status.pid, features: Array.isArray(status.features) ? status.features.filter((feature: unknown): feature is string => typeof feature === "string") : [],
       ...(startModes ? { startModes } : {}),
       ...(status.externalAdapters !== undefined ? { externalAdapters: externalAdapterMetadata(status.externalAdapters) } : {}),
       ...(typeof status.pidSignature === "string" && status.pidSignature ? { pidSignature: status.pidSignature } : {}) };
@@ -97,6 +116,10 @@ export function controlRequestTimeout(msg: Record<string, unknown>, requested =
 /** One authenticated control connection. `request` correlates replies by `rid`; everything else goes to `onPush`. */
 export class ControlClient {
   features: readonly string[] = [];
+  /** The id the hub minted for a distinct session (agent-hub#1036); absent for every ordinary connection. */
+  sessionId?: string;
+  /** Selected wire version, checked against the welcome when that legacy-optional field is present. */
+  protocol?: number;
   private welcomeInstanceId?: string;
   /** Identity from the authenticated welcome, never the unauthenticated descriptor alone. */
   get instanceId(): string | undefined { return this.welcomeInstanceId; }
@@ -120,17 +143,20 @@ export class ControlClient {
   }
 
   /** `protocol` is used only by the upgrade coordinator for an authenticated, explicitly supported source contract. */
-  static connect(stateDir: string, hello: Hello, timeoutMs = 3000, protocol = PROTOCOL): Promise<ControlClient> {
-    if (!RECOVERY_SOURCE_PROTOCOLS.includes(protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number])) return Promise.reject(new Error(`unsupported recovery source protocol ${protocol}`));
+  static connect(stateDir: string, hello: Hello, timeoutMs = 3000, protocol?: number): Promise<ControlClient> {
+    if (protocol !== undefined && !RECOVERY_SOURCE_PROTOCOLS.includes(protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number])) return Promise.reject(new Error(`unsupported recovery source protocol ${protocol}`));
     const control = readControl(stateDir);
     if (!control) return Promise.reject(new Error(`no hub running for ${stateDir} (run: ahub up)`));
     const pin = instancePins.get(resolve(stateDir));
     if (pin && (control.instanceId !== pin.instanceId || hello.instanceId !== undefined && hello.instanceId !== pin.instanceId)) {
       return Promise.reject(new Error("delegated audit consumer changed; refusing a connection to its replacement"));
     }
-    if (control.protocol !== undefined && control.protocol !== protocol) {
-      return Promise.reject(Object.assign(new Error(`wire version mismatch: hub speaks ${control.protocol}, CLI speaks ${protocol}; stop it with its matching CLI, then upgrade and restart`), { code: 4426 }));
-    }
+    const local = protocolWindow(protocol ?? PROTOCOL, protocol ?? PROTOCOL_MIN)!;
+    const versioned = control.protocol !== undefined || control.protocolMin !== undefined || control.protocolMax !== undefined;
+    const remote = versioned ? controlProtocolWindow(control) : undefined;
+    const selected = versioned ? remote && negotiateProtocol(local, remote) : protocol ?? PROTOCOL_MIN;
+    const mismatch = () => Object.assign(new Error(`wire version mismatch: hub speaks ${control.protocolMax ?? control.protocol}, CLI speaks ${protocol ?? PROTOCOL}; stop it with its matching CLI, then upgrade and restart`), { code: 4426 });
+    if (selected === undefined) return Promise.reject(mismatch());
     if ((hello.projectId && hello.projectId !== control.projectId) ||
         (hello.instanceId && hello.instanceId !== control.instanceId) ||
         (hello.projectRoot && hello.projectRoot !== control.cwd)) {
@@ -161,15 +187,18 @@ export class ControlClient {
         client.pending.delete(msg.rid);
         done(msg);
       };
-      ws.onopen = () => void client.request({ t: "hello", v: protocol, token: control.token, ...hello, ...expected }, timeoutMs).then((reply) => {
+      ws.onopen = () => void client.request({ t: "hello", token: control.token, ...hello, ...expected, v: selected, vMin: remote?.vMin === undefined ? selected : Math.max(local.vMin, remote.vMin) }, timeoutMs).then((reply) => {
         if (reply.t !== "welcome" || reply.ok === false) return refuse(new Error(reply.error ?? "hub refused handshake"));
         if ((expected.projectId && reply.projectId !== expected.projectId) ||
             (expected.instanceId && reply.instanceId !== expected.instanceId) ||
             (expected.projectRoot && reply.cwd !== expected.projectRoot)) {
           return refuse(Object.assign(new Error("connected hub has a different project or instance"), { code: 4404 }));
         }
+        if (reply.protocol !== undefined && reply.protocol !== selected) return refuse(mismatch());
+        client.protocol = selected;
         client.features = Object.freeze(Array.isArray(reply.features) ? reply.features.filter((feature: unknown): feature is string => typeof feature === "string") : []);
         client.welcomeInstanceId = typeof reply.instanceId === "string" && reply.instanceId ? reply.instanceId : undefined;
+        client.sessionId = typeof reply.session === "string" && reply.session.length <= 64 ? reply.session : undefined;
         clearTimeout(timer);
         resolve(client);
       });