@bitkyc08/opencodex 2.87.0 → 2.89.0

package/src/messaging/remote-process.ts

@@ -0,0 +1,131 @@
+import { linkSshSpawnEnv } from "../link/ssh-runner";
+import { MessageBudget } from "./budget";
+import { RemoteCapacity, remoteError, REMOTE_LIMITS } from "./remote-contract";
+import { LocalMessagingError } from "./types";
+
+export interface RemoteHelper {
+  readonly pid: number; readonly exited: Promise<number>; readonly output: Promise<string>;
+  close(): Promise<void>;
+}
+/** Narrow subprocess seam for offline lifecycle tests; production always uses owned Bun children. */
+export interface RemoteHelperProcess {
+  readonly pid: number; readonly exitCode: number | null; readonly exited: Promise<number>;
+  readonly stdout: ReadableStream<Uint8Array>; readonly stderr: ReadableStream<Uint8Array>;
+  readonly stdin: Pick<Bun.FileSink, "write" | "end">;
+}
+export interface RemoteHelperOptions {
+  purpose?: "persistent" | "transient";
+  spawn?: (argv: readonly string[], env: NodeJS.ProcessEnv | undefined) => RemoteHelperProcess;
+  signalGroup?: (pid: number, kind: NodeJS.Signals) => void;
+  successCodes?: readonly number[];
+}
+/** Spawn only invocation-owned process groups; bounded drains and cleanup are shared by helpers/tunnels. */
+export function spawnRemoteHelper(argv: readonly string[], capacity: RemoteCapacity, signal?: AbortSignal,
+  stdin?: string, env = linkSshSpawnEnv(), options: RemoteHelperOptions = {}): RemoteHelper {
+  if (signal?.aborted) throw remoteError("cancelled", "Messaging helper was cancelled before spawn.");
+  const release = capacity.reserveHelper(options.purpose ?? "persistent");
+  let child: RemoteHelperProcess;
+  try { child = options.spawn ? options.spawn(argv, env)
+    : Bun.spawn([...argv], { stdin: "pipe", stdout: "pipe", stderr: "pipe", detached: true, env }); }
+  catch { release(); throw remoteError("ssh_unavailable", "The messaging SSH helper could not start."); }
+  const readers = [child.stdout.getReader(), child.stderr.getReader()];
+  let closing: Promise<void> | undefined;
+  let failure: Error | undefined;
+  const cancelledPipes = [false, false];
+  const pipeEnds: (() => void)[] = [];
+  const naturalPipes = readers.map(() => new Promise<void>(resolve => { pipeEnds.push(resolve); }));
+  const physicallyClosed = Promise.all([child.exited, ...naturalPipes]);
+  void physicallyClosed.then(() => release()).catch(() => {});
+  let stopOutput!: (reason: unknown) => void;
+  const stopped = new Promise<never>((_, reject) => { stopOutput = reject; });
+  const signalGroup = (kind: NodeJS.Signals) => {
+    if (child.exitCode !== null) return;
+    try { if (options.signalGroup) options.signalGroup(child.pid, kind); else process.kill(-child.pid, kind); }
+    catch { /* Exit racing owned cleanup is harmless. */ }
+  };
+  const close = (): Promise<void> => closing ??= (async () => {
+    signal?.removeEventListener("abort", abort);
+    signalGroup("SIGTERM");
+    const force = setTimeout(() => signalGroup("SIGKILL"), 500);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let cleanupFailure: unknown;
+    try {
+      await Promise.race([physicallyClosed, new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(remoteError("cleanup_incomplete", "An owned messaging helper or its pipes did not settle within cleanup budget.")), REMOTE_LIMITS.shutdownMs);
+      })]);
+    } catch (error) {
+      cleanupFailure = error;
+      if (error instanceof Error && failure) error.cause = failure;
+      throw error; // Incomplete cleanup remains visible even when an earlier failure triggered it.
+    }
+    finally {
+      clearTimeout(force); clearTimeout(timer);
+      // Escaped descendants retaining a pipe cannot hold shutdown open forever.
+      for (const [index, reader] of readers.entries()) {
+        cancelledPipes[index] = true; void reader.cancel().catch(() => {});
+      }
+      stopOutput(cleanupFailure ?? failure ?? remoteError("ssh_incomplete", "Messaging helper output capture was stopped."));
+      // Cancellation cannot prove natural EOF; unresolved ownership keeps its helper capacity charged.
+    }
+  })();
+  const abort = () => { void close().catch(() => {}); };
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted) abort();
+  const drain = async (index: number): Promise<string> => {
+    const chunks: Uint8Array[] = [], reservations: (() => void)[] = [];
+    let bytes = 0, discarding = false;
+    try {
+      for (;;) {
+        const next = await readers[index]!.read();
+        if (next.done) { if (!cancelledPipes[index]) pipeEnds[index]!(); break; }
+        if (index === 1 || discarding) continue; // stderr is never retained or returned.
+        try {
+          bytes += next.value.byteLength;
+          if (bytes > 64 * 1024) throw remoteError("ssh_output_limit", "Messaging helper output exceeded its limit.");
+          reservations.push(capacity.reserve("outputBytes", next.value.byteLength || 1)); chunks.push(next.value);
+        } catch (error) {
+          failure ??= error instanceof LocalMessagingError ? error : remoteError("ssh_incomplete", "Messaging helper output could not be captured safely.");
+          discarding = true; chunks.length = 0;
+          for (const free of reservations.splice(0)) free();
+          abort(); // Continue discarding until natural EOF proves cleanup, rather than abandoning the reader.
+        }
+      }
+      return index === 0 ? new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)) : "";
+    } catch {
+      failure ??= remoteError("ssh_incomplete", "Messaging helper output could not be captured safely.");
+      abort(); return "";
+    } finally { for (const free of reservations) free(); readers[index]!.releaseLock(); }
+  };
+  const input = (async () => {
+    if (stdin !== undefined) await child.stdin.write(stdin);
+    await child.stdin.end();
+  })().catch(() => {
+    failure ??= remoteError("ssh_incomplete", "Messaging control input could not be written.");
+    abort(); throw failure;
+  });
+  const output = Promise.race([stopped, Promise.all([drain(0), drain(1), input]).then(([out]) => {
+    if (failure) throw failure; return out;
+  })]);
+  void output.catch(() => {});
+  void child.exited.then(() => { signal?.removeEventListener("abort", abort); }).catch(() => {});
+  return { pid: child.pid, exited: child.exited, output, close };
+}
+
+/** One bounded batch covers helper startup, stdin, exit and output; errors never include raw output. */
+export async function runRemoteHelper(argv: readonly string[], budget: MessageBudget,
+  capacity: RemoteCapacity, stdin?: string, env?: NodeJS.ProcessEnv, options: RemoteHelperOptions = {}): Promise<string> {
+  budget.throwIfEnded();
+  const helper = spawnRemoteHelper(argv, capacity, budget.signal, stdin, env ?? linkSshSpawnEnv(), { ...options, purpose: "transient" });
+  let cancelled!: () => void;
+  const cancellation = new Promise<never>((_, reject) => {
+    cancelled = () => reject(budget.signal.reason);
+    budget.signal.addEventListener("abort", cancelled, { once: true });
+    if (budget.signal.aborted) cancelled();
+  });
+  try {
+    const [code, output] = await Promise.race([Promise.all([helper.exited, helper.output]), cancellation]);
+    budget.throwIfEnded();
+    if (!(options.successCodes ?? [0]).includes(code)) throw remoteError(code === 127 ? "remote_ocx_missing" : "ssh_failed", "Messaging SSH command did not complete successfully.");
+    return output;
+  } finally { budget.signal.removeEventListener("abort", cancelled); await helper.close(); }
+}

package/src/messaging/remote-replies.ts

@@ -0,0 +1,98 @@
+import { exactRecord, remoteError, type RemotePeer } from "./remote-contract";
+import type { RemoteMessageStore } from "./remote-store";
+import type { messageEnvelope } from "./envelope";
+import { isThreadId } from "./types";
+
+interface ReplyGrant {
+  peer: string;
+  transaction: string;
+  thread: string;
+  expires: number;
+  busy: boolean;
+}
+export const REPLY_GRANT_LIMIT = 256;
+export const REPLY_GRANT_MS = 24 * 60 * 60 * 1000;
+
+/** Owner-lifetime, bounded return routes; enrollment alone never authorizes unrelated return traffic. */
+export class RemoteReplyGrants {
+  private readonly grants = new Map<string, ReplyGrant>();
+  constructor(private readonly store: RemoteMessageStore, private readonly now = () => performance.now()) {}
+
+  private current(peer: RemotePeer) {
+    return this.store.requireEnabled().peers.find(item => item.machine.id === peer.machine.id
+      && item.transaction === peer.transaction && item.incoming === peer.incoming && item.outgoing === peer.outgoing);
+  }
+  private prune() {
+    const peers = this.store.requireEnabled().peers;
+    for (const [id, grant] of this.grants) {
+      if (grant.expires <= this.now() || !peers.some(peer =>
+        peer.machine.id === grant.peer && peer.transaction === grant.transaction)) {
+        this.grants.delete(id);
+      }
+    }
+  }
+  /** Local-control only: register before dispatch, forget only on definite request non-submission. */
+  control(value: unknown) {
+    const raw = exactRecord(value, ["peerId", "transaction", "messageId", "threadId", "action"]);
+    if (![raw.peerId, raw.transaction, raw.messageId, raw.threadId].every(isThreadId)
+      || !["open", "forget"].includes(String(raw.action))) {
+      throw remoteError("invalid_reply_route", "Invalid reply route registration.");
+    }
+    const peer = this.store.peer(raw.peerId as string);
+    if (peer.transaction !== raw.transaction) {
+      throw remoteError("peer_revoked", "Reply route enrollment changed.");
+    }
+    this.prune();
+    const id = raw.messageId as string;
+    if (raw.action === "forget") {
+      const existing = this.grants.get(id);
+      if (existing && (existing.peer !== raw.peerId || existing.transaction !== raw.transaction
+        || existing.thread !== raw.threadId || existing.busy)) {
+        throw remoteError("invalid_reply_route", "Reply route is not removable.");
+      }
+      this.grants.delete(id);
+      return { registered: false };
+    }
+    if (this.grants.has(id) || this.grants.size >= REPLY_GRANT_LIMIT) {
+      throw remoteError("remote_capacity", "The owner's bounded reply-route capacity was reached; no new request was dispatched.");
+    }
+    this.grants.set(id, { peer: peer.machine.id, transaction: peer.transaction, thread: raw.threadId as string,
+      expires: this.now() + REPLY_GRANT_MS, busy: false });
+    return { registered: true };
+  }
+  /** Response-only peers can discover only the original local senders awaiting their response. */
+  visible(peer: RemotePeer, thread: string): boolean {
+    this.prune();
+    const current = this.current(peer);
+    return !!current && (current.allowInbound === true || [...this.grants.values()].some(grant =>
+      grant.peer === peer.machine.id && grant.transaction === peer.transaction && grant.thread === thread && !grant.busy));
+  }
+  /** Reserve synchronously before native dispatch; an uncertain response consumes its grant, never replays it. */
+  begin(peer: RemotePeer, header: ReturnType<typeof messageEnvelope>["header"], thread: string) {
+    this.prune();
+    const current = this.current(peer);
+    if (!current) {
+      throw remoteError("peer_revoked", "Message enrollment changed before dispatch.");
+    }
+    const grant = header.kind === "response" && header.inReplyTo ? this.grants.get(header.inReplyTo) : undefined;
+    if (!grant || grant.peer !== peer.machine.id || grant.transaction !== peer.transaction
+      || grant.thread !== thread) {
+      if (current.allowInbound === true) {
+        return (_submitted: boolean) => {};
+      }
+      throw remoteError("reply_route_required", "This peer may send only a correlated response to an opened local reply route.");
+    }
+    if (grant.busy) {
+      throw remoteError("reply_route_required", "A correlated response is already in flight on this reply route.");
+    }
+    // Broad consent may allow unrelated traffic, but a matching response still spends its one-shot grant.
+    grant.busy = true;
+    return (submitted: boolean) => {
+      if (submitted) {
+        this.grants.delete(header.inReplyTo!);
+      } else {
+        grant.busy = false;
+      }
+    };
+  }
+}

package/src/messaging/remote-rpc-admission.ts

@@ -0,0 +1,32 @@
+import { exactRecord, remoteError } from "./remote-contract";
+import { isThreadId } from "./types";
+
+/** Validate only the native operations this gateway implements; never pass arbitrary JSON-RPC through. */
+export function admitRemoteRpc(method: string, value: unknown): Record<string, unknown> {
+  if (method === "initialize") {
+    const raw = exactRecord(value, ["clientInfo", "capabilities"]);
+    const client = exactRecord(raw.clientInfo, ["name", "version"]);
+    const caps = exactRecord(raw.capabilities, ["experimentalApi"]);
+    if (client.name !== "opencodex_message" || client.version !== "1.0.0" || caps.experimentalApi !== true) throw new Error();
+    return raw;
+  }
+  if (method === "initialized") return exactRecord(value, []);
+  if (method === "thread/loaded/list") {
+    const raw = exactRecord(value, value && typeof value === "object" && Object.hasOwn(value, "cursor") ? ["limit", "cursor"] : ["limit"]);
+    if (raw.limit !== 50 || (raw.cursor !== undefined && (typeof raw.cursor !== "string" || !raw.cursor || raw.cursor.length > 4096))) throw new Error();
+    return raw;
+  }
+  if (method === "thread/read") {
+    const raw = exactRecord(value, ["threadId", "includeTurns"]);
+    if (!isThreadId(raw.threadId) || raw.includeTurns !== false) throw new Error(); return raw;
+  }
+  if (method === "thread/queue/add") {
+    const raw = exactRecord(value, ["threadId", "input", "clientUserMessageId"]);
+    if (!isThreadId(raw.threadId) || !isThreadId(raw.clientUserMessageId) || !Array.isArray(raw.input) || raw.input.length !== 1) throw new Error();
+    const input = exactRecord(raw.input[0], ["type", "text"]);
+    if (input.type !== "text" || typeof input.text !== "string" || !input.text.trim()
+      || input.text.includes("\0") || Buffer.byteLength(input.text) > 32 * 1024) throw new Error();
+    return raw;
+  }
+  throw remoteError("remote_method_refused", "This RPC method is not admitted by the messaging gateway.");
+}

package/src/messaging/remote-send.ts

@@ -0,0 +1,72 @@
+import { MessageBudget } from "./budget";
+import { authenticatedRemoteSocket, remoteControl } from "./remote-auth";
+import { discoverLoaded, resolveLoaded } from "./discovery";
+import { messageEnvelope, validateMessage, type MessageOptions } from "./envelope";
+import { ownerEndpoint, resolveRemoteRoute } from "./remote-owner";
+import { LocalMessageRpc } from "./rpc";
+import { localDaemonEndpoint } from "./socket";
+import { messageFailure, type MessageReceipt } from "./send";
+import type { RemoteMessageStore } from "./remote-store";
+import { isThreadId, LocalMessagingError } from "./types";
+
+/** Remote discovery is explicit and loaded-only; it uses a live owner route and one proven connection. */
+export async function remoteSessions(store: RemoteMessageStore, host: string, budget: MessageBudget) {
+  const route = await resolveRemoteRoute(store, host, budget);
+  store.requireCurrentPeer(route.state, route.peer);
+  const rpc = await LocalMessageRpc.attach(await authenticatedRemoteSocket(route.state, route.endpoint, budget), budget);
+  try {
+    const sessions = await discoverLoaded(rpc, budget);
+    store.requireCurrentPeer(route.state, route.peer);
+    return { machine: route.peer.machine, sessions };
+  }
+  finally { rpc.close(); }
+}
+/** Attribute locally, discover/revalidate/queue remotely on one socket, and never replay an unknown result. */
+export async function sendRemoteMessage(store: RemoteMessageStore,
+  options: MessageOptions & { host: string; thread?: string; name?: string; body: string },
+  context: { home: string; senderId?: string }, budget: MessageBudget) {
+  const receipt: MessageReceipt & { machine?: { id: string; name: string }; targetMachine?: { id: string; name: string } } = {
+    schema: "ocx-message/1", messageId: crypto.randomUUID(), kind: options.kind, inReplyTo: options.inReplyTo ?? null,
+    status: "not_sent", sender: null, target: null,
+  };
+  let rpc: LocalMessageRpc | undefined;
+  try {
+    validateMessage(options, options.body);
+    if (context.senderId !== undefined && !isThreadId(context.senderId)) throw new LocalMessagingError("invalid_sender", "CODEX_THREAD_ID must be a UUID, not a claimed peer identity.");
+    const route = await resolveRemoteRoute(store, options.host, budget);
+    receipt.machine = route.state.machine; receipt.targetMachine = route.peer.machine;
+    let sender = null;
+    if (context.senderId) {
+      const local = await LocalMessageRpc.connect(localDaemonEndpoint(context.home).url, budget);
+      try { sender = resolveLoaded(await discoverLoaded(local, budget), { thread: context.senderId }); }
+      finally { local.close(); }
+    }
+    receipt.sender = sender ? { threadId: sender.id, name: sender.name, identitySource: "CODEX_THREAD_ID" } : null;
+    store.requireCurrentPeer(route.state, route.peer);
+    rpc = await LocalMessageRpc.attach(await authenticatedRemoteSocket(route.state, route.endpoint, budget), budget);
+    const target = resolveLoaded(await discoverLoaded(rpc, budget), options);
+    receipt.target = { threadId: target.id, name: target.name };
+    const envelope = messageEnvelope(receipt.messageId, options, options.body, sender, route.state.machine);
+    const fresh = await rpc.readThread(target.id);
+    if (fresh.status === "notLoaded") throw new LocalMessagingError("target_not_loaded", "The destination unloaded before remote submission.");
+    budget.throwIfEnded();
+    store.requireCurrentPeer(route.state, route.peer);
+    const replyRoute = sender && options.kind === "request" ? {
+      peerId: route.peer.machine.id, transaction: route.peer.transaction,
+      messageId: receipt.messageId, threadId: sender.id,
+    } : undefined;
+    if (replyRoute) {
+      await remoteControl(route.state, ownerEndpoint(route.state), "message/reply-route", { ...replyRoute, action: "open" }, budget);
+      store.requireCurrentPeer(route.state, route.peer);
+      budget.throwIfEnded();
+    }
+    Object.assign(receipt, await rpc.queueMessage(target.id, envelope.text, receipt.messageId));
+    if (replyRoute && receipt.status === "not_sent") {
+      try {
+        await remoteControl(route.state, ownerEndpoint(route.state), "message/reply-route", { ...replyRoute, action: "forget" }, budget);
+      } catch { /* No message was submitted; an unused bounded grant expires with the owner or its deadline. */ }
+    }
+  } catch (error) { receipt.error = messageFailure(error); }
+  finally { rpc?.close(); }
+  return receipt;
+}

package/src/messaging/remote-store.ts

@@ -0,0 +1,111 @@
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { isSshAlias } from "../link/ssh-argv";
+import { isThreadId } from "./types";
+import { capability, exactRecord, REMOTE_LIMITS, REMOTE_PROTOCOL, remoteError, validAlias,
+  validCapability, validMachine, validPort, type RemotePeer, type RemoteState } from "./remote-contract";
+import { createRemoteDirectory, readRemoteFile, withRemoteLock, writeRemoteFile } from "./remote-files";
+
+/** Strict versioned state; neither unknown fields nor duplicate aliases/identities are ignored. */
+export function parseRemoteState(value: unknown): RemoteState {
+  const raw = exactRecord(value, ["protocol", "machine", "enabled", "port", "controlKey", "generation", "peers"]);
+  if (raw.protocol !== REMOTE_PROTOCOL || !validMachine(raw.machine) || typeof raw.enabled !== "boolean"
+    || !validPort(raw.port) || !validCapability(raw.controlKey) || !isThreadId(raw.generation)
+    || !Array.isArray(raw.peers) || raw.peers.length > REMOTE_LIMITS.peers) throw remoteError("invalid_remote_state", "Messaging state has an invalid schema.");
+  const aliases = new Set<string>(), ids = new Set<string>(), transactions = new Set<string>();
+  for (const item of raw.peers) {
+    const peer = exactRecord(item, ["alias", "machine", "transaction", "incoming", "outgoing", "port", "ssh", "hostKey", "fingerprint",
+      ...(Object.hasOwn(item, "allowInbound") ? ["allowInbound"] : [])]);
+    if (!validAlias(peer.alias) || !validMachine(peer.machine) || peer.machine.id === raw.machine.id
+      || !isThreadId(peer.transaction) || !validCapability(peer.incoming) || !validCapability(peer.outgoing)
+      || peer.incoming === peer.outgoing || !validPort(peer.port)
+      || (Object.hasOwn(peer, "allowInbound") && typeof peer.allowInbound !== "boolean")
+      || (peer.ssh !== null && (typeof peer.ssh !== "string" || !isSshAlias(peer.ssh)))
+      || (peer.hostKey !== null && (typeof peer.hostKey !== "string" || peer.hostKey.length > 8192))
+      || (peer.fingerprint !== null && (typeof peer.fingerprint !== "string" || !/^SHA256:[A-Za-z0-9+/=]{1,64}$/.test(peer.fingerprint)))
+      || (peer.ssh === null) !== (peer.hostKey === null) || (peer.ssh === null) !== (peer.fingerprint === null)
+      || aliases.has(peer.alias) || ids.has(peer.machine.id) || transactions.has(peer.transaction)) throw remoteError("invalid_remote_state", "Messaging peer state is invalid or ambiguous.");
+    aliases.add(peer.alias); ids.add(peer.machine.id); transactions.add(peer.transaction);
+  }
+  return raw as unknown as RemoteState;
+}
+
+/** Messaging owns a small separate private JSON store, never Remote Link/provider state. */
+export class RemoteMessageStore {
+  readonly directory: string;
+  readonly path: string;
+  /** Select an explicit configuration home without reading or creating it. */
+  constructor(home: string) { this.directory = join(home, "messaging-remote"); this.path = join(this.directory, "state.json"); }
+  /** Absent state stays absent; malformed or unsafe state does not become a default. */
+  read(): RemoteState | null {
+    const text = readRemoteFile(this.path);
+    if (text === null) return null;
+    try { return parseRemoteState(JSON.parse(text)); }
+    catch { throw remoteError("invalid_remote_state", "Messaging state cannot be safely interpreted."); }
+  }
+  /** Enable explicitly, retaining stable identity and existing peer capabilities. */
+  enable(port = 39176): RemoteState {
+    if (!validPort(port)) throw remoteError("invalid_port", "Choose an unprivileged messaging port.");
+    createRemoteDirectory(this.directory);
+    return withRemoteLock(this.directory, () => {
+      const state = this.read() ?? { protocol: REMOTE_PROTOCOL, machine: { id: crypto.randomUUID(),
+        name: hostname().replace(/[\x00-\x1f\x7f-\x9f]/g, "").slice(0, 128) || "node" }, enabled: false,
+        port, controlKey: capability(), generation: crypto.randomUUID(), peers: [] };
+      if (!state.enabled || state.port !== port) state.generation = crypto.randomUUID();
+      state.enabled = true; state.port = port;
+      writeRemoteFile(this.path, JSON.stringify(parseRemoteState(state)));
+      return state;
+    });
+  }
+  /** Publish under one lock, then complete related journal cleanup before releasing ownership. */
+  mutate(action: (state: RemoteState) => void, afterPublish?: () => void): RemoteState {
+    this.requireEnabled();
+    return withRemoteLock(this.directory, () => {
+      const state = this.requireEnabled(); action(state);
+      writeRemoteFile(this.path, JSON.stringify(parseRemoteState(state))); afterPublish?.(); return state;
+    });
+  }
+  /** Disabling revokes current admission and invalidates every owner generation. */
+  disable(): void { this.mutate(state => { state.enabled = false; state.generation = crypto.randomUUID(); }); }
+  /** Require deliberate enablement rather than repairing or creating state on reads. */
+  requireEnabled(): RemoteState {
+    const state = this.read();
+    if (!state?.enabled) throw remoteError("remote_disabled", "Explicitly enable messaging on this node first.");
+    return state;
+  }
+  /** Select only one exact enrolled alias or machine UUID. */
+  peer(selector: string): RemotePeer {
+    const peers = this.requireEnabled().peers.filter(peer => peer.alias === selector || peer.machine.id === selector);
+    if (peers.length !== 1) throw remoteError("unknown_peer", "No unique enrolled messaging peer matches this exact host.");
+    return peers[0]!;
+  }
+  /** Local, explicit consent only; possession of a peer capability cannot widen inbound access. */
+  setInbound(selector: string, allow: boolean) {
+    const peer = this.peer(selector);
+    this.mutate(state => {
+      const current = state.peers.find(item => item.machine.id === peer.machine.id && item.transaction === peer.transaction);
+      if (!current) throw remoteError("peer_revoked", "Enrollment changed before inbound consent was saved.");
+      current.allowInbound = allow;
+    });
+    return { machine: peer.machine, inbound: allow ? "messages" : "responses-only" };
+  }
+  /** Revalidate captured route authority after awaits without retiring unrelated peer routes. */
+  requireCurrentPeer(state: RemoteState, peer: RemotePeer): void {
+    const current = this.requireEnabled();
+    const enrolled = current.peers.find(item => item.machine.id === peer.machine.id);
+    if (current.generation !== state.generation || current.machine.id !== state.machine.id
+      || current.controlKey !== state.controlKey || current.port !== state.port || !enrolled
+      || enrolled.transaction !== peer.transaction || enrolled.incoming !== peer.incoming
+      || enrolled.outgoing !== peer.outgoing || enrolled.port !== peer.port) {
+      throw remoteError("peer_revoked", "Messaging route authority changed before dispatch; no new work was sent.");
+    }
+  }
+  /** Listings never include capabilities, known-hosts records or private configuration paths. */
+  publicState() {
+    const state = this.read();
+    return state ? { protocol: state.protocol, machine: state.machine, enabled: state.enabled, port: state.port,
+      peers: state.peers.map(peer => ({ alias: peer.alias, machine: peer.machine, direction: peer.ssh ? "initiating" : "return-only",
+        inbound: peer.allowInbound === true ? "messages" : "responses-only",
+        fingerprint: peer.fingerprint })) } : { protocol: REMOTE_PROTOCOL, enabled: false, peers: [] };
+  }
+}

package/src/messaging/remote-tunnels.ts

@@ -0,0 +1,65 @@
+import { join } from "node:path";
+import { buildExecArgv, buildTunnelArgv, remoteOcxArgv } from "../link/ssh-argv";
+import { MessageBudget } from "./budget";
+import { exactRecord, RemoteCapacity, remoteError, validPort, type RemotePeer } from "./remote-contract";
+import { withRemoteLock, writeRemoteFile } from "./remote-files";
+import { remotePortCandidate, remotePortIsLoopback } from "./remote-ports";
+import { runRemoteHelper, spawnRemoteHelper, type RemoteHelper } from "./remote-process";
+import type { RemoteMessageStore } from "./remote-store";
+
+export interface RemoteTunnelPair {
+  localPort: number; returnPort: number; readonly alive: boolean; readonly exited: Promise<unknown>;
+  close(): Promise<void>;
+}
+export interface RemoteTunnelDeps {
+  run?: typeof runRemoteHelper;
+  spawn?: typeof spawnRemoteHelper;
+}
+/** Own one -L/-R pair with shared SSH policy and one setup deadline; never adopt/kill existing tunnels. */
+export async function startRemoteTunnels(store: RemoteMessageStore, peer: RemotePeer, budget: MessageBudget,
+  capacity: RemoteCapacity, ownerSignal: AbortSignal, deps: RemoteTunnelDeps = {}): Promise<RemoteTunnelPair> {
+  if (!peer.ssh || !peer.hostKey) throw remoteError("return_route_only", "This peer has no initiating SSH enrollment; wait for its return route.");
+  const knownHosts = join(store.directory, `${peer.machine.id}.known_hosts`);
+  withRemoteLock(store.directory, () => writeRemoteFile(knownHosts, peer.hostKey!));
+  const result = exactRecord(JSON.parse(await (deps.run ?? runRemoteHelper)(buildExecArgv({ alias: peer.ssh,
+    knownHostsFile: knownHosts, argv: remoteOcxArgv(["message", "_port"]) }), budget, capacity)), ["port"]);
+  if (!validPort(result.port)) throw remoteError("remote_incompatible", "Remote node did not offer an unprivileged return port.");
+  const localPort = remotePortCandidate(), returnPort = result.port, helpers: RemoteHelper[] = [];
+  let alive = true, closing: Promise<void> | undefined;
+  const close = (): Promise<void> => closing ??= (async () => {
+    alive = false; ownerSignal.removeEventListener("abort", abort);
+    const results = await Promise.allSettled(helpers.map(helper => helper.close()));
+    const failure = results.find(result => result.status === "rejected");
+    if (failure?.status === "rejected") throw failure.reason;
+  })();
+  const abort = () => { void close().catch(() => {}); };
+  ownerSignal.addEventListener("abort", abort, { once: true });
+  const cancelSetup = () => { void close().catch(() => {}); };
+  budget.signal.addEventListener("abort", cancelSetup, { once: true });
+  try {
+    budget.throwIfEnded(); if (ownerSignal.aborted) throw new Error();
+    for (const [direction, bindPort, targetPort] of [["L", localPort, peer.port], ["R", returnPort, store.requireEnabled().port]] as const) {
+      budget.throwIfEnded();
+      const helper = (deps.spawn ?? spawnRemoteHelper)(buildTunnelArgv({ alias: peer.ssh, knownHostsFile: knownHosts,
+        direction, bindPort, targetPort }), capacity, ownerSignal);
+      helpers.push(helper);
+      void helper.exited.then(() => close()).catch(() => {});
+    }
+    let ready = false;
+    while (!ready) {
+      budget.throwIfEnded();
+      if (!alive) throw new Error();
+      ready = await remotePortIsLoopback(localPort, budget, capacity);
+      if (!ready) await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(() => { budget.signal.removeEventListener("abort", cancel); resolve(); }, budget.remainingMs(100));
+        const cancel = () => { clearTimeout(timer); budget.signal.removeEventListener("abort", cancel); reject(budget.signal.reason); };
+        budget.signal.addEventListener("abort", cancel, { once: true });
+        if (budget.signal.aborted) cancel();
+      });
+    }
+    const exited = Promise.race(helpers.map(helper => helper.exited));
+    void exited.then(() => close()).catch(() => {});
+    return { localPort, returnPort, get alive() { return alive; }, exited, close };
+  } catch (error) { await close(); throw error; }
+  finally { budget.signal.removeEventListener("abort", cancelSetup); }
+}

package/src/messaging/rpc.ts

@@ -59,6 +59,16 @@ export class LocalMessageRpc implements LocalMetadataClient {
         if (budget.signal.aborted) abort();
       });
     } catch (error) { socket.terminate(); throw error; }
+    return LocalMessageRpc.attach(socket, budget, rpcTimeoutMs);
+  }
+
+  /** Initialize an already authenticated transport; local connect still accepts Unix sockets only. */
+  static async attach(socket: LocalSocket, budget: MessageBudget, rpcTimeoutMs = 10_000): Promise<LocalMessageRpc> {
+    try { budget.throwIfEnded(); } catch (error) { socket.terminate(); throw error; }
+    if (socket.readyState !== 1 || !Number.isInteger(rpcTimeoutMs) || rpcTimeoutMs <= 0 || rpcTimeoutMs > 10_000) {
+      socket.terminate();
+      throw new LocalMessagingError("invalid_transport", "Messaging transport must be connected with a bounded RPC deadline.");
+    }
     const rpc = new LocalMessageRpc(socket, budget, rpcTimeoutMs);
     try {
       const result = await rpc.request("initialize", {
@@ -97,7 +107,8 @@ export class LocalMessageRpc implements LocalMetadataClient {
   }
 
   /** Submit once on this connection; after an accepted write only a correlated reply is definitive. */
-  async queueMessage(threadId: string, text: string, messageId: string): Promise<QueueResult> {
+  async queueMessage(threadId: string, text: string, messageId: string,
+    acknowledge?: (submissionId: string) => void): Promise<QueueResult> {
     let written = false;
     try {
       if (!isThreadId(threadId) || !isThreadId(messageId) || !text || text.includes("\0")
@@ -115,6 +126,7 @@ export class LocalMessageRpc implements LocalMetadataClient {
           && (!Array.isArray(queued.input[0].text_elements) || queued.input[0].text_elements.length !== 0))) {
         throw this.invalidMetadata();
       }
+      acknowledge?.(queued.id);
       return { status: "queued" };
     } catch (error) {
       if (error instanceof QueueRejection || !written) {

package/src/oauth/account-auto-pause-policy.ts

@@ -0,0 +1,66 @@
+import type { AccountPauseReason, AccountAutoPausePolicy } from "../types/account-auto-pause";
+import { readBoundedResponseBody } from "../lib/bounded-body";
+
+/** Only whole, account-scoped messages are authority; model/resource policy errors are not. */
+export function classifyPermanentAccountRefusal(status: number, payload: unknown): AccountPauseReason | undefined {
+  if (status !== 401 && status !== 403 || !payload || typeof payload !== "object" || Array.isArray(payload)) return;
+  const error = (payload as { error?: unknown }).error;
+  if (!error || typeof error !== "object" || Array.isArray(error)) return;
+  const { type: rawType, code, message, status: googleStatus } = error as Record<string, unknown>;
+  const google = googleStatus === "PERMISSION_DENIED" || googleStatus === "UNAUTHENTICATED";
+  const type = rawType ?? (googleStatus === "PERMISSION_DENIED" ? "permission_error" : googleStatus === "UNAUTHENTICATED" ? "authentication_error" : undefined);
+  if (typeof message !== "string" || !["permission_error", "authentication_error", "invalid_request_error"].includes(String(type))) return;
+  if (code != null && !(google && code === status) && !["permission_error", "permission_denied", "subscription_inactive", "subscription_expired", "subscription_required", "plan_downgraded"].includes(String(code))) return;
+  const text = message.trim();
+  if (/^OAuth authentication is (?:currently )?not allowed for this organi[sz]ation[.!]?$/i.test(text)) return "oauth_organization_disabled";
+  if (/^(?:Your |The )?(?:Claude |ChatGPT )?subscription (?:has expired|is expired)[.!]?$/i.test(text)) return "subscription_expired";
+  if (/^(?:(?:Your |The )?(?:Claude |ChatGPT )?subscription is inactive|Your account does not have an active subscription)[.!]?$/i.test(text)) return "subscription_inactive";
+  if (/^Your (?:account|plan) (?:has been |was )?downgraded to (?:the )?free(?: plan)? (?:and |with )?(?:has )?(?:no|without) (?:remaining )?credits[.!]?$/i.test(text)) return "plan_downgraded";
+  if (type === "permission_error" && /^Your account (?:does not have access to Claude Code|is (?:disabled|suspended)|is not permitted to use (?:the |this )?API)[.!]?$/i.test(text)) return "account_permission_denied";
+}
+
+export async function permanentAccountRefusal(response: Response, signal?: AbortSignal): Promise<AccountPauseReason | undefined> {
+  if (response.status !== 401 && response.status !== 403) return;
+  try {
+    const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true,
+      maxBytes: 16_384, totalTimeoutMs: 250, inactivityTimeoutMs: 250 });
+    if (!body.displaySafe || body.truncated) return;
+    return classifyPermanentAccountRefusal(response.status, JSON.parse(body.text));
+  } catch { return; }
+}
+
+export function autoPauseThreshold(policy: AccountAutoPausePolicy | undefined): number | undefined {
+  if (policy?.enabled !== true) return;
+  const threshold = policy.consecutiveFailures ?? 2;
+  return Number.isInteger(threshold) && threshold >= 1 && threshold <= 100 ? threshold : undefined;
+}
+
+type Streak = { incarnation: string; count: number; tail: Promise<unknown>; paused: boolean };
+/** Process-local streaks, serialized in response-arrival order, including asynchronous reads/writes. */
+export class AccountRefusalStreaks {
+  private readonly accounts = new Map<string, Streak>();
+  observe(key: string, incarnation: string, threshold: number, verdict: Promise<AccountPauseReason | undefined>, success: boolean,
+    current: () => boolean, pause: (reason: AccountPauseReason) => Promise<boolean>): Promise<boolean> {
+    if (!current()) return Promise.resolve(false);
+    let streak = this.accounts.get(key);
+    if (!streak || streak.incarnation !== incarnation) {
+      // Capacity refusal forgets no live streak and never pauses on incomplete evidence.
+      if (!streak && this.accounts.size >= 2048) return Promise.resolve(false);
+      streak = { incarnation, count: 0, tail: Promise.resolve(), paused: false };
+      this.accounts.set(key, streak);
+    }
+    const owned = streak;
+    const result = owned.tail.catch(() => undefined).then(async () => {
+      const reason = await verdict;
+      if (this.accounts.get(key) !== owned || owned.paused || !current()) return false;
+      if (success) { owned.count = 0; return false; }
+      if (!reason) return false;
+      owned.count = Math.min(owned.count + 1, threshold);
+      if (owned.count < threshold) return false;
+      owned.paused = await pause(reason);
+      return owned.paused;
+    });
+    owned.tail = result;
+    return result;
+  }
+}