@bitkyc08/opencodex 2.87.0 → 2.89.0

package/src/messaging/remote-auth.ts

@@ -0,0 +1,83 @@
+import { MessageBudget } from "./budget";
+import type { LocalSocket } from "./socket";
+import { capability, exactRecord, matchesProof, peerProof, REMOTE_PROTOCOL, remoteError,
+  validCapability, type RemotePeer, type RemoteState } from "./remote-contract";
+
+export interface RemoteEndpoint { port: number; machineId: string; transaction: string; key: string }
+/** Select one directional receiver-issued capability, not a provider or Remote Link credential. */
+export function peerEndpoint(peer: RemotePeer, port: number): RemoteEndpoint {
+  return { port, machineId: peer.machine.id, transaction: peer.transaction, key: peer.outgoing };
+}
+/** Authenticate the actual socket before sending a bearer-derived client proof or any native/body frame. */
+export async function authenticatedRemoteSocket(state: RemoteState, endpoint: RemoteEndpoint,
+  budget: MessageBudget): Promise<LocalSocket> {
+  budget.throwIfEnded();
+  if (!Number.isInteger(endpoint.port) || endpoint.port < 1024 || endpoint.port > 65535) throw remoteError("invalid_port", "Invalid messaging route port.");
+  const Constructor = WebSocket as unknown as { new(url: string): LocalSocket };
+  const socket = new Constructor(`ws://127.0.0.1:${endpoint.port}/message`);
+  const nonce = capability();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      let stage = 0;
+      const cleanup = () => {
+        clearTimeout(timer); budget.signal.removeEventListener("abort", abort);
+        socket.onopen = socket.onerror = socket.onclose = socket.onmessage = null;
+      };
+      const fail = () => { cleanup(); reject(remoteError("remote_auth_failed", "Messaging connection identity/authentication failed; no message was sent.")); };
+      const abort = () => { cleanup(); reject(budget.signal.reason); };
+      const timer = setTimeout(fail, budget.remainingMs(5000));
+      budget.signal.addEventListener("abort", abort, { once: true });
+      socket.onerror = socket.onclose = fail;
+      socket.onopen = () => socket.send(JSON.stringify({ type: "hello", protocol: REMOTE_PROTOCOL,
+        from: state.machine.id, to: endpoint.machineId, transaction: endpoint.transaction, nonce }));
+      socket.onmessage = event => {
+        try {
+          if (typeof event.data !== "string" || Buffer.byteLength(event.data) > 4096) throw new Error();
+          const raw: unknown = JSON.parse(event.data);
+          if (stage === 0) {
+            const proof = exactRecord(raw, ["type", "nonce", "proof"]);
+            if (proof.type !== "challenge" || !validCapability(proof.nonce)
+              || !matchesProof(proof.proof, peerProof(endpoint.key, "server", state.machine.id, endpoint.machineId,
+                endpoint.transaction, nonce, proof.nonce))) throw new Error();
+            budget.throwIfEnded(); stage = 1;
+            socket.send(JSON.stringify({ type: "authorize", proof: peerProof(endpoint.key, "client", state.machine.id,
+              endpoint.machineId, endpoint.transaction, nonce, proof.nonce) }));
+          } else {
+            const ready = exactRecord(raw, ["type", "protocol"]);
+            if (ready.type !== "authorized" || ready.protocol !== REMOTE_PROTOCOL) throw new Error();
+            cleanup(); resolve();
+          }
+        } catch { fail(); }
+      };
+      if (budget.signal.aborted) abort();
+    });
+    budget.throwIfEnded(); return socket;
+  } catch (error) { socket.terminate(); throw error; }
+}
+/** Bound a control operation to one authenticated connection; never reconnect/replay on uncertainty. */
+export async function remoteControl(state: RemoteState, endpoint: RemoteEndpoint, action: string,
+  params: Record<string, unknown>, budget: MessageBudget): Promise<unknown> {
+  const socket = await authenticatedRemoteSocket(state, endpoint, budget);
+  try {
+    return await new Promise((resolve, reject) => {
+      const finish = (error?: Error, result?: unknown) => {
+        clearTimeout(timer); budget.signal.removeEventListener("abort", abort);
+        socket.onmessage = socket.onerror = socket.onclose = null;
+        if (error) reject(error); else resolve(result);
+      };
+      const abort = () => finish(remoteError("remote_control_unknown", "Messaging control outcome is unconfirmed; reconcile configuration before retrying."));
+      const timer = setTimeout(abort, budget.remainingMs(10000));
+      budget.signal.addEventListener("abort", abort, { once: true });
+      socket.onclose = socket.onerror = abort;
+      socket.onmessage = event => {
+        try {
+          if (typeof event.data !== "string" || Buffer.byteLength(event.data) > 8192) throw new Error();
+          const reply = exactRecord(JSON.parse(event.data), ["id", "result"]);
+          if (reply.id !== 1) throw new Error(); finish(undefined, reply.result);
+        } catch { abort(); }
+      };
+      if (budget.signal.aborted) { abort(); return; }
+      try { socket.send(JSON.stringify({ id: 1, method: action, params })); } catch { abort(); }
+    });
+  } finally { socket.terminate(); }
+}

package/src/messaging/remote-bridge.ts

@@ -0,0 +1,270 @@
+import type { ServerWebSocket } from "bun";
+import { MessageBudget } from "./budget";
+import { LocalMessageRpc } from "./rpc";
+import { localDaemonEndpoint } from "./socket";
+import { isRecord, isThreadId } from "./types";
+import { capability, exactRecord, matchesProof, peerProof, RemoteCapacity, REMOTE_LIMITS,
+  REMOTE_PROTOCOL, validCapability, type RemotePeer } from "./remote-contract";
+import { admitRemoteRpc } from "./remote-rpc-admission";
+import { receiveRemoteEnvelope } from "./remote-envelope";
+import { RemoteReplyGrants } from "./remote-replies";
+import type { RemoteMessageStore } from "./remote-store";
+
+interface Connection {
+  stage: "hello" | "proof" | "authorized";
+  budget: MessageBudget;
+  release: () => void;
+  peer?: RemotePeer;
+  key?: string;
+  from?: string;
+  transaction?: string;
+  nonce?: string;
+  serverNonce?: string;
+  ws?: ServerWebSocket<Connection>;
+  rpc?: LocalMessageRpc;
+  pending: number;
+  lastId: number;
+  queue: boolean;
+  initialized: boolean;
+  initializing: boolean;
+  closed: boolean;
+  authTimer?: ReturnType<typeof setTimeout>;
+  loadedIds: Set<string>;
+}
+export interface RemoteBridgeHooks {
+  control(peer: RemotePeer | null, method: string, params: unknown, budget: MessageBudget): Promise<unknown>;
+}
+/** A foreground-owned loopback gateway authenticates before touching the existing native daemon. */
+export function startRemoteBridge(store: RemoteMessageStore, codexHome: string, capacity: RemoteCapacity,
+  signal: AbortSignal, hooks: RemoteBridgeHooks) {
+  const initial = store.requireEnabled();
+  const connections = new Set<Connection>();
+  const tasks = new Set<Promise<void>>();
+  const replies = new RemoteReplyGrants(store);
+  let stopping = false;
+  let closePromise: Promise<void> | undefined;
+  const validConnection = (data: Connection): boolean => {
+    const state = store.requireEnabled();
+    if (state.generation !== initial.generation) return false;
+    if (!data.peer) return data.key === state.controlKey;
+    return state.peers.some(peer => peer.machine.id === data.from
+      && peer.transaction === data.transaction && peer.incoming === data.key);
+  };
+  const retire = (data: Connection) => {
+    if (data.closed) return;
+    data.closed = true;
+    clearTimeout(data.authTimer);
+    connections.delete(data);
+    data.budget.dispose();
+    data.rpc?.close();
+    data.ws?.terminate();
+    data.release();
+  };
+  const send = (data: Connection, value: unknown) => {
+    const frame = JSON.stringify(value);
+    const free = capacity.reserve("outputBytes", Buffer.byteLength(frame));
+    try {
+      if (!data.ws || data.ws.send(frame) <= 0) retire(data);
+    } finally {
+      free();
+    }
+  };
+  const authenticate = (data: Connection, raw: unknown) => {
+    const state = store.requireEnabled();
+    if (state.generation !== initial.generation) throw new Error("Messaging owner generation changed.");
+    if (data.stage === "hello") {
+      const hello = exactRecord(raw, ["type", "protocol", "from", "to", "transaction", "nonce"]);
+      if (hello.type !== "hello" || hello.protocol !== REMOTE_PROTOCOL || !isThreadId(hello.from)
+        || hello.to !== state.machine.id || !isThreadId(hello.transaction) || !validCapability(hello.nonce)) {
+        throw new Error("Invalid messaging authentication hello.");
+      }
+      const peer = state.peers.find(item => item.machine.id === hello.from && item.transaction === hello.transaction);
+      const isLocalControl = hello.from === state.machine.id && hello.transaction === state.generation;
+      const key = isLocalControl ? state.controlKey : peer?.incoming;
+      if (!key) throw new Error("Messaging enrollment is unavailable.");
+      Object.assign(data, { peer, key, from: hello.from, transaction: hello.transaction, nonce: hello.nonce, serverNonce: capability() });
+      data.stage = "proof";
+      send(data, { type: "challenge", nonce: data.serverNonce, proof: peerProof(key, "server", data.from!, state.machine.id,
+        data.transaction!, data.nonce!, data.serverNonce!) });
+    } else {
+      const proof = exactRecord(raw, ["type", "proof"]);
+      if (proof.type !== "authorize" || !validConnection(data) || !matchesProof(proof.proof,
+        peerProof(data.key!, "client", data.from!, state.machine.id, data.transaction!, data.nonce!, data.serverNonce!))) {
+        throw new Error("Messaging authentication proof was refused.");
+      }
+      // Unverified sockets never consume outgoing/control capacity. Promote only after proof verification.
+      // Peer sockets share the connections outside the owner's reserved control/probe/renewal slots.
+      const release = data.peer ? capacity.reservePeerConnection() : capacity.reserve("connections");
+      data.release();
+      data.release = release;
+      data.stage = "authorized";
+      clearTimeout(data.authTimer);
+      send(data, { type: "authorized", protocol: REMOTE_PROTOCOL });
+    }
+  };
+  const execute = async (data: Connection, frame: Record<string, unknown>) => {
+    const id = frame.id;
+    const method = frame.method as string;
+    data.budget.throwIfEnded();
+    if (!validConnection(data)) throw new Error("Messaging enrollment changed.");
+    if (method.startsWith("message/")) {
+      if (data.rpc || data.pending !== 1) throw new Error("Control and native RPC cannot share a connection.");
+      const result = method === "message/reply-route" && !data.peer
+        ? replies.control(frame.params)
+        : await hooks.control(data.peer ?? null, method, frame.params, data.budget);
+      if (!data.closed && validConnection(data)) send(data, { id, result });
+      return;
+    }
+    const params = admitRemoteRpc(method, frame.params);
+    let result: unknown;
+    if (method === "initialize") {
+      if (data.rpc || data.initializing || data.initialized) throw new Error("Messaging connection was already initialized.");
+      data.initializing = true;
+      data.rpc = await LocalMessageRpc.connect(localDaemonEndpoint(codexHome).url, data.budget);
+      data.initializing = false;
+      result = { userAgent: REMOTE_PROTOCOL };
+    } else if (method === "initialized") {
+      if (id !== undefined || !data.rpc || data.initialized) throw new Error("Invalid messaging initialization acknowledgement.");
+      data.initialized = true;
+      return;
+    } else {
+      if (!data.rpc || !data.initialized) throw new Error("Initialize the messaging connection before native RPC.");
+      if (method === "thread/loaded/list") {
+        const page = await data.rpc.loadedPage(params.cursor as string | undefined);
+        const visible = page.data.filter(id => !data.peer || replies.visible(data.peer, id));
+        for (const id of visible) data.loadedIds.add(id);
+        if (data.loadedIds.size > 1000) throw new Error("Loaded session limit exceeded.");
+        result = { ...page, data: visible };
+      }
+      else if (method === "thread/read") {
+        if (!data.loadedIds.has(params.threadId as string)
+          || (data.peer && !replies.visible(data.peer, params.threadId as string))) {
+          throw new Error("Session is outside this peer's reply routes.");
+        }
+        const thread = await data.rpc.readThread(params.threadId as string);
+        if (data.peer && !replies.visible(data.peer, thread.id)) throw new Error("Session permission changed during lookup.");
+        result = { thread: { id: thread.id, name: thread.name, status: { type: thread.status } } };
+      } else {
+        if (data.queue || !data.peer) throw new Error("Only one peer message may be queued per connection.");
+        data.queue = true;
+        const envelope = receiveRemoteEnvelope((params.input as { text: string }[])[0]!.text,
+          params.clientUserMessageId as string, data.peer);
+        if (!data.loadedIds.has(params.threadId as string)) {
+          send(data, { id, error: { code: -32000, message: "Recipient was not discovered loaded on this connection." } });
+          return;
+        }
+        const fresh = await data.rpc.readThread(params.threadId as string);
+        if (fresh.status === "notLoaded") {
+          send(data, { id, error: { code: -32000, message: "Recipient unloaded before queue submission." } });
+          return;
+        }
+        if (!validConnection(data)) throw new Error("Messaging enrollment changed before submission.");
+        data.budget.throwIfEnded();
+        const settleReply = replies.begin(data.peer, envelope.header, params.threadId as string);
+        let submissionId: string | undefined;
+        // An exception or uncertain receipt must spend the one-shot route, not authorize a replay.
+        let submitted = true;
+        let receipt;
+        try {
+          receipt = await data.rpc.queueMessage(params.threadId as string,
+            envelope.text, params.clientUserMessageId as string, value => { submissionId = value; });
+          submitted = receipt.status !== "not_sent";
+        } finally {
+          settleReply(submitted);
+        }
+        if (receipt.status === "unknown") {
+          retire(data);
+          return;
+        }
+        if (receipt.status === "not_sent") {
+          send(data, { id, error: { code: receipt.error?.code === "unsupported_queue" ? -32601 : -32000,
+            message: "Messaging queue request was rejected." } });
+          return;
+        }
+        result = { queuedSubmission: { id: submissionId, input: params.input, clientUserMessageId: params.clientUserMessageId } };
+      }
+    }
+    if (!data.closed && validConnection(data)) {
+      send(data, { id, result });
+    } else {
+      retire(data);
+    }
+  };
+  const server = Bun.serve<Connection>({ hostname: "127.0.0.1", port: initial.port, development: false,
+    maxRequestBodySize: 4096, idleTimeout: 30,
+    fetch(req, runtime) {
+      try {
+        const url = new URL(req.url);
+        if (stopping || signal.aborted || !store.requireEnabled() || url.pathname !== "/message" || url.search
+          || req.method !== "GET" || req.headers.has("origin") || req.headers.has("authorization")) return new Response(null, { status: 403 });
+        const unauthenticated = [...connections].filter(data => data.stage !== "authorized");
+        // Reclaim the oldest idle admission instead of letting four silent clients block all fresh proofs.
+        if (unauthenticated.length >= REMOTE_LIMITS.unauthenticated) retire(unauthenticated[0]!);
+        const release = () => {};
+        const budget = new MessageBudget(30000, signal);
+        const data: Connection = { stage: "hello", budget, release, pending: 0, lastId: 0, queue: false,
+          initialized: false, initializing: false, closed: false, loadedIds: new Set() };
+        connections.add(data);
+        budget.signal.addEventListener("abort", () => retire(data), { once: true });
+        data.authTimer = setTimeout(() => retire(data), REMOTE_LIMITS.authMs);
+        if (runtime.upgrade(req, { data })) return;
+        retire(data);
+        return new Response(null, { status: 400 });
+      } catch { return new Response(null, { status: 503 }); }
+    },
+    websocket: { maxPayloadLength: REMOTE_LIMITS.frameBytes, backpressureLimit: 1,
+      closeOnBackpressureLimit: true,
+      open(ws) { ws.data.ws = ws; },
+      close(ws) { retire(ws.data); },
+      message(ws, message) {
+        const data = ws.data;
+        try {
+          if (stopping || data.closed || typeof message !== "string"
+            || Buffer.byteLength(message) > (data.stage === "authorized" ? REMOTE_LIMITS.frameBytes : 4096)) {
+            throw new Error("Messaging connection is closed or its frame is invalid.");
+          }
+          const raw: unknown = JSON.parse(message);
+          if (data.stage !== "authorized") {
+            authenticate(data, raw);
+            return;
+          }
+          if (!isRecord(raw) || typeof raw.method !== "string" || Object.keys(raw).some(key => !["id", "method", "params"].includes(key))) {
+            throw new Error("Invalid messaging RPC frame.");
+          }
+          if (raw.method !== "initialized") {
+            if (!Number.isSafeInteger(raw.id) || Number(raw.id) <= data.lastId) throw new Error("Messaging RPC IDs must strictly increase.");
+            data.lastId = Number(raw.id);
+          } else if (raw.id !== undefined) throw new Error("The initialized notification must not have a request ID.");
+          if (data.pending >= 4) throw new Error("Messaging RPC concurrency limit exceeded.");
+          const free = capacity.reserve("requests");
+          let freeBytes: () => void;
+          try {
+            freeBytes = capacity.reserve("outputBytes", Buffer.byteLength(message));
+          } catch (error) {
+            free();
+            throw error;
+          }
+          data.pending++;
+          const task = execute(data, raw).catch(() => retire(data)).finally(() => {
+            data.pending--;
+            free();
+            freeBytes();
+            tasks.delete(task);
+          });
+          tasks.add(task);
+        } catch { retire(data); }
+      },
+    }, error() { return new Response(null, { status: 503 }); },
+  });
+  const close = (): Promise<void> => closePromise ??= (async () => {
+    stopping = true;
+    signal.removeEventListener("abort", abort);
+    for (const data of [...connections]) retire(data);
+    await server.stop(true);
+    await Promise.allSettled([...tasks]);
+  })();
+  const abort = () => { void close(); };
+  signal.addEventListener("abort", abort, { once: true });
+  if (signal.aborted) abort();
+  return { port: server.port!, close };
+}

package/src/messaging/remote-contract.ts

@@ -0,0 +1,108 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { isRecord, isThreadId, LocalMessagingError } from "./types";
+
+export const REMOTE_PROTOCOL = "ocx-message-remote/1";
+export const REMOTE_LIMITS = Object.freeze({ peers: 4, connections: 16, requests: 32, helpers: 10,
+  unauthenticated: 4,
+  // Authenticated peer sockets together may never use the slots kept for this node's own
+  // control, outgoing probes and lease renewal.
+  ownerReservedConnections: 4,
+  persistentHelpers: 8, transientHelpers: 2,
+  outputBytes: 2 * 1024 * 1024, frameBytes: 1024 * 1024, storeBytes: 128 * 1024, authMs: 5000,
+  leaseMs: 25000, shutdownMs: 3000 });
+export interface MessageMachine { id: string; name: string }
+export interface RemotePeer {
+  alias: string; machine: MessageMachine; transaction: string; incoming: string; outgoing: string;
+  port: number; ssh: string | null; hostKey: string | null; fingerprint: string | null;
+  allowInbound?: boolean;
+}
+export interface RemoteState {
+  protocol: typeof REMOTE_PROTOCOL; machine: MessageMachine; enabled: boolean; port: number;
+  controlKey: string; generation: string; peers: RemotePeer[];
+}
+
+/** Fail closed with authored diagnostics rather than untrusted transport/configuration output. */
+export function remoteError(code: string, message: string): LocalMessagingError {
+  return new LocalMessagingError(code, message);
+}
+/** Accept an exact bounded object schema, including rejection of unknown fields. */
+export function exactRecord(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (!isRecord(value) || Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) {
+    throw remoteError("invalid_remote_contract", "Messaging peer returned an invalid protocol object.");
+  }
+  return value;
+}
+/** Validate the stable machine identity; names are display metadata, never route authority. */
+export function validMachine(value: unknown): value is MessageMachine {
+  return isRecord(value) && Object.keys(value).length === 2 && isThreadId(value.id)
+    && typeof value.name === "string" && value.name.length > 0 && value.name.length <= 128
+    && !/[\x00-\x1f\x7f-\x9f]/.test(value.name);
+}
+/** Permit exact CLI aliases, not names containing shell syntax or fuzzy selectors. */
+export function validAlias(value: unknown): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(value);
+}
+/** Messaging listeners and both forward directions use unprivileged ports only. */
+export function validPort(value: unknown): value is number {
+  return Number.isInteger(value) && Number(value) >= 1024 && Number(value) <= 65535;
+}
+/** Generate a receiver-issued 256-bit capability; never print it in ordinary CLI output. */
+export function capability(): string { return randomBytes(32).toString("hex"); }
+/** Validate protocol capability/nonces before any keyed proof calculation. */
+export function validCapability(value: unknown): value is string {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+/** Direction-separated proofs bind both identities, enrollment and fresh nonces on one socket. */
+export function peerProof(key: string, direction: "server" | "client", from: string, to: string,
+  transaction: string, clientNonce: string, serverNonce: string): string {
+  return createHmac("sha256", key).update(JSON.stringify([
+    REMOTE_PROTOCOL, direction, from, to, transaction, clientNonce, serverNonce,
+  ])).digest("hex");
+}
+/** Fixed-size comparison refuses malformed proofs rather than comparing secret strings. */
+export function matchesProof(actual: unknown, expected: string): boolean {
+  return validCapability(actual) && timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));
+}
+
+/** One foreground owner's reservations are shared across peers and both tunnel directions. */
+export class RemoteCapacity {
+  private used = { connections: 0, requests: 0, helpers: 0, outputBytes: 0 };
+  private helperSlots = { persistent: 0, transient: 0 };
+  private peerTotal = 0;
+  /** Enrolled peers share the connections outside the owner's reserved control/probe/renewal slots. */
+  reservePeerConnection(): () => void {
+    if (this.peerTotal + 1 > REMOTE_LIMITS.connections - REMOTE_LIMITS.ownerReservedConnections) {
+      throw remoteError("remote_capacity", "The enrolled peers' connection share was reached.");
+    }
+    const free = this.reserve("connections");
+    this.peerTotal++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.peerTotal--;
+      free();
+    };
+  }
+  /** Keep transient inspectors/control commands available alongside all eight tunnel children. */
+  reserveHelper(purpose: "persistent" | "transient"): () => void {
+    const limit = purpose === "persistent" ? REMOTE_LIMITS.persistentHelpers : REMOTE_LIMITS.transientHelpers;
+    if (this.helperSlots[purpose] >= limit) {
+      throw remoteError("remote_capacity", "The messaging owner's aggregate helper purpose limit was reached.");
+    }
+    const free = this.reserve("helpers"); this.helperSlots[purpose]++;
+    let released = false;
+    return () => { if (!released) { released = true; this.helperSlots[purpose]--; free(); } };
+  }
+  /** Reserve before allocating/spawning; overload creates no hidden waiting queue. */
+  reserve(kind: keyof RemoteCapacity["used"], amount = 1): () => void {
+    if (!Number.isSafeInteger(amount) || amount < 1 || this.used[kind] + amount > REMOTE_LIMITS[kind]) {
+      throw remoteError("remote_capacity", "The messaging owner's aggregate resource limit was reached.");
+    }
+    this.used[kind] += amount;
+    let released = false;
+    return () => { if (!released) { released = true; this.used[kind] -= amount; } };
+  }
+  /** Safe counters for tests/status: no identities, capabilities or message bodies. */
+  snapshot() { return { ...this.used }; }
+}

package/src/messaging/remote-enrollment-recovery.ts

@@ -0,0 +1,59 @@
+import { join } from "node:path";
+import { isSshAlias } from "../link/ssh-argv";
+import { exactRecord, remoteError, REMOTE_PROTOCOL, validAlias, validCapability, validMachine, validPort, type MessageMachine } from "./remote-contract";
+import { readRemoteFile, removeRemoteFile, withRemoteLock } from "./remote-files";
+import type { RemoteMessageStore } from "./remote-store";
+import { isThreadId } from "./types";
+
+interface EnrollmentJournal {
+  alias: string; ssh: string; fingerprint: string; generation: string;
+  request: { protocol: typeof REMOTE_PROTOCOL; action: "enroll";
+    params: { machine: MessageMachine; transaction: string; returnCapability: string; port: number } };
+}
+
+/** Interpret only safely read local journal text; storage/lock failures keep their own classification. */
+export function parseEnrollmentJournal(text: string): EnrollmentJournal {
+  try {
+    const saved = exactRecord(JSON.parse(text), ["alias", "ssh", "fingerprint", "generation", "request"]);
+    const request = exactRecord(saved.request, ["protocol", "action", "params"]);
+    const params = exactRecord(request.params, ["machine", "transaction", "returnCapability", "port"]);
+    if (!validAlias(saved.alias) || typeof saved.ssh !== "string" || !isSshAlias(saved.ssh)
+      || typeof saved.fingerprint !== "string" || !/^SHA256:[A-Za-z0-9+/=]{1,64}$/.test(saved.fingerprint)
+      || !isThreadId(saved.generation) || request.protocol !== REMOTE_PROTOCOL || request.action !== "enroll"
+      || !validMachine(params.machine) || !isThreadId(params.transaction) || !validCapability(params.returnCapability)
+      || !validPort(params.port)) throw new Error();
+    // Preserve the parsed record's property order for exact saved-transaction ownership checks.
+    return saved as unknown as EnrollmentJournal;
+  } catch { throw remoteError("invalid_enrollment_journal", "Pending enrollment cannot be safely interpreted; explicit operator recovery is required."); }
+}
+
+/** Validate a recovery journal before exposing metadata or authorizing its exact removal. */
+function readPending(store: RemoteMessageStore) {
+  const text = readRemoteFile(join(store.directory, "enrollment.json"));
+  if (text === null) return null;
+  const saved = parseEnrollmentJournal(text);
+  return { alias: saved.alias, generation: saved.generation,
+    transaction: saved.request.params.transaction, machineId: saved.request.params.machine.id };
+}
+
+/** Read only bounded non-secret recovery metadata; absent storage remains absent. */
+export function pendingRemoteEnrollment(store: RemoteMessageStore) {
+  const pending = readPending(store);
+  return pending ? { alias: pending.alias, transaction: pending.transaction,
+    stale: pending.generation !== store.read()?.generation } : null;
+}
+
+/** Abandon one explicitly selected local transaction, never retrying it or claiming remote cleanup. */
+export function abandonRemoteEnrollment(store: RemoteMessageStore, transaction: string) {
+  if (!isThreadId(transaction)) throw remoteError("invalid_enrollment", "An exact pending transaction UUID is required.");
+  // Recovery remains available while disabled, but never creates a missing store or lock.
+  if (!readPending(store)) throw remoteError("enrollment_pending", "No pending enrollment exists to abandon.");
+  return withRemoteLock(store.directory, () => {
+    const pending = readPending(store);
+    if (!pending || pending.transaction !== transaction) throw remoteError("enrollment_pending", "Pending enrollment changed; inspect it before abandoning the exact transaction.");
+    removeRemoteFile(join(store.directory, "enrollment.json"));
+    return { protocol: REMOTE_PROTOCOL, transaction, locallyAbandoned: true, remote: "unconfirmed",
+      remoteCleanupCommand: `ocx message hosts remove ${pending.machineId} --transaction ${transaction} --json`,
+      message: "Only the local recovery journal was removed. Existing peers are unchanged; the remote node may retain an enrollment requiring explicit cleanup." };
+  });
+}