@opengeni/api-router 0.30.1 → 2.1.0-canary.0

package/src/routes/install.ts

@@ -44,15 +44,34 @@ const BAKED_DIR = new URL("baked/", INSTALL_DIR);
 // The static text artifacts served verbatim, with their content types. Each is
 // read once at first request and memoized (committed files; immutable per deploy).
 const TEXT_ASSETS: Record<string, { file: string; contentType: string }> = {
-  "/install.sh": { file: "install.sh", contentType: "text/x-shellscript; charset=utf-8" },
-  "/install.ps1": { file: "install.ps1", contentType: "text/plain; charset=utf-8" },
-  "/uninstall.sh": { file: "uninstall.sh", contentType: "text/x-shellscript; charset=utf-8" },
+  "/install.sh": {
+    file: "install.sh",
+    contentType: "text/x-shellscript; charset=utf-8",
+  },
+  "/install.ps1": {
+    file: "install.ps1",
+    contentType: "text/plain; charset=utf-8",
+  },
+  "/uninstall.sh": {
+    file: "uninstall.sh",
+    contentType: "text/x-shellscript; charset=utf-8",
+  },
   "/opengeni-agent-minisign.pub": {
     file: "opengeni-agent-minisign.pub",
     contentType: "text/plain; charset=utf-8",
   },
 };
 
+// Non-executable resources needed to assemble a complete platform bundle. These
+// stay committed beside the installer rather than depending on a release/CDN so
+// an exact-SHA local or private deployment remains self-contained.
+const COMMITTED_BINARY_ASSETS: Record<string, { file: string; contentType: string }> = {
+  "OpenGeni-Agent.icns": {
+    file: "OpenGeni-Agent.icns",
+    contentType: "image/icns",
+  },
+};
+
 const assetCache = new Map<string, string>();
 
 async function loadAsset(file: string): Promise<string> {
@@ -73,26 +92,40 @@ async function loadAsset(file: string): Promise<string> {
 // `curl https://<this-host>/install.sh | sh` installs the exact agent that
 // matches the API it enrolls against, with NO dependency on a public CDN (which a
 // private/air-gapped deploy may not even resolve). When a public base URL is
-// configured we therefore rewrite each script's default-base-URL marker line to
-// that origin before serving. The user's OPENGENI_INSTALL_BASE_URL env override
-// still wins at run time (the scripts use `:-default`); only the built-in DEFAULT
-// changes. The marker lines are kept shape-stable in agent/install/install.{sh,ps1}.
-const DEFAULT_BASE_REWRITES: Record<string, (base: string) => { from: string; to: string }> = {
-  "install.sh": (base) => ({
-    from: 'OPENGENI_INSTALL_DEFAULT_BASE_URL="https://get.opengeni.ai"',
-    to: `OPENGENI_INSTALL_DEFAULT_BASE_URL="${base}"`,
-  }),
-  "install.ps1": (base) => ({
-    from: "$OpengeniInstallDefaultBaseUrl = 'https://get.opengeni.ai'",
-    to: `$OpengeniInstallDefaultBaseUrl = '${base}'`,
-  }),
+// configured we therefore rewrite each script's release-asset AND connection-API
+// default markers to that origin before serving. The user's
+// OPENGENI_INSTALL_BASE_URL / OPENGENI_API_URL overrides still win at run time;
+// only the built-in defaults change. The marker lines are kept shape-stable in
+// agent/install/install.{sh,ps1}.
+type DefaultRewrite = { from: string; to: string };
+
+const DEFAULT_BASE_REWRITES: Record<string, (base: string) => DefaultRewrite[]> = {
+  "install.sh": (base) => [
+    {
+      from: 'OPENGENI_INSTALL_DEFAULT_BASE_URL="https://get.opengeni.ai"',
+      to: `OPENGENI_INSTALL_DEFAULT_BASE_URL="${base}"`,
+    },
+    {
+      from: 'OPENGENI_API_DEFAULT_URL="https://app.opengeni.ai"',
+      to: `OPENGENI_API_DEFAULT_URL="${base}"`,
+    },
+  ],
+  "install.ps1": (base) => [
+    {
+      from: "$OpengeniInstallDefaultBaseUrl = 'https://get.opengeni.ai'",
+      to: `$OpengeniInstallDefaultBaseUrl = '${base}'`,
+    },
+    {
+      from: "$OpengeniApiDefaultUrl = 'https://app.opengeni.ai'",
+      to: `$OpengeniApiDefaultUrl = '${base}'`,
+    },
+  ],
 };
 
-// Rewrite a served script's default release-asset base URL to this deployment's
-// own public origin. A no-op when no public base URL is configured (the public
-// archive default stands), when the URL is not absolute http(s) (never serve a
-// script with a broken base), or when the file has no marker (script drift — fail
-// safe to serving it verbatim rather than crashing the install surface).
+// Rewrite a served script's default release-asset and connection-API URLs to this
+// deployment's own public origin. A no-op when no public base URL is configured,
+// when the URL is not absolute http(s), or when either marker is absent (script
+// drift — fail safe to serving it verbatim rather than splitting the two origins).
 function rewriteDefaultBaseUrl(
   file: string,
   body: string,
@@ -102,11 +135,11 @@ function rewriteDefaultBaseUrl(
     return body;
   }
   const base = publicBaseUrl.replace(/\/+$/, "");
-  const rule = DEFAULT_BASE_REWRITES[file]?.(base);
-  if (!rule || !body.includes(rule.from)) {
+  const rules = DEFAULT_BASE_REWRITES[file]?.(base);
+  if (!rules || rules.some((rule) => !body.includes(rule.from))) {
     return body;
   }
-  return body.replace(rule.from, rule.to);
+  return rules.reduce((rewritten, rule) => rewritten.replace(rule.from, rule.to), body);
 }
 
 // The content type for a baked release asset. The binary is an
@@ -173,6 +206,18 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
   // un-baked asset). The baked path makes the agent the API enrolls against
   // identical to the API that serves it — no version skew, no extra hop.
   async function serveAsset(asset: string, redirectUrl: string): Promise<Response> {
+    const committed = COMMITTED_BINARY_ASSETS[asset];
+    if (committed) {
+      const buf = await readFile(new URL(committed.file, INSTALL_DIR));
+      return new Response(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength), {
+        status: 200,
+        headers: {
+          "content-type": committed.contentType,
+          "cache-control": "public, max-age=3600",
+          "x-opengeni-agent-source": "committed",
+        },
+      });
+    }
     const baked = await readBaked(asset);
     if (baked !== null) {
       return new Response(baked, {
@@ -189,7 +234,10 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
     // Not baked here → the GitHub Release is the source of truth (the public
     // archive + the documented install.sh fallback). 302 so the client refetches.
-    return new Response(null, { status: 302, headers: { location: redirectUrl } });
+    return new Response(null, {
+      status: 302,
+      headers: { location: redirectUrl },
+    });
   }
 
   // `latest` → the BAKED binary if present, else the operator-selected immutable
@@ -217,10 +265,14 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     app.get(`/agent/${channel}/:manifestAsset`, (c) => {
       const manifestAsset = c.req.param("manifestAsset");
       if (manifestAsset !== "manifest.json" && manifestAsset !== "manifest.json.minisig") {
-        throw new HTTPException(404, { message: "update manifest asset not found" });
+        throw new HTTPException(404, {
+          message: "update manifest asset not found",
+        });
       }
       if (!version) {
-        throw new HTTPException(404, { message: `${channel} agent channel is not configured` });
+        throw new HTTPException(404, {
+          message: `${channel} agent channel is not configured`,
+        });
       }
       return new Response(null, {
         status: 302,
@@ -240,7 +292,9 @@ export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
     // `/agent/latest/<asset>` is handled by the more specific route above; any
     // other version segment must be the `v<ver>` shape.
     if (!VERSION_SEG.test(versionSeg) || !ASSET_NAME.test(asset)) {
-      throw new HTTPException(400, { message: "invalid version or asset name" });
+      throw new HTTPException(400, {
+        message: "invalid version or asset name",
+      });
     }
     return serveAsset(asset, `${releasesBase}/download/agent-${versionSeg}/${asset}`);
   });

package/src/routes/integration-facets.ts

@@ -13,6 +13,7 @@ import {
 } from "@opengeni/core";
 import {
   configureIntegrationFacet,
+  integrationFacetConfigureRequestDigest,
   IntegrationFacetBindingOwnershipConflictError,
   IntegrationFacetBindingVersionConflictError,
   IntegrationFacetBindingVersionRequiredError,
@@ -22,6 +23,7 @@ import {
   IntegrationFacetOperationIdempotencyError,
   listIntegrationInstanceFacets,
   removeIntegrationFacet,
+  replayCompletedIntegrationFacetOperation,
   setIntegrationFacetLifecycle,
 } from "@opengeni/db";
 import type { Hono } from "hono";
@@ -126,6 +128,33 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
       const instanceKey = decoded(c.req.param("instanceKey"));
       const facetKey = decoded(c.req.param("facetKey"));
       try {
+        const replayed =
+          await replayCompletedIntegrationFacetOperation<IntegrationFacetMutationResult>(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            capabilityId,
+            instanceKey,
+            facetKey,
+            idempotencyKey: payload.idempotencyKey,
+            kind: "configure",
+            expectedRequestDigest: integrationFacetConfigureRequestDigest({
+              capabilityId,
+              instanceKey,
+              facetKey,
+              displayName: payload.displayName,
+              config: payload.config,
+              ...(payload.expectedVersion !== undefined
+                ? { expectedVersion: payload.expectedVersion }
+                : {}),
+            }),
+          });
+        if (replayed) {
+          return c.json(
+            IntegrationFacetMutationResult.parse(replayed),
+            payload.expectedVersion === undefined ? 201 : 200,
+          );
+        }
         const instance = await listIntegrationInstanceFacets(
           deps.db,
           workspaceId,

package/src/routes/interaction-resources.ts

@@ -48,6 +48,8 @@ import {
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
   requireAccessGrant,
+  requireFreshAccessGrant,
+  requirePermission,
   requireSessionAuthorization,
   type ApiRouteDeps,
   workflowIdForSession,
@@ -70,7 +72,18 @@ export function registerInteractionResourceRoutes(app: Hono, deps: ApiRouteDeps)
       nonnegativeSafeIntegerQuery(context, "controlAfter", 0),
       nonnegativeSafeIntegerQuery(context, "interactionAfter", 0),
       context.req.raw.signal,
-      { observability: deps.observability },
+      {
+        observability: deps.observability,
+        reauthorize: async () => {
+          const freshGrant = await requireFreshAccessGrant(
+            context,
+            deps,
+            workspaceId,
+            "sessions:read",
+          );
+          requirePermission(freshGrant, "workspace:read");
+        },
+      },
     );
   });
 
@@ -83,7 +96,12 @@ export function registerInteractionResourceRoutes(app: Hono, deps: ApiRouteDeps)
       workspaceId,
       after,
       context.req.raw.signal,
-      { observability: deps.observability },
+      {
+        observability: deps.observability,
+        reauthorize: async () => {
+          await requireFreshAccessGrant(context, deps, workspaceId, "sessions:read");
+        },
+      },
     );
   });
 

package/src/routes/machines.ts

@@ -5,9 +5,10 @@
 // (default OFF → 404, invisible). Both routes need perm enrollments:read.
 //
 //   GET /v1/workspaces/:ws/machines[?sessionId=...]  -> MachinesResponse
-//     The dashboard list: the workspace's enrolled selfhosted machines (state +
-//     latest metrics + sharedSessionCount) and, when sessionId is supplied, the
-//     session's synthetic Modal group box + the active-sandbox pointer.
+//     The dashboard list: the workspace's enrolled selfhosted machines (heartbeat
+//     state + latest metrics + sharedSessionCount) and, when sessionId is
+//     supplied, the session's synthetic Modal group box + the active-sandbox
+//     pointer. This GET does not ControlRpc-ping.
 //
 //   GET /v1/workspaces/:ws/machines/:enrollmentId/metrics/series?window=1h
 //     -> { samples: MetricSample[] }
@@ -15,18 +16,31 @@
 
 import {
   MachineMetricsSeriesResponse,
+  MachineOperationPolicy,
   MachinesResponse,
   SwapActiveSandboxRequest,
   SwapActiveSandboxResponse,
+  UpdateMachineOperationPolicyRequest,
+  UpdateMachineAgentResponse,
 } from "@opengeni/contracts";
-import { getEnrollment, readMachineMetricsSeries, requireSession } from "@opengeni/db";
+import {
+  advanceEnrollmentAgentUpdate,
+  beginEnrollmentAgentUpdate,
+  getLiveEnrollmentConnection,
+  listEnrollments,
+  readMachineMetricsSeries,
+  requireSession,
+  updateEnrollmentOperationPolicy,
+} from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { requireAccessGrant } from "@opengeni/core";
+import { requireAccessGrant, requireAccessGrantAuthorization } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { buildFleetContextForSession, swapActiveSandbox } from "@opengeni/core";
 import { listMachines, metricRowToSample } from "../sandbox/machines";
 import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../sandbox/viewer";
+import { ControlRequest, ErrorCode } from "@opengeni/agent-proto";
+import { NatsControlRpc, subjectFor } from "@opengeni/runtime/sandbox";
 
 // The supported series windows → milliseconds. An unknown/absent window defaults
 // to 1h (the default). Bounded so a caller cannot request an unbounded
@@ -52,33 +66,55 @@ export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
   }
 
+  async function requireScopedEnrollment(
+    grant: Awaited<ReturnType<typeof requireAccessGrant>>,
+    enrollmentId: string,
+  ) {
+    const enrollment = (await listEnrollments(db, grant, { status: "active" })).find(
+      (candidate) => candidate.id === enrollmentId,
+    );
+    if (!enrollment) {
+      throw new HTTPException(404, { message: "machine not found in this access scope" });
+    }
+    return enrollment;
+  }
+
   // ── GET /workspaces/:ws/machines (the dashboard list) ───────────────────────
   app.get("/v1/workspaces/:workspaceId/machines", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
     assertSelfhostedEnabled();
     // sessionId is OPTIONAL: present → an in-session view (synthetic group box +
     // active pointer); absent → the pure workspace dashboard.
     const sessionId = c.req.query("sessionId") ?? null;
-    const response = await listMachines({ db, settings, bus }, { workspaceId, sessionId });
+    const response = await listMachines(
+      { db, settings },
+      {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        sessionId,
+      },
+    );
     return c.json(MachinesResponse.parse(response));
   });
 
   // ── GET /workspaces/:ws/machines/:enrollmentId/metrics/series ───────────────
   app.get("/v1/workspaces/:workspaceId/machines/:enrollmentId/metrics/series", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
     assertSelfhostedEnabled();
     const enrollmentId = c.req.param("enrollmentId");
     // Validate the machine belongs to this workspace (RLS already scopes the read,
     // but a clear 404 beats an empty series for an unknown/cross-workspace id).
-    const enrollment = await getEnrollment(db, workspaceId, enrollmentId);
-    if (!enrollment || enrollment.status !== "active") {
-      throw new HTTPException(404, { message: "machine not found in this workspace" });
-    }
+    const enrollment = await requireScopedEnrollment(grant, enrollmentId);
     const windowMs = SERIES_WINDOWS_MS[c.req.query("window") ?? ""] ?? DEFAULT_SERIES_WINDOW_MS;
     const since = new Date(Date.now() - windowMs);
-    const rows = await readMachineMetricsSeries(db, { workspaceId, enrollmentId, since });
+    const rows = await readMachineMetricsSeries(db, {
+      workspaceId: enrollment.workspaceId,
+      enrollmentId,
+      since,
+    });
     return c.json(
       MachineMetricsSeriesResponse.parse({
         samples: rows.map(metricRowToSample),
@@ -86,6 +122,230 @@ export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  // ── PATCH /workspaces/:ws/machines/:enrollmentId/operation-policy ──────────
+  // Null limits deliberately mean unrestricted. The revision is an optimistic
+  // concurrency fence so two operators cannot silently overwrite each other.
+  app.patch("/v1/workspaces/:workspaceId/machines/:enrollmentId/operation-policy", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "enrollments:manage",
+    );
+    const grant = authorization.grant;
+    assertSelfhostedEnabled();
+    const enrollmentId = c.req.param("enrollmentId");
+    let json: unknown;
+    try {
+      json = await c.req.json();
+    } catch {
+      throw new HTTPException(400, {
+        message: "operation policy body must be valid JSON",
+      });
+    }
+    const parsed = UpdateMachineOperationPolicyRequest.safeParse(json);
+    if (!parsed.success) {
+      throw new HTTPException(400, {
+        message: "invalid machine operation policy",
+      });
+    }
+    const body = parsed.data;
+    const current = await requireScopedEnrollment(grant, enrollmentId);
+    if (
+      current.scope === "organization" &&
+      authorization.accountGrant?.permissions.includes("account:admin") !== true
+    ) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const updated = await updateEnrollmentOperationPolicy(db, {
+      accountId: grant.accountId,
+      workspaceId: current.workspaceId,
+      enrollmentId,
+      subjectId: grant.subjectId,
+      expectedRevision: body.expectedRevision,
+      memoryMaxBytes: body.memoryMaxBytes,
+      memoryHighBytes: body.memoryHighBytes,
+      ...(body.cpuMaxMillicores !== undefined ? { cpuMaxMillicores: body.cpuMaxMillicores } : {}),
+    });
+    if (!updated) {
+      throw new HTTPException(409, {
+        message: "machine operation policy changed; refresh and retry",
+      });
+    }
+    return c.json(MachineOperationPolicy.parse(updated.operationPolicy));
+  });
+
+  // ── POST /workspaces/:ws/machines/:enrollmentId/update ─────────────────────
+  // Reserve one exact-generation operation, ask the authoritative runner to
+  // drain and apply the signed promoted release, then let progress events + the
+  // successor Hello drive the durable state to completion.
+  app.post("/v1/workspaces/:workspaceId/machines/:enrollmentId/update", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "enrollments:manage",
+    );
+    const grant = authorization.grant;
+    assertSelfhostedEnabled();
+    const enrollmentId = c.req.param("enrollmentId");
+    const visibleEnrollment = await requireScopedEnrollment(grant, enrollmentId);
+    if (
+      visibleEnrollment.scope === "organization" &&
+      authorization.accountGrant?.permissions.includes("account:admin") !== true
+    ) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const originWorkspaceId = visibleEnrollment.workspaceId;
+    const live = await getLiveEnrollmentConnection(
+      db,
+      visibleEnrollment.scope === "user" ? grant : originWorkspaceId,
+      enrollmentId,
+    );
+    if (!live?.connectionInstanceId || !live.agentVersion) {
+      throw new HTTPException(409, {
+        message: "machine has no authoritative live agent build",
+      });
+    }
+    const channel = live.agentUpdateChannel ?? "stable";
+    const targetVersion =
+      channel === "beta"
+        ? (settings.agentBetaVersion ?? settings.agentStableVersion)
+        : settings.agentStableVersion;
+    const reusableRequest =
+      live.agentUpdate?.status === "requested" &&
+      live.agentUpdate.targetVersion === targetVersion &&
+      live.agentUpdate.connectionInstanceId === live.connectionInstanceId &&
+      live.agentUpdate.connectionGeneration === live.connectionGeneration
+        ? live.agentUpdate
+        : null;
+    if (
+      !reusableRequest &&
+      live.agentVersion === targetVersion &&
+      live.agentUpdate?.status !== "failed"
+    ) {
+      throw new HTTPException(409, {
+        message: "machine already runs the promoted version",
+      });
+    }
+    const operationId = reusableRequest?.operationId ?? crypto.randomUUID();
+    if (!reusableRequest) {
+      const reserved = await beginEnrollmentAgentUpdate(db, {
+        accountId: grant.accountId,
+        workspaceId: originWorkspaceId,
+        enrollmentId,
+        connectionInstanceId: live.connectionInstanceId,
+        connectionGeneration: live.connectionGeneration,
+        operationId,
+        targetVersion,
+      });
+      if (!reserved) {
+        throw new HTTPException(409, {
+          message: "machine update state changed; refresh and retry",
+        });
+      }
+    }
+
+    const rpc = new NatsControlRpc(async () => bus?.getRequestConnection() ?? null);
+    const request: ControlRequest = {
+      requestId: operationId,
+      // The subject already selects the exact authoritative process instance.
+      // `epoch` is the sandbox lease epoch, not the enrollment connection
+      // generation, so this process-scoped operation intentionally leaves it 0.
+      epoch: 0,
+      resourcePolicy: undefined,
+      op: {
+        $case: "agentUpdateApply",
+        agentUpdateApply: {
+          operationId,
+          targetVersion,
+          channel,
+          expectedCurrentVersion: live.agentVersion,
+          expectedCurrentSha256: live.agentBinarySha256 ?? "",
+          releaseBaseUrl: (settings.publicBaseUrl ?? new URL(c.req.url).origin).replace(/\/+$/, ""),
+        },
+      },
+    };
+    let response = await rpc.request(
+      subjectFor(originWorkspaceId, enrollmentId, live.connectionInstanceId),
+      request,
+      { timeoutMs: 10_000 },
+    );
+    // The operation id is idempotent. One retry heals an ambiguous lost reply;
+    // the agent returns the same acceptance and never starts a second update.
+    if (response.error?.code === ErrorCode.ERROR_CODE_TIMEOUT) {
+      response = await rpc.request(
+        subjectFor(originWorkspaceId, enrollmentId, live.connectionInstanceId),
+        request,
+        { timeoutMs: 10_000 },
+      );
+    }
+    if (response.error) {
+      // A second timeout remains ambiguous: progress/Hello may still prove the
+      // operation. Keep it requested rather than racing a false terminal failure.
+      if (response.error.code !== ErrorCode.ERROR_CODE_TIMEOUT) {
+        await advanceEnrollmentAgentUpdate(db, {
+          accountId: grant.accountId,
+          workspaceId: originWorkspaceId,
+          enrollmentId,
+          connectionInstanceId: live.connectionInstanceId,
+          connectionGeneration: live.connectionGeneration,
+          operationId,
+          status: "failed",
+          errorCode:
+            response.error.detail.failure_code ??
+            (response.error.code === ErrorCode.ERROR_CODE_AGENT_OFFLINE
+              ? "agent_offline"
+              : "update_dispatch_rejected"),
+          retryable: response.error.retryable,
+          rolledBack: false,
+        });
+        throw new HTTPException(response.error.retryable ? 409 : 422, {
+          message: response.error.message,
+        });
+      }
+    } else if (
+      response.result?.$case !== "agentUpdateApply" ||
+      !response.result.agentUpdateApply.accepted
+    ) {
+      await advanceEnrollmentAgentUpdate(db, {
+        accountId: grant.accountId,
+        workspaceId: originWorkspaceId,
+        enrollmentId,
+        connectionInstanceId: live.connectionInstanceId,
+        connectionGeneration: live.connectionGeneration,
+        operationId,
+        status: "failed",
+        errorCode: "invalid_agent_response",
+        retryable: true,
+        rolledBack: false,
+      });
+      throw new HTTPException(502, {
+        message: "agent returned an invalid update response",
+      });
+    } else {
+      await advanceEnrollmentAgentUpdate(db, {
+        accountId: grant.accountId,
+        workspaceId: originWorkspaceId,
+        enrollmentId,
+        connectionInstanceId: live.connectionInstanceId,
+        connectionGeneration: live.connectionGeneration,
+        operationId,
+        status: "accepted",
+      });
+    }
+    return c.json(
+      UpdateMachineAgentResponse.parse({
+        operationId,
+        accepted: true,
+        targetVersion,
+      }),
+      202,
+    );
+  });
+
   // ── POST /workspaces/:ws/sessions/:sessionId/active-sandbox (swap) ───────────
   // The user-authenticated equivalent of the M7 `sandbox_swap` MCP tool: repoint
   // a session's active sandbox under the epoch fence. Same perm as PATCH session
@@ -102,6 +362,7 @@ export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
       accountId: grant.accountId,
       workspaceId,
       sessionId,
+      subjectId: grant.subjectId,
     });
     const result = await swapActiveSandbox(
       {
@@ -116,6 +377,7 @@ export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
               accountId: fleetCtx.accountId,
               workspaceId: fleetCtx.workspaceId,
               session,
+              subjectId: fleetCtx.subjectId ?? null,
             },
           );
         },