pwragent 0.0.0 → 1.3.7

package/src/federation.js

@@ -0,0 +1,454 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { readFileSync, lstatSync } from "node:fs";
+import { hostname, arch, platform, release } from "node:os";
+import path from "node:path";
+import {
+  connectFederationClient, FederationGatewayWebSocketServer, FederationRouter,
+  generateFederationIdentityKeyPair, generateFederationNoiseStaticKeyPair,
+  noiseKeyPairFromRawPrivate, decodeFederationInvite, encodeFederationInvite,
+  FEDERATION_PROTOCOL_VERSION, FEDERATION_INVITE_VERSION, FederationRpcEndpoint,
+  FederationReplacementReceiver, pushFederationFile, authenticateMessageOrigin, FederationPtyService, TerminalHistoryStore, FEDERATION_PTY_METHOD_CAPABILITIES, registerFederationPtyHandlers,
+} from "../dist/federation-core.js";
+import { setupHandoffs, HANDOFF_CAPABILITIES } from "./handoffs.js";
+import { atomicJson } from "./store.js";
+import { HeadlessBackend, METHOD_CAPABILITIES } from "./federation-backend.js";
+
+export const HEADLESS_CAPABILITIES = ["remote_window", "thread_navigation", "thread_detail", "turn_control", "event_subscriptions", "gateway_relay", "transport_brotli", "remote_pty", "messaging_route", "messaging_destinations", "messaging_files", "environment_actions", "thread_handoff", "file_push"];
+
+const RECEIVER_PERMISSIONS = Object.freeze({ remoteShells: true, portForwarding: false, filePush: true, filePull: false, filePullOutsideThreadDirectories: false });
+
+const EVENT_CAPABILITIES = new Map([
+  ["navigation", "thread_navigation"], ["star_map", "thread_navigation"],
+  ["directory_set", "thread_navigation"], ["transcript", "thread_detail"],
+  ["pending_requests", "pending_request_control"], ["scheduled_actions", "scheduled_actions"],
+]);
+
+function forwardEndpoint(value) {
+  const url = new URL(value);
+  if (url.username || url.password || url.search || url.hash
+    || (url.protocol !== "wss:" && !(url.protocol === "ws:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) {
+    throw new Error("Gateway must be a loopback ws:// forward or a wss:// endpoint without credentials");
+  }
+  return url.toString();
+}
+
+/** Identity persists independently of compute/tunnel presence. No VM API calls. */
+export class HeadlessFederation {
+  constructor({ directory, runtime, profile, onFailure }) {
+    this.file = path.join(directory, "federation.json");
+    this.runtime = runtime;
+    this.profile = profile;
+    this.onFailure = onFailure;
+    this.connections = new Map();
+    this.endpoints = new Map();
+    this.remotePeers = new Map();
+    this.peerDirectory = new FederationReplacementReceiver();
+    this.ptyRoutes = new Map();
+    this.subscriptions = new Map();
+    this.retryDelay = 1000;
+    this.generation = 0;
+    try {
+      const stat = lstatSync(this.file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid() || (stat.mode & 0o077)) throw new Error("Federation identity file must be private and owned by this user");
+      this.state = JSON.parse(readFileSync(this.file, "utf8"));
+      if (this.state.version !== 1 || !this.state.instanceId || !this.state.identity?.privateKeyPem || !this.state.noise?.privateKeyBase64) throw new Error("Invalid federation identity file");
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+    this.backend = new HeadlessBackend(runtime, (event, eventClass) => this.publish(event, eventClass));
+    runtime.onEvent = (message) => this.backend.event(message);
+    runtime.requestMessaging = (request, loadFile) => this.requestMessaging(request, loadFile);
+    this.backend.authenticateOrigin = (origin, envelope) => this.authenticateOrigin(origin, envelope);
+    this.pty = new FederationPtyService({
+      historyStore: new TerminalHistoryStore(path.join(directory, "terminal-history")),
+      resolveThreadCwd: async ({ backend, threadId }) => {
+        if (backend !== "codex") throw new Error("This outpost serves Codex only");
+        return runtime.projects.resolve(this.backend.owned(threadId).cwd || runtime.workspace);
+      },
+      spawnPty: async ({ cwd, cols, rows }) => {
+        const { spawn } = await import("node-pty");
+        if (!cwd) throw new Error("An owned thread cwd is required");
+        const shell = { file: "/bin/bash", args: ["--noprofile", "--norc"] };
+        const pty = spawn(shell.file, shell.args, { cwd, cols, rows, name: "xterm-256color", env: { ...process.env, TERM: "xterm-256color" } });
+        return { pty, cwd, shell };
+      },
+      sendNotification: (peer, method, params) => this.notify(peer, method, params),
+    });
+  }
+
+  save() {
+    try { atomicJson(this.file, this.state); } catch (error) { this.onFailure(error); throw error; }
+  }
+
+  ensureIdentity(label) {
+    if (label !== undefined && (typeof label !== "string" || !label.trim() || label.length > 200)) throw new Error("Label must be 1–200 characters");
+    if (this.state) return;
+    this.state = { version: 1, instanceId: randomUUID(), label: label || `${hostname()} outpost`,
+      identity: generateFederationIdentityKeyPair(), noise: generateFederationNoiseStaticKeyPair(),
+      hmacKey: randomBytes(32).toString("hex"), peers: {}, invites: [],
+      lifecycle: { kind: "outpost", role: "remote_agent", persistence: "unknown", retainUntil: null, threadStorage: "owner" } };
+    this.save();
+  }
+
+  setupRouter() {
+    this.router = new FederationRouter({ localInstanceId: this.state.instanceId,
+      trustedRelayPeerId: () => this.state.gateway?.gatewayInstanceId, methodCapabilities: { ...METHOD_CAPABILITIES, ...FEDERATION_PTY_METHOD_CAPABILITIES, ...HANDOFF_CAPABILITIES,
+        "outpost.projects.list": "thread_navigation", "outpost.projects.create": "environment_actions",
+        "outpost.projects.add": "environment_actions", "outpost.projects.remove": "environment_actions" },
+      additionalRequiredCapabilities: (envelope) => {
+        const required = envelope.method.startsWith("thread.handoff.") ? ["turn_control", "environment_actions", "file_push"] : [];
+        if (envelope.params?.messageOrigin?.kind === "messaging" || envelope.params?.messageOrigin?.causalMessagingSource) required.push("messaging_route");
+        return required;
+      } });
+    this.handoffs = setupHandoffs(this, path.dirname(this.file));
+    registerFederationPtyHandlers({ router: this.router, service: this.pty });
+    for (const [method, command] of [["list", "project-list"], ["create", "project-create"], ["add", "project-add"], ["remove", "project-remove"]]) {
+      this.router.registerHandler(`outpost.projects.${method}`, (envelope) => this.runtime.handle(command, envelope.params));
+    }
+    for (const method of Object.keys(METHOD_CAPABILITIES)) {
+      this.router.registerHandler(method, (envelope) => this.backend.handle(method, envelope.params, envelope));
+    }
+  }
+
+  async start() {
+    if (!this.state) return;
+    this.stopping = false;
+    if (!this.router) this.setupRouter();
+    if (this.state.listenPort !== undefined) await this.listen(this.state.listenPort);
+    if (this.state.gateway) void this.connect();
+  }
+
+  host() {
+    return { hostname: hostname(), platform: platform(), osVersion: release(), arch: arch(),
+      machineId: this.state.instanceId, outpost: this.state.lifecycle };
+  }
+
+  status() {
+    return { enabled: Boolean(this.state), supportedCapabilities: HEADLESS_CAPABILITIES, messagingService: "consumer-only", instanceId: this.state?.instanceId,
+      label: this.state?.label, lifecycle: this.state?.lifecycle, listener: this.listenerAddress,
+      gateway: this.state?.gateway ? { instanceId: this.state.gateway.gatewayInstanceId,
+        endpoint: this.state.gateway.endpoint, status: this.client ? "connected" : "unreachable", error: this.connectionError } : undefined,
+      peers: [...this.connections.keys()].map((id) => ({ id, status: "connected" })) };
+  }
+
+  async join({ invite, gateway, label }) {
+    if (this.state?.gateway) throw new Error("This outpost already has a gateway; use federation-leave before importing another invite");
+    const decoded = decodeFederationInvite(invite);
+    const endpoint = forwardEndpoint(gateway || decoded.gatewayUrl);
+    this.ensureIdentity(label);
+    this.state.gateway = { ...decoded, endpoint };
+    this.save();
+    if (!this.router) this.setupRouter();
+    await this.connect();
+    return this.status();
+  }
+
+  async invite({ port = 47831, label }) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("Federation port must be between 1 and 65535");
+    this.ensureIdentity(label);
+    if (!this.router) this.setupRouter();
+    if (this.state.listenPort !== undefined && this.state.listenPort !== port) throw new Error("Restart with the existing listener port; it cannot change while serving");
+    await this.listen(port);
+    this.state.listenPort = port;
+    const token = randomBytes(32).toString("base64url");
+    const now = Date.now();
+    const entry = { id: randomUUID(), status: "pending", generatedAt: now, expiresAt: now + 15 * 60_000,
+      gatewayInstanceId: this.state.instanceId, tokenHash: this.hashToken(token) };
+    this.state.invites = this.state.invites.filter((item) => item.status === "pending" && item.expiresAt > now).slice(-15);
+    this.state.invites.push(entry);
+    this.save();
+    return { invite: encodeFederationInvite({ version: FEDERATION_INVITE_VERSION, token,
+      gatewayInstanceId: this.state.instanceId, gatewayPublicKeyPem: this.state.identity.publicKeyPem,
+      gatewayNoisePublicKey: this.state.noise.publicKeyBase64, gatewayUrl: this.listenerAddress.url, expiresAt: entry.expiresAt }),
+    expiresAt: entry.expiresAt, instanceId: this.state.instanceId };
+  }
+
+  hashToken(token) { return createHmac("sha256", this.state.hmacKey).update(token).digest("hex"); }
+
+  store() {
+    return {
+      getPeer: (id) => this.state.peers[id],
+      upsertPeer: ({ peer, clearRevocation }) => {
+        const existing = this.state.peers[peer.id];
+        this.state.peers[peer.id] = existing?.revokedAt && !clearRevocation ? { ...peer, status: "revoked", revokedAt: existing.revokedAt } : peer;
+        this.save();
+      },
+      findMatchingPendingEnrollment: ({ token, now }) => this.state.invites.find((entry) => entry.status === "pending" && entry.expiresAt > now
+        && timingSafeEqual(Buffer.from(entry.tokenHash, "hex"), Buffer.from(this.hashToken(token), "hex"))),
+      markEnrollmentUsed: ({ enrollmentId, peerId, usedAt }) => {
+        const entry = this.state.invites.find((item) => item.id === enrollmentId);
+        if (!entry || entry.status !== "pending") return undefined;
+        Object.assign(entry, { status: "used", peerId, usedAt });
+        this.save();
+        return entry;
+      },
+      appendAudit: (entry) => ({ ...entry, eventId: 0 }),
+    };
+  }
+
+  async listen(port) {
+    if (this.listener) return;
+    this.listener = new FederationGatewayWebSocketServer({ gatewayInstanceId: this.state.instanceId,
+      gatewayPrivateKeyPem: this.state.identity.privateKeyPem, gatewayPublicKeyPem: this.state.identity.publicKeyPem,
+      noiseStatic: noiseKeyPairFromRawPrivate(Buffer.from(this.state.noise.privateKeyBase64, "base64")),
+      host: "127.0.0.1", port, store: this.store(),
+      supportedCapabilities: HEADLESS_CAPABILITIES,
+      onConnection: (connection) => this.register(connection.peerId, connection.capabilities, connection),
+      onDisconnect: (connection) => this.unregister(connection.peerId, connection),
+      onEnvelope: (envelope, connection) => this.receive(envelope, connection.peerId),
+    });
+    try { this.listenerAddress = await this.listener.start(); } catch (error) { this.listener = null; throw error; }
+  }
+
+  async connect() {
+    const gateway = this.state?.gateway;
+    if (this.stopping || !gateway || this.connecting || this.client) return;
+    this.connecting = true;
+    const generation = this.generation;
+    const dial = async (mode) => {
+      let connection;
+      connection = await connectFederationClient({ url: gateway.endpoint, mode,
+      gatewayInstanceId: gateway.gatewayInstanceId, gatewayPublicKeyPem: gateway.gatewayPublicKeyPem,
+      gatewayNoisePublicKey: Buffer.from(gateway.gatewayNoisePublicKey, "base64"),
+      noiseStatic: noiseKeyPairFromRawPrivate(Buffer.from(this.state.noise.privateKeyBase64, "base64")),
+      peerInstanceId: this.state.instanceId, ...this.state.identity, capabilities: HEADLESS_CAPABILITIES,
+      inviteToken: mode === "enroll" ? gateway.token : undefined, label: this.state.label,
+      role: this.listener ? "dual" : "client", profileName: this.profile, receiverPermissions: RECEIVER_PERMISSIONS,
+      notes: "Headless outpost: retained identity; tunnel loss does not stop work or imply deletion.", host: this.host(),
+      deferReceiving: true, connectTimeoutMs: 5000,
+      onEnvelope: (envelope) => this.receive(envelope, gateway.gatewayInstanceId),
+      onClose: (info) => {
+        if (!connection || this.client !== connection) return;
+        this.unregister(gateway.gatewayInstanceId, connection);
+        this.client = null;
+        if (info?.code === 4002 || info?.code === 4001) {
+          this.connectionError = info.code === 4002 ? "revoked_peer" : "identity_in_use";
+          return;
+        }
+        this.schedule();
+      },
+      });
+      return connection;
+    };
+    try {
+      let client;
+      // Enrollment may already have succeeded before its acknowledgment was
+      // persisted. Reconnect first, so a consumed one-time token is not reused.
+      try { client = await dial("reconnect"); } catch (error) {
+        if (this.stopping || generation !== this.generation) throw error;
+        if (error.message !== "unknown_peer" || !gateway.token || gateway.expiresAt <= Date.now()) throw error;
+        client = await dial("enroll");
+      }
+      if (this.stopping || generation !== this.generation) { client.close(); return; }
+      this.client = client;
+      if (gateway.token) { delete gateway.token; this.save(); }
+      this.connectionError = undefined;
+      this.retryDelay = 1000;
+      this.register(gateway.gatewayInstanceId, client.capabilities, client);
+      client.startReceiving();
+    } catch (error) {
+      if (this.stopping || generation !== this.generation) return;
+      this.connectionError = ["revoked_peer", "unknown_peer", "missing_invite"].includes(error.message) ? error.message : "connection_failed";
+      if (this.connectionError === "connection_failed") this.schedule();
+    } finally {
+      this.connecting = false;
+      // A leave/join can replace the pairing while this handshake owns the
+      // dial guard. Its completion must release admission to the new pairing.
+      if (generation !== this.generation && !this.stopping) void this.connect();
+    }
+  }
+
+  schedule() {
+    if (this.stopping || !this.state?.gateway || this.retryTimer) return;
+    this.retryTimer = setTimeout(() => { this.retryTimer = null; void this.connect(); }, this.retryDelay);
+    this.retryDelay = Math.min(30000, this.retryDelay * 2);
+  }
+
+  register(id, capabilities, connection) {
+    this.connections.set(id, connection);
+    this.pty.notifyPeerConnected(id);
+    this.router.registerConnection({ peerId: id, capabilities, sendEnvelope: (envelope) => connection.sendEnvelope(envelope) });
+  }
+
+  unregister(id, connection) {
+    if (this.connections.get(id) !== connection) return;
+    this.connections.delete(id);
+    this.router.unregisterConnection(id);
+    if (id === this.state.gateway?.gatewayInstanceId) { this.remotePeers.clear(); this.peerDirectory.clear(); }
+    this.pty.notifyPeerDisconnected(id);
+    for (const [origin, via] of this.ptyRoutes) {
+      if (via === id) { this.pty.notifyPeerDisconnected(origin); this.ptyRoutes.delete(origin); }
+    }
+    for (const [target, endpoint] of this.endpoints) {
+      if (target === id || id === this.state.gateway?.gatewayInstanceId) endpoint.rejectAll(new Error("Original messaging owner unavailable; send outcome may be uncertain. No automatic replay."));
+    }
+    for (const [subscriber, subscription] of this.subscriptions) {
+      if (subscription.via === id) this.subscriptions.delete(subscriber);
+    }
+  }
+
+  endpoint(target) {
+    if (!this.endpoints.has(target)) this.endpoints.set(target, new FederationRpcEndpoint({
+      localInstanceId: this.state.instanceId, remoteInstanceId: target,
+      sendEnvelope: (envelope) => {
+        const route = this.connections.get(target) || this.connections.get(this.state.gateway?.gatewayInstanceId);
+        if (!route) throw new Error("Original service owner is unavailable");
+        route.sendEnvelope(envelope);
+      },
+    }));
+    return this.endpoints.get(target);
+  }
+
+  notify(target, method, params) {
+    const route = this.connections.get(target) || this.connections.get(this.state?.gateway?.gatewayInstanceId);
+    if (!route || !this.state) return false;
+    try { route.sendEnvelope({ kind: "notification", method, params, id: randomUUID(), protocolVersion: FEDERATION_PROTOCOL_VERSION,
+      sourceInstanceId: this.state.instanceId, targetInstanceId: target, createdAt: Date.now() }); return true; } catch { return false; }
+  }
+
+  authenticateOrigin(origin, envelope) {
+    if (!origin) return undefined;
+    if (Buffer.byteLength(JSON.stringify(origin)) > 16384) throw new Error("Messaging origin exceeds its byte budget");
+    const source = origin.causalMessagingSource;
+    if (source && (typeof source.ownerId !== "string" || !source.ownerId || typeof source.requestId !== "string" || !source.requestId
+      || (origin.kind === "messaging" && source.instanceId && source.instanceId !== envelope.sourceInstanceId))) throw new Error("Messaging source must belong to the authenticated originating peer");
+    return authenticateMessageOrigin({ messageOrigin: { ...origin,
+      ...(source ? { causalMessagingSource: { ...source, instanceId: source.instanceId || envelope.sourceInstanceId } } : {}) },
+    sourceInstanceId: envelope.sourceInstanceId });
+  }
+
+  async requestMessaging(request, loadFile) {
+    const owner = request.context.causalMessagingSource?.instanceId;
+    if (!owner || request.context.causalMessagingAmbiguous) return { ok: false, error: { code: "forbidden", message: "No unambiguous original messaging destination is retained for this turn" } };
+    // Capability negotiation is necessary on the selected route, and the owner
+    // repeats admission/RBAC/route checks. Connection alone grants no service.
+    const route = this.router?.getConnection(owner) || this.router?.getConnection(this.state?.gateway?.gatewayInstanceId);
+    if (!route?.capabilities.includes("messaging_route") || !route.capabilities.includes("messaging_destinations")) return { ok: false, error: { code: "peer_unavailable", message: "The original messaging owner is unavailable or messaging_route is not granted" } };
+    const attachmentTool = request.operation === "send_messaging_file" || ["inspect_messaging_pdfs", "search_messaging_pdf_text", "render_messaging_pdf_pages"].includes(request.operation);
+    if (attachmentTool && !route.capabilities.includes("messaging_files")) return { ok: false, error: { code: "unsupported_operation", message: "The original messaging owner requires a file/PDF tools upgrade" } };
+    if (loadFile && !route.capabilities.includes("file_push")) return { ok: false, error: { code: "forbidden", message: "File transfer is not granted on the messaging route" } };
+    try {
+      const endpoint = this.endpoint(owner);
+      const check = { ...request.context, category: "messaging_context", tool: request.operation, arguments: request.args };
+      const permission = await endpoint.request({ method: "messaging.destination", params: { kind: "authorize", context: request.context, check } });
+      if (!permission.allowed) return { ok: false, error: { code: "forbidden", message: "The original messaging owner denied this operation" } };
+      let file;
+      if (loadFile) {
+        const surface = await endpoint.request({ method: "messaging.destination", params: { kind: "request", request: { ...request, operation: "get_current_messaging_surface", args: {} } } });
+        if (!surface.ok) return surface;
+        const capabilities = surface.data?.location?.outboundAttachments;
+        if (!capabilities) return { ok: false, error: { code: "unsupported_operation", message: "The messaging owner did not supply upload limits" } };
+        const outbound = await loadFile(capabilities);
+        if (!outbound.ok) return { ok: false, error: { code: outbound.code, message: outbound.message } };
+        // Transfer the validated snapshot, never reopen its original path.
+        file = await pushFederationFile(endpoint, outbound.data, "messaging-upload.bin");
+        request = { ...request, args: { ...request.args, path: "", filename: outbound.filename } };
+      }
+      return await endpoint.request({ method: "messaging.destination", params: { kind: "request", request, ...(file ? { file } : {}) } });
+    } catch {
+      return { ok: false, error: { code: "peer_unavailable", message: "The original messaging service is unavailable. A send may have an uncertain outcome; it was not replayed." } };
+    }
+  }
+
+  receive(envelope, peerId) {
+    if (envelope.kind === "notification" && envelope.method === "federation.peerDirectoryPage") {
+      // Only the pinned gateway can replace routing metadata. A sibling's
+      // relayed notification must never authorize a handoff destination.
+      if (peerId !== this.state.gateway?.gatewayInstanceId || envelope.sourceInstanceId !== peerId
+        || envelope.targetInstanceId !== this.state.instanceId || !this.router.getConnection(peerId)?.capabilities.includes("gateway_relay")
+        || !this.router.authenticatesOrigin(envelope, peerId)) return;
+      try {
+        const peers = this.peerDirectory.accept(envelope.params);
+        if (peers) {
+          const replacement = new Map();
+          for (const peer of peers) {
+            if (!peer || typeof peer.id !== "string" || !peer.id || !Array.isArray(peer.capabilities)
+              || peer.capabilities.some((capability) => typeof capability !== "string")) throw new Error("Invalid peer directory entry");
+            if (peer.id !== this.state.instanceId) replacement.set(peer.id, peer);
+          }
+          this.remotePeers = replacement;
+        }
+      } catch { this.remotePeers.clear(); this.peerDirectory.clear(); }
+      return;
+    }
+    if (envelope.kind === "request" && envelope.targetInstanceId === this.state.instanceId && envelope.method.startsWith("pty.")
+      && this.router.authenticatesOrigin(envelope, peerId) && this.router.getConnection(peerId)?.capabilities.includes("remote_pty")) {
+      if (!this.ptyRoutes.has(envelope.sourceInstanceId)) this.pty.notifyPeerConnected(envelope.sourceInstanceId);
+      this.ptyRoutes.set(envelope.sourceInstanceId, peerId);
+    }
+    if (envelope.targetInstanceId === this.state.instanceId && this.router.authenticatesOrigin(envelope, peerId)
+      && this.endpoints.get(envelope.sourceInstanceId)?.receiveEnvelope(envelope)) return;
+    if (envelope.kind === "notification" && envelope.method === "federation.eventSubscription") {
+      if (envelope.sourceInstanceId !== peerId && (peerId !== this.state.gateway?.gatewayInstanceId || !(envelope.hopCount >= 1))) return;
+      const capabilities = this.router.getConnection(peerId)?.capabilities || [];
+      if (!capabilities.includes("event_subscriptions")) return;
+      const subscription = envelope.params;
+      const validSelection = (selection) => selection?.kind === "all" || (selection?.kind === "threads"
+        && Array.isArray(selection.threads) && selection.threads.length <= 100
+        && selection.threads.every((thread) => thread.backend === "codex" && typeof thread.threadId === "string"));
+      if (!Array.isArray(subscription?.eventClasses) || subscription.eventClasses.length > 16
+        || (subscription.threadSelection !== undefined && !validSelection(subscription.threadSelection))
+        || (subscription.eventClassSelections && !Object.values(subscription.eventClassSelections).every(validSelection))) return;
+      const eventClasses = subscription.eventClasses.filter((eventClass) => capabilities.includes(EVENT_CAPABILITIES.get(eventClass)));
+      const authorized = { ...subscription, eventClasses, threadSelection: subscription.threadSelection || { kind: "all" } };
+      if (envelope.targetInstanceId === this.state.instanceId) {
+        if (!eventClasses.length) this.subscriptions.delete(envelope.sourceInstanceId);
+        else if (this.subscriptions.size < 128 || this.subscriptions.has(envelope.sourceInstanceId)) {
+          this.subscriptions.set(envelope.sourceInstanceId, { ...authorized, via: peerId });
+        }
+        return;
+      }
+      // Filter at the first hop, before a trusted relay could amplify the
+      // subscriber's grants. Empty replacements also clear earlier demand.
+      envelope = { ...envelope, params: authorized };
+    }
+    void this.router.routeEnvelope({ envelope, sourcePeerId: peerId }).catch(() => { /* Transport shutdown can race a response. */ });
+  }
+
+  publish(event, eventClass = "transcript") {
+    for (const [subscriber, subscription] of this.subscriptions) {
+      if (!subscription.eventClasses?.includes(eventClass)) continue;
+      const selection = subscription.eventClassSelections ? subscription.eventClassSelections[eventClass] : subscription.threadSelection;
+      const threadId = event.notification.params?.threadId || event.notification.params?.thread?.id;
+      if (selection?.kind !== "all" && !selection?.threads?.some((thread) => thread.backend === "codex" && thread.threadId === threadId)) continue;
+      try { this.connections.get(subscription.via)?.sendEnvelope({ kind: "notification", method: "backend.event",
+        params: event, id: randomUUID(), protocolVersion: FEDERATION_PROTOCOL_VERSION,
+        sourceInstanceId: this.state.instanceId, targetInstanceId: subscriber, createdAt: Date.now() }); } catch { /* Reconnect reestablishes demand; no job is cancelled. */ }
+    }
+  }
+
+  async leave() {
+    this.generation++;
+    clearTimeout(this.retryTimer);
+    this.retryTimer = null;
+    const gatewayId = this.state?.gateway?.gatewayInstanceId;
+    const client = this.client;
+    this.remotePeers.clear();
+    this.peerDirectory.clear();
+    if (this.state) { delete this.state.gateway; this.save(); }
+    if (client) this.unregister(gatewayId, client);
+    this.client = null;
+    client?.close();
+    this.connectionError = undefined;
+    return this.status();
+  }
+
+  revoke(id) {
+    const peer = this.state?.peers[id];
+    if (!peer) throw new Error("Unknown enrolled peer");
+    peer.status = "revoked";
+    peer.revokedAt = Date.now();
+    this.save();
+    this.listener?.closePeer(id);
+    return { revoked: id };
+  }
+
+  async stop() {
+    this.stopping = true;
+    this.generation++;
+    clearTimeout(this.retryTimer);
+    this.client?.close();
+    for (const endpoint of this.endpoints.values()) endpoint.rejectAll(new Error("Outpost is stopping"));
+    await this.pty.disposeAll();
+    await this.handoffs?.stop();
+    await this.listener?.stop();
+  }
+}

package/src/handoffs.js

@@ -0,0 +1,141 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { createGitHandoffService, ThreadInstanceHandoffService, FederationFilePushReceiver,
+  registerFilePushHandlers, pushFederationFile, THREAD_HANDOFF_METHODS, FILE_PUSH_METHOD_CAPABILITIES } from "../dist/federation-core.js";
+import { atomicJson, digest } from "./store.js";
+
+export const HANDOFF_CAPABILITIES = {
+  ...FILE_PUSH_METHOD_CAPABILITIES,
+  ...Object.fromEntries(Object.values(THREAD_HANDOFF_METHODS).map((method) => [method, "thread_handoff"])),
+};
+
+/** Adapts shared transactional intake to this daemon's protocol-owned threads. */
+export function setupHandoffs(federation, directory) {
+  const { runtime, backend, router } = federation;
+  const receipts = new Map();
+  const locked = new Set();
+  const runGitCommand = (cwd, args, options) => runtime.projects.git.git(cwd, args, options);
+  const receiver = new FederationFilePushReceiver({
+    allowed: () => !federation.stopping,
+    formatError: (error, folder, operation) => new Error(`Cannot ${operation} in outpost receiving directory "${folder}" (${error.code || "unknown error"}). Check the outpost disk and permissions.`),
+    directory: () => path.join(directory, "incoming"),
+    onCompleted: (peer, file) => {
+      if (receipts.size >= 128) receipts.delete(receipts.keys().next().value);
+      receipts.set(file.path, { peer, ...file });
+    },
+  });
+  runtime.threadLocked = (id) => locked.has(id);
+  const service = new ThreadInstanceHandoffService({
+    directory: path.join(directory, "handoffs"),
+    localInstanceId: () => federation.state.instanceId,
+    runGitCommand,
+    git: createGitHandoffService(runGitCommand),
+    allocateWorktree: async (repository) => {
+      const base = path.join(repository, ".worktrees");
+      await mkdir(base, { recursive: true });
+      return path.join(runtime.projects.contained(await realpath(base)), `outpost-${randomUUID()}`);
+    },
+    releaseWorktree: async () => {},
+    createHistoryWorkspace: async () => {
+      const cwd = path.join(runtime.projects.resolve(), `intake-${randomUUID()}`);
+      await mkdir(cwd, { mode: 0o700 });
+      return cwd;
+    },
+    assertTarget: (target) => {
+      const required = ["thread_handoff", "turn_control", "environment_actions", "file_push"];
+      const direct = router.getConnection(target);
+      const gateway = router.getConnection(federation.state.gateway?.gatewayInstanceId);
+      const relayed = !direct && gateway?.capabilities.includes("gateway_relay")
+        && required.every((capability) => gateway.capabilities.includes(capability))
+        ? federation.remotePeers.get(target) : undefined;
+      const destination = direct || (relayed?.status === "connected" ? relayed : undefined);
+      if (!destination || !required.every((capability) => destination.capabilities.includes(capability))) {
+        throw new Error("The receiving peer must be connected and grant thread handoff, turn control, environment actions and file push");
+      }
+      if (!direct && relayed.receiverPermissions?.filePush !== true) throw new Error("The receiving peer must allow incoming files");
+    },
+    push: (target, file) => pushFederationFile(federation.endpoint(target), file),
+    remoteImport: (target, request) => federation.endpoint(target).request({ method: THREAD_HANDOFF_METHODS.import, params: request, timeoutMs: 120000 }),
+    prepareTarget: (target, request) => federation.endpoint(target).request({ method: THREAD_HANDOFF_METHODS.prepare, params: request, timeoutMs: 120000 }),
+    receipt: (peer, file) => {
+      const receipt = receipts.get(file.path);
+      return receipt?.peer === peer && receipt.sha256 === file.sha256 && receipt.sizeBytes === file.sizeBytes;
+    },
+    backend: {
+      withThreadHandoff: async (id, work) => {
+        backend.owned(id);
+        if (locked.has(id) || runtime.active || backend.creating || runtime.intakeBusy) throw new Error("Wait for the outpost to become idle before handoff");
+        locked.add(id);
+        try { return await work(); } finally { locked.delete(id); }
+      },
+      exportThreadForHandoff: async (id) => {
+        const owned = backend.owned(id);
+        if (runtime.active) throw new Error("Wait for the source turn to finish");
+        const result = await runtime.codex.request("thread/read", { threadId: id, includeTurns: false });
+        if (result.thread?.id !== id || typeof result.thread.path !== "string") throw new Error("Codex did not provide a persisted thread for protocol export");
+        const file = await runtime.codex.request("fs/readFile", { path: result.thread.path });
+        if (typeof file.dataBase64 !== "string") throw new Error("Codex protocol thread export is unavailable");
+        return { rolloutBase64: file.dataBase64, replay: (await backend.readThread(id)).replay,
+          cwd: runtime.projects.resolve(owned.cwd || runtime.workspace), title: owned.title };
+      },
+      forkThread: async (request) => {
+        if (runtime.active || backend.creating) throw new Error("Outpost is busy");
+        backend.creating = true;
+        try {
+          const cwd = runtime.projects.contained(await realpath(request.directoryPath));
+          if (backend.threads.size >= 10000) throw new Error("Thread retention limit reached");
+          const result = await runtime.codex.request("thread/fork", { threadId: request.sourceThreadId, path: request.sourceThreadPath,
+            cwd, approvalPolicy: "never", sandbox: "read-only" });
+          const id = result.thread?.id;
+          if (typeof id !== "string" || !id || backend.threads.has(id)) throw new Error("Invalid forked thread identity");
+          backend.threads.set(id, { id, cwd, title: "Imported thread", titleSource: "fallback", createdAt: Date.now(), sandbox: "read-only" });
+          runtime.loadedThreads.add(id);
+          backend.persist();
+          backend.invalidate(id);
+          return { threadId: id };
+        } finally { backend.creating = false; }
+      },
+      readThread: async ({ threadId }) => ({ replay: (await backend.readThread(threadId)).replay }),
+      archiveThread: async ({ threadId }) => {
+        backend.owned(threadId);
+        await runtime.codex.request("thread/archive", { threadId });
+        backend.owned(threadId).archived = true;
+        backend.persist();
+        backend.invalidate(threadId);
+      },
+      renameThread: (request) => backend.handle("backend.renameThread", request),
+    },
+  });
+  registerFilePushHandlers(router, receiver);
+  router.registerHandler(THREAD_HANDOFF_METHODS.prepare, (envelope) => {
+    if (envelope.params?.repository) runtime.projects.resolve(envelope.params.repository);
+    return service.prepare(envelope.params);
+  });
+  router.registerHandler(THREAD_HANDOFF_METHODS.send, (envelope) => service.send(envelope.params));
+  // A lost acknowledgement or cold restart must never repeat a fork whose
+  // outcome is uncertain. Operators reconcile it using the destination list.
+  router.registerHandler(THREAD_HANDOFF_METHODS.import, async (envelope) => {
+    const request = envelope.params;
+    if (request?.targetRepositoryPath) runtime.projects.resolve(request.targetRepositoryPath);
+    const file = path.join(directory, `intake-${digest([envelope.sourceInstanceId, request?.handoffId])}.json`);
+    const fingerprint = digest(request);
+    try {
+      const prior = JSON.parse(await readFile(file, "utf8"));
+      if (prior.fingerprint !== fingerprint) throw new Error("Intake identity was reused with different input");
+      if (prior.result) return prior.result;
+      throw new Error("Intake outcome is uncertain; inspect destination threads before starting a new handoff");
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (runtime.active || backend.creating || runtime.intakeBusy) throw new Error("Outpost is busy; no intake was started");
+    runtime.intakeBusy = true;
+    try {
+      atomicJson(file, { fingerprint, status: "pending" });
+      const result = await service.receive(envelope.sourceInstanceId, request);
+      await runtime.projects.add({ path: backend.owned(result.threadId).cwd });
+      atomicJson(file, { fingerprint, status: "completed", result });
+      receipts.delete(request.file.path);
+      return result;
+    } finally { runtime.intakeBusy = false; }
+  });
+  return { stop: () => receiver.dispose() };
+}