@opengeni/runtime 0.2.0

package/src/sandbox/select.ts

@@ -0,0 +1,371 @@
+// Backend selection + capability negotiation/degradation (module 03 §0, §5).
+//
+// negotiateCapabilities() turns a static CapabilityDescriptor + runtime context
+// (the selected OS, the lease liveness/epoch, and the deployment's desktop
+// policy) into a coherent SessionCapabilities document. The load-bearing rule
+// (master-spine Part D): a capability cell is ALWAYS present — when unavailable
+// it is `available:false` + a typed `reason`, NEVER absent. Degradation is a
+// value, not a silent drop.
+
+import {
+  CAPABILITY_DESCRIPTORS,
+  type CapabilityDescriptor,
+  type CapabilityUnavailableReason,
+  type SandboxBackend,
+  type SandboxOs,
+  type SessionCapabilities,
+} from "@opengeni/contracts";
+
+export interface NegotiationContext {
+  sessionId: string;
+  backend: SandboxBackend;
+  os: SandboxOs;
+  /** Current lease liveness; cold means nothing is provisioned yet. */
+  liveness: "cold" | "warming" | "warm" | "draining";
+  /** The lease epoch echoed on viewer heartbeats (the split-brain fence). */
+  leaseEpoch: number;
+  /** The deployment desktop toggle (settings.sandboxDesktopEnabled). */
+  desktopEnabled: boolean;
+  /**
+   * The HUMAN take-control toggle (settings.sandboxDesktopInteractive). When true
+   * (default) and the desktop cell is available, the negotiated DesktopStream.mode
+   * is "interactive" — the noVNC viewer can drive mouse+keyboard into :0 (the box's
+   * x11vnc runs without -viewonly). When false the cell reports mode "read-only"
+   * and the client disables the "Take control" affordance (a genuinely read-only
+   * deployment). Independent of `computerUseReadOnly`, which gates the AGENT
+   * driver, not the human viewer plane. Defaults to true so a caller that never
+   * threads it (e.g. headless tests) still gets the interactive plane when the
+   * desktop is available.
+   */
+  desktopInteractive?: boolean;
+  /** The deployment computer-use toggle (settings.computerUseEnabled). The agent
+   *  drives :0 via xdotool/scrot; availability tracks desktop. Defaults to true. */
+  computerUseEnabled?: boolean;
+  /** Whether the agent computer-use driver is gated to no-op input
+   *  (settings.computerUseReadOnly). v1 default false (the agent clicks/types). */
+  computerUseReadOnly?: boolean;
+  /**
+   * Whether a scoped-stream-token secret is resolvable (I8/OD-8). When desktop
+   * is enabled but this is false (no streamTokenSecret AND no delegationSecret),
+   * the desktop plane GRACEFULLY DEGRADES to transport:null — the deployment
+   * boots, but the pixel plane cannot mint scoped tokens. Defaults to true so a
+   * caller that never threads it (e.g. headless tests) is unaffected.
+   */
+  streamTokenSecretAvailable?: boolean;
+  /** Whether the calling principal has acknowledged the un-redacted desktop
+   *  pixels (and, for a shared box, the shared-exposure disclosure). When the
+   *  box is shared this must be the SHARED acknowledgment; a bare un-redacted ack
+   *  does not satisfy a shared box. */
+  desktopAcknowledged?: boolean;
+  /** True when the box's group has >1 session: watching this desktop also shows
+   *  the sibling sessions' agents on the one :0 framebuffer (addendum E.1). */
+  shared?: boolean;
+  /** The OTHER sessions whose agents may appear on the shared desktop — IDS
+   *  ONLY, never their conversation/metadata (stress g). Empty for a solo box. */
+  sharedSessionIds?: string[];
+  /**
+   * The minted pixel-plane endpoint (P4.2): the direct-to-provider WS URL + the
+   * scoped stream token + its expiry + the framebuffer geometry. Threaded by the
+   * API-direct handshake AFTER it has resumed the box, ensured the display stack,
+   * and resolved the provider tunnel. When ABSENT (the negotiation-only read, a
+   * cold lease, or a degraded desktop) the DesktopStream cell reports url/token/
+   * expiresAt as null — the capability is advertised, the live address is not yet
+   * minted (the caller POSTs to /viewers to mint it). Presence does NOT override
+   * the gates: a degraded/cold/unacked desktop still reports transport:null and
+   * the minted endpoint is dropped.
+   */
+  desktopStream?: {
+    url: string;
+    token: string;
+    expiresAt: string;
+    resolution: [number, number];
+  };
+  /** The deployment terminal toggle (settings.sandboxTerminalEnabled). The REAL
+   *  PTY (ttyd pty-ws) is gated on this + a real-PTY backend; when off the
+   *  Terminal cell still advertises the read-only sse-events firehose. Defaults to
+   *  true so a caller that never threads it is unaffected. */
+  terminalEnabled?: boolean;
+  /**
+   * The minted terminal-plane endpoint (P5.t): the direct-to-provider ttyd
+   * PTY-over-websocket URL + the scoped stream token + its expiry. Threaded by the
+   * API-direct handshake AFTER it has resumed the box, ensured the terminal
+   * server, and resolved the provider tunnel (mintTerminalStream) — SYMMETRIC with
+   * `desktopStream`. When ABSENT (the negotiation-only read, a cold lease, or a
+   * degraded terminal) the Terminal cell reports url/token/expiresAt as null and
+   * falls back to transport "sse-events" (the read-only firehose) — the caller
+   * POSTs to /viewers to mint the live pty-ws address.
+   */
+  terminalStream?: {
+    url: string;
+    token: string;
+    expiresAt: string;
+  };
+  /** Override the negotiation clock (tests). */
+  now?: Date;
+}
+
+/**
+ * Resolve the descriptor for a backend. Throws on an unknown backend rather than
+ * returning a half-formed default (the registry is the single source of truth).
+ */
+export function selectBackend(backend: SandboxBackend): CapabilityDescriptor {
+  const descriptor = CAPABILITY_DESCRIPTORS[backend];
+  if (!descriptor) {
+    throw new Error(`Unknown sandbox backend "${backend}"`);
+  }
+  return descriptor;
+}
+
+/** True iff the descriptor lists the requested OS as supported. */
+export function backendSupportsOs(descriptor: CapabilityDescriptor, os: SandboxOs): boolean {
+  return descriptor.os.supported.includes(os);
+}
+
+/**
+ * True iff the backend can serve the Channel-B desktop pixel plane at all — i.e.
+ * its static descriptor advertises DesktopStream as available. The gate the
+ * worker / API use before launching the display stack (so a headless-only
+ * backend like cloudflare/vercel/none never tries). This is the STATIC
+ * feasibility only; the runtime `sandboxDesktopEnabled` policy toggle and the
+ * stream-token-secret gate are layered on by the caller / negotiateCapabilities.
+ *
+ * Accepts EITHER the SandboxBackend enum value (e.g. "local") OR the SDK
+ * client backendId (e.g. "unix_local") — they diverge for the local backend —
+ * so a caller holding only `established.backendId` resolves correctly.
+ */
+export function desktopCapableBackend(backend: SandboxBackend | string): boolean {
+  const direct = CAPABILITY_DESCRIPTORS[backend as SandboxBackend];
+  if (direct) {
+    return direct.capabilities.DesktopStream.available === true;
+  }
+  // Fall back to a backendId lookup (the SDK client id, which differs from the
+  // enum key for `local`/`unix_local`).
+  for (const descriptor of Object.values(CAPABILITY_DESCRIPTORS)) {
+    if (descriptor.backendId === backend) {
+      return descriptor.capabilities.DesktopStream.available === true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Negotiate a coherent SessionCapabilities document for (backend, os). Every
+ * capability is reported with availability + a reason-when-unavailable; nothing
+ * is ever absent. The reason precedence is: os_unsupported (the OS axis can't be
+ * served at all) > the per-capability static feasibility > policy/liveness gates.
+ */
+export function negotiateCapabilities(ctx: NegotiationContext): SessionCapabilities {
+  const descriptor = selectBackend(ctx.backend);
+  const osSupported = backendSupportsOs(descriptor, ctx.os);
+  const negotiatedAt = (ctx.now ?? new Date()).toISOString();
+
+  // The dominant degrade: an unsupported OS knocks out every capability with a
+  // single coherent reason.
+  const osReason: CapabilityUnavailableReason | null = osSupported ? null : "os_unsupported";
+
+  const fileSystem = (() => {
+    if (osReason) {
+      return { available: false, readOnly: true, root: descriptor.workspaceRoot, pathSep: "/" as const, treeMode: "lazy" as const, reason: osReason };
+    }
+    const cap = descriptor.capabilities.FileSystem;
+    return {
+      available: cap.available,
+      readOnly: cap.readOnly,
+      root: descriptor.workspaceRoot,
+      pathSep: "/" as const,
+      treeMode: "lazy" as const,
+      reason: cap.available ? null : ("backend_unsupported" as const),
+    };
+  })();
+
+  const terminal = (() => {
+    const cap = descriptor.capabilities.Terminal;
+    if (osReason) {
+      return { transport: null, ptyCapable: false, shell: "/bin/bash", url: null, token: null, expiresAt: null, reason: osReason };
+    }
+    if (!cap.available) {
+      return { transport: null, ptyCapable: false, shell: "/bin/bash", url: null, token: null, expiresAt: null, reason: "backend_unsupported" as const };
+    }
+    // The REAL PTY (ttyd pty-ws) rides the SAME tunnel as the desktop, so it is
+    // gated identically: a real-PTY backend (cap.pty), the terminal policy toggle
+    // ON, and a live box. Until those hold the cell advertises the read-only
+    // sse-events firehose (Channel-A command.output still works) with a typed
+    // reason — degradation is a value, never an absent capability.
+    //   - terminal off         -> sse-events + disabled_by_policy.
+    //   - cold lease + NO mint  -> sse-events + lease_cold (no live pty-ws address;
+    //                             the caller mints it via mintTerminalStream at
+    //                             viewer attach).
+    //   - not a real-PTY backend-> sse-events (no reason; the firehose IS the cap).
+    // A PRESENT minted pty-ws url (ctx.terminalStream) is ITSELF proof of liveness:
+    // the box (Modal-warm OR selfhosted-online) actually served the ttyd port, so a
+    // cold MODAL-GROUP lease liveness must NOT degrade it. lease_cold only fires
+    // when nothing was minted. A selfhosted-active session has no warm Modal lease
+    // (liveness "cold") yet mints a valid RELAY pty-ws cell — honour it.
+    const ptyCapable = cap.pty;
+    let transport: "pty-ws" | "sse-events" = ptyCapable ? "pty-ws" : "sse-events";
+    let reason: CapabilityUnavailableReason | null = null;
+    if (ptyCapable && ctx.terminalEnabled === false) {
+      transport = "sse-events";
+      reason = "disabled_by_policy";
+    } else if (ptyCapable && ctx.liveness === "cold" && !ctx.terminalStream) {
+      transport = "sse-events";
+      reason = "lease_cold";
+    }
+    // The minted pty-ws endpoint is folded in ONLY when the terminal is actually
+    // serving pty-ws (the gates passed). When absent the cell advertises the
+    // capability with a null live address — the caller mints it via POST /viewers.
+    const minted = transport === "pty-ws" ? ctx.terminalStream : undefined;
+    return {
+      transport,
+      ptyCapable,
+      shell: "/bin/bash",
+      url: minted?.url ?? null,
+      token: minted?.token ?? null,
+      expiresAt: minted?.expiresAt ?? null,
+      reason,
+    };
+  })();
+
+  const git = (() => {
+    const cap = descriptor.capabilities.Git;
+    if (osReason) {
+      return { available: false, repos: [], reason: osReason };
+    }
+    return { available: cap.available, repos: [], reason: cap.available ? null : ("backend_unsupported" as const) };
+  })();
+
+  const desktop = (() => {
+    const cap = descriptor.capabilities.DesktopStream;
+    // Reason precedence: OS > backend-tier feasibility > policy disable >
+    // stream-token-secret > cold lease WITHOUT a mint.
+    let reason: CapabilityUnavailableReason | null = null;
+    let available = cap.available;
+    if (osReason) {
+      available = false;
+      reason = osReason;
+    } else if (!cap.available) {
+      available = false;
+      // Headless tiers expose the typed tier_headless reason; dev/none are
+      // backend_unsupported for desktop.
+      reason = descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported";
+    } else if (!ctx.desktopEnabled) {
+      available = false;
+      reason = "disabled_by_policy";
+    } else if (ctx.streamTokenSecretAvailable === false) {
+      // Graceful degrade (I8/OD-8): desktop is enabled + backend-capable, but no
+      // stream-token secret is resolvable, so no scoped token can be minted. The
+      // deployment boots; the desktop cell reports transport:null + a typed
+      // reason rather than crashing the API.
+      available = false;
+      reason = "disabled_by_policy";
+    } else if (ctx.liveness === "cold" && !ctx.desktopStream) {
+      // A PRESENT minted pixel url (ctx.desktopStream) is ITSELF proof of liveness:
+      // the box (Modal-warm OR selfhosted-online) actually served the noVNC port,
+      // so a cold MODAL-GROUP lease liveness must NOT degrade it. lease_cold only
+      // fires when nothing was minted. A selfhosted-active session has no warm
+      // Modal lease (liveness "cold") yet mints a valid RELAY framebuffer cell —
+      // honour it (the un-redacted-pixel ack gate below still applies).
+      available = false;
+      reason = "lease_cold";
+    }
+    const shared = available ? Boolean(ctx.shared) : false;
+    // The minted pixel endpoint is handed out ONLY when the desktop is actually
+    // available (the gates passed) AND acknowledged: an unacked/cold/degraded
+    // desktop never leaks a live URL (the un-redacted-pixel consent gate). When
+    // absent the cell advertises the capability with a null live address — the
+    // caller mints it via POST /viewers.
+    const acknowledged = available ? Boolean(ctx.desktopAcknowledged) : false;
+    const minted = available && acknowledged ? ctx.desktopStream : undefined;
+    // Human take-control: the cell is "interactive" when the desktop is actually
+    // available AND the deployment's take-control policy is on (default true). The
+    // box's x11vnc runs without -viewonly, so a viewer driving input reaches :0;
+    // this mode bit is the CLIENT gate (the "Take control" affordance). A
+    // deployment that wants a genuinely read-only desktop sets
+    // sandboxDesktopInteractive=false → mode "read-only" and the client disables
+    // take-control. An unavailable cell is always "read-only" (nothing to drive).
+    // Selfhosted desktop is the RELAY framebuffer: PNG-per-frame protobuf datagrams
+    // spliced over the relay, rendered by the "frames" canvas client — NOT noVNC/RFB
+    // (that x11vnc path exists only for Modal boxes). It is VIEW-ONLY in v1 (the
+    // frame client does not forward input yet), so its mode is always read-only
+    // regardless of the take-control policy.
+    const selfhostedFrames = ctx.backend === "selfhosted";
+    const interactive = available && !selfhostedFrames && ctx.desktopInteractive !== false;
+    const mode = interactive ? ("interactive" as const) : ("read-only" as const);
+    return {
+      transport: available ? (selfhostedFrames ? ("relay-frames" as const) : cap.transport) : null,
+      client: available ? (selfhostedFrames ? ("frames" as const) : ("novnc" as const)) : null,
+      mode,
+      url: minted?.url ?? null,
+      token: minted?.token ?? null,
+      expiresAt: minted?.expiresAt ?? null,
+      resolution: minted?.resolution ?? ([1024, 768] as [number, number]),
+      // Desktop pixels are ALWAYS un-redacted when present (the literal
+      // framebuffer); the acknowledgment gate rests on this.
+      unredacted: true,
+      requiresAcknowledgment: available,
+      acknowledged: available ? Boolean(ctx.desktopAcknowledged) : false,
+      // Shared-exposure disclosure (addendum E.1): `shared` when the group has
+      // >1 session; `sharedSessionIds` is the OTHER sessions' ids ONLY (never
+      // their conversation/metadata). Empty/false for a solo box or when the
+      // desktop cell is unavailable.
+      shared,
+      sharedSessionIds: shared ? (ctx.sharedSessionIds ?? []) : [],
+      reason,
+    };
+  })();
+
+  const recording = (() => {
+    const cap = descriptor.capabilities.Recording;
+    if (osReason) {
+      return { available: false, modes: [] as ("manual" | "on-turn" | "on-verify")[], codecs: [] as ("h264-mp4" | "vp9-webm")[], reason: osReason };
+    }
+    if (!cap.available) {
+      return { available: false, modes: [] as ("manual" | "on-turn" | "on-verify")[], codecs: [] as ("h264-mp4" | "vp9-webm")[], reason: descriptor.tier === "headless" ? ("tier_headless" as const) : ("backend_unsupported" as const) };
+    }
+    // Recording feasibility tracks desktop; policy-gate it the same way.
+    if (!ctx.desktopEnabled) {
+      return { available: false, modes: [] as ("manual" | "on-turn" | "on-verify")[], codecs: [] as ("h264-mp4" | "vp9-webm")[], reason: "disabled_by_policy" as const };
+    }
+    return {
+      available: true,
+      modes: ["manual", "on-turn", "on-verify"] as ("manual" | "on-turn" | "on-verify")[],
+      codecs: ["h264-mp4", "vp9-webm"] as ("h264-mp4" | "vp9-webm")[],
+      reason: null,
+    };
+  })();
+
+  const computerUse = (() => {
+    // The agent computer-use driver requires the same desktop image (X stack) as
+    // the pixel plane: it drives :0 with xdotool/scrot. Availability == desktop-
+    // capable backend && desktopEnabled && computerUseEnabled. Degradation is a
+    // value, never silent (an unavailable cell carries a reason).
+    const desktopCapable = descriptor.capabilities.DesktopStream.available;
+    const readOnly = ctx.computerUseReadOnly ?? false;
+    if (osReason) {
+      return { available: false, readOnly, reason: osReason };
+    }
+    if (!desktopCapable) {
+      return { available: false, readOnly, reason: descriptor.tier === "headless" ? ("tier_headless" as const) : ("backend_unsupported" as const) };
+    }
+    if (!ctx.desktopEnabled || ctx.computerUseEnabled === false) {
+      return { available: false, readOnly, reason: "disabled_by_policy" as const };
+    }
+    return { available: true, readOnly, reason: null };
+  })();
+
+  return {
+    sessionId: ctx.sessionId,
+    backend: ctx.backend,
+    os: ctx.os,
+    liveness: ctx.liveness,
+    leaseEpoch: ctx.leaseEpoch,
+    viewerHeartbeatIntervalMs: 30_000,
+    FileSystem: fileSystem,
+    Terminal: terminal,
+    Git: git,
+    DesktopStream: desktop,
+    Recording: recording,
+    ComputerUse: computerUse,
+    negotiatedAt,
+  };
+}

package/src/sandbox/selfhosted/capabilities.ts

@@ -0,0 +1,255 @@
+// Selfhosted capability negotiation (M3, dossier §10.2 item 4).
+//
+// `negotiateSelfhostedCapabilities` resolves the selfhosted-specific cells from
+//   (a) the M2 enrollment row (consent / display / status / lastSeenAt), and
+//   (b) a LIVENESS PROBE (a `ControlRpc` Ping, mockable) — "is there a responder
+//       on the subject right now?"
+// into the right `SessionCapabilities` cells with the selfhosted reasons:
+//   - online              → responder + consented: cells available.
+//   - offline             → no enrollment / revoked / no responder: agent_offline.
+//   - reconnecting        → a transient blip (a recent lastSeenAt but the probe
+//                           missed): agent_reconnecting.
+//   - consent_required    → enrolled but whole-machine / screen-control not acked:
+//                           consent_required on the desktop/computer-use cells.
+//   - display_unavailable → online but the machine has no display (headless, no
+//                           Xvfb): the desktop/computer-use cells degrade with
+//                           display_unavailable.
+//
+// It REUSES `negotiateCapabilities` for the descriptor-shaped cells (so the
+// "every cell present, degradation is a value" rule and the FS/Terminal/Git
+// surface stay identical to Modal), then overlays the selfhosted liveness/consent
+// /display reasons. The base function stays pure + synchronous; this is the
+// selfhosted-aware entrypoint the API/worker call.
+
+import type {
+  CapabilityUnavailableReason,
+  SandboxOs,
+  SessionCapabilities,
+} from "@opengeni/contracts";
+import { negotiateCapabilities, type NegotiationContext } from "../select";
+import type { SelfhostedSession } from "./session";
+
+/**
+ * The structural slice of the M2 `@opengeni/db` `EnrollmentRecord` the selfhosted
+ * negotiation reads. Defined STRUCTURALLY (not imported from `@opengeni/db`) so
+ * the agent-loop-free sandbox leaf does not couple to the DB package's graph —
+ * the API/worker pass an `EnrollmentRecord`, which satisfies this shape. The
+ * fields: `status` (active gates reachability), `exposure` +
+ * `allowScreenControl` (whole-machine + screen-control consent),`hasDisplay`
+ * (the display plane), `lastSeenAt` (the reconnecting-window disambiguator).
+ */
+export interface SelfhostedEnrollment {
+  status: string;
+  exposure: string;
+  allowScreenControl: boolean;
+  hasDisplay: boolean;
+  lastSeenAt: string | null;
+}
+
+/** The derived liveness state of a selfhosted machine (the online/offline/
+ *  reconnecting/consent/display matrix). */
+export interface SelfhostedLivenessState {
+  /** The dominant machine state. */
+  state: "online" | "reconnecting" | "offline";
+  /** Whole-machine + screen-control consent acknowledged (gates desktop input). */
+  consented: boolean;
+  /** A display (real or Xvfb) is present (gates the desktop pixel plane). */
+  hasDisplay: boolean;
+}
+
+/**
+ * The window after `lastSeenAt` within which a missed liveness probe is read as a
+ * transient BLIP (`reconnecting`) rather than a hard `offline`. Mirrors the
+ * resiliency model (§10.6: reconnecting after 1 missed window, offline after
+ * ~30s). A probe miss with a lastSeenAt inside this window → reconnecting.
+ */
+export const SELFHOSTED_RECONNECT_WINDOW_MS = 30_000;
+
+/**
+ * Derive the selfhosted liveness state from the enrollment row + a liveness probe
+ * outcome. The probe is the authoritative "is the agent answering NOW" signal;
+ * `lastSeenAt` disambiguates a probe-miss into reconnecting (recent) vs offline
+ * (stale / never seen).
+ *
+ *   - no enrollment / revoked         → offline (the machine isn't enrolled).
+ *   - probe responded                 → online.
+ *   - probe missed, lastSeenAt recent → reconnecting (a transient blip).
+ *   - probe missed, lastSeenAt stale  → offline.
+ */
+export function selfhostedLiveness(input: {
+  enrollment: SelfhostedEnrollment | null;
+  /** The ControlRpc Ping outcome: true iff a responder answered. */
+  probeResponded: boolean;
+  /** Override the clock (tests). */
+  now?: Date;
+}): SelfhostedLivenessState {
+  const { enrollment } = input;
+  if (!enrollment || enrollment.status !== "active") {
+    return { state: "offline", consented: false, hasDisplay: false };
+  }
+  const consented = enrollment.exposure === "whole-machine" && enrollment.allowScreenControl;
+  const hasDisplay = enrollment.hasDisplay;
+  if (input.probeResponded) {
+    return { state: "online", consented, hasDisplay };
+  }
+  // Probe missed → reconnecting if we saw it recently, else offline.
+  const now = (input.now ?? new Date()).getTime();
+  const lastSeen = enrollment.lastSeenAt ? new Date(enrollment.lastSeenAt).getTime() : null;
+  if (lastSeen !== null && now - lastSeen <= SELFHOSTED_RECONNECT_WINDOW_MS) {
+    return { state: "reconnecting", consented, hasDisplay };
+  }
+  return { state: "offline", consented, hasDisplay };
+}
+
+export interface SelfhostedNegotiationInput {
+  sessionId: string;
+  os?: SandboxOs;
+  leaseEpoch: number;
+  /** The M2 enrollment row for the machine (null → never enrolled → offline). */
+  enrollment: SelfhostedEnrollment | null;
+  /** A live liveness probe — typically `session.ping()`. When a session is
+   *  provided this is called; otherwise pass `probeResponded` explicitly. */
+  session?: Pick<SelfhostedSession, "ping">;
+  /** Explicit probe outcome (when no session is given, e.g. a pure read). */
+  probeResponded?: boolean;
+  /** The deployment desktop/terminal/computer-use policy toggles (threaded
+   *  through to the base negotiation). */
+  desktopEnabled?: boolean;
+  terminalEnabled?: boolean;
+  computerUseEnabled?: boolean;
+  /** Whether the calling principal acknowledged the un-redacted desktop. */
+  desktopAcknowledged?: boolean;
+  shared?: boolean;
+  sharedSessionIds?: string[];
+  /** Override the clock (tests). */
+  now?: Date;
+}
+
+/**
+ * Negotiate the full `SessionCapabilities` document for a selfhosted machine,
+ * with the online/offline/reconnecting/consent_required/display_unavailable cells
+ * correctly decided. Async because it issues the liveness probe.
+ */
+export async function negotiateSelfhostedCapabilities(input: SelfhostedNegotiationInput): Promise<SessionCapabilities> {
+  const probeResponded = input.probeResponded ?? (input.session ? await input.session.ping() : false);
+  const liveness = selfhostedLiveness({
+    enrollment: input.enrollment,
+    probeResponded,
+    ...(input.now ? { now: input.now } : {}),
+  });
+
+  // The base context: map the machine state onto the lease `liveness` axis so the
+  // descriptor-shaped cells (FS/Terminal/Git/Desktop) negotiate as on a warm box
+  // when online, and a cold box when not reachable (no live tunnel). The
+  // selfhosted overlay below then stamps the selfhosted-specific reasons.
+  const baseLiveness: NegotiationContext["liveness"] = liveness.state === "online" ? "warm" : "cold";
+  const base: NegotiationContext = {
+    sessionId: input.sessionId,
+    backend: "selfhosted",
+    os: input.os ?? "linux",
+    liveness: baseLiveness,
+    leaseEpoch: input.leaseEpoch,
+    desktopEnabled: input.desktopEnabled ?? true,
+    terminalEnabled: input.terminalEnabled ?? true,
+    computerUseEnabled: input.computerUseEnabled ?? true,
+    ...(input.desktopAcknowledged !== undefined ? { desktopAcknowledged: input.desktopAcknowledged } : {}),
+    ...(input.shared !== undefined ? { shared: input.shared } : {}),
+    ...(input.sharedSessionIds !== undefined ? { sharedSessionIds: input.sharedSessionIds } : {}),
+    ...(input.now ? { now: input.now } : {}),
+  };
+  const caps = negotiateCapabilities(base);
+
+  // ── Overlay the selfhosted liveness/consent/display reasons ────────────────
+
+  // When the machine is not online, the Channel-A surface (FS/Terminal/Git) and
+  // the desktop plane cannot be reached — stamp the machine-liveness reason. This
+  // is the dominant degrade (like os_unsupported): an offline/reconnecting agent
+  // knocks out every reachable capability with the single coherent reason.
+  if (liveness.state !== "online") {
+    const reason: CapabilityUnavailableReason = liveness.state === "offline" ? "agent_offline" : "agent_reconnecting";
+    return {
+      ...caps,
+      FileSystem: { ...caps.FileSystem, available: false, readOnly: true, reason },
+      Terminal: { ...caps.Terminal, transport: null, url: null, token: null, expiresAt: null, reason },
+      Git: { ...caps.Git, available: false, reason },
+      DesktopStream: {
+        ...caps.DesktopStream,
+        transport: null,
+        client: null,
+        mode: "read-only",
+        url: null,
+        token: null,
+        expiresAt: null,
+        requiresAcknowledgment: false,
+        acknowledged: false,
+        shared: false,
+        sharedSessionIds: [],
+        reason,
+      },
+      Recording: { ...caps.Recording, available: false, modes: [], codecs: [], reason },
+      ComputerUse: { ...caps.ComputerUse, available: false, reason },
+    };
+  }
+
+  // Online: FS/Terminal/Git stay as the base negotiated them (the machine is
+  // reachable). The desktop plane splits VIEW from CONTROL:
+  //  - VIEW (a read-only DesktopStream, Recording) requires a DISPLAY only. The
+  //    agent already holds whole-machine shell exec (it can `screencapture` the
+  //    screen itself), so passive viewing is within the exposure the user already
+  //    consented to; a missing display (headless, no Xvfb / no macOS Screen
+  //    Recording grant) is the only blocker.
+  //  - CONTROL — driving input (ComputerUse) or an INTERACTIVE stream —
+  //    additionally requires the explicit allowScreenControl consent (`consented`).
+  // Precedence: a headless machine blocks everything (display_unavailable); a
+  // displayed-but-unconsented machine can be VIEWED (read-only) + RECORDED but not
+  // CONTROLLED (consent_required). (If the base already degraded a cell for a
+  // policy reason — desktop disabled / no stream-token secret — that base reason
+  // wins; we only stamp a selfhosted reason on a cell the base left AVAILABLE.)
+  if (!liveness.hasDisplay) {
+    const reason: CapabilityUnavailableReason = "display_unavailable";
+    return {
+      ...caps,
+      DesktopStream: caps.DesktopStream.transport !== null
+        ? {
+          ...caps.DesktopStream,
+          transport: null,
+          client: null,
+          mode: "read-only",
+          url: null,
+          token: null,
+          expiresAt: null,
+          requiresAcknowledgment: false,
+          acknowledged: false,
+          shared: false,
+          sharedSessionIds: [],
+          reason,
+        }
+        : caps.DesktopStream,
+      Recording: caps.Recording.available
+        ? { ...caps.Recording, available: false, modes: [], codecs: [], reason }
+        : caps.Recording,
+      ComputerUse: caps.ComputerUse.available
+        ? { ...caps.ComputerUse, available: false, reason }
+        : caps.ComputerUse,
+    };
+  }
+
+  if (!liveness.consented) {
+    // Displayed but no screen-CONTROL consent: VIEW (read-only) + Recording stay
+    // available; only CONTROL (input) is withheld. Force the stream to read-only
+    // so no input is forwarded even if the base offered an interactive mode.
+    return {
+      ...caps,
+      DesktopStream: caps.DesktopStream.transport !== null
+        ? { ...caps.DesktopStream, mode: "read-only" }
+        : caps.DesktopStream,
+      ComputerUse: caps.ComputerUse.available
+        ? { ...caps.ComputerUse, available: false, reason: "consent_required" }
+        : caps.ComputerUse,
+    };
+  }
+
+  // Fully online + displayed + consented: the base negotiation already produced
+  // the correct available cells (desktop vnc-ws, computer-use available, etc.).
+  return caps;
+}