@staix/agent-hub 0.19.0 → 0.21.0

package/src/adapters/external-modules.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, 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";
@@ -18,6 +18,38 @@ 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 interface ExternalModuleIdentity {
+  readonly projectRoot: string;
+  readonly modulePath: string;
+  readonly sha256: string;
+  readonly api: 1;
+  readonly capabilityDigest: string;
+}
+const capturedIdentities = new WeakMap<AdapterDefinition, ExternalModuleIdentity>();
+/** Only the verified startup loader can establish this provenance; display metadata and caller copies cannot. */
+export function externalModuleIdentity(definition: AdapterDefinition): ExternalModuleIdentity | undefined {
+  return capturedIdentities.get(definition);
+}
+/** Revalidate captured provenance synchronously without evaluating module code or trusting definition getters. */
+export function externalModuleIdentityCurrent(definition: AdapterDefinition): boolean {
+  const identity = capturedIdentities.get(definition);
+  if (!identity) return false;
+  try {
+    const root = identity.projectRoot, file = join(root, ".agenthub", "config.local.json");
+    if (realPath(root) !== root || configRefusal(root, "config.local.json")) return false;
+    const local = regularPath(root, file);
+    if ((local.mode & 0o002) !== 0) return false;
+    const source = readFileSync(file, "utf8");
+    const raw = dataObject(JSON.parse(source));
+    const { modules } = readAdapterModuleDeclarations(root, [{ name: "config.local.json", raw }]);
+    const matching = modules.filter(module => relative(root, resolve(root, module.path)).split(sep).join("/") === identity.modulePath);
+    if (matching.length !== 1 || matching[0]!.sha256 !== identity.sha256) return false;
+    captureBundle(root, matching[0]!);
+    const current = regularPath(root, file);
+    return current.dev === local.dev && current.ino === local.ino && current.mtimeMs === local.mtimeMs && current.ctimeMs === local.ctimeMs
+      && (current.mode & 0o002) === 0 && readFileSync(file, "utf8") === source && !configRefusal(root, "config.local.json");
+  } catch { return false; }
+}
 export function adapterModuleDeclarations(raw: unknown): readonly AdapterModuleDeclaration[] {
   if (raw === undefined) return Object.freeze([]);
   return Object.freeze(array(raw, MAX_MODULES).map(value => {
@@ -113,6 +145,29 @@ function only(value: unknown, keys: readonly string[]): Record<string, unknown>
   if (Object.keys(fields).some(key => !keys.includes(key))) return fail("field is outside the supported external definition subset");
   return fields;
 }
+function headlessInstancePolicy(definition: AdapterDefinition): AdapterDefinition["headlessInstances"] {
+  if (!Object.hasOwn(definition, "headlessInstances")) return undefined;
+  const policy = only(definition.headlessInstances, ["form", "roles"]);
+  const roles = array(policy.roles, 3);
+  if (policy.form !== "headless" || !roles.length || new Set(roles).size !== roles.length
+    || roles.some(role => typeof role !== "string" || !["implementer", "verifier", "reviewer"].includes(role) || !definition.roles.includes(role))) return fail("headless instance roles must fit the module role ceiling");
+  return Object.freeze({ form: "headless", roles: Object.freeze(roles as ("implementer" | "verifier" | "reviewer")[]) });
+}
+
+/** Canonical own-data serialization: never stringify callbacks or module-controlled toJSON methods. */
+function capabilityDigest(definition: AdapterDefinition): string {
+  const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical)
+    : value && typeof value === "object" ? Object.fromEntries(Object.entries(dataObject(value)).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, member]) => [key, canonical(member)])) : value;
+  const ceiling = {
+    api: definition.api, kind: definition.kind, family: definition.family, transport: definition.transport,
+    roles: [...definition.roles].sort(), trust: definition.trust,
+    headlessInstances: definition.headlessInstances ? { form: "headless", roles: [...definition.headlessInstances.roles].sort() } : null,
+    start: { forms: definition.start.forms, defaultForm: definition.start.defaultForm, daemonPort: definition.start.daemonPort, conductorStartable: definition.start.conductorStartable },
+    permission: definition.permission, identity: definition.identity, turnEnd: definition.turnEnd,
+    session: { idField: definition.session.idField, resumeById: definition.session.resumeById, launchKind: definition.session.launchKind },
+  };
+  return digest(new TextEncoder().encode(JSON.stringify(canonical(ceiling))));
+}
 export function validateExternalDefinition(raw: unknown): AdapterDefinition {
   const definition = snapshot(raw) as AdapterDefinition;
   if (definition.api !== ADAPTER_API) return fail("adapter API mismatch");
@@ -123,9 +178,10 @@ export function validateExternalDefinition(raw: unknown): AdapterDefinition {
   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");
+  if (Object.hasOwn(definition, "instances")) return fail("external builtin instance policy is unsupported; use headlessInstances");
+  const instancePolicy = headlessInstancePolicy(definition);
   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, ["api", "kind", "family", "displayName", "transport", "roles", "optional", "defaultOnRoster", "trust", "start", "identity", "permission", "session", "turnEnd", "cli", "display", "headlessInstances"]);
   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"
@@ -159,6 +215,7 @@ export function validateExternalDefinition(raw: unknown): AdapterDefinition {
     try { return callback(); } catch { return fail(`${name} refused (details withheld)`); }
   };
   return snapshot({ ...definition,
+    ...(instancePolicy ? { headlessInstances: instancePolicy, instances: { mode: "headless", roles: instancePolicy.roles } } : {}),
     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", () => {
@@ -216,6 +273,7 @@ export async function loadExternalAdapterDefinitions(cwd: string, layers: readon
   const definitions: AdapterDefinition[] = [];
   for (const [index, declaration] of modules.entries()) {
     try {
+      const projectRoot = realPath(cwd);
       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");
@@ -228,6 +286,8 @@ export async function loadExternalAdapterDefinitions(cwd: string, layers: readon
       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");
+      capturedIdentities.set(definition, Object.freeze({ projectRoot, modulePath: relative(projectRoot, resolve(projectRoot, declaration.path)).split(sep).join("/"),
+        sha256: declaration.sha256, api: ADAPTER_API, capabilityDigest: capabilityDigest(definition) }));
       definitions.push(definition);
     } catch (error) {
       const refusal = error instanceof ExternalAdapterRefusal ? error : new ExternalAdapterRefusal("external adapter: module could not be verified or loaded (details withheld)");

package/src/adapters/jcode.ts

@@ -5,7 +5,7 @@ import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, op
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import type { Readable } from "node:stream";
-import { renderDigest, type Envelope, type PeerState } from "../hub/envelope.ts";
+import { JCODE_DEFERRED_TOOLS_INSTRUCTION, renderDigest, type Envelope, type PeerState } from "../hub/envelope.ts";
 import { AcpPeer, type AcpOptions } from "./acp.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
@@ -25,6 +25,10 @@ export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: s
   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"])];
 }
+/** The session preamble of a Jcode peer: the deferred-tools guidance (#912), then the hub's role contract when there is one. Sent once, with the session's first prompt. */
+export function jcodePreamble(roleContract?: string): string {
+  return roleContract ? `${JCODE_DEFERRED_TOOLS_INSTRUCTION}\n\n${roleContract}` : JCODE_DEFERRED_TOOLS_INSTRUCTION;
+}
 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 } };
@@ -201,7 +205,7 @@ export class JcodePeer extends AcpPeer {
     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 } });
+    super(peer, { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, AGENTHUB_LAUNCH_ID: launchId, ...JCODE_OWNED_ENV }, mcpServers: [], preamble: jcodePreamble(jcode.preamble), requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
     this.root = root; this.socket = socket; this.launchId = launchId;
   }
 

package/src/adapters/local-worker.ts

@@ -9,7 +9,9 @@ import { CONDUCTOR_TOOL_NAMES, CONDUCTOR_TOOLS, TASK_TOOL_NAMES, TASK_TOOLS, pro
 import { BasePeer } from "../hub/peers.ts";
 import type { PublishResult } from "../hub/bus.ts";
 import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
-import { runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, ApprovalWaitStop, type ToolApproval, type ApprovalProvenance, type ToolContext } from "../local/tools.ts";
+import type { DocReadPort } from "../local/doc-read.ts";
+import type { WebFetchPort } from "../local/web-fetch.ts";
+import { DOC_READ_SCHEMA, WEB_FETCH_SCHEMA, runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, ApprovalWaitStop, type ToolApproval, type ApprovalProvenance, type ToolContext } from "../local/tools.ts";
 import type { Capture } from "../memory/capture.ts";
 import type { ChatMessage, ChatResult, OmniRoute, ToolCall } from "../omniroute/client.ts";
 import { safeModelLabel } from "../omniroute/usage.ts";
@@ -36,7 +38,7 @@ export interface LocalOptions {
   turnId?: () => string | undefined;
   onApprovalStop?: (reason: string) => void;
   onTool?: (observation: ToolObservation, task?: string) => void;
-  tools: { deny: string[]; permit: ToolContext["permit"]; shellExecutionCheck?: ToolContext["shellExecutionCheck"]; bashNetwork?: SandboxNetwork; readAllow?: string[]; readOnly?: string[] };
+  tools: { docRead?: DocReadPort; webFetch?: WebFetchPort; deny: string[]; permit: ToolContext["permit"]; shellExecutionCheck?: ToolContext["shellExecutionCheck"]; bashNetwork?: SandboxNetwork; readAllow?: string[]; readOnly?: string[] };
   capture?: Capture;
   /** Runs a hub task tool (hub_task_*, hub_review, hub_remember) as this peer. Absent = the tools are not offered. */
   taskTool?: (name: string, args: Record<string, unknown>, turn: { pii: boolean }) => Promise<string>;
@@ -77,6 +79,8 @@ const system = (cwd: string, preamble = "") =>
 /** Hub-native agent loop: the hub owns every model call, so it can choose the model per call (L2) and the gateway (L3). */
 export class LocalPeer extends BasePeer {
   readonly hubNative = true;
+  readonly deliveryOnly: boolean = true;
+  readonly hubOwned: boolean = true;
   private readonly history: ChatMessage[] = [];
   private readonly sessionId = `agent-hub-local-${randomUUID()}`;
   private readonly routes: HubRouteRuntime;
@@ -109,7 +113,7 @@ export class LocalPeer extends BasePeer {
         await this.requireBudget(envs, "model_calls");
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
         if (signal.aborted) throw new Error("turn cancelled before model request");
-        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+        const tools = judge ? undefined : [...this.toolSchemas(), ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
         const result = await this.opts.omni.chat({ model, messages, ...(tools ? { tools } : {}), ...(judge ? { max_tokens: maxTokens ?? 2048 } : {}) }, { signal, ...(pii ? { onCampusOnly: true } : {}) });
         this.recordUsage(result, model, task);
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
@@ -165,6 +169,8 @@ export class LocalPeer extends BasePeer {
     const progress = { sideEffects: 0, last: "" };
     const requestedPolicy = this.opts.turnPolicy?.(envs);
     const policy = envs.some(env => env.private) ? { ...requestedPolicy, pii: true } : requestedPolicy;
+    const remoteTurn = envs.some(env => env.from.includes("@"));
+    const preserveHistory = !policy?.pii && !remoteTurn;
     const labelTurn = this.beginRouteTurn(turn, !!policy?.pii || envs.some(env => env.private), policy?.task);
     let completed = false;
     // A PII turn speaks to the console user only, and privately: its answer must not be broadcast to cloud-hosted peers.
@@ -173,7 +179,7 @@ export class LocalPeer extends BasePeer {
     this.run(envs, turn, msgs, progress, policy, reply)
       .then((answer) => {
         if (turn !== this.turn) return;
-        if (!policy?.pii) this.commit(msgs); // a PII turn leaves nothing in the history later turns send along
+        if (preserveHistory) this.commit(msgs); // Private and remote turns never enter later local capture through model history.
         if (answer) this.onMessage?.(answer, reply);
         if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed" });
         completed = true;
@@ -181,31 +187,33 @@ export class LocalPeer extends BasePeer {
       .catch((e: Error) => {
         if (turn !== this.turn) return; // aborted by the watchdog or stop(): nothing to report, nothing was committed
         if (e instanceof ApprovalWaitStop) {
+          const message = remoteTurn ? "remote turn failed" : e.message;
           this.completeMissingToolResults(msgs, "not run: turn ended after unanswered approvals");
-          msgs.push({ role: "assistant", content: e.message });
-          if (!policy?.pii) this.commit(msgs);
-          this.onMessage?.(e.message, reply);
-          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed", reason: e.message });
+          msgs.push({ role: "assistant", content: message });
+          if (preserveHistory) this.commit(msgs);
+          this.onMessage?.(message, reply);
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed", reason: message });
           return; // even without effects, an unanswered approval must not trigger safe replay
         }
         if (this.budgetStopReason && !(e instanceof ExecutionBudgetStop)) e = new ExecutionBudgetStop(this.budgetStopReason);
-        this.opts.log?.(`[${this.id}] turn failed: ${e.message}`);
+        const message = remoteTurn ? "remote turn failed" : e.message;
+        this.opts.log?.(`[${this.id}] turn failed: ${message}`);
         if (e instanceof ExecutionBudgetStop) {
-          this.reportBudgetStop(e, msgs, progress, reply, !!policy?.pii, deliveryId);
+          this.reportBudgetStop(e, msgs, progress, reply, !preserveHistory, deliveryId, remoteTurn);
           return;
         }
         if (!progress.sideEffects) {
-          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: e.message });
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: message });
           else this.onFailed?.(envs); // legacy delivery: safe to redeliver
           return;
         }
         // Tools already changed things. Redelivering would redo approved writes and commits, so report instead.
         // A model call is the only thing that throws here, and every tool call before it has its result: msgs is consistent.
-        const note = `(turn failed after ${progress.sideEffects} tool call(s) with side effects: ${e.message.slice(0, 200)}. The work may be partial; check before repeating it.) ${progress.last}`.trim();
+        const note = remoteTurn ? message : `(turn failed after ${progress.sideEffects} tool call(s) with side effects: ${message.slice(0, 200)}. The work may be partial; check before repeating it.) ${progress.last}`.trim();
         msgs.push({ role: "assistant", content: note });
-        if (!policy?.pii) this.commit(msgs);
+        if (preserveHistory) this.commit(msgs);
         this.onMessage?.(note, reply);
-        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
+        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: message });
       })
       .finally(() => {
         this.endRouteTurn(labelTurn, completed ? "completed" : "failed");
@@ -235,8 +243,9 @@ export class LocalPeer extends BasePeer {
   ): Promise<string> {
     const { maxSteps = 30 } = this.opts;
     const turnSignal = this.abort!.signal;
-    // Local capture preserves the host privacy fence: nothing of a PII turn is recorded.
-    const capture = policy?.pii ? undefined : this.opts.capture;
+    // Remote text/tool output is never memory evidence, even beside ordinary local work in the same turn.
+    const remoteTurn = envs.some(env => env.from.includes("@"));
+    const capture = policy?.pii || remoteTurn ? undefined : this.opts.capture;
     // Unknown gateway state is never permission to send PII.
     if (policy?.pii && !(await this.opts.omni.onCampus())) {
       return "Refused: this is a PII task and the only reachable gateway is off campus (Cloudflare Access). Connect the VPN and assign it again.";
@@ -279,9 +288,11 @@ export class LocalPeer extends BasePeer {
           const result: ChatMessage = { role: "tool", tool_call_id: call.id, content: output, is_error: toolResultFailed(name, output) };
           msgs.push(result); results.push(result);
           if (this.approvalStopReason) { this.abort?.abort(); throw new ApprovalWaitStop(this.approvalStopReason); }
-          this.observeTool(call, output, policy, `${this.sessionId}.${turn}.${step}`);
+          if (!remoteTurn) this.observeTool(call, output, policy, `${this.sessionId}.${turn}.${step}`);
           // Hub tool arguments/results are not capture evidence; Tasks owns its screened memory writes.
-          if (name !== "hub_send" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, sourceId: `${this.sessionId}.${turn}.${step}.${captureInvocation++}`, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
+          // doc_read text is converted document content (a converter can surface hidden text), never memory evidence: not captured, whatever the turn.
+          // web_fetch text is a third party's page and its URL is the model's own request: neither is memory evidence either (#515b).
+          if (name !== "hub_send" && name !== "doc_read" && name !== "web_fetch" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, sourceId: `${this.sessionId}.${turn}.${step}.${captureInvocation++}`, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
         }
       } finally { if (results.length) this.routes.observeResults(res.routeDecision, res.message, results); }
     }
@@ -289,9 +300,14 @@ export class LocalPeer extends BasePeer {
     return `(stopped after ${maxSteps} steps) ${progress.last}`.trim();
   }
 
+  /** The base tools, plus `doc_read` and `web_fetch` only when the project opted in (`local.doc_read`, `local.web_fetch.allow`; both off by default). */
+  private toolSchemas() { const extra = [...(this.opts.tools.docRead ? [DOC_READ_SCHEMA] : []), ...(this.opts.tools.webFetch ? [WEB_FETCH_SCHEMA] : [])]; return extra.length ? [...TOOL_SCHEMAS, ...extra] : TOOL_SCHEMAS; }
+
   private toolContext(envs: Envelope[], turnSignal: AbortSignal, pii: boolean, reply: EnvelopeOpts): ToolContext {
     const executionGeneration=this.turn;
     return {
+      ...(this.opts.tools.docRead ? { docRead: { ...this.opts.tools.docRead, pii } } : {}),
+      ...(this.opts.tools.webFetch ? { webFetch: { ...this.opts.tools.webFetch, pii } } : {}),
       cwd: this.opts.cwd,
       deny: this.opts.tools.deny,
       readOnly: this.opts.tools.readOnly,
@@ -337,15 +353,16 @@ export class LocalPeer extends BasePeer {
     };
   }
 
-  private reportBudgetStop(e: Error, msgs: ChatMessage[], progress: { sideEffects: number; last: string }, reply: EnvelopeOpts, pii: boolean, deliveryId?: string): void {
-    this.completeMissingToolResults(msgs, `not run: ${e.message}`);
-    const detail = progress.sideEffects
+  private reportBudgetStop(e: Error, msgs: ChatMessage[], progress: { sideEffects: number; last: string }, reply: EnvelopeOpts, privateHistory: boolean, deliveryId?: string, remoteTurn = false): void {
+    const message = remoteTurn ? "remote turn failed" : e.message;
+    this.completeMissingToolResults(msgs, `not run: ${message}`);
+    const detail = remoteTurn ? message : progress.sideEffects
       ? `(execution budget stopped after ${progress.sideEffects} tool call(s) with side effects; partial work may exist and needs review) ${progress.last}`.trim()
       : `(execution budget stopped before any tool side effects; no work was repeated) ${progress.last}`.trim();
     msgs.push({ role: "assistant", content: detail });
-    if (!pii) this.commit(msgs);
+    if (!privateHistory) this.commit(msgs);
     this.onMessage?.(detail, reply);
-    if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
+    if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: message });
   }
 
   private async requireBudget(envs: Envelope[], unit: "model_calls" | "tool_calls"): Promise<void> {
@@ -384,7 +401,7 @@ export class LocalPeer extends BasePeer {
     }
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
     const task = policy?.task === undefined ? undefined : Number(policy.task);
-    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+    const tools = [...this.toolSchemas(), ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
     const signal = this.abort!.signal;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
     const routed = await this.hubCall(route, messages, policy, signal);
@@ -444,7 +461,7 @@ export class LocalPeer extends BasePeer {
   }
 
   private observeTool(call: ToolCall, output: string, policy: { pii: boolean; task?: string } | undefined, nativeTurn: string): void {
-    if (policy?.pii) return;
+    if (policy?.pii || call.function.name === "doc_read" || call.function.name === "web_fetch") return; // document and web text: no research observation carries it
     try {
       const command = safeParse(call.function.arguments).command;
       this.opts.onTool?.({ name: call.function.name, ...(typeof command === "string" ? { command } : {}), resultText: output, isError: toolResultFailed(call.function.name, output), source: "local", turn: nativeTurn }, policy?.task);

package/src/adapters/native-proof-ports.ts

@@ -0,0 +1,10 @@
+import type { PeerAdapter } from "../hub/peers.ts";
+import { isFixedBuiltinDefinition, type AdapterDefinition } from "./registry.ts";
+
+/** Presence is forbidden on a foreign runtime, including a member whose value is undefined. */
+export function assertNativeProofPorts(definition: AdapterDefinition | undefined, product: PeerAdapter): void {
+  if (isFixedBuiltinDefinition(definition)) return;
+  for (const port of ["frontendProxy", "statusNotice", "revertTurn"] as const) {
+    if (port in product) throw new Error(`${definition?.kind ?? product.id}: ${port} is restricted to fixed builtin adapter products`);
+  }
+}

package/src/adapters/pi.ts

@@ -12,6 +12,7 @@ import { PiSessionBookmarkMismatch, validatePiSession } from "../pi/session.ts";
 import { ApprovalWaitStop, toolResultFailed, type ApprovalProvenance } from "../local/tools.ts";
 import { piToolStepCeiling, type PiToolStepCeiling } from "../pi/ceiling.ts";
 import type { ExecutionBudgetDecision, ExecutionUnit } from "../hub/execution-budget.ts";
+import type { StartForm } from "./registry-types.ts";
 
 export interface PiModelDescriptor { id: string; name?: string; contextWindow?: number; maxTokens?: number; reasoning?: boolean; }
 export interface PiToolSchema { name: string; description?: string; parameters: Record<string, unknown>; }
@@ -99,6 +100,7 @@ function ownerStillAlive(pid: number, signature: string | undefined): boolean {
 
 export class PiPeer extends BasePeer {
   readonly hubNative = true;
+  readonly hubOwned: boolean = true;
   private proc?: ChildProcessWithoutNullStreams;
   private server?: ReturnType<typeof Bun.serve>;
   private buffer = "";
@@ -202,6 +204,10 @@ export class PiPeer extends BasePeer {
     const file = this.sessionFile && (exists || !empty) ? this.sessionFile : undefined;
     return { launch: { kind: "pi", cwd: this.opts.cwd, mode: this.opts.mode, backend: this.opts.backend, ...(this.opts.model ? { model: this.opts.model } : {}), ...(file ? { sessionFile: file } : {}) }, ...(this.sessionId ? { sessionId: this.sessionId } : {}), ...(file ? { sessionFile: file } : {}) };
   }
+  get nativeSession(): string | undefined {
+    const session = this.recoveryMetadata().sessionId;
+    return typeof session === "string" ? session : undefined;
+  }
 
   /** Verify the live source before choosing ID-only restoration. Never infer emptiness from a missing file. */
   async captureResume(): Promise<Record<string, unknown>> {
@@ -502,6 +508,7 @@ export class PiPeer extends BasePeer {
     return pending.map((call) => call.settled);
   }
   get mode(): "headless" | "tui" { return this.opts.mode; }
+  get form(): StartForm { return this.opts.mode; }
 
   /** Withdraw hub admission without shutting down a person's Pi TUI or its bridge. */
   async detachForRoster(): Promise<void> {

package/src/adapters/registry-types.ts

@@ -72,6 +72,8 @@ export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
   projectRoot: string;
   stateDir: string;
+  /** Host-derived private external-instance state namespace; stateDir remains the canonical daemon control directory. */
+  instanceStateDir?: string;
   kindConfig: unknown;
   permission: PermissionMode | "read-only";
   mcpServers: NonNullable<AcpOptions["mcpServers"]>;
@@ -207,6 +209,8 @@ export interface AdapterDefinition {
     conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin"; currentChild?: true };
+  /** External module data-only opt-in. The verified loader derives the internal instances policy from it (#754). */
+  headlessInstances?: { form: "headless"; roles: readonly ("implementer" | "verifier" | "reviewer")[] };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
   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. */

package/src/adapters/reviewer-print.ts

@@ -156,6 +156,7 @@ const reviewTask = (env: Envelope): number | undefined => {
 
 export class ReviewerPrintPeer extends BasePeer {
   readonly hubNative = true;
+  readonly hubOwned: boolean = true;
   private generation = 0;
   private child: OwnedPrintChild | undefined;
   private childCleanup: (() => Promise<void>) | undefined;

package/src/broker/protocol.ts

@@ -0,0 +1,203 @@
+/** Broker v1 control protocol. The broker verifies public signatures and never opens room ciphertext. */
+import {
+  decodeBase64url, encodeBase64url, signBytes, verifyBytes,
+  type HubIdentity,
+} from "../rooms/crypto.ts";
+import {
+  brokerUrl, canonicalBytes, decodeRoster, publicRosterWire, verifyPublicRoster,
+  type OwnerPin, type VerifiedPublicRoster,
+} from "../rooms/wire.ts";
+
+export const BROKER_CONTROL_LIMITS = Object.freeze({ control: 1_048_576, challenge: 8192, nonceBytes: 32 });
+export type BrokerProtocolCode = "invalid_wire" | "limit" | "untrusted" | "expired" | "authentication_failed";
+export class BrokerProtocolError extends Error {
+  constructor(readonly code: BrokerProtocolCode) { super(`Broker protocol: ${code}`); this.name = "BrokerProtocolError"; }
+}
+function fail(code: BrokerProtocolCode = "invalid_wire"): never { throw new BrokerProtocolError(code); }
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const FP = /^[0-9a-f]{64}$/;
+const DIGEST = /^[A-Za-z0-9_-]{43}$/;
+const B64URL = /^[A-Za-z0-9_-]+$/;
+
+export interface BrokerChallenge {
+  v: 1;
+  type: "challenge";
+  room: string;
+  broker: string;
+  nonce: string;
+  expiresAt: number;
+  rosterDigest: string | null;
+}
+export interface BrokerAuth {
+  v: 1;
+  type: "auth";
+  member: string;
+  roster: string | null;
+  signature: string;
+}
+export interface BrokerRosterReady { v: 1; type: "roster_ready"; digest: string }
+export interface BrokerReceived { v: 1; type: "received"; digest: string }
+export type BrokerControl = BrokerAuth | BrokerRosterReady | BrokerReceived;
+
+function record(x: unknown, keys: string[]): Record<string, unknown> {
+  if (typeof x !== "object" || x === null || Array.isArray(x) || Object.getPrototypeOf(x) !== Object.prototype) fail();
+  const value = x as Record<string, unknown>;
+  if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) fail();
+  return value;
+}
+function canonicalDecode<T>(input: Uint8Array, max: number, parse: (value: unknown) => T): T {
+  if (!(input instanceof Uint8Array) || input.length === 0 || input.length > max) fail("limit");
+  let raw: unknown;
+  try { raw = JSON.parse(decoder.decode(input)); } catch { fail(); }
+  const value = parse(raw), bytes = canonicalBytes(value);
+  if (bytes.length !== input.length || bytes.some((byte, i) => input[i] !== byte)) fail();
+  return value;
+}
+function exactText(x: unknown, pattern: RegExp): string {
+  if (typeof x !== "string" || !pattern.test(x)) fail();
+  return x;
+}
+function roomId(x: unknown): string {
+  if (typeof x !== "string" || x.length !== 43 || !B64URL.test(x)) fail();
+  try { decodeBase64url(x, 32); } catch { fail(); }
+  return x;
+}
+function digestText(x: unknown): string {
+  const value = exactText(x, DIGEST);
+  try { decodeBase64url(value, 32); } catch { fail(); }
+  return value;
+}
+function timestamp(x: unknown): number {
+  if (typeof x !== "number" || !Number.isSafeInteger(x) || x <= 0) fail();
+  return x;
+}
+function nullableDigest(x: unknown): string | null { return x === null ? null : digestText(x); }
+function brokerAudience(value: unknown): string {
+  try {
+    const normalized = brokerUrl(value), url = new URL(normalized);
+    if (url.pathname !== "/" || url.search) fail();
+    return normalized;
+  } catch { return fail(); }
+}
+function parseChallenge(x: unknown): BrokerChallenge {
+  const o = record(x, ["v", "type", "room", "broker", "nonce", "expiresAt", "rosterDigest"]);
+  if (o.v !== 1 || o.type !== "challenge") fail();
+  const nonce = exactText(o.nonce, B64URL);
+  try { decodeBase64url(nonce, BROKER_CONTROL_LIMITS.nonceBytes); } catch { fail(); }
+  return { v: 1, type: "challenge", room: roomId(o.room), broker: brokerAudience(o.broker), nonce,
+    expiresAt: timestamp(o.expiresAt), rosterDigest: nullableDigest(o.rosterDigest) };
+}
+function parseAuth(x: unknown): BrokerAuth {
+  const o = record(x, ["v", "type", "member", "roster", "signature"]);
+  if (o.v !== 1 || o.type !== "auth") fail();
+  let roster: string | null = null;
+  if (o.roster !== null) {
+    roster = exactText(o.roster, B64URL);
+    if (roster.length > Math.ceil(524288 * 4 / 3)) fail("limit");
+    let wire: Uint8Array;
+    try { wire = decodeBase64url(roster); } catch { fail(); }
+    decodeRoster(wire);
+  }
+  const signature = exactText(o.signature, B64URL);
+  try { decodeBase64url(signature, 64); } catch { fail(); }
+  return { v: 1, type: "auth", member: exactText(o.member, FP), roster, signature };
+}
+function parseControl(x: unknown): BrokerControl {
+  if (typeof x !== "object" || x === null || Array.isArray(x)) fail();
+  const type = (x as Record<string, unknown>).type;
+  if (type === "auth") return parseAuth(x);
+  if (type === "roster_ready" || type === "received") {
+    const o = record(x, ["v", "type", "digest"]);
+    if (o.v !== 1 || o.type !== type) fail();
+    return { v: 1, type: type as "roster_ready" | "received", digest: digestText(o.digest) };
+  }
+  fail();
+}
+function challengeBytes(challenge: BrokerChallenge, member: string, initialRosterDigest: string | null): Uint8Array {
+  return canonicalBytes(["agent-hub.rooms.broker.v1", "auth", challenge, member, initialRosterDigest]);
+}
+function validateChallenge(challenge: BrokerChallenge): BrokerChallenge {
+  return parseChallenge(challenge);
+}
+
+export function decodeBrokerChallenge(input: Uint8Array): BrokerChallenge {
+  return canonicalDecode(input, BROKER_CONTROL_LIMITS.challenge, parseChallenge);
+}
+export function encodeBrokerChallenge(challenge: BrokerChallenge): Uint8Array {
+  return canonicalBytes(validateChallenge(challenge));
+}
+export function decodeBrokerControl(input: Uint8Array): BrokerControl {
+  return canonicalDecode(input, BROKER_CONTROL_LIMITS.control, parseControl);
+}
+export function encodeBrokerControl(control: BrokerControl): Uint8Array {
+  return canonicalBytes(parseControl(control));
+}
+
+export async function createBrokerAuth(input: {
+  challenge: BrokerChallenge;
+  identity: HubIdentity;
+  broker: string;
+  room: string;
+  initialRoster?: Uint8Array;
+}): Promise<Uint8Array> {
+  const challenge = validateChallenge(input.challenge);
+  if (brokerAudience(input.broker) !== challenge.broker || roomId(input.room) !== challenge.room) fail("untrusted");
+  const member = input.identity.public.fingerprint;
+  if (!FP.test(member)) fail("untrusted");
+  let rosterWire: string | null = null;
+  let rosterDigest: string | null = null;
+  if (input.initialRoster !== undefined) {
+    if (challenge.rosterDigest !== null) fail("untrusted");
+    if (!(input.initialRoster instanceof Uint8Array)) fail();
+    const initialRoster = Uint8Array.from(input.initialRoster);
+    const decoded = decodeRoster(initialRoster);
+    const pin: OwnerPin = { room: decoded.room, owner: decoded.owner, minEpoch: "0" };
+    const proof = await verifyPublicRoster({ wire: initialRoster, pin });
+    if (proof.room !== challenge.room || proof.owner !== member || !proof.members.some(m => m.fingerprint === member)) fail("untrusted");
+    rosterWire = encodeBase64url(initialRoster);
+    rosterDigest = proof.digest;
+  } else {
+    if (challenge.rosterDigest === null) fail("untrusted");
+    rosterDigest = null;
+  }
+  const body = { v: 1 as const, type: "auth" as const, member, roster: rosterWire };
+  const auth = { ...body, signature: encodeBase64url(await signBytes(input.identity, challengeBytes(challenge, member, rosterDigest))) };
+  const wire = canonicalBytes(auth);
+  parseAuth(auth);
+  return wire;
+}
+
+/** Verify the challenge signature and resolve the public roster used for membership. */
+export async function verifyBrokerAuth(input: {
+  wire: Uint8Array;
+  challenge: BrokerChallenge;
+  roster?: VerifiedPublicRoster;
+}): Promise<{ member: string; roster: VerifiedPublicRoster; initial: boolean }> {
+  const challenge = validateChallenge(input.challenge);
+  const auth = canonicalDecode(input.wire, BROKER_CONTROL_LIMITS.control, parseAuth);
+  let roster: VerifiedPublicRoster;
+  let signedRosterDigest: string | null;
+  let initial: boolean;
+  if (challenge.rosterDigest === null) {
+    if (auth.roster === null || input.roster !== undefined) fail("untrusted");
+    let rosterWire: Uint8Array;
+    try { rosterWire = decodeBase64url(auth.roster); } catch { fail(); }
+    const decoded = decodeRoster(rosterWire);
+    roster = await verifyPublicRoster({ wire: rosterWire, pin: { room: decoded.room, owner: decoded.owner, minEpoch: "0" } });
+    if (roster.room !== challenge.room || roster.owner !== auth.member) fail("untrusted");
+    signedRosterDigest = roster.digest;
+    initial = true;
+  } else {
+    if (auth.roster !== null || !input.roster) fail("untrusted");
+    roster = input.roster;
+    publicRosterWire(roster);
+    if (roster.room !== challenge.room || roster.digest !== challenge.rosterDigest) fail("untrusted");
+    signedRosterDigest = null;
+    initial = false;
+  }
+  const member = roster.members.find(candidate => candidate.fingerprint === auth.member);
+  if (!member) fail("untrusted");
+  const signature = decodeBase64url(auth.signature, 64);
+  if (!await verifyBytes(member, challengeBytes(challenge, auth.member, signedRosterDigest), signature)) fail("authentication_failed");
+  return { member: auth.member, roster, initial };
+}