@opengeni/core 0.28.1 → 1.0.0

package/src/sandbox/fleet.ts

@@ -1,6 +1,6 @@
 // apps/api/src/sandbox/fleet.ts — the FLEET service backing the fleet MCP tools
 // (M7): list / attach / swap / run_on / provision over the heterogeneous fleet
-// (the session's Modal group box + the workspace's enrolled selfhosted machines).
+// (the session's managed group box + the workspace's enrolled selfhosted machines).
 //
 // Each operation is workspace-scoped (the caller's grant) and, for the
 // session-pointer mutations (attach/swap), session-scoped (the worker-signed
@@ -12,12 +12,17 @@
 // single op WITHOUT touching the active pointer.
 
 import type { Settings } from "@opengeni/config";
+import type { SandboxBackend } from "@opengeni/contracts";
 import {
+  authorizePersonalMachineForAttempt,
   getEnrollment,
+  getLiveEnrollmentConnection,
   getSandbox,
+  listEnrollments,
   listSandboxes,
   readActiveSandbox,
   readLease,
+  resolvePersonalMachineConnectionForAttempt,
   requireSession,
   setActiveSandbox,
   type Database,
@@ -30,14 +35,18 @@ import {
   NatsOpStreamTransport,
   selfhostedLiveness,
   SelfhostedSession,
+  resolveConnectedMachineWorkspaceRoot,
   swapTargetEstablishability,
   type BackendUnresolvableCode,
   type ControlRpc,
   type NatsRequestConnection,
   type SelfhostedRelayConfig,
   type SelfhostedOpStreamDeps,
+  type SelfhostedOperationAdmission,
+  type SelfhostedOperationResourcePolicy,
 } from "@opengeni/runtime/sandbox";
 import { relayConfigFromSettings } from "./routing";
+import { managedSessionGroupBackend, sessionGroupMachinePresentation } from "./runtime-settings";
 
 export type FleetServices = {
   db: Database;
@@ -57,11 +66,18 @@ export type FleetReadinessHold = {
 export type FleetContext = {
   accountId: string;
   workspaceId: string;
+  subjectId?: string;
+  attemptAuthority?: {
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+    initiatingHumanSubjectId: string;
+  };
   /** The calling session (the pointer the attach/swap mutates + whose group box
    *  is the default fleet member). */
   sessionId: string;
-  /** The session's own group sandbox backend (modal/selfhosted/…). */
-  sessionBackend: string;
+  /** The session's durable home-compute policy. */
+  sessionBackend: SandboxBackend;
   /** The session's own group sandbox id (the lease group). */
   sessionGroupId: string;
 };
@@ -78,12 +94,20 @@ export type FleetContext = {
  */
 export async function buildFleetContextForSession(
   deps: { db: Database },
-  ctx: { accountId: string; workspaceId: string; sessionId: string },
+  ctx: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    subjectId?: string;
+    attemptAuthority?: FleetContext["attemptAuthority"];
+  },
 ): Promise<FleetContext> {
   const session = await requireSession(deps.db, ctx.workspaceId, ctx.sessionId);
   return {
     accountId: ctx.accountId,
     workspaceId: ctx.workspaceId,
+    ...(ctx.subjectId ? { subjectId: ctx.subjectId } : {}),
+    ...(ctx.attemptAuthority ? { attemptAuthority: ctx.attemptAuthority } : {}),
     sessionId: ctx.sessionId,
     sessionBackend: session.sandboxBackend,
     sessionGroupId: session.sandboxGroupId,
@@ -98,14 +122,15 @@ export type FleetOperationAvailability = "ready" | "wakeable" | "recovering" | "
  * A fleet member as the agent + the dock see it (the M8b/M9 UI seam — the
  * `sandboxes_list` response entry the dock renders). STABLE shape: the dock keys
  * on `id`, renders `name`/`kind`/`liveness`, and marks `active`. The session's own
- * Modal group box is a synthetic entry with `id: groupId`, `kind: "modal"`, and a
- * null `enrollmentId`; an enrolled machine carries its sandbox + enrollment ids.
+ * managed group box is a synthetic entry with `id: groupId`, its actual
+ * provisioned backend kind, and a null `enrollmentId`; an enrolled machine
+ * carries its sandbox + enrollment ids.
  */
 export type FleetSandboxEntry = {
   /** The sandbox id used as the attach/swap/run_on `target`. For the session's
    *  own group box this is the group id (a null active pointer == this box). */
   id: string;
-  kind: "modal" | "selfhosted";
+  kind: Exclude<SandboxBackend, "none">;
   name: string;
   liveness: FleetLiveness;
   /** True for the session's currently-active sandbox (the routing target). */
@@ -165,6 +190,7 @@ export type FleetSwapResult = {
   reason?: string;
   code?:
     | BackendUnresolvableCode
+    | "invalid_working_directory"
     | "concurrent_swap"
     | "recovery_in_progress"
     | "recovery_degraded"
@@ -191,13 +217,22 @@ async function probeEnrollment(
   services: FleetServices,
   workspaceId: string,
   enrollment: EnrollmentRecord,
-): Promise<{ liveness: FleetLiveness; consented: boolean; hasDisplay: boolean }> {
+  liveConnection: EnrollmentRecord | null = enrollment,
+): Promise<{
+  liveness: FleetLiveness;
+  consented: boolean;
+  hasDisplay: boolean;
+}> {
   const { settings, bus } = services;
   let probeResponded = false;
-  if (enrollment.status === "active") {
+  if (liveConnection?.connectionInstanceId) {
     const session = new SelfhostedSession({
       workspaceId,
       agentId: enrollment.id,
+      connectionInstanceId: liveConnection.connectionInstanceId,
+      // Ping does not touch the filesystem. Use the reported root when present;
+      // older agents can still answer liveness before they reconnect and report it.
+      workspaceRoot: enrollment.workspaceRoot ?? "/",
       controlRpc: controlRpc(bus),
       relay: relayConfigFromSettings(settings),
       timeoutMs: PROBE_TIMEOUT_MS,
@@ -220,29 +255,45 @@ async function probeEnrollment(
     },
     probeResponded,
   });
-  return { liveness: state.state, consented: state.consented, hasDisplay: state.hasDisplay };
+  return {
+    liveness: state.state,
+    consented: state.consented,
+    hasDisplay: state.hasDisplay,
+  };
 }
 
 /**
  * List the fleet: the session's own group box when it has one (a synthetic
  * entry) + the workspace's first-class selfhosted sandboxes (each probed for
  * liveness), each with an `active` marker derived from the session's active
- * pointer. A backend:none session has no synthetic home entry; a null pointer
- * then means no compute is attached.
+ * pointer. A backend:none session and a machine-home session on a deployment
+ * without a managed provider have no synthetic group entry; a null pointer then
+ * means no compute is attached.
  */
 export async function listFleet(
   services: FleetServices,
   ctx: FleetContext,
 ): Promise<FleetListResult> {
   const { db } = services;
+  const resourceAccess = ctx.subjectId
+    ? {
+        accountId: ctx.accountId,
+        workspaceId: ctx.workspaceId,
+        subjectId: ctx.subjectId,
+      }
+    : ctx.workspaceId;
   const pointer = (await readActiveSandbox(db, ctx.workspaceId, ctx.sessionId)) ?? {
     activeSandboxId: null,
     activeEpoch: 0,
   };
 
   const entries: FleetSandboxEntry[] = [];
+  const groupBackend = managedSessionGroupBackend(
+    services.settings.sandboxBackend,
+    ctx.sessionBackend,
+  );
 
-  if (ctx.sessionBackend !== "none") {
+  if (groupBackend) {
     // The session's own group box (the default/home sandbox; null active pointer ==
     // this box). A session/group row is not provider existence. Online requires a
     // warm lease, observed provider existence, and verified workspace readiness.
@@ -273,13 +324,12 @@ export async function listFleet(
         ? "unavailable"
         : groupRecovering
           ? "recovering"
-          : ctx.sessionBackend === "selfhosted"
-            ? "unavailable"
-            : "wakeable";
+          : "wakeable";
+    const presentation = sessionGroupMachinePresentation(groupBackend);
     entries.push({
       id: ctx.sessionGroupId,
-      kind: ctx.sessionBackend === "selfhosted" ? "selfhosted" : "modal",
-      name: "session sandbox",
+      kind: presentation.kind,
+      name: presentation.name,
       liveness: groupOnline ? "online" : groupRecovering ? "reconnecting" : "offline",
       active: groupActive,
       isSessionGroup: true,
@@ -302,20 +352,65 @@ export async function listFleet(
 
   // The workspace's first-class selfhosted sandboxes (enrolled machines). Probe
   // each for liveness; a missing enrollment is offline.
-  const sandboxes = await listSandboxes(db, ctx.workspaceId);
+  const legacySandboxes = await listSandboxes(db, ctx.workspaceId);
+  const enrollments = await listEnrollments(
+    db,
+    ctx.subjectId
+      ? {
+          accountId: ctx.accountId,
+          workspaceId: ctx.workspaceId,
+          subjectId: ctx.subjectId,
+        }
+      : ctx.workspaceId,
+    { status: "active" },
+  );
+  const enrollmentById = new Map(enrollments.map((enrollment) => [enrollment.id, enrollment]));
+  const scopedSandboxes: SandboxRecord[] = enrollments.flatMap((enrollment) =>
+    enrollment.sandboxId
+      ? [
+          {
+            id: enrollment.sandboxId,
+            accountId: enrollment.accountId,
+            workspaceId: enrollment.workspaceId,
+            kind: "selfhosted" as const,
+            name: enrollment.sandboxName ?? `${enrollment.os} machine`,
+            enrollmentId: enrollment.id,
+            createdAt: enrollment.createdAt,
+            updatedAt: enrollment.updatedAt,
+          },
+        ]
+      : [],
+  );
+  const sandboxes = [
+    ...legacySandboxes.filter(
+      (sandbox) => !scopedSandboxes.some((scoped) => scoped.id === sandbox.id),
+    ),
+    ...scopedSandboxes,
+  ];
   for (const sandbox of sandboxes) {
     if (sandbox.kind !== "selfhosted" || !sandbox.enrollmentId) {
       continue;
     }
-    const enrollment = await getEnrollment(db, ctx.workspaceId, sandbox.enrollmentId);
+    const enrollment =
+      enrollmentById.get(sandbox.enrollmentId) ??
+      (await getEnrollment(db, resourceAccess, sandbox.enrollmentId));
     if (!enrollment || enrollment.status !== "active") {
       // Revoked enrollments remain durable audit/history records, but they are
       // intentionally absent from the normal attach/run picker.
       continue;
     }
+    const liveConnection = await getLiveEnrollmentConnection(
+      db,
+      resourceAccess,
+      sandbox.enrollmentId,
+    );
     const probe = enrollment
-      ? await probeEnrollment(services, ctx.workspaceId, enrollment)
-      : { liveness: "offline" as FleetLiveness, consented: false, hasDisplay: false };
+      ? await probeEnrollment(services, sandbox.workspaceId, enrollment, liveConnection)
+      : {
+          liveness: "offline" as FleetLiveness,
+          consented: false,
+          hasDisplay: false,
+        };
     entries.push({
       id: sandbox.id,
       kind: "selfhosted",
@@ -360,29 +455,29 @@ export async function listFleet(
   };
 }
 
-/** Resolve a swap target id → the value `setActiveSandbox` writes. The session's
- *  own group id maps to NULL (the default pointer); a first-class sandbox id is
- *  validated (workspace ownership + liveness) and written verbatim. */
-async function resolveTarget(
+type FleetResourceContext = Pick<FleetContext, "accountId" | "workspaceId" | "subjectId">;
+
+type ResolvedNamedSandboxTarget =
+  | { ok: true; targetSandboxId: string; workspaceRoot?: string }
+  | { ok: false; reason: string; code: BackendUnresolvableCode };
+
+/** Resolve one named sandbox, independent of any existing session pointer. */
+async function resolveNamedSandboxTarget(
   services: FleetServices,
-  ctx: FleetContext,
+  ctx: FleetResourceContext,
   target: string,
-): Promise<
-  | { ok: true; targetSandboxId: string | null }
-  | { ok: false; reason: string; code: BackendUnresolvableCode }
-> {
-  // The session's own group box → the default pointer (null).
-  if (target === ctx.sessionGroupId || target === "session" || target === "default") {
-    if (ctx.sessionBackend === "none") {
-      return {
-        ok: false,
-        reason: "this session has no home sandbox; attach a Connected Machine",
-        code: "unsupported_backend_context",
-      };
-    }
-    return { ok: true, targetSandboxId: null };
-  }
-  const sandbox = await getSandbox(services.db, ctx.workspaceId, target);
+): Promise<ResolvedNamedSandboxTarget> {
+  const sandbox = await getSandbox(
+    services.db,
+    ctx.subjectId
+      ? {
+          accountId: ctx.accountId,
+          workspaceId: ctx.workspaceId,
+          subjectId: ctx.subjectId,
+        }
+      : ctx.workspaceId,
+    target,
+  );
   if (!sandbox) {
     return {
       ok: false,
@@ -402,8 +497,13 @@ async function resolveTarget(
     isSessionGroup: false,
   });
   if (!establishable.ok) {
-    return { ok: false, reason: establishable.reason, code: establishable.code };
+    return {
+      ok: false,
+      reason: establishable.reason,
+      code: establishable.code,
+    };
   }
+  let targetWorkspaceRoot: string | undefined;
   if (sandbox.kind === "selfhosted") {
     if (!sandbox.enrollmentId) {
       return {
@@ -412,7 +512,17 @@ async function resolveTarget(
         code: "offline_enrollment",
       };
     }
-    const enrollment = await getEnrollment(services.db, ctx.workspaceId, sandbox.enrollmentId);
+    const enrollment = await getLiveEnrollmentConnection(
+      services.db,
+      ctx.subjectId
+        ? {
+            accountId: ctx.accountId,
+            workspaceId: ctx.workspaceId,
+            subjectId: ctx.subjectId,
+          }
+        : sandbox.workspaceId,
+      sandbox.enrollmentId,
+    );
     if (!enrollment) {
       return {
         ok: false,
@@ -420,7 +530,15 @@ async function resolveTarget(
         code: "offline_enrollment",
       };
     }
-    const probe = await probeEnrollment(services, ctx.workspaceId, enrollment);
+    if (!enrollment.workspaceRoot) {
+      return {
+        ok: false,
+        reason: `sandbox ${target} has not reported an absolute workspace root; reconnect it with a current agent`,
+        code: "workspace_root_unavailable",
+      };
+    }
+    targetWorkspaceRoot = enrollment.workspaceRoot;
+    const probe = await probeEnrollment(services, sandbox.workspaceId, enrollment, enrollment);
     if (probe.liveness !== "online") {
       return {
         ok: false,
@@ -429,7 +547,86 @@ async function resolveTarget(
       };
     }
   }
-  return { ok: true, targetSandboxId: sandbox.id };
+  return {
+    ok: true,
+    targetSandboxId: sandbox.id,
+    ...(targetWorkspaceRoot ? { workspaceRoot: targetWorkspaceRoot } : {}),
+  };
+}
+
+export type CreateTimeSandboxTargetPreflight =
+  | { ok: true; targetSandboxId: string; workingDir: string | null }
+  | {
+      ok: false;
+      reason: string;
+      code: BackendUnresolvableCode | "invalid_working_directory";
+    };
+
+/**
+ * Validate a named create-time machine target before any session row exists.
+ * The caller still commits the pointer with `setActiveSandbox` inside the
+ * session-create transaction, which rechecks durable ownership/enrollment
+ * authority and closes the remove/revoke race without holding database locks
+ * across the liveness probe.
+ */
+export async function preflightCreateTimeSandboxTarget(
+  services: FleetServices,
+  ctx: FleetResourceContext,
+  target: string,
+  workingDir: string | null,
+): Promise<CreateTimeSandboxTargetPreflight> {
+  const resolved = await resolveNamedSandboxTarget(services, ctx, target);
+  if (!resolved.ok) return resolved;
+  if (!resolved.workspaceRoot) {
+    return {
+      ok: true,
+      targetSandboxId: resolved.targetSandboxId,
+      workingDir,
+    };
+  }
+  try {
+    return {
+      ok: true,
+      targetSandboxId: resolved.targetSandboxId,
+      workingDir:
+        resolveConnectedMachineWorkspaceRoot(resolved.workspaceRoot, workingDir) ??
+        resolved.workspaceRoot,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+      code: "invalid_working_directory",
+    };
+  }
+}
+
+/** Resolve a swap target id → the value `setActiveSandbox` writes. The session's
+ *  own group id maps to NULL (the default pointer); a first-class sandbox id is
+ *  validated (workspace ownership + liveness) and written verbatim. */
+async function resolveTarget(
+  services: FleetServices,
+  ctx: FleetContext,
+  target: string,
+): Promise<
+  | { ok: true; targetSandboxId: string | null; workspaceRoot?: string }
+  | { ok: false; reason: string; code: BackendUnresolvableCode }
+> {
+  // The session's own group box → the default pointer (null).
+  if (target === ctx.sessionGroupId || target === "session" || target === "default") {
+    if (!managedSessionGroupBackend(services.settings.sandboxBackend, ctx.sessionBackend)) {
+      return {
+        ok: false,
+        reason:
+          ctx.sessionBackend === "none"
+            ? "this session has no home sandbox; attach a Connected Machine"
+            : "this deployment has no managed session sandbox; select an enrolled machine",
+        code: "unsupported_backend_context",
+      };
+    }
+    return { ok: true, targetSandboxId: null };
+  }
+  return await resolveNamedSandboxTarget(services, ctx, target);
 }
 
 /**
@@ -482,6 +679,7 @@ export async function swapActiveSandbox(
       const pointer = (await readActiveSandbox(services.db, ctx.workspaceId, ctx.sessionId)) ?? {
         activeSandboxId: null,
         activeEpoch: 0,
+        workingDir: null,
       };
       return {
         swapped: false,
@@ -503,7 +701,27 @@ export async function swapActiveSandbox(
       const pointer = (await readActiveSandbox(services.db, ctx.workspaceId, ctx.sessionId)) ?? {
         activeSandboxId: null,
         activeEpoch: 0,
+        workingDir: null,
       };
+      let effectiveWorkingDir = workingDir;
+      if (resolved.workspaceRoot) {
+        try {
+          effectiveWorkingDir = resolveConnectedMachineWorkspaceRoot(
+            resolved.workspaceRoot,
+            workingDir === undefined && pointer.activeSandboxId === resolved.targetSandboxId
+              ? pointer.workingDir
+              : workingDir,
+          );
+        } catch (error) {
+          return {
+            swapped: false,
+            activeSandboxId: pointer.activeSandboxId,
+            activeEpoch: pointer.activeEpoch,
+            reason: error instanceof Error ? error.message : String(error),
+            code: "invalid_working_directory",
+          };
+        }
+      }
       // Even a same-target attach advances active_epoch. It is a repair/fence
       // request, not a no-op acknowledgment: any cached stale route is invalidated
       // only after target readiness has been proved above.
@@ -513,7 +731,13 @@ export async function swapActiveSandbox(
         sessionId: ctx.sessionId,
         targetSandboxId: resolved.targetSandboxId,
         expectedEpoch: pointer.activeEpoch,
-        ...(workingDir !== undefined ? { workingDir } : {}),
+        ...(ctx.subjectId ? { subjectId: ctx.subjectId } : {}),
+        ...(ctx.attemptAuthority ? { personalMachineAttempt: ctx.attemptAuthority } : {}),
+        ...(resolved.workspaceRoot !== undefined
+          ? { workingDir: effectiveWorkingDir ?? resolved.workspaceRoot }
+          : workingDir !== undefined
+            ? { workingDir }
+            : {}),
       });
       if (result.swapped && result.pointer) {
         return {
@@ -569,6 +793,9 @@ export type RunOnResult = {
 export type RunOnSelfhostedMachine = {
   workspaceId: string;
   agentId: string;
+  /** Exact live daemon pinned for this operation. */
+  connectionInstanceId: string;
+  workspaceRoot: string;
   controlRpc: ControlRpc;
   relay: SelfhostedRelayConfig;
   /** Short request/reply deadline for read/write and other control operations. */
@@ -577,8 +804,50 @@ export type RunOnSelfhostedMachine = {
   execTimeoutMs: number;
   /** Streaming transport required when execTimeoutMs is 0 (unbounded). */
   opStream?: SelfhostedOpStreamDeps;
+  operationResourcePolicy?: SelfhostedOperationResourcePolicy;
+  operationResourcePolicySupported?: boolean;
+  operationCpuQuotaSupported?: boolean;
+  /** Last-boundary authority/connection resolver invoked before every physical
+   * provider operation. */
+  resolveOperationAdmission?: () => Promise<SelfhostedOperationAdmission | null>;
+  /**
+   * Exact-attempt values for this one child process. Never persisted on the
+   * enrollment or machine. The caller may supply these only after authenticating
+   * the active attempt that owns the one-off operation.
+   */
+  transientExecEnvironment?: Readonly<Record<string, string>>;
 };
 
+export type RunOnOptions = {
+  transientExecEnvironment?: Readonly<Record<string, string>>;
+};
+
+function runOnOperationAdmission(
+  services: FleetServices,
+  enrollment: EnrollmentRecord | null,
+): SelfhostedOperationAdmission | null {
+  if (!enrollment?.connectionInstanceId || !enrollment.workspaceRoot) return null;
+  const opStream =
+    services.settings.agentOpStreamEnabled === true &&
+    enrollment.opStream === true &&
+    services.bus?.getOpStreamConnection
+      ? {
+          transport: new NatsOpStreamTransport(
+            async () => services.bus?.getOpStreamConnection?.() ?? null,
+          ),
+        }
+      : undefined;
+  return {
+    workspaceId: enrollment.workspaceId,
+    connectionInstanceId: enrollment.connectionInstanceId,
+    workspaceRoot: enrollment.workspaceRoot,
+    ...(opStream ? { opStream } : {}),
+    operationResourcePolicy: enrollment.operationPolicy,
+    operationResourcePolicySupported: enrollment.agentCapabilities.operationResourcePolicy === true,
+    operationCpuQuotaSupported: enrollment.agentCapabilities.operationCpuQuota === true,
+  };
+}
+
 /**
  * Execute the one-off machine operation once the workspace/enrollment lookup has
  * succeeded. Kept separate from {@link runOnSandbox} so the command/deadline
@@ -593,10 +862,29 @@ export async function executeRunOnSelfhostedMachine(
   const session = new SelfhostedSession({
     workspaceId: machine.workspaceId,
     agentId: machine.agentId,
+    connectionInstanceId: machine.connectionInstanceId,
+    workspaceRoot: machine.workspaceRoot,
     controlRpc: machine.controlRpc,
     relay: machine.relay,
     timeoutMs: machine.controlTimeoutMs,
     execTimeoutMs: machine.execTimeoutMs,
+    ...(machine.operationResourcePolicy !== undefined
+      ? { operationResourcePolicy: machine.operationResourcePolicy }
+      : {}),
+    ...(machine.operationResourcePolicySupported !== undefined
+      ? {
+          operationResourcePolicySupported: machine.operationResourcePolicySupported,
+        }
+      : {}),
+    ...(machine.operationCpuQuotaSupported !== undefined
+      ? { operationCpuQuotaSupported: machine.operationCpuQuotaSupported }
+      : {}),
+    ...(machine.resolveOperationAdmission !== undefined
+      ? { resolveOperationAdmission: machine.resolveOperationAdmission }
+      : {}),
+    ...(machine.transientExecEnvironment !== undefined
+      ? { transientExecEnvironment: () => machine.transientExecEnvironment! }
+      : {}),
     ...(machine.opStream !== undefined ? { opStream: machine.opStream } : {}),
   });
 
@@ -622,7 +910,9 @@ export async function executeRunOnSelfhostedMachine(
         timedOut,
         deadlineMs,
         ...(timedOut
-          ? { reason: `command exceeded the ${deadlineMs} ms execution deadline` }
+          ? {
+              reason: `command exceeded the ${deadlineMs} ms execution deadline`,
+            }
           : !hasTerminalExit
             ? { reason: "machine returned no terminal exit code" }
             : {}),
@@ -630,9 +920,17 @@ export async function executeRunOnSelfhostedMachine(
     }
     if (op.kind === "read") {
       const bytes = await session.readFile({ path: op.path });
-      return { target, kind: "read", ok: true, content: new TextDecoder().decode(bytes) };
+      return {
+        target,
+        kind: "read",
+        ok: true,
+        content: new TextDecoder().decode(bytes),
+      };
     }
-    const bytesWritten = await session.writeFile({ path: op.path, content: op.content });
+    const bytesWritten = await session.writeFile({
+      path: op.path,
+      content: op.content,
+    });
     return { target, kind: "write", ok: true, bytesWritten };
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
@@ -667,8 +965,19 @@ export async function runOnSandbox(
   ctx: FleetContext,
   target: string,
   op: RunOnOp,
+  options: RunOnOptions = {},
 ): Promise<RunOnResult> {
-  const sandbox = await getSandbox(services.db, ctx.workspaceId, target);
+  const sandbox = await getSandbox(
+    services.db,
+    ctx.subjectId
+      ? {
+          accountId: ctx.accountId,
+          workspaceId: ctx.workspaceId,
+          subjectId: ctx.subjectId,
+        }
+      : ctx.workspaceId,
+    target,
+  );
   if (!sandbox) {
     return {
       target,
@@ -686,8 +995,59 @@ export async function runOnSandbox(
       reason: `run_on routes one-off ops to enrolled selfhosted machines; ${sandbox.kind} targets are reached via the active sandbox (swap to it first)`,
     };
   }
-  const enrollment = await getEnrollment(services.db, ctx.workspaceId, sandbox.enrollmentId);
-  if (!enrollment || enrollment.status !== "active") {
+  if (sandbox.scope === "user") {
+    if (!ctx.subjectId || !ctx.attemptAuthority) {
+      return {
+        target,
+        targetName: sandbox.name,
+        kind: op.kind,
+        ok: false,
+        reason: "personal Connected Machine use requires an exact admitted agent attempt",
+      };
+    }
+    try {
+      const authorized = await authorizePersonalMachineForAttempt(services.db, {
+        accountId: ctx.accountId,
+        workspaceId: ctx.workspaceId,
+        subjectId: ctx.subjectId,
+        sessionId: ctx.sessionId,
+        turnId: ctx.attemptAuthority.turnId,
+        attemptId: ctx.attemptAuthority.attemptId,
+        executionGeneration: ctx.attemptAuthority.executionGeneration,
+        enrollmentId: sandbox.enrollmentId,
+        requireActiveSandbox: false,
+      });
+      if (!authorized) {
+        return {
+          target,
+          targetName: sandbox.name,
+          kind: op.kind,
+          ok: false,
+          reason: "personal Connected Machine authority was not admitted for this attempt",
+        };
+      }
+    } catch {
+      return {
+        target,
+        targetName: sandbox.name,
+        kind: op.kind,
+        ok: false,
+        reason: "personal Connected Machine authority is not live for this attempt",
+      };
+    }
+  }
+  const enrollment = await getLiveEnrollmentConnection(
+    services.db,
+    ctx.subjectId
+      ? {
+          accountId: ctx.accountId,
+          workspaceId: ctx.workspaceId,
+          subjectId: ctx.subjectId,
+        }
+      : sandbox.workspaceId,
+    sandbox.enrollmentId,
+  );
+  if (!enrollment || enrollment.status !== "active" || !enrollment.connectionInstanceId) {
     return {
       target,
       targetName: sandbox.name,
@@ -696,15 +1056,65 @@ export async function runOnSandbox(
       reason: `sandbox ${target} is not enrolled/active`,
     };
   }
+  if (!enrollment.workspaceRoot) {
+    return {
+      target,
+      targetName: sandbox.name,
+      kind: op.kind,
+      ok: false,
+      reason: `sandbox ${target} has not reported an absolute workspace root; reconnect it with a current agent`,
+    };
+  }
+  const resolveOperationAdmission = async (): Promise<SelfhostedOperationAdmission | null> => {
+    try {
+      const current =
+        sandbox.scope === "user" && ctx.subjectId && ctx.attemptAuthority
+          ? await resolvePersonalMachineConnectionForAttempt(services.db, {
+              accountId: ctx.accountId,
+              workspaceId: ctx.workspaceId,
+              subjectId: ctx.subjectId,
+              sessionId: ctx.sessionId,
+              turnId: ctx.attemptAuthority.turnId,
+              attemptId: ctx.attemptAuthority.attemptId,
+              executionGeneration: ctx.attemptAuthority.executionGeneration,
+              enrollmentId: sandbox.enrollmentId!,
+              requireActiveSandbox: false,
+            })
+          : await getLiveEnrollmentConnection(
+              services.db,
+              ctx.subjectId
+                ? {
+                    accountId: ctx.accountId,
+                    workspaceId: ctx.workspaceId,
+                    subjectId: ctx.subjectId,
+                  }
+                : sandbox.workspaceId,
+              sandbox.enrollmentId!,
+            );
+      return runOnOperationAdmission(services, current);
+    } catch {
+      return null;
+    }
+  };
 
   const result = await executeRunOnSelfhostedMachine(
     {
-      workspaceId: ctx.workspaceId,
+      workspaceId: sandbox.workspaceId,
       agentId: sandbox.enrollmentId,
+      connectionInstanceId: enrollment.connectionInstanceId,
+      workspaceRoot: enrollment.workspaceRoot,
       controlRpc: controlRpc(services.bus),
       relay: relayConfigFromSettings(services.settings),
       controlTimeoutMs: services.settings.sandboxSelfhostedControlTimeoutMs,
       execTimeoutMs: services.settings.sandboxSelfhostedExecTimeoutMs,
+      operationResourcePolicy: enrollment.operationPolicy,
+      operationResourcePolicySupported:
+        enrollment.agentCapabilities.operationResourcePolicy === true,
+      operationCpuQuotaSupported: enrollment.agentCapabilities.operationCpuQuota === true,
+      resolveOperationAdmission,
+      ...(options.transientExecEnvironment !== undefined
+        ? { transientExecEnvironment: options.transientExecEnvironment }
+        : {}),
       ...(services.settings.agentOpStreamEnabled === true &&
       enrollment.opStream === true &&
       services.bus?.getOpStreamConnection
@@ -749,17 +1159,19 @@ export async function provisionSandbox(
   input: { kind: "selfhosted" | "modal"; name?: string },
 ): Promise<ProvisionResult> {
   if (input.kind === "selfhosted") {
-    const base = (services.settings.publicBaseUrl ?? "https://get.opengeni.ai").replace(/\/+$/, "");
+    const base = (services.settings.publicBaseUrl ?? "https://app.opengeni.ai").replace(/\/+$/, "");
+    const unixEnvironment = `OPENGENI_API_URL=${base} OPENGENI_WORKSPACE_ID=${ctx.workspaceId}`;
+    const windowsEnvironment = `$env:OPENGENI_API_URL='${base}'; $env:OPENGENI_WORKSPACE_ID='${ctx.workspaceId}';`;
     return {
       kind: "selfhosted",
       instructions:
-        "Share these instructions with a human operator. They install the OpenGeni agent on the machine, run `opengeni-agent connect`, complete the device-flow at the verification URL (the loud whole-machine + screen-control consent), and the machine then appears here as an attachable selfhosted sandbox. Existing connections to other OpenGeni workspaces or deployments are preserved.",
+        "Share one of these deployment-specific commands with a human operator. It installs the Opengeni agent and starts `opengeni-agent connect` for this exact deployment and workspace; do not run a second bare `connect`. Complete the device-flow at the verification URL (the loud whole-machine + screen-control consent), and the machine then appears here as an attachable selfhosted sandbox. Existing connections to other Opengeni workspaces or deployments are preserved.",
       // Install from THIS control plane's origin (not a hardcoded public CDN): the
       // served install script is rewritten to pull the per-SHA agent baked into
       // this exact deployment (see apps/api/src/routes/install.ts), so a deployed
       // env is self-contained and a private/air-gapped one works with no public DNS.
-      installCommandUnix: `curl -fsSL ${base}/install.sh | sh`,
-      installCommandWindows: `irm ${base}/install.ps1 | iex`,
+      installCommandUnix: `curl -fsSL ${base}/install.sh | ${unixEnvironment} sh`,
+      installCommandWindows: `${windowsEnvironment} irm ${base}/install.ps1 | iex`,
       verificationUri: `${base}/device`,
       note: "Whole-machine access requires explicit human consent in the device-flow web page; the agent cannot self-consent.",
     };