@staix/agent-hub 0.19.0 → 0.21.0

package/src/adapters/codex-appserver.ts

@@ -2,13 +2,22 @@ import { spawn, type ChildProcess } from "node:child_process";
 import type { Server, ServerWebSocket } from "bun";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import type { PermissionMode } from "../hub/permission-mode.ts";
-import { BasePeer } from "../hub/peers.ts";
+import { BasePeer, type FrontendProxyPort } from "../hub/peers.ts";
 import { codexContext, type ContextReading } from "../hub/context-window.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import type { ContextReader } from "./registry-types.ts";
 import { ACTION_BUDGET_OPTION, type ActionGateVerdict, type PermissionRequest } from "./acp.ts";
 
 const UNIDENTIFIED_CANCELLATION_NOTICE = "Codex cancelled turn has no verified native id; reattach the native session before further hub delivery";
+const PLANNER_SANDBOX_REFUSAL = "Codex planner thread requires a confirmed read-only sandbox";
+
+/** Codex 0.164.0 SandboxPolicy readOnly variant; an unreadable or widened policy is not proof. */
+function confirmsReadOnlySandbox(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const policy = value as Record<string, unknown>;
+  return policy.type === "readOnly" && Object.keys(policy).every(key => key === "type" || key === "networkAccess")
+    && (!Object.hasOwn(policy, "networkAccess") || typeof policy.networkAccess === "boolean");
+}
 
 /** A counter Codex reported: a finite non-negative number, otherwise 0 (an absent kind is not a negative delta). */
 const counter = (value: unknown): number => { const n = Number(value); return Number.isFinite(n) && n >= 0 ? n : 0; };
@@ -16,6 +25,8 @@ export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
   proxyPort: number;
   permissionMode?: PermissionMode;
+  /** Live host planner ceiling on initial thread start/resume; the attached person may change later turn policy. */
+  threadSandbox?: "read-only" | (() => "read-only" | "unavailable" | undefined);
   /** Host-only always-ask gate, shared with ACP; an absent verdict preserves native handling. */
   actionGate?: (call: { names: readonly string[]; kind?: string; input: unknown }, session: string) => ActionGateVerdict | undefined;
   onPermission?: (request: PermissionRequest, signal?: AbortSignal) => Promise<string | undefined>;
@@ -71,6 +82,10 @@ interface Link {
   backlog: string[]; // TUI frames that arrived before the upstream socket opened
   approvalIds: Set<string | number>; // intercepted native ids stay tombstoned for this socket lifetime
   tracked: Map<string | number, string>; // request id -> method, for thread/start and thread/resume
+  /** Correlated native initial policy, retained even before this instance gains the planner role. */
+  readOnlyThread?: string;
+  /** An ordinary client reused an outstanding id; this link cannot attest a planner thread until reattach. */
+  ambiguousThreadRpc?: true;
 }
 
 const TRACKED = new Set(["thread/start", "thread/resume"]);
@@ -82,6 +97,7 @@ const TRACKED = new Set(["thread/start", "thread/resume"]);
  * TUI's, and their responses are swallowed.
  */
 export class CodexPeer extends BasePeer {
+  readonly frontendProxy: FrontendProxyPort;
   private permissionMode: PermissionMode;
   private readonly actionWaits = new Map<AbortController, { link: Link; turn: string | undefined }>();
   get actionGated(): boolean { return this.opts.actionGate !== undefined; }
@@ -136,6 +152,13 @@ export class CodexPeer extends BasePeer {
   ) {
     super(id, opts.watchdogMs);
     this.permissionMode = opts.permissionMode ?? "ask";
+    const owner = this;
+    this.frontendProxy = {
+      get url() { return owner.proxyUrl; },
+      get attached() { return owner.proxyAttached; },
+      setStartupPermissionMode: this.setStartupPermissionMode.bind(this),
+      clearPermissionMode: this.clearPermissionMode.bind(this),
+    };
   }
 
   recoveryMetadata(): Record<string, unknown> {
@@ -149,6 +172,7 @@ export class CodexPeer extends BasePeer {
   get thread(): string {
     return this.threadId;
   }
+  get nativeSession(): string | undefined { return this.threadId || undefined; }
 
   get proxyUrl(): string {
     return `ws://127.0.0.1:${this.server?.port ?? this.opts.proxyPort}`;
@@ -224,7 +248,7 @@ export class CodexPeer extends BasePeer {
   /** Resolves when app-server accepts the turn. Only called while idle, i.e. a thread exists and no turn runs. */
   deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
     const link = this.link;
-    if (this.state !== "idle" || !link || link.up.readyState !== WebSocket.OPEN) {
+    if (this.state !== "idle" || !link || link.up.readyState !== WebSocket.OPEN || !this.threadSandboxReady(link)) {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is not injectable` });
       return Promise.reject(new Error(`${this.id} is not injectable`));
     }
@@ -276,6 +300,10 @@ export class CodexPeer extends BasePeer {
           reject(e);
         },
       });
+      if (!this.threadSandboxReady(link)) {
+        const pending = this.pending.get(id); this.pending.delete(id);
+        pending?.reject(new Error(`${this.id} is not injectable`)); return;
+      }
       link.up.send(
         JSON.stringify({ method: "turn/start", id, params: this.applyPermissionPolicy({ threadId: this.threadId, input: [{ type: "text", text }] }, id) }),
       );
@@ -290,7 +318,7 @@ export class CodexPeer extends BasePeer {
   steer(envs: Envelope[], deliveryId?: string): Promise<void> {
     const link = this.link;
     const expectedTurnId = [...this.activeTurns].reverse().find((t) => !t.startsWith("unknown:"));
-    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId) {
+    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId || !this.threadSandboxReady(link)) {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} has no steerable turn` });
       return Promise.reject(new Error(`${this.id} has no steerable turn`));
     }
@@ -337,6 +365,10 @@ export class CodexPeer extends BasePeer {
         reject: fail,
       });
       const input = [{ type: "text", text: this.render(envs) }];
+      if (!this.threadSandboxReady(link)) {
+        const pending = this.pending.get(id); this.pending.delete(id);
+        pending?.reject(new Error(`${this.id} is not injectable`)); return;
+      }
       link.up.send(JSON.stringify({ method: "turn/steer", id, params: { threadId: this.threadId, expectedTurnId, input } }));
     });
   }
@@ -349,12 +381,16 @@ export class CodexPeer extends BasePeer {
   steerText(text: string): Promise<"accepted" | "refused" | "unanswered"> {
     const link = this.link;
     const expectedTurnId = [...this.activeTurns].reverse().find((t) => !t.startsWith("unknown:"));
-    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId) return Promise.resolve("refused");
+    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId || !this.threadSandboxReady(link)) return Promise.resolve("refused");
     const id = this.nextId--;
     return new Promise((resolve) => {
       const timer = setTimeout(() => this.pending.delete(id) && resolve("unanswered"), this.opts.steerTimeoutMs ?? 10_000);
       timer.unref?.();
       this.pending.set(id, { resolve: () => (clearTimeout(timer), resolve("accepted")), reject: () => (clearTimeout(timer), resolve("refused")) });
+      if (!this.threadSandboxReady(link)) {
+        const pending = this.pending.get(id); this.pending.delete(id);
+        pending?.reject(new Error(`${this.id} is not injectable`)); return;
+      }
       link.up.send(JSON.stringify({ method: "turn/steer", id, params: { threadId: this.threadId, expectedTurnId, input: [{ type: "text", text }] } }));
     });
   }
@@ -474,6 +510,7 @@ export class CodexPeer extends BasePeer {
     this.link = undefined;
     this.restoringApprovals.clear();
     this.threadId = "";
+    this.onDoing?.("reset");
     this.contextEpoch++;
     this.deliveryEpoch++;
     this.retiredTurns.clear(); this.unidentifiedCancellation = false;
@@ -551,6 +588,9 @@ export class CodexPeer extends BasePeer {
   private fromTui(link: Link, raw: string): void {
     const msg = parse(raw);
     if (msg?.id !== undefined && !msg.method && link.approvalIds.has(msg.id)) return;
+    const sandbox = this.threadSandboxPolicy();
+    const threadRequest = TRACKED.has(msg?.method), turnRequest = msg?.method === "turn/start" || msg?.method === "turn/steer";
+    if (sandbox === "unavailable" && (threadRequest || turnRequest) || sandbox === "read-only" && turnRequest && (link !== this.link || link.tracked.size > 0 || link.readOnlyThread !== this.threadId)) return this.refusePlannerThread(link, msg.id);
     if (msg?.method === "turn/interrupt" && link === this.link) this.abortActionWaits(link, typeof msg.params?.turnId === "string" ? msg.params.turnId : undefined);
     if (msg?.method === "turn/start" && msg.params && link === this.link) {
       const thread = typeof msg.params.threadId === "string" ? msg.params.threadId : this.threadId;
@@ -563,7 +603,15 @@ export class CodexPeer extends BasePeer {
         raw = JSON.stringify(msg);
       }
     }
-    if (msg?.id !== undefined && TRACKED.has(msg.method)) link.tracked.set(msg.id, msg.method);
+    if (msg?.id !== undefined && TRACKED.has(msg.method)) {
+      if (link.tracked.has(msg.id)) link.ambiguousThreadRpc = true;
+      if (sandbox === "read-only") {
+        if (link.ambiguousThreadRpc || msg.params !== undefined && (!msg.params || typeof msg.params !== "object" || Array.isArray(msg.params))) return this.refusePlannerThread(link, msg.id);
+        msg.params = { ...msg.params, sandbox: "read-only" };
+        raw = JSON.stringify(msg);
+      }
+      link.tracked.set(msg.id, msg.method);
+    }
     if (link.up.readyState === WebSocket.OPEN) link.up.send(raw);
     else link.backlog.push(raw);
   }
@@ -586,7 +634,11 @@ export class CodexPeer extends BasePeer {
     if (typeof msg.result?.userAgent === "string") this.version = /^[^/\s]+\/(\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(msg.result.userAgent)?.[1] ?? this.version;
     const tracked = msg.id !== undefined && !msg.method ? link.tracked.get(msg.id) : undefined;
     if (tracked && link.tracked.delete(msg.id)) {
+      const sandbox = this.threadSandboxPolicy();
+      const readOnly = !link.ambiguousThreadRpc && msg.error === undefined && typeof msg.result?.thread?.id === "string" && !!msg.result.thread.id && confirmsReadOnlySandbox(msg.result?.sandbox);
+      if (sandbox === "unavailable" || sandbox === "read-only" && !readOnly) return this.refusePlannerThread(link, msg.id);
       if (typeof msg.result?.thread?.id === "string") {
+        link.readOnlyThread = readOnly ? msg.result.thread.id : undefined;
         // A resumed response may report the sticky hub override, not the original native choice.
         const thread = msg.result.thread.id;
         if (!this.overriddenApprovals.has(thread) && msg.result.approvalPolicy != null) this.nativeApprovalPolicies.set(thread, msg.result.approvalPolicy);
@@ -597,6 +649,32 @@ export class CodexPeer extends BasePeer {
     link.tui.send(raw);
   }
 
+  private threadSandboxPolicy(): "read-only" | "unavailable" | undefined {
+    try {
+      const value = typeof this.opts.threadSandbox === "function" ? this.opts.threadSandbox() : this.opts.threadSandbox;
+      return value === undefined || value === "read-only" ? value : "unavailable";
+    } catch { return "unavailable"; }
+  }
+
+  /** Role changes never turn an ordinary writable/unknown thread into a proved planner thread. */
+  private threadSandboxReady(link: Link): boolean {
+    const sandbox = this.threadSandboxPolicy();
+    if (sandbox === "unavailable") { this.refusePlannerThread(link, undefined); return false; }
+    if (sandbox === "read-only") {
+      if (link.tracked.size > 0) return false;
+      if (link !== this.link || link.readOnlyThread !== this.threadId) { this.refusePlannerThread(link, undefined); return false; }
+    }
+    return true;
+  }
+
+  /** Refuse before adoption or another host delivery, including while a previous thread was idle. */
+  private refusePlannerThread(link: Link, id: unknown): void {
+    if (link.tui.readyState === WebSocket.OPEN && (typeof id === "string" || typeof id === "number")) link.tui.send(JSON.stringify({ id, error: { code: -32000, message: PLANNER_SANDBOX_REFUSAL } }));
+    link.tracked.clear();
+    this.detach(link);
+    link.tui.close(1008, PLANNER_SANDBOX_REFUSAL);
+  }
+
   private abortActionWaits(link?: Link, turn?: string): void {
     for (const [controller, wait] of this.actionWaits) if ((!link || wait.link === link) && (!turn || wait.turn === turn)) controller.abort();
   }
@@ -664,6 +742,7 @@ export class CodexPeer extends BasePeer {
     this.freshThread = fresh;
     this.link = link;
     this.threadId = threadId;
+    this.onDoing?.("reset");
     this.contextEpoch++;
     this.deliveryEpoch++;
     this.retiredTurns.clear(); this.unidentifiedCancellation = false;
@@ -694,6 +773,7 @@ export class CodexPeer extends BasePeer {
       link.up.send(JSON.stringify({ method: "thread/revert", id, params: { threadId: this.threadId, beforeTurnId: turnId } }));
     });
   }
+  revertTurn(nativeTurn: string): Promise<void> { return this.revert(nativeTurn); }
 
   /** account/rateLimits/read through the TUI's connection, with a hub id so the answer never reaches the TUI. */
   private readUsage(): void {
@@ -712,6 +792,9 @@ export class CodexPeer extends BasePeer {
       this.opts.onUsage?.({ rateLimitReachedType: "usageLimitExceeded" }, true);
     }
     if (link !== this.link || params.threadId !== this.threadId) return;
+    // #878: the bound thread's name and its plan's in-progress step, for the hub's DOING column only.
+    if (method === "thread/name/updated") return void this.onDoing?.("title", params.threadName);
+    if (method === "turn/plan/updated") return void this.onDoing?.("todo", Array.isArray(params.plan) ? params.plan.find((s: any) => s?.status === "inProgress")?.step : undefined);
     const nativeId = method === "turn/started" || method === "turn/completed" ? params.turn?.id : params.turnId;
     if (typeof nativeId === "string" && this.retiredTurns.has(nativeId)) {
       if (method === "turn/completed") this.retiredTurns.delete(nativeId);

package/src/adapters/conformance/enrollment.ts

@@ -4,7 +4,7 @@ import { isFixedBuiltinDefinition } from "../registry.ts";
 /** Stable generic ACP legs; both actual test registration and enrollment validation consume this catalog. */
 export const ACP_LEGS = Object.freeze(["native-approval-rpc", "native-mode-ack", "native-quota", "watchdog-generation"] as const);
 export type AcpLeg = typeof ACP_LEGS[number];
-/** Reserved until 2b supplies the restrictive ACP product members; not an executable ACP leg yet. */
+/** Mandatory product invariant, asserted for generic and owned ACP factories rather than skipped protocol legs. */
 export const ACP_PORTS_LEG = "restrictive-ports";
 export const NATIVE_PROOF_PORTS_LEG = "native-proof-ports";
 /** No unsupported key or non-generic ACP engine can silently escape an executable catalog leg. */
@@ -18,8 +18,9 @@ export function assertAcpLegEnrollment(definitions: readonly AdapterDefinition[]
       if (!row || !isFixedBuiltinDefinition(row.definition)) throw new Error(`${key}: only fixed builtin proof legs may be nonapplicable`);
       continue;
     }
-    if (separator < 1 || !acp.has(kind) || !(ACP_LEGS as readonly string[]).includes(leg) && leg !== ACP_PORTS_LEG) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
-    if (leg === ACP_PORTS_LEG && reason !== "ports added in 2b") throw new Error(`${key}: reserved ACP ports leg requires reason ports added in 2b`);
+    if (separator < 1 || !acp.has(kind)) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
+    if (leg === ACP_PORTS_LEG) throw new Error(`${key}: mandatory ACP restrictive ports leg cannot be unsupported`);
+    if (!(ACP_LEGS as readonly string[]).includes(leg)) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
   }
   for (const definition of acp.values()) if (definition.start.daemonPort !== "acp") {
     for (const leg of ACP_LEGS) {
@@ -50,7 +51,6 @@ export function assertEnrollment(definitions: readonly AdapterDefinition[], enro
   }
   for (const { id, definition } of rows) {
     if (isFixedBuiltinDefinition(definition) && !Object.hasOwn(unsupportedLegs, `${id}:${NATIVE_PROOF_PORTS_LEG}`)) throw new Error(`${id}: native proof ports need an explicit nonapplicable reason`);
-    if (definition.transport === "acp" && !Object.hasOwn(unsupportedLegs, `${id}:${ACP_PORTS_LEG}`)) throw new Error(`${id}: ACP restrictive ports require the reserved 2b reason`);
     if (!enrolled.includes(id) && !Object.hasOwn(unsupported, id)) throw new Error(`${id}: no conformance fixture or unsupported reason`);
     if (definition.transport === "acp" && !enrolled.includes(id)) throw new Error(`${id}: every ACP definition must run the ACP legs`);
     if (id.endsWith(":reviewer") && !definition.reviewer) throw new Error(`${id}: reviewer variant lacks reviewer policy`);

package/src/adapters/conformance/factories.ts

@@ -1,7 +1,7 @@
 import type { AdapterDefinition, CreateContext, DaemonPorts } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
 import { join } from "node:path";
-import { assertNativeProofPorts } from "./kit.ts";
+import { assertAcpProductPorts, assertNativeProofPorts } from "./kit.ts";
 
 /** The supplied definition creates its actual adapter, with only this fixture's transport options. */
 export function createFromDefinition<T extends PeerAdapter>(definition: AdapterDefinition, daemon: DaemonPorts): T {
@@ -10,6 +10,7 @@ export function createFromDefinition<T extends PeerAdapter>(definition: AdapterD
   const product = definition.start.create({ instance: definition.kind, projectRoot: options.cwd, stateDir: options.stateDir ?? join(options.cwd, "state"),
     kindConfig: {}, permission: "ask", mcpServers: options.mcpServers ?? [], daemon }) as T;
   assertNativeProofPorts(definition, product);
+  assertAcpProductPorts(definition, product);
   return product;
 }
 /** Explicit watchdog seam on the factory-created implementation, replacing direct test subclasses. */

package/src/adapters/conformance/fakes/jcode-agent.ts

@@ -1,6 +1,6 @@
 import { createServer } from "node:net";
 import { basename, dirname, join } from "node:path";
-import { writeSync, appendFileSync, mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { writeSync, appendFileSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync } from "node:fs";
 import { createInterface } from "node:readline";
 const args = process.argv.slice(2), value = (key: string) => args[args.indexOf(key) + 1];
 const record = args.includes("--record") ? value("--record") : undefined;
@@ -76,7 +76,11 @@ if (args.includes("version")) {
       }
       const finish = () => {
         send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: session, update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "JCODE_REPLY" } } } });
-        send({ jsonrpc: "2.0", id: msg.id, result: { stopReason: args.includes("--max-tokens-stop") ? "max_tokens" : "end_turn" } });
+        // `--usage-script F`: the 0.99.1 shapes, as probed (docs/verification/2026-10-28-jcode-0.99.1-usage.md). F is a JSON object `{ updates: [...], usage: {...} | null, sessionId?: string }`:
+        // each `updates` entry becomes a `usage_update` notification (for `sessionId` when given, else this session), and `usage` is the prompt result's `usage` member (absent when null).
+        const script = args.includes("--usage-script") && existsSync(value("--usage-script")!) ? JSON.parse(readFileSync(value("--usage-script")!, "utf8")) : undefined;
+        for (const update of script?.updates ?? []) send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: script.sessionId ?? session, update: { sessionUpdate: "usage_update", ...update } } });
+        send({ jsonrpc: "2.0", id: msg.id, result: { stopReason: args.includes("--max-tokens-stop") ? "max_tokens" : "end_turn", ...(script?.usage ? { usage: script.usage } : {}) } });
         if (args.includes("--exit-after-prompt")) setTimeout(() => process.exit(0), 30);
       };
       const steerFile = args.includes("--steer-file") ? value("--steer-file")! : undefined;

package/src/adapters/conformance/kit.ts

@@ -1,8 +1,10 @@
+import { assertNativeProofPorts } from "../native-proof-ports.ts";
+export { assertNativeProofPorts } from "../native-proof-ports.ts";
 import { expect, test } from "bun:test";
 import type { Envelope } from "../../hub/envelope.ts";
 import { newEnvelope } from "../../hub/envelope.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
-import { isFixedBuiltinDefinition, type AdapterDefinition } from "../registry.ts";
+import { type AdapterDefinition } from "../registry.ts";
 
 export async function until(condition: () => boolean, label: string): Promise<void> {
   const deadline = Date.now() + 5000;
@@ -24,12 +26,13 @@ export interface AdapterConformance {
   create(): Promise<ConformanceFixture>;
 }
 
-/** Presence itself is forbidden on a foreign product: even an undefined native proof port must fail the kit. */
-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`);
+/** Every ACP factory product keeps the transport's restrictive delivery and ownership contract. */
+export function assertAcpProductPorts(definition: AdapterDefinition | undefined, product: PeerAdapter): void {
+  if (definition?.transport !== "acp") return;
+  for (const port of ["deliveryOnly", "hubOwned"] as const) {
+    if (product[port] !== true) throw new Error(`${definition.kind}: ACP restrictive port ${port} must be true`);
   }
+  if (product.form !== "headless") throw new Error(`${definition.kind}: ACP restrictive port form must be headless`);
 }
 
 /** Shared observable contract; every invocation uses the real adapter and its fake native transport. */
@@ -38,6 +41,7 @@ export function registerConformance(adapter: AdapterConformance): void {
     const f = await adapter.create();
     try {
       assertNativeProofPorts(adapter.definition, f.peer);
+      assertAcpProductPorts(adapter.definition, f.peer);
       expect(f.peer.id).toBe(adapter.kind);
       expect(f.peer.state).toBe("idle");
       const envelope: Envelope = newEnvelope("user", "conformance ping", { to: [adapter.kind] });

package/src/adapters/definitions/builtin-metadata.ts

@@ -9,7 +9,6 @@ import { previewCodex } from "./native-cli-preview-codex.ts";
 import { previewKimi } from "./native-cli-preview-kimi.ts";
 import { previewPi } from "./native-cli-preview-pi.ts";
 import { previewJcode } from "./native-cli-preview-jcode.ts";
-import type { PermissionMode } from "../../hub/permission-mode.ts";
 import { claudeReviewerBackend, CODEX_REVIEWER_VARIANT, KIMI_REVIEWER_VARIANT } from "./reviewer-variants.ts";
 import { kimiAcpCommand } from "./native-daemon-kimi.ts";
 import { claudeRecoveryLaunch, kimiRecoveryLaunch, claudeRetainedTerminalNotice, piRetainedTerminalNotice, codexRetainedTerminalNotice, codexRosterReturnNotice, jcodeStartPreflight, claudeObservedVersion, codexObservedVersion } from "./native-daemon-policy.ts";
@@ -23,31 +22,9 @@ import { createCodex, createKimi, createJcode, createPi, createLocal, createClau
 import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY, JCODE_DISPLAY } from "./native-display.ts";
 import { CLAUDE_RECOVERY_SESSION, CODEX_RECOVERY_SESSION, KIMI_RECOVERY_SESSION, PI_RECOVERY_SESSION, LOCAL_RECOVERY_SESSION, JCODE_RECOVERY_SESSION } from "./native-recovery.ts";
 import { claudeWindows, codexWindows } from "./native-quota.ts";
-import { claudeContext, codexContext, acpContextValue } from "./native-context.ts";
-import type { AdapterDefinition, LaunchContext, LaunchPlan, StartForm, NativeModeSpec } from "../registry-types.ts";
+import { claudeContext, codexContext, acpContextValue, jcodeContextValue } from "./native-context.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
-import { shellQuote } from "../../cli/shell-quote.ts";
-
-type CompatibilityKind = "claude" | "codex" | "kimi" | "pi" | "local" | "jcode";
-
-/**
- * Preserve CLI-wrapper argv plans only for the frozen A1 compatibility export.
- * Native startup and daemon factories are supplied separately by the runtime definitions.
- */
-function compatibilityLaunch(kind: CompatibilityKind, ctx: LaunchContext, explicitMode = false): LaunchPlan {
-  const mode = explicitMode || kind === "kimi" || kind === "pi" ? ["--mode", ctx.form] : [];
-  const unattended = ctx.unattended && (kind === "claude" || kind === "codex") ? ["--unattended"] : [];
-  const args = [ctx.entrypoint, "--project", ctx.projectRoot, kind, ...mode, ...unattended,
-    ...(ctx.model && !ctx.userArgs.includes("--model") ? ["--model", ctx.model] : []), ...ctx.userArgs];
-  const argv = [process.execPath, ...args];
-  const env = {
-    ...(ctx.env.CODEX_HOME !== undefined ? { CODEX_HOME: ctx.env.CODEX_HOME } : {}),
-    ...(ctx.env.CLAUDE_CONFIG_DIR !== undefined ? { CLAUDE_CONFIG_DIR: ctx.env.CLAUDE_CONFIG_DIR } : {}),
-  };
-  const prefix = Object.entries(env).map(([name, value]) => `${name}=${shellQuote(value)}`);
-  return { cmd: process.execPath, args, ...(unattended.length ? { unattended: true } : {}),
-    metadata: { packageEntrypoint: ctx.entrypoint, argv, env, command: [...prefix, ...argv.map(shellQuote)].join(" ") } };
-}
 
 function sessionId(field: "sessionId" | "threadId"): (peer: PeerAdapter) => string | undefined {
   return peer => {
@@ -175,96 +152,8 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     identity: { mcp: "project-file" }, instances: { mode: "headless", nativeHome: true },
     permission: { unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
       ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode" },
+    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode", context: { source: "jcode_usage_update", read: jcodeContextValue } },
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
     cli: { command: "jcode", entry: { lifecycleAdmission: true, execute: runJcodeEntry }, preview: previewJcode, usage: [["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"]], authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: mode => ["jcode", "--mode", mode] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
   },
 ] satisfies AdapterDefinition[]);
-
-// Frozen A1 metadata is a compatibility snapshot, not the runtime definition contract.
-export type LegacyAdapterDefinition = AdapterDefinition & {
-  init?: { templateFragment?: string; mcpFile?: string };
-  start: AdapterDefinition["start"] & { ownsTerminal(form: StartForm): boolean; launch(ctx: LaunchContext): LaunchPlan };
-  permission: AdapterDefinition["permission"] & { modes: Partial<Record<PermissionMode, NativeModeSpec>>; readOnly?: NativeModeSpec };
-};
-const terminal = (form: StartForm) => form === "tui";
-const headless = () => false;
-/**
- * ponytail: retain the released A1 metadata export for source/library compatibility until A4 retires it.
- * Core runtime consumers use NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN through the registry exclusively.
- * The frozen jcode entry stays byte-identical: its headless `launch` emits `jcode` without `--mode`, which the CLI now
- * resolves to the TUI (#464, #559). Callers of this export must pass `--mode headless` themselves.
- */
-const palette = (fg: string) => ({ palette: { fg, bg: "transparent" } });
-export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly LegacyAdapterDefinition[] = Object.freeze([
-  {
-    api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
-    roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("claude", ctx), conductorStartable: true,
-      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
-    identity: { mcp: "channel-plugin" },
-    permission: { modes: {}, grants: { ask: "Claude's own permission rules decide",
-      "ask-when-needed": "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules",
-      "never-ask": "every tool runs without asking" } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true },
-    turnEnd: "native-hook", budget: { account: "claude", checkpoint: true },
-    cli: { command: "claude", startWords: () => ["claude"] }, display: palette("#6495ed"), hooks: { recallPlatform: "claude" },
-  },
-  {
-    api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
-    roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("codex", ctx), conductorStartable: true,
-      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
-    identity: { mcp: "env" },
-    permission: { modes: { ask: { kind: "native-only", note: "restore the session's captured native approval policy" },
-      "ask-when-needed": { kind: "codex-approval", policy: "on-request" }, "never-ask": { kind: "codex-approval", policy: "never" } },
-      grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
-    session: { idField: "threadId", currentId: sessionId("threadId"), configDirEnv: "CODEX_HOME", zeroTurnFresh: true, launchKind: "codex", launchRecord: true },
-    turnEnd: "adapter", budget: { account: "codex", checkpoint: true },
-    cli: { command: "codex", startWords: () => ["codex"] }, display: palette("#22b8cf"), hooks: { recallPlatform: "codex" },
-  },
-  {
-    api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
-    roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("kimi", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    // ACP sessions carry headless identity; the existing CLI alone owns the TUI's project MCP entry.
-    identity: { mcp: "acp-session" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const) },
-    permission: { modes: { ask: { kind: "acp-mode", modeId: "default" }, "ask-when-needed": { kind: "acp-mode", modeId: "yolo" }, "never-ask": { kind: "acp-mode", modeId: "auto" } },
-      grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
-      unmanagedForms: Object.freeze(["tui"] as const), unmanagedNote: "Kimi approves tools and selects its permission mode in its own TUI; no hub permission mode" },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "acp" },
-    turnEnd: "adapter", budget: { account: "kimi" }, capabilities: { watch: true }, init: { mcpFile: ".kimi-code/mcp.json" },
-    cli: { command: "kimi", startWords: form => ["kimi", "--mode", form] }, display: palette("#bc73ca"),
-  },
-  {
-    api: 1, kind: "pi", displayName: "Pi", family: "pi", transport: "hub-native",
-    roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
-    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("pi", ctx), conductorStartable: true, autoStart: "pi.auto_start", hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    permission: { modes: {}, grants: { ...hubGrants } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "pi", launchRecord: true },
-    turnEnd: "adapter", budget: { account: "pi", noQuotaReason: "on-prem backends have no provider quota" },
-    cli: { command: "pi", startWords: form => ["pi", "--mode", form] }, display: palette("#c79936"),
-  },
-  {
-    api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
-    roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
-    start: { forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("local", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "env" },
-    permission: { modes: {}, grants: { ...hubGrants } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local" },
-    turnEnd: "adapter",
-    cli: { command: "local", startWords: () => ["local"] }, display: palette("#4caa77"),
-  },
-  {
-    api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
-    roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("jcode", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "project-file" },
-    permission: { modes: {}, unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
-      ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
-    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode" }, turnEnd: "adapter", budget: { account: "jcode" },
-    // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
-    cli: { command: "jcode", startWords: () => ["jcode"] }, display: palette("#8a8f99"),
-  },
-] satisfies LegacyAdapterDefinition[]);

package/src/adapters/definitions/native-config-defaults.ts

@@ -9,7 +9,7 @@ export function nativeConfigurationDefaults(ctx: { home: string; env: Readonly<R
     commands: { kimi_cmd: ["kimi", "acp"], qwen_cmd: ["qwen", "--acp"], jcode_cmd: ["jcode"], jcode_home: ctx.env.JCODE_HOME ?? join(ctx.home, ".jcode"), jcode_provider_profile: "" },
     proxy: { codex_bin: "codex" },
     rpc: { pi: { enabled: false, auto_start: false, cmd: ["pi"], backend: "auto" as const, dgx_coding: "coding", dgx_fast: "fast", max_steps: 30 } },
-    sandbox: { local: { deny: [] as string[], bash_network: false, network_allow: ctx.networkAllow, max_steps: 30, read_allow: [] as string[] } },
+    sandbox: { local: { deny: [] as string[], bash_network: false, network_allow: ctx.networkAllow, max_steps: 30, read_allow: [] as string[], doc_read: false, web_fetch: { allow: [] as string[] } } },
   };
 }
 export function mergeNativeConfiguration(file: Record<string, any>, defaults: HubConfig): Pick<HubConfig, "local" | "pi"> {

package/src/adapters/definitions/native-config-policy.ts

@@ -1,12 +1,13 @@
 import type { NativeConfigCheck, NativeConfigValidators } from "../registry-types.ts";
 import type { SettingDef } from "../../hub/settings.ts";
+import { webFetchAllow } from "../../local/web-fetch-config.ts";
 
 /** Native config uses the host's checked schema vocabulary, retaining its shape/path introspection. */
 export function piConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
   return { pi: v.block({ enabled: v.bool, auto_start: v.bool, cmd: v.argv, backend: v.words(["auto", "dgx", "mlx"]), dgx_coding: v.text, dgx_fast: v.text, max_steps: v.number(1, 1_000_000, true) }) };
 }
 export function localConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
-  return { local: v.block({ deny: v.strings, bash_network: (value, key) => { if (value !== "direct") v.bool(value, key); }, network_allow: v.strings, max_steps: v.number(1, 1_000_000, true), read_allow: v.strings }) };
+  return { local: v.block({ deny: v.strings, bash_network: (value, key) => { if (value !== "direct") v.bool(value, key); }, network_allow: v.strings, max_steps: v.number(1, 1_000_000, true), read_allow: v.strings, doc_read: v.bool, web_fetch: v.block({ allow: (value, key) => { webFetchAllow(value); void key; } }) }) };
 }
 export function piRoutingSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
   return { pi: v.block({ dgx_max_context_tokens: v.number(), mlx_max_context_tokens: v.number(), efficient_wait_ms: v.number(0, 119999) }) };
@@ -24,7 +25,7 @@ export const PI_RESTART_REASONS: Readonly<Record<string, string>> = {
 };
 export const LOCAL_RESTART_REASONS: Readonly<Record<string, string>> = {
   "local.deny": "Existing native sessions retain their sandbox deny policy", "local.read_allow": "Existing native sessions retain their sandbox read grants",
-  "local.bash_network": "Existing sandbox and egress proxy contracts require a new instance", "local.network_allow": "Existing egress proxy ownership requires a new instance",
+  "local.bash_network": "Existing sandbox and egress proxy contracts require a new instance", "local.network_allow": "Existing egress proxy ownership requires a new instance", "local.doc_read": "The worker's tool list is bound when its session starts", "local.web_fetch": "The worker's tool list and its web egress proxy are bound when the hub starts",
 };
 export function piEffectiveConfig(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void {
   const object = (value: unknown, key: string): Record<string, unknown> => {

package/src/adapters/definitions/native-context.ts

@@ -33,3 +33,15 @@ export function acpContextValue(value: unknown, sessionId: string, measuredAt: n
   const raw = object(value);
   return acpContext({ used: raw.used as number, size: raw.size as number }, sessionId, measuredAt);
 }
+
+/**
+ * Jcode 0.99.1's ACP `usage_update` is `{ used, size }` (docs/verification/2026-10-28-jcode-0.99.1-usage.md): `used` is the context the last provider call held (its input, and the
+ * cached part where the provider reports it apart), `size` the model's context limit. It is occupancy of the live session, so it is a reading, never consumption; it says nothing
+ * of quota. Anything but two finite integers with a positive size is unknown, and a `used` above `size` clamps the fraction only (tokens keeps what was reported).
+ */
+export function jcodeContextValue(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const raw = object(value);
+  const okay = Number.isSafeInteger(raw.used) && (raw.used as number) >= 0 && Number.isSafeInteger(raw.size) && (raw.size as number) > 0;
+  const tokens = okay ? raw.used as number : null, window = okay ? raw.size as number : null;
+  return { source: "jcode_usage_update", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}

package/src/adapters/external-metadata.ts

@@ -46,3 +46,51 @@ export function externalMetadataDefinitions(raw: unknown): readonly AdapterDefin
     cli: { command: kind, startWords: () => [kind] }, display: { palette: { fg: "white", bg: "black" } },
   })));
 }
+
+export type ExternalInstanceRole = "implementer" | "verifier" | "reviewer";
+export type ExternalInstanceRefusal = "catalog-unavailable" | "module-refused" | "kind-unavailable" | "binding-changed" | "ownership-unverified" | "off-roster" | "not-started";
+export interface ExternalInstanceMetadata {
+  readonly id: string;
+  readonly kind: string;
+  readonly displayName: string;
+  readonly roles: readonly ExternalInstanceRole[];
+  readonly form: "headless";
+  readonly readOnly: boolean;
+  readonly permissionState: "ask" | "ask-when-needed" | "never-ask" | "unmanaged" | "unknown";
+  readonly availability: "ready" | "offline" | "declared-unknown" | "refused";
+  readonly refusalCode?: ExternalInstanceRefusal;
+}
+/** An authenticated observation, never an executable definition or runtime admission receipt. */
+export interface ExternalInstanceCatalog {
+  readonly schema: 1;
+  readonly projectRoot: string;
+  readonly epoch: string;
+  readonly fingerprint: string;
+  readonly instances: readonly ExternalInstanceMetadata[];
+}
+const INSTANCE_ID = /^[a-z][a-z0-9-]{0,31}$/;
+const INSTANCE_ROLES: readonly string[] = ["implementer", "verifier", "reviewer"];
+const INSTANCE_REFUSALS: readonly string[] = ["catalog-unavailable", "module-refused", "kind-unavailable", "binding-changed", "ownership-unverified", "off-roster", "not-started"];
+/** Validate the whole bounded projection; an incomplete or widened row is never silently accepted. */
+export function externalInstanceCatalog(raw: unknown): ExternalInstanceCatalog {
+  const catalog = moduleDataObject(raw);
+  if (Object.keys(catalog).some(key => !["schema", "projectRoot", "epoch", "fingerprint", "instances"].includes(key)) || catalog.schema !== 1
+    || typeof catalog.fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(catalog.fingerprint)) return fail("invalid instance catalog metadata");
+  const instances = moduleArray(catalog.instances, 64).map(value => {
+    const row = moduleDataObject(value);
+    if (Object.keys(row).some(key => !["id", "kind", "displayName", "roles", "form", "readOnly", "permissionState", "availability", "refusalCode"].includes(key))
+      || typeof row.id !== "string" || !INSTANCE_ID.test(row.id) || typeof row.kind !== "string" || !INSTANCE_ID.test(row.kind)
+      || row.form !== "headless" || typeof row.readOnly !== "boolean"
+      || typeof row.permissionState !== "string" || !["ask", "ask-when-needed", "never-ask", "unmanaged", "unknown"].includes(row.permissionState)
+      || typeof row.availability !== "string" || !["ready", "offline", "declared-unknown", "refused"].includes(row.availability)
+      || Object.hasOwn(row, "refusalCode") && (typeof row.refusalCode !== "string" || !INSTANCE_REFUSALS.includes(row.refusalCode))) return fail("invalid instance display metadata");
+    const roles = moduleArray(row.roles, 3);
+    if (roles.some(role => typeof role !== "string" || !INSTANCE_ROLES.includes(role)) || new Set(roles).size !== roles.length) return fail("invalid instance role metadata");
+    return Object.freeze({ id: row.id, kind: row.kind, displayName: moduleText(row.displayName, 256), roles: Object.freeze(roles as ExternalInstanceRole[]),
+      form: "headless" as const, readOnly: row.readOnly, permissionState: row.permissionState as ExternalInstanceMetadata["permissionState"],
+      availability: row.availability as ExternalInstanceMetadata["availability"], ...(row.refusalCode !== undefined ? { refusalCode: row.refusalCode as ExternalInstanceRefusal } : {}) });
+  });
+  if (new Set(instances.map(row => row.id)).size !== instances.length) return fail("duplicate external instance metadata");
+  return Object.freeze({ schema: 1, projectRoot: moduleText(catalog.projectRoot, 4096), epoch: moduleText(catalog.epoch, 128),
+    fingerprint: catalog.fingerprint, instances: Object.freeze(instances) });
+}