@ljwei-stak/dsh-model-route-bot 0.66.4 → 0.67.0

package/modules/openmaus-protocol/vendor/companion/src/e2e/vectors/v1.sha256

@@ -0,0 +1 @@
+5471a0070ddbb69dca34dee6da550de4581e8e1a40e22e0f97873d539793bf4e  v1.json

package/modules/openmaus-protocol/vendor/companion/src/e2e/yamux.ts

@@ -0,0 +1,335 @@
+// The yamux profile carried inside the records: one frame per record, phone-opened streams only, 2 MiB windows.
+// Wire spec: companion/src/e2e/README.md, "Multiplexing". This module does no I/O, so every rule is testable.
+
+export const VERSION = 0;
+export const TYPE = { data: 0, windowUpdate: 1, ping: 2, goAway: 3 } as const;
+export const FLAG = { syn: 0x1, ack: 0x2, fin: 0x4, rst: 0x8 } as const;
+const KNOWN_FLAGS = 0xf;
+/** `removed` goes only from the computer to the phone: this device was removed, and the close that follows is 4001. It
+ * is inside the encryption, so unlike a bare 4001 close code a relay can't forge it. */
+export const GO_AWAY = { normal: 0, protocol: 1, internal: 2, removed: 3 } as const;
+
+export const HEADER_BYTES = 12;
+export const MAX_DATA_PAYLOAD = 65_507;
+export const INITIAL_WINDOW = 256 * 1024;
+export const STREAM_WINDOW = 2 * 1024 * 1024;
+export const OPEN_WINDOW_DELTA = STREAM_WINDOW - INITIAL_WINDOW;
+export const WINDOW_UPDATE_AFTER = 1024 * 1024;
+export const MAX_STREAMS = 64;
+export const MAX_STREAM_ID = 2 ** 31 - 1;
+export const PING_INTERVAL_MS = 20_000;
+export const PING_TIMEOUT_MS = 10_000;
+
+export type FrameType = (typeof TYPE)[keyof typeof TYPE];
+
+export interface Frame {
+  type: FrameType;
+  flags: number;
+  streamId: number;
+  /** Data: the payload size. WindowUpdate: the window delta. Ping: the opaque value. GoAway: the code. */
+  length: number;
+  data?: Uint8Array;
+}
+
+export class YamuxError extends Error {
+  readonly reason: string;
+  constructor(reason: string) {
+    super(`yamux: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+export function encodeFrame(frame: Frame): Buffer {
+  const payload = frame.type === TYPE.data ? frame.data ?? new Uint8Array(0) : new Uint8Array(0);
+  if (frame.type === TYPE.data && payload.length !== frame.length) throw new YamuxError("data_length");
+  if (payload.length > MAX_DATA_PAYLOAD) throw new YamuxError("data_too_large");
+  const out = Buffer.alloc(HEADER_BYTES + payload.length);
+  out.writeUInt8(VERSION, 0);
+  out.writeUInt8(frame.type, 1);
+  out.writeUInt16BE(frame.flags, 2);
+  out.writeUInt32BE(frame.streamId, 4);
+  out.writeUInt32BE(frame.length, 8);
+  out.set(payload, HEADER_BYTES);
+  return out;
+}
+
+/** One record's plaintext is exactly one frame. Everything that can be checked without stream state is
+ * checked here. */
+export function decodeFrame(bytes: Uint8Array): Frame {
+  if (bytes.length < HEADER_BYTES) throw new YamuxError("short_frame");
+  const view = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.readUInt8(0) !== VERSION) throw new YamuxError("version");
+  const type = view.readUInt8(1);
+  if (type > TYPE.goAway) throw new YamuxError("type");
+  const flags = view.readUInt16BE(2);
+  if ((flags & ~KNOWN_FLAGS) !== 0) throw new YamuxError("flags");
+  const streamId = view.readUInt32BE(4);
+  const length = view.readUInt32BE(8);
+  if (type === TYPE.data) {
+    if (length > MAX_DATA_PAYLOAD) throw new YamuxError("data_too_large");
+    if (bytes.length !== HEADER_BYTES + length) throw new YamuxError("data_length");
+    if (streamId === 0) throw new YamuxError("stream_zero");
+    return { type, flags, streamId, length, data: view.subarray(HEADER_BYTES) };
+  }
+  if (bytes.length !== HEADER_BYTES) throw new YamuxError("trailing_bytes");
+  if (type === TYPE.windowUpdate) {
+    if (streamId === 0) throw new YamuxError("stream_zero");
+  } else {
+    if (streamId !== 0) throw new YamuxError("session_frame_stream");
+    if (type === TYPE.ping && flags !== FLAG.syn && flags !== FLAG.ack) throw new YamuxError("ping_flags");
+    if (type === TYPE.goAway && flags !== 0) throw new YamuxError("goaway_flags");
+  }
+  return { type: type as FrameType, flags, streamId, length };
+}
+
+export const openFrame = (streamId: number): Frame => ({ type: TYPE.windowUpdate, flags: FLAG.syn, streamId, length: OPEN_WINDOW_DELTA });
+export const acceptFrame = (streamId: number): Frame => ({ type: TYPE.windowUpdate, flags: FLAG.ack, streamId, length: OPEN_WINDOW_DELTA });
+export const resetFrame = (streamId: number): Frame => ({ type: TYPE.windowUpdate, flags: FLAG.rst, streamId, length: 0 });
+export const finFrame = (streamId: number): Frame => ({ type: TYPE.windowUpdate, flags: FLAG.fin, streamId, length: 0 });
+export const windowFrame = (streamId: number, delta: number): Frame => ({ type: TYPE.windowUpdate, flags: 0, streamId, length: delta });
+export const dataFrame = (streamId: number, data: Uint8Array, flags = 0): Frame => ({ type: TYPE.data, flags, streamId, length: data.length, data });
+export const pingFrame = (value: number, flags: number = FLAG.syn): Frame => ({ type: TYPE.ping, flags, streamId: 0, length: value >>> 0 });
+export const goAwayFrame = (code: number): Frame => ({ type: TYPE.goAway, flags: 0, streamId: 0, length: code });
+
+/** The phone opens every stream; the computer only accepts. */
+export type Role = "phone" | "computer";
+
+interface StreamState {
+  /** The phone side: false until the computer's ACK arrives. The computer side: false until accept(). */
+  established: boolean;
+  /** What the peer may still send before this side grants more. */
+  receiveWindow: number;
+  /** What this side may still send. */
+  sendWindow: number;
+  /** Consumed but not yet granted back. */
+  uncredited: number;
+  localFin: boolean;
+  remoteFin: boolean;
+}
+
+export interface MuxEvents {
+  /** Every frame to seal and send, in order. */
+  send(frame: Frame): void;
+  /** The computer side: a new stream. Answer with accept() or reset(); data may arrive first. */
+  opened?(streamId: number): void;
+  /** The phone side: the computer accepted. */
+  accepted?(streamId: number): void;
+  data(streamId: number, data: Uint8Array): void;
+  /** The peer may send no more (FIN). */
+  ended(streamId: number): void;
+  /** Ended by RST from either side, or the session closing. */
+  reset(streamId: number): void;
+  /** The peer granted more send window. */
+  writable(streamId: number): void;
+  goAway?(code: number): void;
+  pong?(value: number): void;
+}
+
+/** A frame that breaks the profile throws YamuxError. The caller then sends GoAway(1) through
+ * `protocolError()` and closes the WebSocket with 4000. */
+export class Mux {
+  readonly role: Role;
+  readonly #events: MuxEvents;
+  readonly #streams = new Map<number, StreamState>();
+  /** The highest ID the phone has opened. */
+  #highestId = 0;
+  #peerGoneAway = false;
+  #localGoneAway = false;
+
+  constructor(role: Role, events: MuxEvents) {
+    this.role = role;
+    this.#events = events;
+  }
+
+  get activeStreams(): number {
+    return this.#streams.size;
+  }
+
+  get peerGoneAway(): boolean {
+    return this.#peerGoneAway;
+  }
+
+  has(streamId: number): boolean {
+    return this.#streams.has(streamId);
+  }
+
+  sendWindow(streamId: number): number {
+    return this.#streams.get(streamId)?.sendWindow ?? 0;
+  }
+
+  /** The phone side. Data may follow at once, within the first 256 KiB. */
+  open(): number {
+    if (this.role !== "phone") throw new YamuxError("computer_open");
+    if (this.#localGoneAway || this.#peerGoneAway) throw new YamuxError("gone_away");
+    if (this.#streams.size >= MAX_STREAMS) throw new YamuxError("too_many_streams");
+    const streamId = this.#highestId === 0 ? 1 : this.#highestId + 2;
+    if (streamId > MAX_STREAM_ID) throw new YamuxError("ids_exhausted");
+    this.#highestId = streamId;
+    this.#streams.set(streamId, {
+      established: false,
+      receiveWindow: INITIAL_WINDOW + OPEN_WINDOW_DELTA,
+      sendWindow: INITIAL_WINDOW,
+      uncredited: 0,
+      localFin: false,
+      remoteFin: false,
+    });
+    this.#events.send(openFrame(streamId));
+    return streamId;
+  }
+
+  /** The computer side, once the origin socket is connected. */
+  accept(streamId: number): void {
+    const stream = this.#streams.get(streamId);
+    if (!stream || stream.established || this.role !== "computer") return;
+    stream.established = true;
+    stream.receiveWindow += OPEN_WINDOW_DELTA;
+    this.#events.send(acceptFrame(streamId));
+  }
+
+  /** Sends up to the window and the frame cap; returns the bytes taken. */
+  write(streamId: number, data: Uint8Array): number {
+    const stream = this.#streams.get(streamId);
+    if (!stream || stream.localFin || (this.role === "computer" && !stream.established)) return 0;
+    const size = Math.min(data.length, stream.sendWindow, MAX_DATA_PAYLOAD);
+    if (size === 0) return 0;
+    stream.sendWindow -= size;
+    this.#events.send(dataFrame(streamId, data.subarray(0, size)));
+    return size;
+  }
+
+  finish(streamId: number): void {
+    const stream = this.#streams.get(streamId);
+    if (!stream || stream.localFin) return;
+    stream.localFin = true;
+    this.#events.send(finFrame(streamId));
+    this.#closeIfDone(streamId, stream);
+  }
+
+  reset(streamId: number): void {
+    if (!this.#streams.delete(streamId)) return;
+    this.#events.send(resetFrame(streamId));
+    this.#events.reset(streamId);
+  }
+
+  /** The receiver handed `bytes` on (to the origin socket, or the HTTP stack). Grants them back in 1 MiB steps. */
+  consumed(streamId: number, bytes: number): void {
+    const stream = this.#streams.get(streamId);
+    if (!stream || stream.remoteFin) return;
+    stream.uncredited += bytes;
+    if (stream.uncredited < WINDOW_UPDATE_AFTER) return;
+    const delta = stream.uncredited;
+    stream.uncredited = 0;
+    stream.receiveWindow += delta;
+    this.#events.send(windowFrame(streamId, delta));
+  }
+
+  ping(value: number): void {
+    this.#events.send(pingFrame(value));
+  }
+
+  goAway(code: number = GO_AWAY.normal): void {
+    this.#localGoneAway = true;
+    this.#events.send(goAwayFrame(code));
+  }
+
+  /** Sends GoAway(1); the caller closes with 4000. */
+  protocolError(): void {
+    this.goAway(GO_AWAY.protocol);
+    this.closeAll();
+  }
+
+  closeAll(): void {
+    const ids = [...this.#streams.keys()];
+    this.#streams.clear();
+    for (const id of ids) this.#events.reset(id);
+  }
+
+  receive(frame: Frame): void {
+    if (frame.type === TYPE.ping) {
+      if (frame.flags === FLAG.syn) this.#events.send(pingFrame(frame.length, FLAG.ack));
+      else this.#events.pong?.(frame.length);
+      return;
+    }
+    if (frame.type === TYPE.goAway) {
+      this.#peerGoneAway = true;
+      this.#events.goAway?.(frame.length);
+      return;
+    }
+    if (frame.flags & FLAG.syn) {
+      this.#receiveOpen(frame);
+      return;
+    }
+    if (frame.flags & FLAG.ack) {
+      this.#receiveAck(frame);
+      return;
+    }
+    const stream = this.#known(frame.streamId);
+    if (!stream) return;
+    this.#receiveOnStream(frame.streamId, stream, frame);
+  }
+
+  /** A stream that ended is ignored: an RST and the peer's last frames cross. An ID never opened is an error. */
+  #known(streamId: number): StreamState | null {
+    if (streamId % 2 === 0 || streamId > this.#highestId) throw new YamuxError("unknown_stream");
+    return this.#streams.get(streamId) ?? null;
+  }
+
+  #receiveOpen(frame: Frame): void {
+    if (this.role === "phone") throw new YamuxError("computer_opened_stream");
+    if (frame.type !== TYPE.windowUpdate || frame.flags !== FLAG.syn) throw new YamuxError("open_flags");
+    if (frame.streamId % 2 === 0) throw new YamuxError("even_stream");
+    if (frame.streamId <= this.#highestId) throw new YamuxError("stream_reused");
+    this.#highestId = frame.streamId;
+    if (this.#localGoneAway || this.#streams.size >= MAX_STREAMS) {
+      this.#events.send(resetFrame(frame.streamId));
+      return;
+    }
+    this.#streams.set(frame.streamId, {
+      established: false,
+      receiveWindow: INITIAL_WINDOW,
+      sendWindow: INITIAL_WINDOW + frame.length,
+      uncredited: 0,
+      localFin: false,
+      remoteFin: false,
+    });
+    this.#events.opened?.(frame.streamId);
+  }
+
+  #receiveAck(frame: Frame): void {
+    if (this.role === "computer") throw new YamuxError("phone_ack");
+    if (frame.type !== TYPE.windowUpdate || (frame.flags & ~(FLAG.ack | FLAG.fin | FLAG.rst)) !== 0) throw new YamuxError("ack_flags");
+    const stream = this.#known(frame.streamId);
+    if (!stream) return;
+    if (stream.established) throw new YamuxError("duplicate_ack");
+    stream.established = true;
+    this.#events.accepted?.(frame.streamId);
+    this.#receiveOnStream(frame.streamId, stream, { ...frame, flags: frame.flags & ~FLAG.ack });
+  }
+
+  #receiveOnStream(streamId: number, stream: StreamState, frame: Frame): void {
+    if (frame.flags & FLAG.rst) {
+      this.#streams.delete(streamId);
+      this.#events.reset(streamId);
+      return;
+    }
+    if (frame.type === TYPE.data) {
+      if (stream.remoteFin && (frame.length > 0 || frame.flags & FLAG.fin)) throw new YamuxError("data_after_fin");
+      if (frame.length > stream.receiveWindow) throw new YamuxError("window_exceeded");
+      stream.receiveWindow -= frame.length;
+      if (frame.length > 0) this.#events.data(streamId, frame.data as Uint8Array);
+    } else if (frame.length > 0) {
+      stream.sendWindow += frame.length;
+      this.#events.writable(streamId);
+    }
+    if (frame.flags & FLAG.fin) {
+      if (stream.remoteFin) throw new YamuxError("data_after_fin");
+      stream.remoteFin = true;
+      this.#events.ended(streamId);
+      this.#closeIfDone(streamId, stream);
+    }
+  }
+
+  #closeIfDone(streamId: number, stream: StreamState): void {
+    if (stream.localFin && stream.remoteFin) this.#streams.delete(streamId);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ljwei-stak/dsh-model-route-bot",
-  "version": "0.66.4",
+  "version": "0.67.0",
   "type": "module",
   "description": "DSH Bot workspace with integrated model routing, official tools and remote computers",
   "repository": {
@@ -51,6 +51,7 @@
     "modules/bot-runtime/vendor/ds-bot/office.js",
     "modules/bot-runtime/vendor/ds-bot/test/harness-resolve.mjs",
     "modules/bot-runtime/web-search.mjs",
+    "modules/openmaus-protocol/",
     "packages/orchestration/src/bot-runtime-config.mjs",
     ".dsh-plugin/index.mjs",
     ".dsh-plugin/official-tools-remote-service.mjs",
@@ -256,6 +257,7 @@
     "packages/orchestration/src/sqlite-router-state.mjs",
     "packages/orchestration/src/task-contract.mjs",
     "packages/orchestration/src/bot-settings.mjs",
+    "packages/orchestration/src/main-model-routes.mjs",
     "packages/orchestration/src/funding-accounts.mjs",
     "packages/orchestration/src/model-accounting.mjs",
     "packages/capability-broker/src/cli-bootstrap.mjs",
@@ -323,6 +325,7 @@
     "packages/orchestration/src/machine-heartbeat.mjs",
     "remote-computer-agent/start.cmd",
     "remote-computer-agent/setup.ps1",
+    "remote-computer-agent/pair-device.ps1",
     "remote-computer-agent/launch-agent.ps1",
     "native/windows-desktop/",
     "remote-computer-agent/build.mjs",
@@ -338,11 +341,13 @@
     "check:client": "node scripts/build-client.mjs --check",
     "check:contracts": "node scripts/check-contracts.mjs",
     "contracts:write": "node scripts/check-contracts.mjs --write",
-    "build:agent": "node remote-computer-agent/build.mjs",
+    "build:agent": "node scripts/build-openmaus-protocol.mjs && node remote-computer-agent/build.mjs",
     "check:source": "node scripts/integration-product-source.mjs",
     "pretest": "node scripts/prepare-product-tests.mjs",
     "test": "node scripts/run-tests.mjs",
-    "prepack": "node remote-computer-agent/build.mjs && node scripts/prepack.mjs",
+    "verify:independent": "node scripts/verify-bot-independent.mjs",
+    "verify:independent-chat": "node scripts/verify-independent-chat-browser.mjs && node scripts/verify-independent-chat-rich-browser.mjs && node scripts/verify-independent-chat-native-browser.mjs",
+    "prepack": "node scripts/build-openmaus-protocol.mjs && node remote-computer-agent/build.mjs && node scripts/prepack.mjs",
     "prepare:native": "node scripts/prepare-native-driver.mjs",
     "check:github-math": "node scripts/check-github-math.mjs"
   },
@@ -356,12 +361,12 @@
     "@deepseek-ai/dsh-commands": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
     "@deepseek-ai/dsh-llm": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
     "@deepseek-ai/dsh-sandbox": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
     "@deepseek-ai/dsh-settings": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
     "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
     "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
     "@deepseek-ai/dsh-web": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
-    "@deepseek-ai/schemastery": "~3.18.4",
-    "@deepseek-ai/dsh-scope": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3"
+    "@deepseek-ai/schemastery": "~3.18.4"
   },
   "optionalDependencies": {
     "@lydell/node-pty": "1.2.0-beta.15",
@@ -375,6 +380,7 @@
     "@deepseek-ai/cordis-plugin-timer": "1.1.7",
     "@deepseek-ai/dsh-agent": "0.2.1-rc.3 || 0.2.1-rc.4",
     "@deepseek-ai/dsh-agent-default-model": "0.2.1-rc.3 || 0.2.1-rc.4",
+    "@deepseek-ai/dsh-agent-loop": "0.2.1-rc.4",
     "@deepseek-ai/dsh-agent-preset-registry": "0.2.1-rc.3 || 0.2.1-rc.4",
     "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.3 || 0.2.1-rc.4",
     "@deepseek-ai/dsh-api-remotes": "0.2.1-rc.3 || 0.2.1-rc.4",
@@ -439,6 +445,12 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",
     "better-sqlite3": "13.0.3",
-    "deep-view": "0.1.0"
+    "deep-view": "0.1.0",
+    "jsqr": "1.4.0",
+    "qrcode": "1.5.4",
+    "ws": "8.22.1"
+  },
+  "overrides": {
+    "zod": "4.6.6"
   }
 }

package/packages/bot-acp/README.md

@@ -0,0 +1,156 @@
+# packages/bot-acp
+
+The generic ACP (Agent Client Protocol) session core for the Bot runtime: a strictly
+bounded JSON-RPC 2.0 stdio transport, multi-turn session management, fail-closed
+permissions, and a Host-bound adapter the product composition can wire.
+
+Ported and re-grounded from OpenMausBot `server/drivers/acp/*` at pin
+`1bc4749aa8307d7d6998bf86de4ef6478460dd93` (Apache-2.0); see `licenses/NOTICE.md`
+for the exact upstream paths and the preserved license text.
+
+> **Status.** This module is a core, not a product feature. It is **not wired into
+> product composition**, and no ACP CLI is claimed to be verified end-to-end here.
+> Presence in the tree is not availability: the parent composition still has to
+> register a pinned entry, a grant scope and the funding/ledger hooks.
+
+## Modules
+
+| File | Purpose |
+| --- | --- |
+| `src/rpc-codec.mjs` | Pure codec: newline framing with UTF-8 reassembly and a hard frame cap, message classification, id validation, wire-error mapping, client/agent capability schema |
+| `src/stdio-rpc.mjs` | Bounded transport: `createChildPipe` (real stdio) and `createStdioRpc` (id-mapped requests, notifications, responses, pending/deadline/idle/backlog limits, duplicate/unknown/late response accounting, accurate pending rejection on real process exit) |
+| `src/acp-host.mjs` | One agent process and the sessions in it: sessionId routing, single-flight `initialize`/`authenticate`, session/lifetime/draining bounds, fail-closed unrouted handler |
+| `src/session-core.mjs` | Multi-turn session: handshake, `session/new`, capability-gated `session/load`, serial turns with explicit busy, text-only prompts, `session/update` merging, stopReason classification, advertised-only model/config/mode control, an `onDispatched` dispatch marker and `acpNotDispatched`-tagged pre-dispatch refusals |
+| `src/permission-policy.mjs` | `session/request_permission` decided by committed Tool/Task/operation authority; every unknown, duplicate, expired, revoked, timed-out or closing case denies. `createClientMethodGuard` refuses `fs/*` and `terminal/*` unless the Host enables them with a submitted root and IO callbacks |
+| `src/native-launch.mjs` | `pinAcpEntry` (absolute path + digest + real version proof), `createSupervisorPipe` (native supervisor stdio relay), `launchAcpProcess` — all reusing `packages/cli-runtime/src/native-process.mjs` |
+| `src/acp-adapter.mjs` | `createAcpAdapter` — the public surface: identity, Host hooks, the one-slot turn fence, settlement ordering, cancellation, usage/cost evidence, stop evidence |
+## Public API
+
+```js
+import { createAcpAdapter } from './packages/bot-acp/src/acp-adapter.mjs'
+
+const adapter = await createAcpAdapter({
+  authority,            // capability-broker authority: { describe, assertModel, assertTool }
+  subject,              // registered authority subject
+  binding,              // { taskId, attemptId, machineId, workspaceId, location }
+  operationId,          // durable operation identity
+  entry,                // { executable, sha256, version, script?, scriptSha256? } — Host-pinned
+  spawnArgs,            // Host-constructed argv after the executable (e.g. ['acp'])
+  runtimeRoot,          // isolated absolute runtime root (private HOME)
+  workspace,            // agent cwd
+  model,                // { catalogProvider, catalogModel }
+  signal,               // AbortSignal
+  hooks,                // { onBeforeRequest, onObserve, onSettle, onClose } — the only ledger recipients
+  onPermissionRequest,  // Host permission callback; absent denies every ask
+  operationTool,        // (identity) => committed tool name | null
+  resumeSessionId,      // only honoured when the agent advertises loadSession
+})
+
+await adapter.start()                       // initialize → authenticate → session/new (or load)
+const turn = await adapter.submitTurn({ text })   // text only
+adapter.cancel()                            // a request, never a stop confirmation
+await adapter.stop('reason')                // real process stop + evidence
+adapter.snapshot()                          // evidence snapshot
+```
+
+A turn result carries `{ ok, outcome, stopReason, sessionId, text, usage, costUsd,
+costStatus, elapsedMs, cancelRequestedAt, updates, errorText, dispatched }`.
+
+`outcome` is one of `succeeded`, `cancelled`, `failed`, `not-run` or `unknown`.
+`not-run` means the prompt provably never reached the agent (a refused admission, a
+failed launch or session handshake, a pre-dispatch refusal, a cancelled
+reservation); `unknown` means the prompt was issued and the agent may have acted
+on it — an unknown outcome is reported verbatim and is never replayed
+automatically. `dispatched` records whether the prompt was really issued, and
+`snapshot().turnsDispatched` counts dispatches, never completions.
+
+`submitTurn` rejects only for a request that never became a turn (a malformed
+payload, a Host admission refusal, a denied grant). Once a turn exists it always
+ends in exactly one settlement, delivered to `hooks.onSettle` before the returned
+promise resolves.
+
+## Policy invariants
+
+- **Authority is Host state.** Model routes, tools, executable paths, digests,
+  environment and credentials never arrive through a turn payload: `submitTurn`
+  accepts `{ text }` and nothing else. A driver request naming an executable,
+  endpoint or credential is an error (`HOST_OWNED_ENGINE_INPUT` upstream, and the
+  same discipline here). Request JSON that claims a `botId`, `owner` or `config`
+  is never authority.
+- **One turn slot, reserved before the first await.** `submitTurn` takes its slot
+  synchronously, so a second call in the same tick is refused with
+  `ACP_TURN_IN_PROGRESS` and performs no admission, no launch and no prompt.
+  Admission, session start, dispatch, the peer's result and the Host settlement
+  all belong to that one slot, and the Host grant is re-judged after every
+  asynchronous boundary. A turn settled underneath a pending call (cancel, stop,
+  revocation, peer exit) is never resumed: the late continuation refuses with
+  `ACP_TURN_NOT_DISPATCHED`.
+- **Settlement is durable before it is public.** `hooks.onSettle` is the only
+  settlement path, and it runs before the success is published and before the
+  slot is released; a slow hook keeps the turn observably pending
+  (`busy === true`, `snapshot().settlement.inFlight`). A hook that refuses
+  refuses the success: `submitTurn` rejects with `ACP_SETTLEMENT_FAILED` carrying
+  the original native result and its unknown funding evidence, and the adapter
+  retires instead of letting a new request run on an unrecorded turn. Nothing is
+  caught and swallowed into a success, no cost or usage figure is invented, and
+  no second ledger is opened.
+- **Not-run and unknown are different answers.** A refused admission releases the
+  slot so the caller may call again and records no settlement. After admission,
+  a failure before the prompt is issued settles once as `not-run`; a prompt whose
+  write may have reached the agent settles as `unknown`. `turnsDispatched` counts
+  the dispatch moment, not completions.
+- **Session and model identity are fenced by a pending turn.** `start`,
+  `startFresh`, `selectModel` and `setMode` refuse while a turn is pending. The
+  model a turn runs under is the Host-committed `catalogModel`: a peer advertising
+  another model is not authority, and selecting one anyway would make the turn
+  evidence and the funded grant disagree. A different binding needs a rebuilt,
+  re-authorized adapter (`ACP_MODEL_BINDING_CHANGED`), never owner or permission
+  data smuggled through request JSON.
+- **Stop and cancel work at every stage.** `stop` settles a pending turn first
+  (not-run before dispatch, unknown afterwards), awaits a launch that raced it so
+  no late spawn outlives the stop, really stops the native tree, and only then
+  waits for in-flight settlements before reporting `onClose`. `cancel` during a
+  pending admission settles the reservation as not-run; after dispatch it sends
+  `session/cancel`, and an unanswered cancel ends in a real process stop. Only the
+  launcher's own accounting (Windows job object) confirms a tree stop; a cancel
+  request is never a stop confirmation, and a stop without one is reported
+  `unconfirmed`, not `confirmed`.- **Fail-closed permissions.** Only an `allow`-kind option the agent itself offered
+  can approve, and only after the Host handler answers against a committed grant.
+  Missing handler, unknown option, duplicate ask, timeout, close, revocation and
+  abort all deny. Session-scoped "allow always" is deliberately not implemented:
+  every ask is decided by the Host.
+- **Client file and terminal access is off by default.** `fs/read_text_file`,
+  `fs/write_text_file` and `terminal/*` are advertised `false` and refused with
+  method-not-found. Enabling them requires a Host-submitted root plus Host IO
+  callbacks; a hand-written instruction in a prompt is never the boundary.
+- **Unknown is not success.** An unknown `stopReason` is reported verbatim;
+  `end_turn` with no output is a lost turn; a refused resume never opens a new
+  session and replays the old turn.
+- **Cancel is a request, not a confirmation.** `session/cancel` and the process
+  tree-stop are recorded separately; only the native supervisor's own accounting
+  (Windows job object) confirms a tree stop.
+- **No second ledger.** ACP reports token/context usage and no dollar figure, so
+  `costUsd` stays `null` and `costStatus` stays `unknown`; evidence flows to the
+  Host hooks only.
+- **`onObserve` is diagnostic, `onSettle` is the record.** `onObserve` reports
+  that a session exists; it is never a settlement and never carries money. Only
+  `onSettle` records a turn, and only `onClose` reports the stop evidence.
+
+## Tests
+
+| File | Runs |
+| --- | --- |
+| `tests/bot-acp-codec.test.mjs` | fast, offline: framing, UTF-8 splits, oversize, malformed, duplicate/unknown ids, exit rejection, real-child pipe |
+| `tests/bot-acp-permissions.test.mjs` | fast, offline: every deny path, client-method guard, path containment |
+| `tests/bot-acp-session-state.test.mjs` | fast, in-process: session lifecycle, turn rules, model/mode gating, permission routing |
+| `tests/bot-acp-turn-fence.test.mjs` | fast, in-process: the turn fence — same-tick submits, slow/refused admission, slow/refused settlement, stop during a launch, pin/launch/dispatch failures, late and retired-process traffic, cancel/revocation at every stage, identity fences — against a controlled launcher seam |
+| `tests/bot-acp-session.native.mjs` | **serial** (`node --test --test-concurrency=1`): real offline child through the real native supervisor, including the turn-fence suite |
+
+`scripts/verify-bot-acp.mjs` runs all five in an isolated `tmp/integration/bot-acp/`
+directory and writes `report.json`. No agent CLI, network, user profile, credential
+or desktop is touched.
+
+The seam suite proves the *timing* of the fence deterministically; the native
+suite proves the same rules against a real offline Node child and a real native
+supervisor, which is the only real-machine evidence. Neither is a substitute for
+the other.