@staix/agent-hub 0.12.44 → 0.13.0

package/src/adapters/external-modules.ts

@@ -0,0 +1,240 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { isBuiltin } from "node:module";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { moduleDataObject as dataObject, moduleText as text, moduleArray as array } from "./external-metadata.ts";
+import { ADAPTER_API } from "./adapter-api.ts";
+import { CONFIGURED_ACP_RESERVED_COMMANDS } from "./configured-acp.ts";
+import { ADAPTERS, assertDefinitionCoherence, assertNativeCapabilityScope, createProjectAdapterCatalog } from "./registry.ts";
+import type { AdapterDefinition, LaunchPlan } from "./registry-types.ts";
+import { configRefusal } from "../hub/config-trust.ts";
+import { realPath } from "../hub/project.ts";
+import { scanModuleSource } from "./external-module-scan.ts";
+
+export interface AdapterModuleDeclaration { readonly path: string; readonly sha256: string }
+interface ModuleConfigLayer { name: string; raw: Record<string, unknown> }
+const MAX_MODULES = 16, MAX_MODULE_BYTES = 2 * 1024 * 1024;
+const ADAPTER_IMPORT = "@staix/agent-hub/adapter";
+class ExternalAdapterRefusal extends Error {}
+const fail = (reason: string): never => { throw new ExternalAdapterRefusal(`external adapter: ${reason}`); };
+const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+export function adapterModuleDeclarations(raw: unknown): readonly AdapterModuleDeclaration[] {
+  if (raw === undefined) return Object.freeze([]);
+  return Object.freeze(array(raw, MAX_MODULES).map(value => {
+    const row = dataObject(value);
+    if (Object.keys(row).some(key => !["path", "sha256"].includes(key))) return fail("unknown module declaration field");
+    const path = text(row.path, 4096), hash = row.sha256;
+    if (typeof hash !== "string" || !/^[a-f0-9]{64}$/i.test(hash)) return fail("a SHA-256 content pin is required");
+    return Object.freeze({ path, sha256: hash.toLowerCase() });
+  }));
+}
+
+/** This reads declarations only. It never imports code, including for reloads and CLI reads. */
+export function readAdapterModuleDeclarations(cwd: string, layers: readonly ModuleConfigLayer[]) {
+  const ignored: string[] = [];
+  let modules: readonly AdapterModuleDeclaration[] = Object.freeze([]);
+  for (const { name, raw } of layers) {
+    if (raw.adapter_modules === undefined) continue;
+    const refusal = name !== "config.local.json" ? "modules are machine-local config.local.json values" : configRefusal(cwd, name);
+    if (refusal) { ignored.push(`adapter_modules in .agenthub/${name} ignored: ${refusal}`); continue; }
+    modules = adapterModuleDeclarations(raw.adapter_modules);
+  }
+  return { modules, ignored };
+}
+
+const inside = (root: string, file: string) => { const part = relative(root, file); return part !== "" && part !== ".." && !part.startsWith(`..${sep}`) && !isAbsolute(part); };
+function regularPath(root: string, file: string) {
+  if (!inside(root, file)) return fail("module must be inside the project root");
+  let at = root;
+  const parts = relative(root, file).split(sep);
+  for (let index = 0; index < parts.length; index++) {
+    at = join(at, parts[index]!);
+    const stat = lstatSync(at);
+    if (stat.isSymbolicLink() || (index < parts.length - 1 ? !stat.isDirectory() : !stat.isFile())) return fail("symlinked or nonregular module path refused");
+  }
+  return lstatSync(file);
+}
+function captureBundle(cwd: string, declaration: AdapterModuleDeclaration): Buffer {
+  const root = realPath(cwd), file = resolve(root, declaration.path);
+  const observed = regularPath(root, file);
+  if ((observed.mode & 0o002) !== 0) return fail("world-writable module refused");
+  if (observed.size > MAX_MODULE_BYTES) return fail("module exceeds the size bound");
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.dev !== observed.dev || before.ino !== observed.ino || (before.mode & 0o002) !== 0) return fail("module changed before capture");
+    const buffer = Buffer.alloc(MAX_MODULE_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) { const n = readSync(fd, buffer, length, buffer.length - length, length); if (!n) break; length += n; }
+    if (length > MAX_MODULE_BYTES) return fail("module exceeds the size bound");
+    const after = fstatSync(fd), current = regularPath(root, file);
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+      || current.dev !== before.dev || current.ino !== before.ino || !inside(root, realPath(file))) return fail("module changed during capture");
+    const bytes = buffer.subarray(0, length);
+    if (digest(bytes) !== declaration.sha256) return fail("content hash mismatch");
+    return bytes;
+  } finally { closeSync(fd); }
+}
+
+/** Conservative code-loading rejection, not an isolation boundary for approved daemon-privileged code. */
+export function assertModuleBundle(source: string): void {
+  for (const dependency of scanModuleSource(source)) {
+    const allowed = dependency.path === ADAPTER_IMPORT || dependency.path !== "bun:test" && dependency.path !== "bun:ffi"
+      && /^(?:node|bun):/.test(dependency.path) && (isBuiltin(dependency.path) || dependency.path === "bun:sqlite");
+    if (dependency.kind !== "import-statement" || !allowed) return fail("only static builtin and public adapter imports are supported");
+  }
+}
+
+/** Resolve scanned SDK imports against this running package, never project node_modules or process.cwd(). */
+async function executableBundle(source: string): Promise<Uint8Array> {
+  const imports = scanModuleSource(source);
+  const compiled = await Bun.build({ entrypoints: ["a4-pin:entry"], target: "bun", format: "esm",
+    plugins: [{ name: "host-bound-adapter-imports", setup(build) {
+      build.onResolve({ filter: /^a4-pin:/ }, () => ({ path: "entry", namespace: "a4-pin" }));
+      build.onLoad({ filter: /.*/, namespace: "a4-pin" }, () => ({ contents: source, loader: "js" }));
+      build.onResolve({ filter: /.*/ }, args => {
+        if (!imports.some(item => item.path === args.path && item.kind === "import-statement")) return fail("unscanned import refused");
+        return { path: args.path === ADAPTER_IMPORT ? new URL("./public.ts", import.meta.url).href : args.path, external: true };
+      });
+    } }],
+  });
+  if (!compiled.success || compiled.outputs.length !== 1) return fail("bundle compilation refused (details withheld)");
+  return new Uint8Array(await compiled.outputs[0]!.arrayBuffer());
+}
+
+function snapshot(value: unknown, depth = 0): unknown {
+  if (depth > 12) return fail("definition nesting exceeds its bound");
+  if (typeof value === "function" || value === null || ["undefined", "string", "number", "boolean"].includes(typeof value)) return value;
+  if (Array.isArray(value)) return Object.freeze(array(value, 128).map(item => snapshot(item, depth + 1)));
+  return Object.freeze(Object.fromEntries(Object.entries(dataObject(value)).map(([key, member]) => [key, snapshot(member, depth + 1)])));
+}
+function only(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  const fields = dataObject(value);
+  if (Object.keys(fields).some(key => !keys.includes(key))) return fail("field is outside the supported external definition subset");
+  return fields;
+}
+export function validateExternalDefinition(raw: unknown): AdapterDefinition {
+  const definition = snapshot(raw) as AdapterDefinition;
+  if (definition.api !== ADAPTER_API) return fail("adapter API mismatch");
+  const reserved = [...ADAPTERS.map(item => item.kind), ...CONFIGURED_ACP_RESERVED_COMMANDS, "user", "hub", "digest", "constructor", "prototype", "__proto__"];
+  if (typeof definition.kind !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(definition.kind) || reserved.includes(definition.kind)
+    || ADAPTERS.some(builtin => definition.kind.startsWith(`${builtin.kind}-`))) return fail("kind is reserved, invalid or collides with a builtin");
+  text(definition.displayName, 256);
+  if (definition.family !== definition.kind || definition.trust?.onPrem !== false || definition.trust.hubSandboxed !== false
+    || definition.defaultOnRoster !== false || definition.optional !== true) return fail("external kinds must retain their own family and optional off-roster cloud trust");
+  if (!Array.isArray(definition.roles) || !definition.roles.length || definition.roles.some(role => !["planner", "implementer", "verifier", "reviewer"].includes(role)) || new Set(definition.roles).size !== definition.roles.length) return fail("unsupported default roles");
+  if (definition.instances !== undefined) return fail("external adapter instances are unsupported in A4");
+  try { assertNativeCapabilityScope(definition); } catch { return fail("fixed-builtin capability refused"); }
+  only(definition, ["api", "kind", "family", "displayName", "transport", "roles", "optional", "defaultOnRoster", "trust", "start", "identity", "permission", "session", "turnEnd", "cli", "display"]);
+  only(definition.trust, ["onPrem", "hubSandboxed"]);
+  const start = only(definition.start, ["forms", "defaultForm", "daemonPort", "launch", "create", "preflight", "version", "conductorStartable", "hubSwitches", "ownedFlags", "exclusiveStartRefusal"]);
+  if (definition.transport !== "acp" || definition.turnEnd !== "adapter" || definition.start.daemonPort !== "acp"
+    || array(definition.start.forms, 1).length !== 1 || definition.start.forms[0] !== "headless" || definition.start.defaultForm !== "headless"
+    || typeof definition.start.conductorStartable !== "boolean" || typeof definition.start.create !== "function" || typeof definition.start.launch !== "function") return fail("A4 requires a headless ACP transport factory and launch plan");
+  for (const field of ["preflight", "version"] as const) if (start[field] !== undefined && typeof start[field] !== "function") return fail("invalid start callback");
+  if (array(start.hubSwitches, 0).length || array(start.ownedFlags, 0).length) return fail("external launch switches are unsupported");
+  if (start.exclusiveStartRefusal !== undefined) text(start.exclusiveStartRefusal, 2048);
+  if (only(definition.identity, ["mcp"]).mcp !== "acp-session") return fail("external ACP identity must be session-bound");
+  const permission = only(definition.permission, ["genericAcp", "grants", "unmanaged"]);
+  if (permission.genericAcp !== undefined) {
+    const policy = only(permission.genericAcp, ["modes", "readOnly"]);
+    if (policy.modes !== undefined) for (const value of Object.values(only(policy.modes, ["ask", "ask-when-needed", "never-ask"]))) text(value, 256);
+    if (policy.readOnly !== undefined) text(policy.readOnly, 256);
+  }
+  if (permission.grants !== undefined) for (const value of Object.values(only(permission.grants, ["ask", "ask-when-needed", "never-ask"]))) text(value, 2048);
+  if (permission.unmanaged !== undefined) text(permission.unmanaged, 2048);
+  const session = only(definition.session, ["idField", "currentId", "resumeById", "launchKind"]);
+  if (session.idField !== "sessionId" || typeof session.currentId !== "function" || session.resumeById !== undefined && typeof session.resumeById !== "boolean") return fail("invalid external session contract");
+  if (session.launchKind !== undefined && session.launchKind !== definition.kind) return fail("external launch kind must match its own kind");
+  const cli = only(definition.cli, ["command", "startWords"]);
+  if (cli.command !== definition.kind || typeof cli.startWords !== "function") return fail("external command must match its own kind");
+  let words: unknown;
+  try { words = definition.cli.startWords("headless"); } catch { return fail("command metadata refused (details withheld)"); }
+  const commandWords = array(words, 1).map(word => text(word, 64));
+  if (commandWords.length !== 1 || commandWords[0] !== definition.kind) return fail("headless command words must name only their bound kind");
+  const palette = only(only(definition.display, ["palette"]).palette, ["fg", "bg"]);
+  for (const color of [palette.fg, palette.bg]) if (typeof color !== "string" || !/^(?:[a-z]{1,32}|#[a-f0-9]{3,8})$/i.test(color)) return fail("invalid external display color");
+  try { assertDefinitionCoherence(definition); } catch { return fail("definition contracts are incoherent"); }
+  const invoke = <T>(name: string, callback: () => T): T => {
+    try { return callback(); } catch { return fail(`${name} refused (details withheld)`); }
+  };
+  return snapshot({ ...definition,
+    start: { ...definition.start,
+      create: (context: Parameters<NonNullable<AdapterDefinition["start"]["create"]>>[0]) => invoke("factory", () => definition.start.create!(context)),
+      launch: (context: Parameters<NonNullable<AdapterDefinition["start"]["launch"]>>[0]): LaunchPlan => invoke("launch", () => {
+        const plan = only(definition.start.launch!(context), ["cmd", "args", "metadata"]);
+        const cmd = text(plan.cmd, 4096), args = array(plan.args, 128).map(arg => text(arg, 4096));
+        const metadata = only(plan.metadata, ["packageEntrypoint", "command", "argv", "env"]);
+        text(metadata.packageEntrypoint, 4096); text(metadata.command, 16384);
+        array(metadata.argv, 129).forEach(arg => text(arg, 4096));
+        if (Object.keys(dataObject(metadata.env)).length) return fail("external native-home overrides are unsupported");
+        return snapshot({ cmd, args, metadata }) as LaunchPlan;
+      }),
+      ...(definition.start.preflight ? { preflight: (context: Parameters<NonNullable<AdapterDefinition["start"]["preflight"]>>[0]) => {
+        try { if (definition.start.preflight!(context) === undefined) return undefined; } catch { /* Never forward module-authored exception/refusal bodies. */ }
+        return "external adapter preflight refused (details withheld)";
+      } } : {}),
+      ...(definition.start.version ? { version: (context: Parameters<NonNullable<AdapterDefinition["start"]["version"]>>[0]) => {
+        try { if (definition.start.version!(context) === undefined) return undefined; } catch { /* Unknown is a refusal for an external native version check. */ }
+        return "external adapter version refused (details withheld)";
+      } } : {}),
+    },
+    session: { ...definition.session,
+      // ponytail: A4 has no verified controlled-recovery driver; bind native session/group restoration receipts before enabling it.
+      recoveryRefusal: () => "external module has no verified controlled-recovery driver; stop it explicitly and restart with its recorded native session id",
+      currentId: (peer: Parameters<AdapterDefinition["session"]["currentId"]>[0]) => {
+      try {
+        const value = definition.session.currentId(peer);
+        return typeof value === "string" && value.trim() && Buffer.byteLength(value) <= 4096 && !/[\p{Cc}\p{Cf}]/u.test(value) ? value : undefined;
+      } catch { return undefined; }
+    } },
+    // UI polls and CLI metadata never execute plugin code to render a headless command.
+    cli: { command: definition.kind, startWords: () => [definition.kind] },
+  }) as AdapterDefinition;
+}
+
+const MODULE_IMPORT_TIMEOUT_MS = 2000;
+async function importVerifiedModule(executable: Uint8Array): Promise<unknown> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    // ponytail: a deadline stops waiting, not privileged module side effects; cancellation needs an isolated host-port engine.
+    return await Promise.race([
+      import(`data:text/javascript;nonce=${randomUUID()};base64,${Buffer.from(executable).toString("base64")}`),
+      new Promise<never>((_resolve, reject) => { timer = setTimeout(() => reject(new ExternalAdapterRefusal("external adapter: module import timed out")), MODULE_IMPORT_TIMEOUT_MS); }),
+    ]);
+  } finally { clearTimeout(timer); }
+}
+
+/** Only daemon startup calls this. Hash-checked bytes, not the mutable source path, reach import(). */
+export interface ExternalAdapterRefusalRecord { readonly index: number; readonly reason: string }
+export async function loadExternalAdapterDefinitions(cwd: string, layers: readonly ModuleConfigLayer[], onRefusal?: (refusal: ExternalAdapterRefusalRecord) => void): Promise<readonly AdapterDefinition[]> {
+  const { modules } = readAdapterModuleDeclarations(cwd, layers);
+  if (!modules.length) return Object.freeze([]);
+  let rawAdapters: unknown;
+  for (const { name, raw } of layers) if (name === "config.local.json" && !configRefusal(cwd, name) && raw.adapters !== undefined) rawAdapters = raw.adapters;
+  const existingKinds = new Set(createProjectAdapterCatalog(rawAdapters).definitions.map(definition => definition.kind));
+  const definitions: AdapterDefinition[] = [];
+  for (const [index, declaration] of modules.entries()) {
+    try {
+      if (configRefusal(cwd, "config.local.json")) return fail("module configuration provenance changed");
+      const local = regularPath(realPath(cwd), join(realPath(cwd), ".agenthub", "config.local.json"));
+      if ((local.mode & 0o002) !== 0) return fail("world-writable module configuration refused");
+      const bytes = captureBundle(cwd, declaration);
+      const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      assertModuleBundle(source);
+      const executable = await executableBundle(source);
+      if (digest(bytes) !== declaration.sha256 || configRefusal(cwd, "config.local.json")) return fail("module pin or provenance changed before import");
+      const imported = await importVerifiedModule(executable);
+      const definition = validateExternalDefinition((imported as { definition?: unknown }).definition);
+      if ([...existingKinds].some(kind => definition.kind === kind || definition.kind.startsWith(`${kind}-`))) return fail("kind collides with a configured adapter namespace");
+      if (definitions.some(item => item.kind === definition.kind)) return fail("duplicate external kind");
+      definitions.push(definition);
+    } catch (error) {
+      const refusal = error instanceof ExternalAdapterRefusal ? error : new ExternalAdapterRefusal("external adapter: module could not be verified or loaded (details withheld)");
+      if (!onRefusal) throw refusal;
+      onRefusal(Object.freeze({ index, reason: refusal.message }));
+    }
+  }
+  return Object.freeze(definitions);
+}
+

package/src/adapters/jcode.ts

@@ -1,4 +1,5 @@
 import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { assessVersion, COMPAT, type CompatVerdict } from "./compat.ts";
 import { createConnection } from "node:net";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -12,21 +13,25 @@ export interface JcodeOptions extends Omit<AcpOptions, "cmd" | "qwen025" | "expe
   command: string[];
   home: string;
   providerProfile?: string;
+  /** The hub peer id this Jcode acts for: "jcode" for the base peer, an instance id for an extra one (#685). */
+  peer?: string;
+  /** Initial native provider (`-p`), passed exactly as the person wrote it (#685). The hub never handles model credentials. */
+  provider?: string;
   /** How long a native steer may take to be acknowledged (#572); default 5 s. */
   steerTimeoutMs?: number;
 }
-export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string): string[] {
+export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string, provider?: string, peer = "jcode"): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
-  return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
-    ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", "agent-hub-jcode"] : ["--mcp-tools", "eager"])];
+  return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(provider ? ["-p", provider] : []), ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
+    ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", `agent-hub-${peer}`] : ["--mcp-tools", "eager"])];
 }
 export interface JcodeTuiBinding { launchId: string; sessionId: string }
 export type JcodeTuiState = { state: "waiting"; binding: JcodeTuiBinding } |
   { state: "ready"; binding: JcodeTuiBinding; launch: { cmd: string; args: string[]; env: NodeJS.ProcessEnv } };
 
-export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string): string[] {
+export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string, provider?: string): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
-  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev",
+  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev", ...(provider ? ["-p", provider] : []),
     ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : [])];
 }
 
@@ -65,17 +70,8 @@ export class JcodeOptionMismatch extends Error {
   constructor(readonly option: "--session-id" | "--model" | "--provider-profile") { super("Jcode launch options differ from its running session"); }
 }
 const JCODE_OWNED_ENV = { JCODE_DISABLE_CLAUDE_MCP: "1", JCODE_NO_TELEMETRY: "1" } as const;
-/** The oldest native release accepted; its ACP, serve and MCP contract was verified live on 0.98.1 (docs/verification). */
-export const JCODE_MIN_VERSION = "0.98.0";
-/** The first native release assumed to break that contract: the next major. Lower it when a release is shown to break. */
-export const JCODE_BREAKING_VERSION = "1.0.0";
-const release = (version: string) => /^(\d+)\.(\d+)\.(\d+)$/.exec(version)?.slice(1).map(Number);
-const compare = (a: number[], b: number[]) => a[0]! - b[0]! || a[1]! - b[1]! || a[2]! - b[2]!;
-/** A plain release from JCODE_MIN_VERSION up to, not including, JCODE_BREAKING_VERSION; the minor is not pinned (#529). */
-export function jcodeVersionSupported(version: unknown): boolean {
-  const v = typeof version === "string" ? release(version) : undefined;
-  return !!v && compare(v, release(JCODE_MIN_VERSION)!) >= 0 && compare(v, release(JCODE_BREAKING_VERSION)!) < 0;
-}
+/** #691: the verdict lives in `src/adapters/compat.ts` (line, verified versions, the person's trust); never pin here. */
+export const jcodeVersionSupported = (version: unknown): boolean => assessVersion("jcode", version).ok;
 
 /** A native steer the server did not take, with nothing sent: the message may safely stay queued. */
 class SteerRefused extends Error {}
@@ -137,20 +133,56 @@ function nativeSteer(socket: string, cwd: string, sessionId: string, text: strin
 }
 
 /** The wrapper contract preserves every configured prefix argument before the native probe. */
-export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
+export function jcodeVersion(command: string[], cwd: string): CompatVerdict {
   const [bin, ...prefix] = command;
-  if (!bin) return false;
+  if (!bin) return assessVersion("jcode", undefined);
   try {
     const result = spawnSync(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: { ...peerChildEnv("jcode"), ...JCODE_OWNED_ENV }, encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 });
-    if (result.status !== 0) return false;
-    const version = JSON.parse(result.stdout);
-    return jcodeVersionSupported(version.semver);
-  } catch { return false; }
+    return assessVersion("jcode", result.status === 0 ? COMPAT.jcode.parse(result.stdout) : undefined);
+  } catch { return assessVersion("jcode", undefined); }
+}
+export const verifiedJcodeCommand = (command: string[], cwd: string): boolean => jcodeVersion(command, cwd).ok;
+/** Collects at most `cap` bytes; the chunk that would pass it, and every later one, is refused and not kept. */
+export function boundedOutput(cap: number): { push(chunk: Buffer): boolean; text(): string; readonly size: number; readonly overflowed: boolean } {
+  const chunks: Buffer[] = [];
+  let size = 0, overflowed = false;
+  return {
+    push(chunk) { if (overflowed || size + chunk.length > cap) { overflowed = true; return false; } chunks.push(chunk); size += chunk.length; return true; },
+    text: () => Buffer.concat(chunks).toString("utf8"),
+    get size() { return size; },
+    get overflowed() { return overflowed; },
+  };
+}
+/**
+ * The daemon's preflight: the same probe without blocking the event loop (a slow wrapper must not stall peers). The probe owns its
+ * process group: at the deadline, or once stdout passes 64 KiB, the whole group is stopped, descendants included (kimi-review's pattern).
+ */
+export function jcodeVersionAsync(command: string[], cwd: string, timeoutMs = 10_000): Promise<CompatVerdict> {
+  const [bin, ...prefix] = command;
+  if (!bin) return Promise.resolve(assessVersion("jcode", undefined));
+  return new Promise(resolve => {
+    let child: ChildProcess;
+    try { child = spawn(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: { ...peerChildEnv("jcode"), ...JCODE_OWNED_ENV }, detached: true, stdio: ["ignore", "pipe", "ignore"] }); }
+    catch { resolve(assessVersion("jcode", undefined)); return; }
+    const output = boundedOutput(64 * 1024);
+    let done = false;
+    const finish = async (code: number | null) => {
+      if (done) return; done = true; clearTimeout(timer);
+      try { await stopOwnedProcess(child, { group: true }); } catch { resolve(assessVersion("jcode", undefined)); return; }
+      resolve(assessVersion("jcode", code === 0 && !output.overflowed ? COMPAT.jcode.parse(output.text()) : undefined));
+    };
+    const timer = setTimeout(() => { void finish(null); }, timeoutMs);
+    child.once("spawn", () => trackGroup(child));
+    // Chunks after the cap or after settling are drained and discarded, never buffered.
+    child.stdout!.on("data", (bytes: Buffer) => { if (!done && !output.push(bytes)) void finish(null); });
+    child.once("error", () => { void finish(null); });
+    child.once("close", code => { void finish(code); });
+  });
 }
 
 /** Both processes are ours. The user's global daemon and its sockets are never stopped. */
 export class JcodePeer extends AcpPeer {
-  private readonly launchId = crypto.randomUUID();
+  private readonly launchId: string;
   private socketIdentity: { dev: number; ino: number } | undefined;
   private readonly root: string;
   private readonly socket: string;
@@ -161,21 +193,28 @@ export class JcodePeer extends AcpPeer {
 
   constructor(private readonly jcode: JcodeOptions) {
     if (!isAbsolute(jcode.home)) throw new Error("jcode_home must be an absolute native data path");
+    const peer = jcode.peer ?? "jcode";
     jcodeCommand(jcode.command, "acp", "preview", jcode.cwd);
     // The name must end in ".sock": jcode names its debug socket by replacing that suffix, so "s" binds one path twice.
     const root = mkdtempSync(join(tmpdir(), "ahub-jcode-")), socket = join(root, "j.sock");
-    const cmd = jcodeCommand(jcode.command, "acp", socket, jcode.cwd, jcode.launchModel, jcode.providerProfile);
-    super("jcode", { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, ...JCODE_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
-    this.root = root; this.socket = socket;
+    const cmd = jcodeCommand(jcode.command, "acp", socket, jcode.cwd, jcode.launchModel, jcode.providerProfile, jcode.provider, peer);
+    const launchId = crypto.randomUUID();
+    // The ACP child gets peerChildEnv(this.id): the instance id, so its hub tools act as this peer and never as the base Jcode. The launch id
+    // goes with it: the daemon admits a hub-tools hello for this peer only when it carries the id of this peer's current owned launch (#368).
+    super(peer, { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, AGENTHUB_LAUNCH_ID: launchId, ...JCODE_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
+    this.root = root; this.socket = socket; this.launchId = launchId;
   }
 
+  /** True only for the id of this peer's current owned launch, while it is not ending: the proof a hub-tools hello must carry (#368). */
+  ownsLaunch(launchId: unknown): boolean { return !this.ending && typeof launchId === "string" && launchId === this.launchId; }
+
   override async start(): Promise<void> {
     // The native loader otherwise imports Codex MCP into the user's store on first use.
     if (!existsSync(join(this.jcode.home, "mcp.json"))) throw new Error("initialize Jcode's global MCP store with its native client before enabling this peer; the hub never initializes or copies it");
     if (existsSync(this.socket)) { this.preserveRoot = true; throw new Error("Jcode private socket is occupied; no daemon was adopted or removed"); }
     this.ending = false;
-    const [bin, ...args] = jcodeCommand(this.jcode.command, "serve", this.socket, this.jcode.cwd, this.jcode.launchModel, this.jcode.providerProfile);
-    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv("jcode"), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", ...JCODE_OWNED_ENV }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
+    const [bin, ...args] = jcodeCommand(this.jcode.command, "serve", this.socket, this.jcode.cwd, this.jcode.launchModel, this.jcode.providerProfile, this.jcode.provider, this.id);
+    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv(this.id), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", AGENTHUB_LAUNCH_ID: this.launchId, ...JCODE_OWNED_ENV }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
     this.server = server; trackGroup(server);
     try {
       await new Promise<void>((resolve, reject) => {
@@ -279,11 +318,13 @@ export class JcodePeer extends AcpPeer {
       : options.providerProfile !== undefined && options.providerProfile !== this.jcode.providerProfile ? "--provider-profile" : undefined;
     if (differs) throw new JcodeOptionMismatch(differs);
     if (!savedSession(this.jcode.home, sessionId)) return { state: "waiting", binding };
-    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile);
-    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, ...JCODE_OWNED_ENV } } };
+    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile, this.jcode.provider);
+    // The TUI is the person's own client of this peer's server. The shared project MCP entry names no peer (#685), so every launch
+    // path supplies its own id: the base Jcode's too, or its MCP child would fall back to the channel default.
+    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, AGENTHUB_PEER_ID: this.id, AGENTHUB_LAUNCH_ID: this.launchId, ...JCODE_OWNED_ENV } } };
   }
   override recoveryMetadata(): Record<string, unknown> {
-    return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: "jcode", mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
+    return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: this.id, mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
   }
 }
 

package/src/adapters/kimi-review.ts

@@ -1,4 +1,5 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { assessVersion, COMPAT } from "./compat.ts";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -7,7 +8,7 @@ import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { realPath } from "../hub/project.ts";
 import type { ReviewerBackend, ReviewerPrepareContext } from "./reviewer-print.ts";
 
-const VERSION = "2.2.0", MANAGED = "managed:kimi-code";
+const MANAGED = "managed:kimi-code";
 const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
 const hash = (text: string) => createHash("sha256").update(text).digest("hex");
 /** Native discovery can walk above cwd; check lexical aliases as well as the physical temporary root. */
@@ -133,7 +134,9 @@ export const kimiReviewerBackend: ReviewerBackend = {
       const executable = realPath(Bun.which(native[0]!, { PATH: process.env.PATH }) ?? resolve(native[0]!));
       const command = [executable, ...native.slice(1)];
       const executableStat = lstatSync(executable);
-      if (await version(command, cwd, env, context.signal) !== VERSION) throw new Error("unsupported Kimi version; receipt covers 2.2.0");
+      // #691: the verified versions and the person's trust live in compat.ts.
+      const verdict = assessVersion("kimi-review", COMPAT["kimi-review"].parse(await version(command, cwd, env, context.signal)));
+      if (!verdict.ok) throw new Error(verdict.reason);
       const fingerprints = [configFile, mcpFile, agentFile].map(file => hash(read(file, 2_097_152)));
       let cleaned = false;
       const cleanup = () => { if (cleaned) return; rmSync(root, { recursive: true, force: true }); cleaned = true; };
@@ -149,7 +152,7 @@ export const kimiReviewerBackend: ReviewerBackend = {
               && ["credentials", "oauth", "device_id"].every((name, index) => realPath(join(source, name)) === sources[index] && realPath(join(tool, name)) === sources[index]);
           } catch { return false; }
         },
-        isolation: { backend: "kimi", version: VERSION, binary: executable, profile: "private-config-exact-two-tools-shared-native-oauth", readOnly: true, strictMcp: true, ephemeral: true,
+        isolation: { backend: "kimi", version: verdict.version, binary: executable, profile: "private-config-exact-two-tools-shared-native-oauth", readOnly: true, strictMcp: true, ephemeral: true,
           enforcement: "native-policy", freshSession: true, hubToolsOnly: true,
           evidence: ["#533 person ruling2026-10-19: native execution-time exact tool allowlist, no kernel sandbox", "private config/cwd/empty skills; shared OAuth directory symlinks and native lock/atomic rename", "task-bound in-process hub MCP; no full control token", "residual: interruption mid-refresh may require native re-login"] },
       };

package/src/adapters/pi.ts

@@ -157,6 +157,8 @@ export class PiPeer extends BasePeer {
   get sessionGeneration(): string | undefined {
     return this.ownerClaimed && this.ownerPid && this.ownerSignature ? `${this.ownerPid}:${this.ownerSignature}:${this.sessionId ?? ""}` : undefined;
   }
+  // ponytail: retain Pi's owner/session-only checkpoint fence in this slice; a later native-proof port can strengthen it.
+  readonly checkpointUsesSessionGeneration = false;
 
   recoveryMetadata(): Record<string, unknown> {
     const exists = !!this.sessionFile && existsSync(this.sessionFile);

package/src/adapters/public.ts

@@ -0,0 +1,7 @@
+export { ADAPTER_API } from "./adapter-api.ts";
+export { AcpPeer } from "./acp.ts";
+export type { AcpOptions, PermissionRequest, PermissionOption } from "./acp.ts";
+export { BasePeer } from "../hub/peers.ts";
+export type { PeerAdapter, DeliveryReceipt } from "../hub/peers.ts";
+export type { Envelope, PeerId, PeerState } from "../hub/envelope.ts";
+export type * from "./registry-types.ts";

package/src/adapters/registry-types.ts

@@ -16,6 +16,9 @@ import type { LocalOptions } from "./local-worker.ts";
 import type { PiOptions } from "./pi.ts";
 import type { ClaudePrintOptions } from "./claude-print.ts";
 
+import type { BuiltinCliEntry } from "./definitions/native-cli-entry-types.ts";
+import type { NativePreviewBuilder } from "./definitions/native-cli-preview-common.ts";
+
 export type StartForm = "tui" | "headless";
 export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print";
 
@@ -199,7 +202,9 @@ export interface AdapterDefinition {
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
-  instances?: { mode: "external" | "headless"; roles?: readonly string[] };
+  instances?: { mode: "external" | "headless"; roles?: readonly string[];
+    /** Each declared instance runs its own native data home (`jcode_home`) and may pass its own provider, model and profile names (#685). Fixed builtins only. */
+    nativeHome?: true };
   attach?: {
     /** The authenticated external hello may claim this id; independent of MCP configuration shape. */
     externalHello?: boolean;
@@ -272,8 +277,14 @@ export interface AdapterDefinition {
     validateEffective?(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void;
   };
   capabilities?: { manifest?(peer: PeerAdapter): Promise<CapabilityManifest>; watch?: boolean };
+  /** Stable host projection order and planner eligibility, independent of default task roles. */
+  projection?: { roleRank?: number; startRank?: number; helpRank?: number; plannerEligible?: boolean };
   cli: {
     command: string;
+    /** Fixed builtin CLI ports; project definitions cannot supply these callbacks. */
+    entry?: Readonly<Omit<BuiltinCliEntry, "command">>;
+    preview?: NativePreviewBuilder;
+    usage?: readonly (readonly [usage: string, description: string])[];
     /** Configuration leaves that select this peer's next native launch command or provider profile. */
     launchConfigKeys?: readonly string[];
     /** Restrictions only; core identity remains authoritative. */
@@ -299,6 +310,7 @@ export type KindMap = Readonly<Record<string, { readonly kind: string; readonly
 /** Immutable per-project resolver; exported globals remain builtin-only. */
 export interface ProjectAdapterCatalog {
   readonly definitions: readonly AdapterDefinition[];
+  readonly externalDefinitions: readonly AdapterDefinition[];
   definitionOf(id: string, instances?: KindMap): AdapterDefinition | undefined;
   kindOf(id: string, instances?: KindMap): string | undefined;
   familyOf(id: string, instances?: KindMap): string | undefined;