@opengeni/api-router 3.0.1 → 3.1.2

package/src/sandbox/metrics-ingestion.ts

@@ -38,6 +38,8 @@ import {
   clearEnrollmentWentOffline,
   disconnectAttachedBrowserDevices,
   advanceEnrollmentAgentUpdate,
+  enrollmentMacPermissionCapabilities,
+  enrollmentMacPermissions,
   getEnrollment,
   getLiveEnrollmentConnection,
   ingestMachineMetricsSample,
@@ -50,27 +52,34 @@ import {
   setEnrollmentOpStreamState,
   type AppendEventInput,
   type Database,
+  type EnrollmentMacPermissions,
   type MachineMetricsSample,
 } from "@opengeni/db";
 import {
+  AttachedBrowserConnectionEnd as AttachedBrowserConnectionEndContract,
   AttachedBrowserInventorySnapshot as AttachedBrowserInventoryContract,
   type AttachedBrowserInventorySnapshot as AttachedBrowserInventoryContractValue,
+  type AttachedBrowserConnectionEnd as AttachedBrowserConnectionEndValue,
 } from "@opengeni/contracts";
 import { appendAndPublishEvents, type EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
 import { normalizeConnectedMachineWorkspaceRoot } from "@opengeni/runtime/sandbox";
+import type { AutomaticAgentUpdater } from "./agent-update";
 import {
   AgentEvent,
   AgentUpdateStage,
   Arch,
+  AttachedBrowserConnectionEndReason as WireConnectionEndReason,
   GoingOfflineReason,
   Hello,
   Os,
   goingOfflineReasonToJSON,
+  type AttachedBrowserConnectionEnd as WireAttachedBrowserConnectionEnd,
   type AttachedBrowserInventorySnapshot as WireAttachedBrowserInventorySnapshot,
   type MetricsSample,
 } from "@opengeni/agent-proto";
 import { AGENT_CONNECTION_LEASE_MS } from "./connection-authority";
+import { reconcileScreenControlOnHello } from "./screen-control";
 
 /** The wildcard subject the agent event plane publishes heartbeats on. */
 export const AGENT_EVENTS_SUBJECT = "agent.*.*.connection.*.events";
@@ -314,9 +323,53 @@ export function wireAttachedBrowserInventoryToContract(
       tabCount: safeWireInteger(device.tabCount, "attached browser tab count"),
       capabilities: device.capabilities,
     })),
+    connectionEnds: (wire.connectionEnds ?? []).flatMap(wireConnectionEndToContract),
   });
 }
 
+const WIRE_CONNECTION_END_REASONS = new Map<
+  WireConnectionEndReason,
+  AttachedBrowserConnectionEndValue["reason"]
+>([
+  [
+    WireConnectionEndReason.ATTACHED_BROWSER_CONNECTION_END_REASON_BROWSER_CLOSED_PORT,
+    "browser_closed_port",
+  ],
+  [
+    WireConnectionEndReason.ATTACHED_BROWSER_CONNECTION_END_REASON_BROWSER_MESSAGE_INVALID,
+    "browser_message_invalid",
+  ],
+  [
+    WireConnectionEndReason.ATTACHED_BROWSER_CONNECTION_END_REASON_BROWSER_OUTPUT_FAILED,
+    "browser_output_failed",
+  ],
+  [
+    WireConnectionEndReason.ATTACHED_BROWSER_CONNECTION_END_REASON_NATIVE_HOST_LOST,
+    "native_host_lost",
+  ],
+  [WireConnectionEndReason.ATTACHED_BROWSER_CONNECTION_END_REASON_AGENT_REJECTED, "agent_rejected"],
+]);
+
+/** Connection ends are diagnostics. One the contract cannot hold (a future
+ *  reason, or the generation of a hello the bridge rejected as malformed) is
+ *  dropped instead of rejecting the authoritative device inventory. */
+function wireConnectionEndToContract(
+  wire: WireAttachedBrowserConnectionEnd,
+): AttachedBrowserConnectionEndValue[] {
+  const reason = WIRE_CONNECTION_END_REASONS.get(wire.reason);
+  const endedAtMs = Number(wire.endedAtUnixMs);
+  if (!reason || !Number.isSafeInteger(endedAtMs) || endedAtMs <= 0) return [];
+  const parsed = AttachedBrowserConnectionEndContract.safeParse({
+    deviceId: wire.deviceId,
+    connectionGeneration: wire.connectionGeneration,
+    reason,
+    detail: wire.detail.slice(0, 512) || null,
+    endedAt: new Date(endedAtMs).toISOString(),
+    connectedMs: Math.min(Number(wire.connectedMs) || 0, Number.MAX_SAFE_INTEGER),
+  });
+  return parsed.success ? [parsed.data] : [];
+}
+
 function safeWireInteger(value: string | number, label: string): number {
   let parsed: bigint;
   try {
@@ -452,6 +505,7 @@ export async function handleAgentEventPayload(
   payload: Uint8Array,
   subject: string,
   bus?: EventBus,
+  agentUpdates?: AutomaticAgentUpdater | null,
 ): Promise<void> {
   const ids = parseAgentEventSubject(subject);
   if (!ids) {
@@ -619,6 +673,9 @@ export async function handleAgentEventPayload(
     });
     return;
   }
+  // A live machine behind its promoted build is asked to update; the decision
+  // reads only this enrollment, and a request never blocks heartbeat ingestion.
+  agentUpdates?.consider(enrollment);
   if (heartbeat.attachedBrowserInventory) {
     try {
       await ingestAttachedBrowserInventory(db, {
@@ -633,6 +690,41 @@ export async function handleAgentEventPayload(
       });
     }
   }
+  if (heartbeat.desktopStatus) {
+    try {
+      const status = heartbeat.desktopStatus;
+      const available = status.available && !status.unavailableReason;
+      const reason = status.unavailableReason || null;
+      const macPermissions = status.macPermissions;
+      const stored = enrollmentMacPermissions(enrollment.agentCapabilities);
+      // The heartbeat already read the exact enrollment. Steady state adds no
+      // extra query; the change path re-reads and fences its eventual write.
+      if (
+        enrollment.hasDisplay !== available ||
+        (enrollment.desktopUnavailableReason ?? null) !== reason ||
+        enrollment.agentCapabilities?.desktop !== available ||
+        (macPermissions !== undefined &&
+          (stored?.screenRecording !== macPermissions.screenRecording ||
+            stored?.accessibility !== macPermissions.accessibility ||
+            stored?.inputMonitoring !== macPermissions.inputMonitoring))
+      ) {
+        await refreshEnrollmentDisplay(db, {
+          workspaceId: ids.workspaceId,
+          agentId: ids.agentId,
+          hasDisplay: available,
+          desktopUnavailableReason: reason,
+          runtimeDesktop: available,
+          ...(macPermissions ? { macPermissions } : {}),
+          connectionInstanceId: ids.connectionInstanceId,
+        });
+      }
+    } catch (error) {
+      observability?.warn?.("Failed to refresh a machine desktop heartbeat", {
+        subject,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
   const metrics = heartbeat.metrics;
   if (!metrics) return;
   try {
@@ -659,10 +751,18 @@ export function startMetricsIngestion(deps: {
   db: Database;
   bus: EventBus;
   observability?: Observability;
+  agentUpdates?: AutomaticAgentUpdater | null;
 }): () => void {
   const scheduler = createAgentEventIngestionScheduler(
     (payload, subject) =>
-      handleAgentEventPayload(deps.db, deps.observability, payload, subject, deps.bus),
+      handleAgentEventPayload(
+        deps.db,
+        deps.observability,
+        payload,
+        subject,
+        deps.bus,
+        deps.agentUpdates,
+      ),
     {
       onHeartbeatCoalesced: () =>
         deps.observability?.incrementCounter({
@@ -742,6 +842,9 @@ export function helloRuntimeCapabilities(hello: Hello): Record<string, boolean>
     operationResourcePolicy: caps.operationResourcePolicy === true,
     operationCpuQuota: caps.operationCpuQuota === true,
     transactionalFsWrite: caps.transactionalFsWrite === true,
+    credentialRenew: caps.credentialRenew === true,
+    screenControl: caps.consentedScreenControl === true,
+    ...(caps.macPermissions ? enrollmentMacPermissionCapabilities(caps.macPermissions) : {}),
   };
 }
 
@@ -781,6 +884,8 @@ export async function refreshEnrollmentDisplay(
     agentId: string;
     hasDisplay: boolean;
     desktopUnavailableReason?: string | null;
+    runtimeDesktop?: boolean;
+    macPermissions?: EnrollmentMacPermissions;
     connectionInstanceId?: string;
   },
 ): Promise<{ updated: boolean }> {
@@ -791,7 +896,16 @@ export async function refreshEnrollmentDisplay(
   }
   if (
     enrollment.hasDisplay === input.hasDisplay &&
-    (enrollment.desktopUnavailableReason ?? null) === desktopUnavailableReason
+    (enrollment.desktopUnavailableReason ?? null) === desktopUnavailableReason &&
+    (input.runtimeDesktop === undefined ||
+      enrollment.agentCapabilities?.desktop === input.runtimeDesktop) &&
+    (input.macPermissions === undefined ||
+      JSON.stringify(enrollmentMacPermissions(enrollment.agentCapabilities)) ===
+        JSON.stringify({
+          screenRecording: input.macPermissions.screenRecording,
+          accessibility: input.macPermissions.accessibility,
+          inputMonitoring: input.macPermissions.inputMonitoring,
+        }))
   ) {
     // Both fields unchanged — do not even issue the UPDATE (no churn on a
     // steady-state Hello).
@@ -803,6 +917,8 @@ export async function refreshEnrollmentDisplay(
     enrollmentId: input.agentId,
     hasDisplay: input.hasDisplay,
     desktopUnavailableReason,
+    ...(input.runtimeDesktop !== undefined ? { runtimeDesktop: input.runtimeDesktop } : {}),
+    ...(input.macPermissions ? { macPermissions: input.macPermissions } : {}),
     ...(input.connectionInstanceId ? { connectionInstanceId: input.connectionInstanceId } : {}),
   });
 }
@@ -926,6 +1042,21 @@ export async function handleHelloPayload(
       error: error instanceof Error ? error.message : String(error),
     });
   }
+  // Screen control allowed while this machine was offline (or before its agent
+  // could renew on request) applies now. Detached: it waits for the agent to
+  // subscribe and must not hold up Hello ingestion.
+  void reconcileScreenControlOnHello(
+    { bus, observability },
+    {
+      authority,
+      hello,
+      target: {
+        workspaceId: ids.workspaceId,
+        enrollmentId: ids.agentId,
+        connectionInstanceId: ids.connectionInstanceId,
+      },
+    },
+  );
   // A reconnect Hello re-announces the machine, so any pending clean going-offline
   // marker no longer holds — clear it so the liveness derivation stops reading the
   // machine offline. Best-effort + fail-soft, and change-guarded in the DB (a

package/src/sandbox/rematerialize.ts

@@ -7,6 +7,7 @@ import {
   failSandboxRematerialization,
   failWarmingToCold,
   markSandboxRestoreVerifying,
+  sessionHoldsFreshWorkspaceRecovery,
   recordWarmingSandboxCreated,
   SandboxLeaseRecoveryBlockedError,
   SandboxLeaseSupersededError,
@@ -29,6 +30,7 @@ import {
   verifySandboxExecReadiness,
   withoutSandboxProviderIdentity,
   WorkspaceArchiveIntegrityError,
+  workspaceArchiveDownloadTemporaryDirectory,
   type EstablishedSandboxSession,
   type WorkspaceArchiveDescriptor,
 } from "@opengeni/runtime/sandbox";
@@ -73,8 +75,9 @@ async function materializeArchiveObjectRef(
   }
   if (!objectStorage) {
     throw new WorkspaceArchiveIntegrityError(
-      "archive_base64_invalid",
+      "archive_storage_unavailable",
       "workspace archive object storage is not configured",
+      { retryable: true },
     );
   }
   const descriptor = parseWorkspaceArchiveDescriptor(sessionState.workspaceArchiveMeta);
@@ -136,13 +139,29 @@ export async function establishApiSandboxSpawner(input: {
   dataPlaneUrl: string | null;
   objectStorage?: ObjectStorage | null;
 }): Promise<{ established: EstablishedSandboxSession; lease: LeaseSnapshot }> {
+  // An audited decision to continue a definitively lost workspace on a new
+  // EMPTY box: hydrate nothing, including a per-session legacy archive, and
+  // never resume a prior provider identity. Commit verifies the decision.
+  const freshWorkspaceRecoveryId = input.acquiredLease.freshWorkspaceRecoveryId ?? null;
+  // Backstop: a session already told its workspace is empty never gets a
+  // legacy per-session archive back, even if the lease marker was lost.
+  const legacyFallbackRefused =
+    !freshWorkspaceRecoveryId &&
+    input.acquiredLease.recovery.archive.status === "none" &&
+    hasWorkspaceArchive(input.fallbackEnvelope) &&
+    (await sessionHoldsFreshWorkspaceRecovery(input.db, input.workspaceId, input.sessionId));
   const fallbackArchiveEnvelope =
+    !freshWorkspaceRecoveryId &&
+    !legacyFallbackRefused &&
     input.acquiredLease.recovery.archive.status === "none" &&
     hasWorkspaceArchive(input.fallbackEnvelope)
       ? withoutSandboxProviderIdentity(input.fallbackEnvelope)
       : null;
-  let spawnEnvelope =
-    fallbackArchiveEnvelope ?? input.acquiredLease.resumeState ?? input.fallbackEnvelope;
+  let spawnEnvelope = freshWorkspaceRecoveryId
+    ? null
+    : legacyFallbackRefused
+      ? (input.acquiredLease.resumeState ?? null)
+      : (fallbackArchiveEnvelope ?? input.acquiredLease.resumeState ?? input.fallbackEnvelope);
   const archiveSource =
     input.acquiredLease.recovery.archive.status === "none"
       ? fallbackArchiveEnvelope
@@ -161,9 +180,12 @@ export async function establishApiSandboxSpawner(input: {
   const continuityRecovery = input.acquiredLease.recovery.continuity;
   try {
     if (
-      (input.acquiredLease.recovery.archive.status === "available" &&
-        input.acquiredLease.archiveComplete) ||
-      (input.acquiredLease.recovery.archive.status === "none" && hasWorkspaceArchive(archiveSource))
+      !freshWorkspaceRecoveryId &&
+      ((input.acquiredLease.recovery.archive.status === "available" &&
+        (input.acquiredLease.archiveComplete ||
+          input.acquiredLease.historicalRecoveryAuthorized === true)) ||
+        (input.acquiredLease.recovery.archive.status === "none" &&
+          hasWorkspaceArchive(archiveSource)))
     ) {
       const id = crypto.randomUUID();
       const legacyNativeArchive = legacyNativeArchiveFromEnvelope(archiveSource);
@@ -206,7 +228,11 @@ export async function establishApiSandboxSpawner(input: {
         legacyCheckpoint: begun.checkpointArtifact === null ? legacyNativeArchive : null,
         legacyProviderBinding: null,
       };
-    } else if (input.acquiredLease.recovery.archive.status !== "none" && !continuityRecovery) {
+    } else if (
+      !freshWorkspaceRecoveryId &&
+      input.acquiredLease.recovery.archive.status !== "none" &&
+      !continuityRecovery
+    ) {
       throw new SandboxLeaseRecoveryBlockedError(
         input.sandboxGroupId,
         input.expectedEpoch,
@@ -225,10 +251,12 @@ export async function establishApiSandboxSpawner(input: {
         ? {
             loadHostWorkspaceArchive: async (ref) => {
               try {
-                return await downloadWorkspaceArchiveSpool(input.objectStorage!, ref.key, {
-                  bytes: ref.bytes,
-                  sha256: ref.sha256,
-                });
+                return await downloadWorkspaceArchiveSpool(
+                  input.objectStorage!,
+                  ref.key,
+                  { bytes: ref.bytes, sha256: ref.sha256 },
+                  { temporaryDirectory: workspaceArchiveDownloadTemporaryDirectory },
+                );
               } catch (error) {
                 if (error instanceof WorkspaceArchiveStorageError) {
                   throw new WorkspaceArchiveIntegrityError(error.code, error.message, {
@@ -383,16 +411,18 @@ export async function establishApiSandboxSpawner(input: {
       dataPlaneUrl: input.dataPlaneUrl,
       resumeBackendId: established.backendId,
       resumeState,
-      ...(established.providerContinuity
-        ? { continuityRecovery: established.providerContinuity }
-        : rematerialization
-          ? {
-              rematerialization: {
-                id: rematerialization.id,
-                verifiedRevision: rematerialization.selectedRevision,
-              },
-            }
-          : {}),
+      ...(freshWorkspaceRecoveryId
+        ? { freshWorkspace: { operationId: freshWorkspaceRecoveryId } }
+        : established.providerContinuity
+          ? { continuityRecovery: established.providerContinuity }
+          : rematerialization
+            ? {
+                rematerialization: {
+                  id: rematerialization.id,
+                  verifiedRevision: rematerialization.selectedRevision,
+                },
+              }
+            : {}),
       leaseTtlMs: input.settings.sandboxLeaseTtlMs,
     });
     if (!committed.committed || !committed.lease) {

package/src/sandbox/screen-control.ts

@@ -0,0 +1,289 @@
+// Screen control and macOS permission setup for an already-connected machine.
+//
+// Screen-control consent lives on the enrollment row and in the credentials the
+// machine holds (the agent's own dispatch gate checks them). Turning it on
+// records the consent on the row, in place (same id, scope, owner and
+// credential generation), then asks the live agent to renew its credentials
+// now. That renewal is the same install-key-signed exchange the agent runs on
+// its own schedule, and it re-reads consent from the row, so nothing new is
+// trusted: no token, no installer, no restart, no second connection file. A
+// machine that is offline, or whose agent predates credential_renew, picks the
+// consent up when it next says Hello (reconcileScreenControlOnHello).
+
+import { ControlRequest, ErrorCode, type Hello } from "@opengeni/agent-proto";
+import {
+  EnableMachineScreenControlResponse,
+  OpenMachinePrivacySettingsResponse,
+  type MachinePrivacySettingsPane,
+} from "@opengeni/contracts";
+import { runOnEnrollmentDirect, type FleetServices } from "@opengeni/core";
+import {
+  allowEnrollmentScreenControl,
+  getLiveEnrollmentConnection,
+  type EnrollmentRecord,
+} from "@opengeni/db";
+import type { EventBus } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+import { NatsControlRpc, subjectFor } from "@opengeni/runtime/sandbox";
+
+type Services = Pick<FleetServices, "db" | "settings" | "bus"> & {
+  observability?: Observability | undefined;
+};
+type EnrollmentAccess = string | { accountId: string; workspaceId: string; subjectId: string };
+
+/** The agent's renewal HTTP call is bounded at 20s; leave room for the reply. */
+const CREDENTIAL_RENEW_TIMEOUT_MS = 30_000;
+/** Opening a System Settings pane is instant; never hold a request open longer. */
+const PRIVACY_PANE_TIMEOUT_MS = 15_000;
+
+/** macOS System Settings deep links for the three desktop permissions. */
+export const MAC_PRIVACY_PANE_URLS: Record<MachinePrivacySettingsPane, string> = {
+  screen_recording: "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",
+  accessibility: "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility",
+  input_monitoring: "x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent",
+};
+
+/** Read access for live-connection lookups, matching the machine's scope. */
+export function enrollmentAccess(
+  enrollment: Pick<EnrollmentRecord, "scope" | "workspaceId">,
+  personal: { accountId: string; workspaceId: string; subjectId: string },
+): EnrollmentAccess {
+  return enrollment.scope === "user" ? personal : enrollment.workspaceId;
+}
+
+export type CredentialRenewOutcome =
+  | { kind: "renewed"; consentedScreenControl: boolean }
+  | { kind: "offline" }
+  | { kind: "failed"; failureCode: string };
+
+/** Ask one exact live runner process to renew its credentials now. */
+export async function requestCredentialRenew(
+  bus: EventBus | undefined,
+  target: { workspaceId: string; enrollmentId: string; connectionInstanceId: string },
+): Promise<CredentialRenewOutcome> {
+  if (!bus) return { kind: "offline" };
+  const rpc = new NatsControlRpc(async () => bus.getRequestConnection() ?? null);
+  const request: ControlRequest = {
+    requestId: crypto.randomUUID(),
+    // Process-scoped, like agentUpdateApply: the subject names the instance.
+    epoch: 0,
+    resourcePolicy: undefined,
+    op: { $case: "credentialRenew", credentialRenew: {} },
+  };
+  const response = await rpc.request(
+    subjectFor(target.workspaceId, target.enrollmentId, target.connectionInstanceId),
+    request,
+    { timeoutMs: CREDENTIAL_RENEW_TIMEOUT_MS },
+  );
+  if (response.error) {
+    if (response.error.code === ErrorCode.ERROR_CODE_AGENT_OFFLINE) return { kind: "offline" };
+    return {
+      kind: "failed",
+      failureCode:
+        response.error.detail.failure_code ??
+        (response.error.code === ErrorCode.ERROR_CODE_TIMEOUT ? "timeout" : "agent_error"),
+    };
+  }
+  if (response.result?.$case !== "credentialRenew") {
+    return { kind: "failed", failureCode: "invalid_agent_response" };
+  }
+  return {
+    kind: "renewed",
+    consentedScreenControl: response.result.credentialRenew.consentedScreenControl,
+  };
+}
+
+const pending = (
+  reason: "offline" | "agent_update_required" | "renewal_failed" | "reconnect_required",
+  message: string,
+): EnableMachineScreenControlResponse =>
+  EnableMachineScreenControlResponse.parse({ status: "pending", reason, message });
+
+const ACTIVE = { status: "active", reason: null, message: null } as const;
+
+/** Agent failure codes that no retry fixes: the connection must be redone. */
+const PERMANENT_RENEW_FAILURES = new Set([
+  "connection_missing",
+  "legacy_origin",
+  "local_state_unavailable",
+]);
+
+/** The enrollment was revoked or removed between lookup and update. */
+export class MachineNotActiveError extends Error {
+  constructor() {
+    super("machine is no longer connected to this workspace");
+    this.name = "MachineNotActiveError";
+  }
+}
+
+/** Who turned screen control on, for the audit trail. */
+export type ScreenControlActor = {
+  subjectId: string | null;
+  sessionId?: string | null;
+  attemptId?: string | null;
+};
+
+/**
+ * Turn screen control on for one enrolled machine, in place. The caller has
+ * already authorized the actor for this enrollment (enrollments:manage, plus
+ * account:admin for an organization machine, plus personal-machine admission
+ * for an agent attempt). Safe to repeat: a retry re-requests the renewal.
+ */
+export async function enableMachineScreenControl(
+  services: Services,
+  input: { enrollment: EnrollmentRecord; access: EnrollmentAccess; actor: ScreenControlActor },
+): Promise<EnableMachineScreenControlResponse> {
+  const { enrollment } = input;
+  if (!enrollment.allowScreenControl) {
+    const allowed = await allowEnrollmentScreenControl(services.db, {
+      accountId: enrollment.accountId,
+      workspaceId: enrollment.workspaceId,
+      enrollmentId: enrollment.id,
+      ...input.actor,
+    });
+    if (!allowed.active) throw new MachineNotActiveError();
+  }
+  const live = await getLiveEnrollmentConnection(services.db, input.access, enrollment.id);
+  if (!live?.connectionInstanceId) {
+    return pending(
+      "offline",
+      "Screen control is allowed. The machine is offline, so it turns on when the machine reconnects.",
+    );
+  }
+  // The live agent's Hello already carries the consent: nothing to renew, so
+  // repeated calls never churn the connection.
+  if (live.allowScreenControl && live.agentCapabilities.screenControl === true) {
+    return EnableMachineScreenControlResponse.parse(ACTIVE);
+  }
+  if (live.agentCapabilities.credentialRenew !== true) {
+    return pending(
+      "agent_update_required",
+      "Screen control is allowed. This machine's agent is too old to switch it on while connected: update the agent and it turns on after the update.",
+    );
+  }
+  const outcome = await requestCredentialRenew(services.bus, {
+    workspaceId: live.workspaceId,
+    enrollmentId: enrollment.id,
+    connectionInstanceId: live.connectionInstanceId,
+  });
+  if (outcome.kind === "renewed" && outcome.consentedScreenControl) {
+    return EnableMachineScreenControlResponse.parse(ACTIVE);
+  }
+  services.observability?.warn?.("Screen control renewal did not complete", {
+    workspaceId: live.workspaceId,
+    enrollmentId: enrollment.id,
+    outcome: outcome.kind,
+    failureCode: outcome.kind === "failed" ? outcome.failureCode : null,
+  });
+  if (outcome.kind === "offline") {
+    return pending(
+      "offline",
+      "Screen control is allowed. The machine went offline, so it turns on when the machine reconnects.",
+    );
+  }
+  if (outcome.kind === "failed" && PERMANENT_RENEW_FAILURES.has(outcome.failureCode)) {
+    return pending(
+      "reconnect_required",
+      "Screen control is allowed, but this machine's connection can't take it in place. Run the connect command on the machine again with screen control on.",
+    );
+  }
+  return pending(
+    "renewal_failed",
+    "The machine couldn't refresh its credentials. Try again in a moment.",
+  );
+}
+
+const HELLO_RENEW_DELAYS_MS = [2_000, 5_000] as const;
+
+/**
+ * A machine whose enrollment allows screen control but whose credentials do
+ * not (it was offline, or updated from an agent without credential_renew)
+ * renews them as soon as it says Hello. The agent subscribes to requests just
+ * after its Hello, so wait briefly and retry once. Never throws.
+ */
+export async function reconcileScreenControlOnHello(
+  deps: {
+    bus: EventBus | undefined;
+    observability?: Observability | undefined;
+    sleep?: (ms: number) => Promise<void>;
+  },
+  input: {
+    authority: Pick<EnrollmentRecord, "allowScreenControl">;
+    hello: Hello;
+    target: {
+      workspaceId: string;
+      enrollmentId: string;
+      connectionInstanceId: string;
+    };
+  },
+): Promise<CredentialRenewOutcome | null> {
+  const capabilities = input.hello.capabilities;
+  if (
+    !input.authority.allowScreenControl ||
+    !capabilities?.credentialRenew ||
+    capabilities.consentedScreenControl
+  ) {
+    return null;
+  }
+  const sleep = deps.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let outcome: CredentialRenewOutcome = { kind: "offline" };
+  try {
+    for (const delay of HELLO_RENEW_DELAYS_MS) {
+      await sleep(delay);
+      outcome = await requestCredentialRenew(deps.bus, input.target);
+      if (outcome.kind !== "offline") break;
+    }
+  } catch (error) {
+    outcome = {
+      kind: "failed",
+      failureCode: error instanceof Error ? error.message : "request_failed",
+    };
+  }
+  if (outcome.kind !== "renewed") {
+    deps.observability?.warn?.("Could not apply allowed screen control after a Hello", {
+      workspaceId: input.target.workspaceId,
+      enrollmentId: input.target.enrollmentId,
+      outcome: outcome.kind,
+      failureCode: outcome.kind === "failed" ? outcome.failureCode : null,
+    });
+  }
+  return outcome;
+}
+
+/** Open one macOS Privacy & Security pane on a connected Mac. Opening a pane
+ * grants nothing; the person flips the switch for Opengeni. */
+export async function openMachinePrivacySettings(
+  services: Services,
+  input: {
+    enrollment: EnrollmentRecord;
+    access: EnrollmentAccess;
+    pane: MachinePrivacySettingsPane;
+  },
+): Promise<OpenMachinePrivacySettingsResponse> {
+  if (input.enrollment.os !== "macos") {
+    return OpenMachinePrivacySettingsResponse.parse({
+      opened: false,
+      message: "Privacy & Security panes exist only on macOS.",
+    });
+  }
+  const result = await runOnEnrollmentDirect(services, {
+    access: input.access,
+    enrollmentId: input.enrollment.id,
+    target: input.enrollment.id,
+    cmd: `open '${MAC_PRIVACY_PANE_URLS[input.pane]}'`,
+    execTimeoutMs: PRIVACY_PANE_TIMEOUT_MS,
+  });
+  const opened = result.ok && result.exitCode === 0;
+  if (!opened) {
+    services.observability?.warn?.("Could not open a macOS privacy pane", {
+      enrollmentId: input.enrollment.id,
+      pane: input.pane,
+      exitCode: result.ok ? (result.exitCode ?? null) : null,
+      timedOut: result.timedOut === true,
+    });
+  }
+  return OpenMachinePrivacySettingsResponse.parse({
+    opened,
+    message: opened ? null : "The Mac isn't reachable right now.",
+  });
+}