@ornncompute/cli 1.0.75 → 1.0.107

package/README.md

@@ -7,8 +7,17 @@ sends browser and CLI traffic only through the API gateway.
 For the customer install and usage guide, see [`docs/cli.md`](../../docs/cli.md).
 The shared capability catalog in `packages/capabilities` is the authority for
 command identity, role visibility, input schemas, help, and resource discovery.
-The CLI imports `@ornn/capabilities/cli`; packaging includes only that entrypoint's
-dependencies, excluding staff commerce and CRM handlers.
+The CLI imports `@ornn/capabilities/cli`; packaging includes its dependencies,
+including `@ornn/api-client`, and excludes MCP-only catalog handlers. These
+packages run without workspace links or React.
+
+Native Commerce requests use the caller’s bearer directly through the gateway:
+`/commerce/*` for public APIs and `/internal/v1/*` for staff APIs.
+The gateway and Commerce enforce the caller’s organization and staff permissions.
+All Commerce operations use `@ornn/api-client/commerce`, including the reservation
+reads inside launch, connect, and evidence flows. Customer reservation pickers
+explicitly scope every page to the selected organization, including for staff.
+The gateway retains its Commerce workflow adapters for already-published CLI versions.
 
 For GCS imports, start with the [source-bucket permissions and version-specific CLI guide](https://docs.ornn.com/cli#gcs-imports-and-storage-transfer-service).
 It documents the current CLI 1.x GCS verification limitation. Scoped
@@ -82,6 +91,9 @@ filesystems      deploy | show | wait | delete
 ```
 
 `ssh-keys list` uses backend cursors; see [pagination](../../docs/cli.md#advanced-customer-resources).
+Organization key deletion saves removal on reservation lists before revoking the
+account key. If preparation fails, retry the deletion; re-registering the key
+does not restore its removed reservation access.
 
 Market commands call one gateway route each and print that route's JSON.
 `capacity-offers list|show|terms` reads native Commerce capacity
@@ -104,7 +116,9 @@ CLI does not send them yet), end a fill with
 on a whole primary listing for one of its terms (`--listing-term-id`, optional
 `--duration-seconds`), list the offers your organization made or received, and
 accept or cancel offers by `--offer-id`.
-Prices are integer micro-USD per GPU-hour (`1000000` is $1.00). Writes execute
+Prices are integer micro-USD per GPU-hour (`1000000` is $1.00); CPU capacity
+(a null GPU type, traded on the `cpu` book) is priced and counted per vCPU in
+the same fields. Writes execute
 immediately; use `--format json` for machine-readable output and
 `--idempotency-key` for safe retries. Customer payment methods and
 billing stay in the web app. Launch consumes already allocated
@@ -125,8 +139,10 @@ Reuse the key and payload on retries. Creation requires an eligible human
 terminal. Native capacity creation takes
 `--gpu-slug`, `--gpus-per-node`, `--facility-id`, `--provisioning-type`,
 `--state`, `--terms` (a JSON array) and `--idempotency-key`, plus optional
-`--organization-id`. Give `--capacity-node-count`, or `--node-ids` (a JSON array)
-to attach nodes at creation; the count then defaults to the number of nodes.
+`--organization-id`. CPU capacity takes `--gpu-slug cpu` and
+`--cores-per-node` (a whole number of at least 1; each core is 2 vCPUs) instead
+of `--gpus-per-node`; its term prices are per vCPU-hour. Give
+`--capacity-node-count`, or `--node-ids` (a JSON array) to attach nodes at creation; the count then defaults to the number of nodes.
 Primary capacity takes `--days-to-rfs` (0 when ready now) or both
 `--available-at` and `--available-until`, not both. Reuse the key and the same
 body on retries. Prices are integer micro-USD inside terms, with explicit
@@ -187,6 +203,17 @@ include the final newline required by OpenSSH, both in files and with `--print`.
 `ornn admin nodes enroll` takes optional `--filter COMPARTMENT_IDS`
 (omit to run every compartment step); the retired `--mode` flag is gone. The
 gateway, not CLI metadata, authoritatively enforces the admin role.
+`ornn admin nodes sanitize`, `sanitize-status`, and `sanitize-decide` drive one
+node's held sanitize job, sharing the capability with MCP
+`admin_node_sanitize_*` and Slack `node_sanitize_*`. `sanitize` needs
+`--operation`, its exact `--confirmation` phrase, and `--recovery-uuid` for
+`ram_roundtrip` (refused for `data_wipe`); the job then waits for staff approval.
+`sanitize-decide --confirmation "ACCEPT MANUAL CLEANUP"` also needs
+`--reservation`, `--release-operation` (the Orchestrator release operation),
+`--reason`, `--evidence-file` (only its SHA-256 is sent), and each attestation
+flag: `--tenant-access-revoked`, `--data-drives-sanitized`, and
+`--acknowledge-retained-os`. Sanitize writes run only in an eligible human
+terminal. See [manual cleanup with the boot OS retained](../../docs/provisioning/dedicated-machine-runbook.md#manual-cleanup-with-the-boot-os-retained).
 Suppliers are Authorization supplier organizations: `ornn admin suppliers list`
 returns their `id` and `name`, and `--supplier UUID` on `facilities list`,
 `nodes list`, `enrollment-tokens create`, and `nodes enroll` takes that
@@ -430,3 +457,9 @@ request conflicts, and an expired incomplete request requires a new key.
 `ornn volumes refresh <volume>` reconciles recorded usage against stored files.
 The upload replay contract requires the matching gateway/orchestrator release;
 see [the service contract](../../services/orchestrator/README.md#file-upload-replay-and-usage).
+
+Staff can use `ornn admin ssh <node-id>` for certificate access on explicitly
+opted-in nodes. It requires an interactive staff login, creates a temporary
+local key, obtains a 15-minute certificate through the gateway and launches
+OpenSSH with normal host-key verification. Temporary files are removed when
+the command exits. Shared and per-node key access remain available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ornncompute/cli",
-  "version": "1.0.75",
+  "version": "1.0.107",
   "description": "Command-line interface for Ornn compute access workflows.",
   "type": "module",
   "bin": {
@@ -35,7 +35,9 @@
     "test": "node --test 'test/*.test.mjs'"
   },
   "devDependencies": {
-    "@ornn/capabilities": "0.1.0"
+    "@ornn/api-client": "0.1.0",
+    "@ornn/capabilities": "0.1.0",
+    "esbuild": "^0.28.2"
   },
   "engines": {
     "node": ">=20"

package/src/admin-capacity-reservations.mjs

@@ -153,7 +153,10 @@ function reservationCreateReview(input) {
       { label: "Nodes", value: input.nodes },
       { label: "Starts at", value: input.startsAt },
       { label: "Ends at", value: input.endsAt },
-      { label: "Price per GPU-hour (micro-USD)", value: input.pricePerGpuHourMicroUsd },
+      {
+        label: "Price per unit-hour (micro-USD; per vCPU on CPU capacity)",
+        value: input.pricePerGpuHourMicroUsd,
+      },
       { label: "Idempotency key", value: input.idempotencyKey },
     ],
     consequence:

package/src/admin-command-handlers.mjs

@@ -1,16 +1,20 @@
+import { adminSshHandlers } from "./admin-ssh.mjs";
 import { adminCapacityReservationHandlers } from "./admin-capacity-reservations.mjs";
 import { adminCreditHandlers } from "./admin-credits.mjs";
 import { adminEnrollmentHandlers } from "./admin-enrollment.mjs";
 import { adminNodeDiagnosticsHandlers } from "./admin-node-diagnostics.mjs";
 import { adminNodeLifecycleHandlers } from "./admin-node-lifecycle.mjs";
+import { adminNodeSanitizeHandlers } from "./admin-node-sanitize.mjs";
 import { ADMIN_MUTATION_SAFETY, assertAdminMutationContext } from "./admin-mutations.mjs";
 
 const handlers = [
+  ...adminSshHandlers,
   ...adminCapacityReservationHandlers,
   ...adminCreditHandlers,
   ...adminEnrollmentHandlers,
   ...adminNodeDiagnosticsHandlers,
   ...adminNodeLifecycleHandlers,
+  ...adminNodeSanitizeHandlers,
 ];
 
 export function adminCommandHandler(capability) {

package/src/admin-node-diagnostics.mjs

@@ -112,7 +112,6 @@ function nodeContext(payload, expectedNodeId) {
   }
   const explicitReachability =
     presentString(payload.reachability?.status) ??
-    presentString(payload.off_grid_reachability?.status) ??
     (typeof payload.reachable === "boolean"
       ? payload.reachable
         ? "reachable"
@@ -127,10 +126,7 @@ function nodeContext(payload, expectedNodeId) {
       presentString(payload.status) ??
       "unknown",
     reachability: explicitReachability ?? "unknown",
-    observed_at:
-      presentString(payload.observed_at) ??
-      presentString(payload.last_heartbeat_at) ??
-      presentString(payload.off_grid_reachability?.last_checked_at),
+    observed_at: presentString(payload.observed_at) ?? presentString(payload.last_heartbeat_at),
   };
 }
 

package/src/admin-node-lifecycle.mjs

@@ -1,3 +1,4 @@
+import { getReservation } from "../vendor/api-client/commerce.js";
 import { ADMIN_MUTATION_SAFETY, AdminMutationError, runAdminMutation } from "./admin-mutations.mjs";
 import { isRecoverableWaitFailure } from "./interaction-runtime.mjs";
 import { waitForGoal as waitForReadGoal } from "./wait-runtime.mjs";
@@ -9,8 +10,6 @@ const POLL_INTERVAL_MS = 1_000;
 const COMMAND_BY_CAPABILITY = Object.freeze({
   "nodes.reboot": "reboot",
   "nodes.hard_reset": "hard-reset",
-  "node.off-grid": "suspend-management",
-  "node.on-grid": "resume-management",
   "node.terminate": "terminate",
   "nodes.assign": "assign",
 });
@@ -25,30 +24,18 @@ const USAGE = Object.freeze({
   reboot: "Usage: ornn admin nodes reboot <node-ref> [--no-wait] [--timeout SECONDS]",
   "hard-reset":
     "Usage: ornn admin nodes hard-reset <node-ref> --erase-local-data [--no-wait] [--timeout SECONDS]",
-  "suspend-management":
-    "Usage: ornn admin nodes suspend-management <node-ref> [--reason TEXT] [--idempotency-key KEY] [--wait|--no-wait] [--timeout SECONDS]",
-  "resume-management":
-    "Usage: ornn admin nodes resume-management <node-ref> [--idempotency-key KEY] [--wait|--no-wait] [--timeout SECONDS]",
   terminate:
-    "Usage: ornn admin nodes terminate <node-ref> --delete-node-record [--skip-cleanup] [--reason TEXT] [--idempotency-key KEY]",
+    "Usage: ornn admin nodes terminate <node-ref> --delete-node-record [--reason TEXT] [--idempotency-key KEY]",
   assign:
     "Usage: ornn admin nodes assign <node-ref> --reservation RESERVATION [--idempotency-key KEY] [--wait|--no-wait] [--timeout SECONDS]",
 });
 
-const BOOLEAN_OPTIONS = new Set([
-  "delete-node-record",
-  "erase-local-data",
-  "no-wait",
-  "skip-cleanup",
-  "wait",
-]);
+const BOOLEAN_OPTIONS = new Set(["delete-node-record", "erase-local-data", "no-wait", "wait"]);
 const VALUE_OPTIONS = new Set(["idempotency-key", "reason", "reservation", "timeout"]);
 const ALLOWED_OPTIONS = Object.freeze({
   reboot: new Set(["wait", "no-wait", "timeout"]),
   "hard-reset": new Set(["erase-local-data", "wait", "no-wait", "timeout"]),
-  "suspend-management": new Set(["reason", "idempotency-key", "wait", "no-wait", "timeout"]),
-  "resume-management": new Set(["idempotency-key", "wait", "no-wait", "timeout"]),
-  terminate: new Set(["delete-node-record", "skip-cleanup", "reason", "idempotency-key"]),
+  terminate: new Set(["delete-node-record", "reason", "idempotency-key"]),
   assign: new Set(["reservation", "idempotency-key", "wait", "no-wait", "timeout"]),
 });
 
@@ -152,13 +139,9 @@ export function parseAdminNodeLifecycleInput(command, argv) {
     });
   }
   if (name !== "hard-reset" && options["erase-local-data"]) throw mutationError(usage);
-  if (name !== "terminate" && (options["delete-node-record"] || options["skip-cleanup"])) {
-    throw mutationError(usage);
-  }
+  if (name !== "terminate" && options["delete-node-record"]) throw mutationError(usage);
   if (name !== "assign" && options.reservation) throw mutationError(usage);
-  if (!name.includes("management") && name !== "terminate" && options.reason) {
-    throw mutationError(usage);
-  }
+  if (name !== "terminate" && options.reason) throw mutationError(usage);
 
   const idempotencyKey = options["idempotency-key"]?.trim();
   const safety =
@@ -173,12 +156,7 @@ export function parseAdminNodeLifecycleInput(command, argv) {
       ...(options.wait ? { wait: true } : options["no-wait"] ? { wait: false } : {}),
       ...(options.timeout ? { timeout_seconds: durationSeconds(options.timeout, usage) } : {}),
       ...(name === "hard-reset" ? { erase_local_data: true } : {}),
-      ...(name === "terminate"
-        ? {
-            delete_node_record: true,
-            ...(options["skip-cleanup"] ? { skip_cleanup: true } : {}),
-          }
-        : {}),
+      ...(name === "terminate" ? { delete_node_record: true } : {}),
       ...(name === "assign" ? { reservation_id: options.reservation } : {}),
     },
     mutation: {
@@ -209,16 +187,7 @@ function nodeSnapshot(node) {
     organization_id: text(node?.organization_id),
     facility_id: text(node?.facility_id ?? node?.facilityId),
     reservation_id: reservationId(node),
-    off_grid: node?.off_grid === true,
     cleanup_state: text(node?.cleanup_state),
-    reachability:
-      node?.reachable === false || node?.health_readiness?.reachable === false
-        ? "unreachable"
-        : text(
-            node?.reachability?.status ??
-              node?.off_grid_reachability?.status ??
-              node?.health_readiness?.reachability
-          ),
   };
 }
 
@@ -226,18 +195,6 @@ function sameSnapshot(left, right) {
   return JSON.stringify(nodeSnapshot(left)) === JSON.stringify(nodeSnapshot(right));
 }
 
-function isOffGrid(node) {
-  const snapshot = nodeSnapshot(node);
-  return snapshot.off_grid || ["off-grid", "off_grid"].includes(snapshot.status.toLowerCase());
-}
-
-function isUnreachable(node) {
-  const snapshot = nodeSnapshot(node);
-  return (
-    isOffGrid(node) || ["unreachable", "offline"].includes(snapshot.reachability.toLowerCase())
-  );
-}
-
 function nodeRows(payload) {
   if (Array.isArray(payload)) return payload;
   return Array.isArray(payload?.nodes) ? payload.nodes : [];
@@ -348,20 +305,18 @@ async function resolveLiveMachine(fetch, node) {
 function reservationSnapshot(reservation, requestedId) {
   return {
     reservation_id: text(reservation?.reservationId) || requestedId,
-    organization_id: text(reservation?.organizationId),
+    organization_id: text(reservation?.customerId ?? reservation?.organizationId),
     listing_id: text(reservation?.listingId),
     kind: text(reservation?.kind),
     status: text(reservation?.status),
-    node_count: Number(reservation?.nodeCount ?? 0) || 0,
+    node_count: Number(reservation?.reservedNodeCount ?? 0) || 0,
     starts_at: text(reservation?.startsAt),
     ends_at: text(reservation?.endsAt),
   };
 }
 
 async function readReservation(fetch, id) {
-  const reservation = await fetch(`/commerce/reservations/${encodeURIComponent(id)}`, {
-    method: "GET",
-  });
+  const reservation = await getReservation(fetch, id);
   return reservationSnapshot(reservation, id);
 }
 
@@ -403,11 +358,9 @@ function safeOwnerResult(result) {
   const safe = {};
   for (const key of [
     "deleted",
-    "forced",
     "id",
     "mode",
     "node_id",
-    "off_grid",
     "packet_id",
     "request_id",
     "reservation_id",
@@ -475,47 +428,13 @@ async function prepareLifecycle({ command, fetch, input, machine }) {
     };
   }
 
-  if (command === "suspend-management") {
-    fields.push({ label: "Host power", value: "leave powered on" });
-    fields.push({ label: "Managed access", value: "remove agent management and managed SSH keys" });
-    if (input.reason) fields.push({ label: "Reason", value: input.reason });
-    return {
-      review: {
-        title: "Review management suspension",
-        fields,
-        consequence: "Ornn management and managed access end while the host remains powered on.",
-      },
-      value,
-    };
-  }
-
-  if (command === "resume-management") {
-    fields.push({ label: "Management", value: "remotely re-enroll the node" });
-    fields.push({ label: "Managed access", value: "restore after successful enrollment" });
-    return {
-      review: {
-        title: "Review management resumption",
-        fields,
-        consequence: "Ornn uses the stored admin access to reinstall management on this host.",
-      },
-      value,
-    };
-  }
-
   if (command === "terminate") {
-    if (input.skip_cleanup && !isUnreachable(node)) {
-      throw mutationError(
-        "--skip-cleanup is allowed only when the authoritative node read says the node is unreachable or off-grid.",
-        { code: "skip_cleanup_requires_unreachable", field: "skip-cleanup" }
-      );
-    }
     fields.push({
       label: "Host cleanup",
-      value: input.skip_cleanup
-        ? "SKIP; the node is authoritatively unreachable/off-grid"
-        : "not dispatched by termination; complete any required host wipe separately before reuse",
+      value:
+        "not dispatched by termination; complete any required host wipe separately before reuse",
     });
-    fields.push({ label: "Node record", value: "PERMANENTLY DELETE" });
+    fields.push({ label: "Node record", value: "MARK TERMINATED" });
     fields.push({
       label: "Reservation/capacity consequence",
       value: reservationId(node)
@@ -529,7 +448,7 @@ async function prepareLifecycle({ command, fetch, input, machine }) {
         title: "Review node termination",
         fields,
         consequence:
-          "The node record is permanently deleted; this does not cancel its capacity reservation.",
+          "The node record is marked terminated; this does not cancel its capacity reservation.",
       },
       value,
     };
@@ -573,11 +492,11 @@ async function reconcileLifecycle({ fetch, input, value }) {
         data: { node_id: id, status: "already_absent", deleted: false },
       };
     }
-    if (input.skip_cleanup && !isUnreachable(current)) {
+    // Terminate keeps the record, so a re-run finds it terminated, not gone.
+    if (isTerminated(current)) {
       return {
-        status: "conflict",
-        message:
-          "The node is no longer authoritatively unreachable/off-grid; renew review without --skip-cleanup.",
+        status: "satisfied",
+        data: { node_id: id, status: "terminated", deleted: true },
       };
     }
     if (!sameSnapshot(reviewedNode, current)) {
@@ -590,29 +509,6 @@ async function reconcileLifecycle({ fetch, input, value }) {
   }
   if (!current) return { status: "conflict", message: "The exact node no longer exists." };
 
-  if (command === "suspend-management") {
-    if (isOffGrid(current)) {
-      return { status: "satisfied", data: { node_id: id, status: "off-grid", off_grid: true } };
-    }
-    if (!sameSnapshot(reviewedNode, current)) {
-      return { status: "conflict", message: "The node's management goal changed after review." };
-    }
-    return { status: "apply" };
-  }
-
-  if (command === "resume-management") {
-    if (!isOffGrid(current)) {
-      return {
-        status: "satisfied",
-        data: { node_id: id, status: nodeSnapshot(current).status, off_grid: false },
-      };
-    }
-    if (!sameSnapshot(reviewedNode, current)) {
-      return { status: "conflict", message: "The node's management goal changed after review." };
-    }
-    return { status: "apply" };
-  }
-
   if (command === "assign") {
     const currentReservation = reservationId(current);
     if (currentReservation === input.reservation_id) {
@@ -660,15 +556,17 @@ async function reconcileLifecycle({ fetch, input, value }) {
 }
 
 function goalSatisfied(command, node, input) {
-  if (command === "terminate") return node === null;
+  if (command === "terminate") return node === null || isTerminated(node);
   if (!node) return false;
-  if (command === "suspend-management") return isOffGrid(node);
-  if (command === "resume-management") return !isOffGrid(node);
   if (command === "assign") return reservationId(node) === input.reservation_id;
   if (cleanupState(node) === "failed") return false;
   return !restartInProgress(node);
 }
 
+function isTerminated(node) {
+  return text(node?.status).toLowerCase() === "terminated";
+}
+
 function cleanupState(node) {
   return text(node?.cleanup_state).toLowerCase();
 }

package/src/admin-node-sanitize.mjs

@@ -0,0 +1,243 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+import { ADMIN_MUTATION_SAFETY, AdminMutationError, runAdminMutation } from "./admin-mutations.mjs";
+import { parseSemanticArguments } from "./interaction-runtime.mjs";
+
+const MANUAL_CLEANUP = "ACCEPT MANUAL CLEANUP";
+
+function usageError(capability, detail, field) {
+  return new AdminMutationError(
+    [`Usage: ${capability.cli.vnext.human}`, detail].filter(Boolean).join("\n"),
+    { code: "usage_error", ...(field ? { field } : {}) }
+  );
+}
+
+function semanticArguments(argv, capability) {
+  const { $positionals, ...options } = parseSemanticArguments(argv);
+  if ($positionals.length !== 1 || !$positionals[0]) {
+    throw usageError(capability, "Pass exactly one canonical node ID.", "node-id");
+  }
+  return { nodeId: $positionals[0], options };
+}
+
+function rejectExtra(capability, extra) {
+  const [name] = Object.keys(extra);
+  if (name) throw usageError(capability, `Unknown option: --${name}`, name);
+}
+
+function validated(capability, input) {
+  const parsed = capability.input.safeParse(input);
+  if (!parsed.success) throw usageError(capability, parsed.error.message);
+  return parsed.data;
+}
+
+function evidenceSha256(capability, path) {
+  try {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+  } catch (error) {
+    throw usageError(
+      capability,
+      `Could not read --evidence-file: ${error instanceof Error ? error.message : String(error)}`,
+      "evidence-file"
+    );
+  }
+}
+
+function parseStart(argv, capability) {
+  const {
+    nodeId,
+    options: { operation, confirmation, jobId, batch, recoveryUuid, ...extra },
+  } = semanticArguments(argv, capability);
+  rejectExtra(capability, extra);
+  if (typeof operation !== "string") throw usageError(capability, "--operation is required.");
+  const input = validated(capability, {
+    node_id: nodeId,
+    job_id: jobId ?? randomUUID(),
+    operation,
+    ...(batch ? { maintenance_batch_id: batch } : {}),
+    ...(recoveryUuid ? { recovery_uuid: recoveryUuid } : {}),
+    confirmation,
+  });
+  return {
+    input,
+    mutation: { idempotencyKey: input.job_id, safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly },
+  };
+}
+
+function parseStatus(argv, capability) {
+  const {
+    nodeId,
+    options: { job, ...extra },
+  } = semanticArguments(argv, capability);
+  rejectExtra(capability, extra);
+  return { input: validated(capability, { node_id: nodeId, job_id: job }) };
+}
+
+function parseDecision(argv, capability) {
+  const {
+    nodeId,
+    options: {
+      job,
+      confirmation,
+      reservation,
+      releaseOperation,
+      reason,
+      evidenceFile,
+      tenantAccessRevoked,
+      dataDrivesSanitized,
+      acknowledgeRetainedOs,
+      ...extra
+    },
+  } = semanticArguments(argv, capability);
+  rejectExtra(capability, extra);
+  const cleanupOptions = {
+    reservation,
+    releaseOperation,
+    reason,
+    evidenceFile,
+    tenantAccessRevoked,
+    dataDrivesSanitized,
+    acknowledgeRetainedOs,
+  };
+  if (confirmation !== MANUAL_CLEANUP) {
+    const [supplied] =
+      Object.entries(cleanupOptions).find(([, value]) => value !== undefined) ?? [];
+    if (supplied) {
+      throw usageError(
+        capability,
+        `Manual cleanup options require --confirmation "${MANUAL_CLEANUP}".`
+      );
+    }
+    return {
+      input: validated(capability, { node_id: nodeId, job_id: job, confirmation }),
+      mutation: { safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly },
+    };
+  }
+  // Each attestation is the operator's own flag, never a default.
+  for (const [name, value] of Object.entries(cleanupOptions)) {
+    if (value === undefined || value === "") {
+      const flag = name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+      throw usageError(capability, `--${flag} is required for manual cleanup.`, flag);
+    }
+  }
+  const input = validated(capability, {
+    node_id: nodeId,
+    job_id: job,
+    confirmation,
+    manual_cleanup: {
+      reservation_id: reservation,
+      lifecycle_operation_id: releaseOperation,
+      reason,
+      evidence_sha256: evidenceSha256(capability, evidenceFile),
+      acknowledge_retained_os: true,
+      tenant_access_revoked: true,
+      data_drives_sanitized: true,
+    },
+  });
+  return { input, mutation: { safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly } };
+}
+
+const startConsequence = {
+  data_wipe: "Erases every local data drive; the OS drive is preserved.",
+  ram_roundtrip: "Boots the node through RAM and back without erasing drives.",
+  node_turnover: "Erases the whole node, including the OS drive, and restores a host image.",
+  host_restore: "Restores the host OS from its trusted image.",
+};
+
+function decisionReview(input) {
+  const fields = [
+    { label: "Node", value: input.node_id },
+    { label: "Sanitize job", value: input.job_id },
+    { label: "Decision", value: input.confirmation },
+  ];
+  if (input.confirmation === "APPROVE SANITIZATION") {
+    return { fields, consequence: "Starts the held destructive maintenance on this node." };
+  }
+  if (input.confirmation === "SKIP SANITIZATION") {
+    return {
+      fields,
+      consequence: "Skips an eligible first-use wipe; nothing is erased or certified.",
+    };
+  }
+  const cleanup = input.manual_cleanup;
+  return {
+    fields: [
+      ...fields,
+      { label: "Reservation", value: cleanup.reservation_id },
+      { label: "Release operation", value: cleanup.lifecycle_operation_id },
+      { label: "Reason", value: cleanup.reason },
+      { label: "Evidence SHA-256", value: cleanup.evidence_sha256 },
+      {
+        label: "You attest",
+        value:
+          "tenant access revoked; every local data drive sanitized; existing OS retained and not certified",
+      },
+    ],
+    consequence:
+      "Lets the held release finish without a full wipe. The boot disk and prior root exposure remain.",
+  };
+}
+
+async function runStart({ execute, input, mutation, runtime }) {
+  return runAdminMutation({
+    ...runtime,
+    ...mutation,
+    prepare: async () => ({
+      review: {
+        title: "Start node sanitization",
+        fields: [
+          { label: "Node", value: input.node_id },
+          { label: "Operation", value: input.operation ?? "data_wipe" },
+          ...(input.recovery_uuid ? [{ label: "Recovery UUID", value: input.recovery_uuid }] : []),
+          { label: "Sanitize job", value: input.job_id },
+          { label: "Confirmation", value: input.confirmation },
+        ],
+        consequence: `${startConsequence[input.operation ?? "data_wipe"]} The job waits for staff approval.`,
+      },
+      value: input,
+    }),
+    execute: (value) => execute(value, { confirmed: true }),
+  });
+}
+
+async function runStatus({ execute, input }) {
+  return {
+    data: await execute(input),
+    exitCode: 0,
+    outcome: { class: "ready", phase: "complete" },
+  };
+}
+
+async function runDecision({ execute, input, mutation, runtime }) {
+  return runAdminMutation({
+    ...runtime,
+    ...mutation,
+    prepare: async () => ({
+      review: { title: "Decide node sanitize job", ...decisionReview(input) },
+      value: input,
+    }),
+    execute: (value) => execute(value, { confirmed: true }),
+  });
+}
+
+export const adminNodeSanitizeHandlers = [
+  {
+    capabilityId: "node.sanitize.start",
+    parse: parseStart,
+    run: runStart,
+    safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+  },
+  {
+    capabilityId: "node.sanitize.show",
+    parse: parseStatus,
+    run: runStatus,
+    safety: ADMIN_MUTATION_SAFETY.direct,
+  },
+  {
+    capabilityId: "node.sanitize.update",
+    parse: parseDecision,
+    run: runDecision,
+    safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+  },
+];