@rehearsal-db/core 0.1.0-beta.12 → 0.1.0-beta.13

package/src/baseline/artifact.mjs

@@ -372,12 +372,35 @@ export const createAndActivateBaseline = async ({
     }
     return manifest;
   } catch (error) {
+    let cleanupFailure;
     if (dataHandle) await dataHandle.close().catch(() => undefined);
-    await chmod(buildDirectory, 0o700).catch(() => undefined);
-    await rm(buildDirectory, { recursive: true, force: true });
+    await makeArtifactTreeWritable(buildDirectory).catch(() => undefined);
+    await rm(buildDirectory, { recursive: true, force: true }).catch(
+      (cleanupError) => {
+        cleanupFailure = cleanupError;
+      },
+    );
     if (finalCreated) {
-      await chmod(finalDirectory, 0o700).catch(() => undefined);
-      await rm(finalDirectory, { recursive: true, force: true });
+      await makeArtifactTreeWritable(finalDirectory).catch(() => undefined);
+      await rm(finalDirectory, { recursive: true, force: true }).catch(
+        (cleanupError) => {
+          cleanupFailure ??= cleanupError;
+        },
+      );
+    }
+    if (
+      cleanupFailure &&
+      error &&
+      (typeof error === "object" || typeof error === "function")
+    ) {
+      try {
+        Object.defineProperty(error, "cleanupError", {
+          value: cleanupFailure,
+          enumerable: false,
+        });
+      } catch {
+        // Preserve the preparation failure even when its Error is immutable.
+      }
     }
     throw error;
   }

package/src/baseline/privacy_engine.mjs

@@ -22,6 +22,7 @@ const ACTIONS = new Set([
 const PSEUDONYM_FORMATS = new Set(["uuid", "email", "text", "integer"]);
 const DERIVATION_KINDS = new Set([
   "date-shift",
+  "path-map",
   "json-object",
   "json-array",
   "approved-owner",
@@ -29,6 +30,8 @@ const DERIVATION_KINDS = new Set([
 const KEY_BYTES = 32;
 const DEFAULT_JSON_MAXIMUM_BYTES = 65_536;
 const DEFAULT_JSON_MAXIMUM_DEPTH = 8;
+const DEFAULT_PATH_MAXIMUM_BYTES = 2_048;
+const DEFAULT_PATH_MAXIMUM_SEGMENTS = 32;
 const MAXIMUM_POLICY_DEPTH = 16;
 
 const isObject = (value) =>
@@ -142,6 +145,8 @@ const validateRecipe = (action, recipe, label, depth = 0) => {
     [
       "kind",
       "days",
+      "group",
+      "mapping",
       "fields",
       "items",
       "approved",
@@ -158,12 +163,32 @@ const validateRecipe = (action, recipe, label, depth = 0) => {
   }
   if (recipe.kind === "date-shift") {
     const days = positiveInteger(recipe.days, `${label}.recipe.days`, 3_650);
-    if (Object.keys(recipe).some((key) => !["kind", "days"].includes(key))) {
+    if (
+      Object.keys(recipe).some(
+        (key) => !["kind", "days", "group"].includes(key),
+      )
+    ) {
       throw new Error(
         `${label}.recipe contains fields not used by date-shift.`,
       );
     }
-    return Object.freeze({ kind: "date-shift", days });
+    if (recipe.group !== undefined && !BINDING_NAME.test(recipe.group)) {
+      throw new Error(`${label}.recipe.group is invalid.`);
+    }
+    return Object.freeze({
+      kind: "date-shift",
+      days,
+      ...(recipe.group === undefined ? {} : { group: recipe.group }),
+    });
+  }
+  if (recipe.kind === "path-map") {
+    if (Object.keys(recipe).some((key) => !["kind", "mapping"].includes(key))) {
+      throw new Error(`${label}.recipe contains fields not used by path-map.`);
+    }
+    if (!BINDING_NAME.test(recipe.mapping ?? "")) {
+      throw new Error(`${label}.recipe.mapping is invalid.`);
+    }
+    return Object.freeze({ kind: "path-map", mapping: recipe.mapping });
   }
   if (recipe.kind === "approved-owner") {
     if (
@@ -280,7 +305,14 @@ export const validateExecutablePrivacyPolicy = (policy) => {
   if (!isObject(policy)) throw new Error("Privacy policy must be an object.");
   knownKeys(
     policy,
-    ["policyVersion", "draft", "migrationCutoff", "bindings", "tables"],
+    [
+      "policyVersion",
+      "draft",
+      "migrationCutoff",
+      "bindings",
+      "pathMappings",
+      "tables",
+    ],
     "policy",
   );
   if (policy.policyVersion !== 2) {
@@ -323,6 +355,60 @@ export const validateExecutablePrivacyPolicy = (policy) => {
       return [name, Object.freeze({ ...binding })];
     }),
   );
+  if (policy.pathMappings !== undefined && !isObject(policy.pathMappings)) {
+    throw new Error("policy.pathMappings must be an object.");
+  }
+  const pathMappings = Object.fromEntries(
+    Object.entries(policy.pathMappings ?? {}).map(([name, mapping]) => {
+      const label = `policy.pathMappings.${name}`;
+      if (!BINDING_NAME.test(name) || !isObject(mapping)) {
+        throw new Error("policy.pathMappings contains an invalid mapping.");
+      }
+      knownKeys(
+        mapping,
+        [
+          "binding",
+          "format",
+          "namespace",
+          "maxLength",
+          "maximumBytes",
+          "maximumSegments",
+        ],
+        label,
+      );
+      if (!Object.hasOwn(bindings, mapping.binding ?? "")) {
+        throw new Error(`${label}.binding references an unknown binding.`);
+      }
+      if (!["uuid", "text"].includes(mapping.format)) {
+        throw new Error(`${label}.format must be uuid or text.`);
+      }
+      const normalized = {
+        binding: mapping.binding,
+        format: mapping.format,
+        namespace: nonEmpty(mapping.namespace, `${label}.namespace`),
+        maximumBytes: positiveInteger(
+          mapping.maximumBytes ?? DEFAULT_PATH_MAXIMUM_BYTES,
+          `${label}.maximumBytes`,
+          16_384,
+        ),
+        maximumSegments: positiveInteger(
+          mapping.maximumSegments ?? DEFAULT_PATH_MAXIMUM_SEGMENTS,
+          `${label}.maximumSegments`,
+          256,
+        ),
+      };
+      if (mapping.format === "text") {
+        normalized.maxLength = positiveInteger(
+          mapping.maxLength,
+          `${label}.maxLength`,
+          1_024,
+        );
+      } else if (mapping.maxLength !== undefined) {
+        throw new Error(`${label}.maxLength is supported only for text.`);
+      }
+      return [name, Object.freeze(normalized)];
+    }),
+  );
   const names = new Set();
   const tables = policy.tables.map((table, tableIndex) => {
     const label = `policy.tables[${tableIndex}]`;
@@ -423,12 +509,9 @@ export const validateExecutablePrivacyPolicy = (policy) => {
         throw new Error(`${label}.ownerBinding references an unknown column.`);
       }
       const ownerColumn = columns.find((entry) => entry.name === column);
-      if (
-        ownerColumn.action !== "PSEUDONYMIZE" ||
-        ownerColumn.identity !== "YES"
-      ) {
+      if (ownerColumn.action !== "PSEUDONYMIZE") {
         throw new Error(
-          `${label}.ownerBinding column must be an explicitly pseudonymized identity.`,
+          `${label}.ownerBinding column must be explicitly pseudonymized.`,
         );
       }
       ownerBinding = Object.freeze({ binding, column });
@@ -442,6 +525,31 @@ export const validateExecutablePrivacyPolicy = (policy) => {
     if (columns.some(usesApprovedOwner) && !ownerBinding) {
       throw new Error(`${label} uses approved-owner without ownerBinding.`);
     }
+    const visitRecipes = (declaration, visit) => {
+      visit(declaration.recipe);
+      if (declaration.recipe?.kind === "approved-owner") {
+        visitRecipes(declaration.recipe.approved, visit);
+        visitRecipes(declaration.recipe.otherwise, visit);
+      } else if (declaration.recipe?.kind === "json-object") {
+        Object.values(declaration.recipe.fields).forEach((nested) =>
+          visitRecipes(nested, visit),
+        );
+      } else if (declaration.recipe?.kind === "json-array") {
+        visitRecipes(declaration.recipe.items, visit);
+      }
+    };
+    for (const column of columns) {
+      visitRecipes(column, (recipe) => {
+        if (
+          recipe?.kind === "path-map" &&
+          !Object.hasOwn(pathMappings, recipe.mapping)
+        ) {
+          throw new Error(
+            `${label} references unknown path mapping ${recipe.mapping}.`,
+          );
+        }
+      });
+    }
     return Object.freeze({
       schema,
       name,
@@ -450,10 +558,33 @@ export const validateExecutablePrivacyPolicy = (policy) => {
       columns: Object.freeze(columns),
     });
   });
+  const dateShiftGroups = new Map();
+  const visitDateShiftGroups = (declaration) => {
+    const recipe = declaration.recipe;
+    if (recipe?.kind === "date-shift" && recipe.group) {
+      const existing = dateShiftGroups.get(recipe.group);
+      if (existing !== undefined && existing !== recipe.days) {
+        throw new Error(
+          `Privacy date-shift group ${recipe.group} must use one days value.`,
+        );
+      }
+      dateShiftGroups.set(recipe.group, recipe.days);
+    }
+    if (recipe?.kind === "approved-owner") {
+      visitDateShiftGroups(recipe.approved);
+      visitDateShiftGroups(recipe.otherwise);
+    } else if (recipe?.kind === "json-object") {
+      Object.values(recipe.fields).forEach(visitDateShiftGroups);
+    } else if (recipe?.kind === "json-array") {
+      visitDateShiftGroups(recipe.items);
+    }
+  };
+  tables.forEach((table) => table.columns.forEach(visitDateShiftGroups));
   return Object.freeze({
     policyVersion: 2,
     migrationCutoff: policy.migrationCutoff,
     bindings: Object.freeze(bindings),
+    pathMappings: Object.freeze(pathMappings),
     tables: Object.freeze(tables),
   });
 };
@@ -485,6 +616,47 @@ const pseudonym = (key, recipe, value) => {
   return token.slice(0, recipe.maxLength);
 };
 
+const remapPath = ({ key, mapping, bindingValue, value, label }) => {
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a Storage-style path string.`);
+  }
+  if (Buffer.byteLength(value) > mapping.maximumBytes) {
+    throw new Error(`${label} exceeds its reviewed byte limit.`);
+  }
+  const segments = value.split("/");
+  if (
+    !value ||
+    value.startsWith("/") ||
+    value.endsWith("/") ||
+    segments.length > mapping.maximumSegments ||
+    segments.some((segment) => !segment || segment === "." || segment === "..")
+  ) {
+    throw new Error(`${label} is not a safe bounded Storage path.`);
+  }
+  if (
+    typeof bindingValue !== "string" ||
+    !bindingValue ||
+    bindingValue.includes("/") ||
+    bindingValue === "." ||
+    bindingValue === ".."
+  ) {
+    throw new Error(`${label} has an invalid reviewed identity binding.`);
+  }
+  if (segments[0] !== bindingValue) {
+    throw new Error(
+      `${label} does not begin with its exact reviewed identity.`,
+    );
+  }
+  const destination = [
+    String(pseudonym(key, mapping, bindingValue)),
+    ...segments.slice(1),
+  ].join("/");
+  if (Buffer.byteLength(destination) > mapping.maximumBytes) {
+    throw new Error(`${label} destination exceeds its reviewed byte limit.`);
+  }
+  return destination;
+};
+
 const assertJsonBounds = (value, recipe, path) => {
   let bytes = 0;
   const jsonStringBytes = (string) => {
@@ -545,6 +717,8 @@ const executeDeclaration = ({
   key,
   path,
   ownerApproved,
+  pathMappings,
+  bindingValues,
 }) => {
   if (declaration.action === "KEEP") return value;
   if (declaration.action === "EXCLUDE") return undefined;
@@ -558,10 +732,26 @@ const executeDeclaration = ({
     const date = new Date(value);
     if (!Number.isFinite(date.valueOf()))
       throw new Error(`${path} is not a valid date.`);
-    const direction = digest(key, path, value)[0] % 2 === 0 ? -1 : 1;
+    const direction = declaration.recipe.group
+      ? digest(key, "date-shift-group", declaration.recipe.group)[0] % 2 === 0
+        ? -1
+        : 1
+      : digest(key, path, value)[0] % 2 === 0
+        ? -1
+        : 1;
     date.setUTCDate(date.getUTCDate() + direction * declaration.recipe.days);
     return date.toISOString();
   }
+  if (declaration.recipe.kind === "path-map") {
+    const mapping = pathMappings[declaration.recipe.mapping];
+    return remapPath({
+      key,
+      mapping,
+      bindingValue: bindingValues.get(mapping.binding),
+      value,
+      label: path,
+    });
+  }
   if (declaration.recipe.kind === "approved-owner") {
     if (ownerApproved === undefined) {
       throw new Error(`${path} has no reviewed owner condition.`);
@@ -574,6 +764,8 @@ const executeDeclaration = ({
       key,
       path,
       ownerApproved,
+      pathMappings,
+      bindingValues,
     });
   }
   if (value === null && declaration.recipe.allowNull) return null;
@@ -587,6 +779,8 @@ const executeDeclaration = ({
         key,
         path: `${path}[${index}]`,
         ownerApproved,
+        pathMappings,
+        bindingValues,
       });
       return transformed === undefined ? [] : [transformed];
     });
@@ -611,6 +805,8 @@ const executeDeclaration = ({
         key,
         path: `${path}.${field}`,
         ownerApproved,
+        pathMappings,
+        bindingValues,
       });
       return transformed === undefined ? [] : [[field, transformed]];
     }),
@@ -652,6 +848,19 @@ export const createPrivacyEngine = ({
   );
   return Object.freeze({
     keyFingerprint: createHash("sha256").update(secret).digest("hex"),
+    remapPath({ mapping: mappingName, value }) {
+      const mapping = normalized.pathMappings[mappingName];
+      if (!mapping) {
+        throw new Error(`Privacy path mapping ${mappingName} is not declared.`);
+      }
+      return remapPath({
+        key: secret,
+        mapping,
+        bindingValue: bindingValues.get(mapping.binding),
+        value,
+        label: `Privacy path mapping ${mappingName}`,
+      });
+    },
     sanitize(record) {
       if (
         !isObject(record) ||
@@ -692,6 +901,8 @@ export const createPrivacyEngine = ({
             key: secret,
             path: `${relation}.${column.name}`,
             ownerApproved,
+            pathMappings: normalized.pathMappings,
+            bindingValues,
           });
           return transformed === undefined ? [] : [[column.name, transformed]];
         }),

package/src/cli/arguments.mjs

@@ -4,6 +4,7 @@ export const parseArguments = (arguments_) => {
   const flags = {
     json: false,
     help: false,
+    version: false,
     verbosity: "normal",
     dryRun: false,
     write: false,
@@ -30,6 +31,8 @@ export const parseArguments = (arguments_) => {
   for (const argument of arguments_) {
     if (argument === "--json") flags.json = true;
     else if (argument === "--help" || argument === "-h") flags.help = true;
+    else if (argument === "--version" || argument === "-V")
+      flags.version = true;
     else if (argument === "--verbose") flags.verbosity = "verbose";
     else if (argument === "--debug") flags.verbosity = "debug";
     else if (argument === "--dry-run") flags.dryRun = true;

package/src/cli/guided.mjs

@@ -31,6 +31,7 @@ import {
 } from "../baseline/policy_review.mjs";
 import { formatCount } from "../shared/human_output.mjs";
 import { redactDiagnosticValue } from "../shared/diagnostics.mjs";
+import { REHEARSAL_NODE_LABEL } from "../shared/node_runtime.mjs";
 import {
   renderBaselineInputInspection,
   renderBaselinePreparation,
@@ -336,7 +337,7 @@ const guidedOptions = (state, hasLastDetails) => {
   const options = [];
   if (!state.node.supported) {
     options.push({
-      label: "Show Node.js 24 setup instructions",
+      label: "Show supported Node.js versions",
       hint: "Required before Rehearsal can change this project",
       command: "node-help",
     });
@@ -427,7 +428,7 @@ const showGuidedStatus = ({ state, options, flags }) => {
   const marker = (complete) =>
     complete ? terminalStyle(flags, "32", "✓") : terminalStyle(flags, "2", "○");
   const statusLines = [
-    `${marker(state.node.supported)} Node.js ${state.node.version}${state.node.supported ? "" : " (Node.js 24 required)"}`,
+    `${marker(state.node.supported)} Node.js ${state.node.version}${state.node.supported ? "" : ` (${REHEARSAL_NODE_LABEL} required)`}`,
     `${marker(state.target === "supabase" ? state.detected.hasSupabaseConfig : state.detected.hasPostgresqlMigrations)} ${state.target === "supabase" ? "Supabase" : "PostgreSQL"} project detected`,
     `${marker(state.target === "supabase" ? state.detected.hasMigrations : state.detected.hasPostgresqlMigrations)} Migration history detected`,
     `${marker(state.config === "valid")} Rehearsal configuration${state.config === "invalid" ? " needs attention" : ""}`,
@@ -685,12 +686,13 @@ export const createGuidedHome =
       console.log(
         [
           "",
-          terminalStyle(flags, "1", "NODE.JS 24 REQUIRED"),
+          terminalStyle(flags, "1", "SUPPORTED NODE.JS REQUIRED"),
           `This shell is using Node.js ${state.node.version}. Rehearsal has not changed your project.`,
+          `Supported releases: ${REHEARSAL_NODE_LABEL}.`,
           "",
-          "With nvm:",
-          "  nvm install 24",
-          "  nvm use 24",
+          "Recommended with nvm:",
+          "  nvm install --lts",
+          "  nvm use --lts",
           "",
           "Then reinstall Rehearsal in your scratch project and run npx rehearsal again.",
         ].join("\n"),

package/src/cli/rehearsal.mjs

@@ -15,6 +15,7 @@ import * as prompts from "@clack/prompts";
 import {
   createRehearsalResult,
   normalizeRehearsalError,
+  REHEARSAL_VERSION,
   renderHumanError,
   serializeRehearsalError,
 } from "../shared/diagnostics.mjs";
@@ -311,6 +312,7 @@ const loadIdentityClaimPlan = async ({ flags, planOptions }) => {
 const usage = () => `Usage: rehearsal <command> [options]
 
 Commands:
+  version                     Print the installed Rehearsal version
   guide                       Open the interactive, state-aware home screen
   setup [--target=] [--write] Preview or create safe first-run scaffolding
   init [--write]              Preview or explicitly write safe starter config
@@ -343,7 +345,8 @@ Commands:
                              Preview or apply conservative disk cleanup
   verify                     Verify the current local Rehearsal runtime
 
-Options: --json --verbose --debug --plain --config=<path> --target=supabase|postgresql
+Options: --help, -h --version, -V --json --verbose --debug --plain
+         --config=<path> --target=supabase|postgresql
          --confirm-source-access=<digest> --confirm-source-retirement=<digest>
          --confirm-refresh=<digest>`;
 
@@ -362,6 +365,18 @@ const runGuidedHome = createGuidedHome({
 });
 
 const executeCommand = async ({ command, flags, planOptions, guided }) => {
+  if (command === "version" || flags.version) {
+    if (flags.json) {
+      console.log(
+        JSON.stringify(
+          { name: "@rehearsal-db/core", version: REHEARSAL_VERSION },
+          null,
+          2,
+        ),
+      );
+    } else console.log(REHEARSAL_VERSION);
+    return;
+  }
   if (command === "help" || flags.help) {
     console.log(usage());
     return;
@@ -454,7 +469,10 @@ const executeCommand = async ({ command, flags, planOptions, guided }) => {
           ? renderSourceAccessPlan(result.plan)
           : [
               "SOURCE ACCESS — READY",
-              `Temporary reader expires: ${result.receipt.expiresAt}`,
+              `${result.receipt.accessMode === "external" ? "External" : "Temporary"} reader expires: ${result.receipt.expiresAt}`,
+              result.receipt.accessMode === "external"
+                ? "Rehearsal made no source-side changes."
+                : "Rehearsal created only the reviewed temporary source access.",
               `Local credential: ${result.credentialFile}`,
               "",
               "Next: run rehearsal baseline refresh, then retire source access.",

package/src/cli/renderers.mjs

@@ -507,7 +507,10 @@ export const renderSourceAccessPlan = (plan) =>
     "SOURCE ACCESS — PREVIEW",
     "",
     `Target fingerprint: ${plan.review.targetFingerprint}`,
-    `Temporary reader: ${plan.review.reader.role} (${plan.review.reader.validForMinutes} minutes)`,
+    plan.review.reader.mode === "managed"
+      ? `Managed temporary reader: ${plan.review.reader.role} (${plan.review.reader.validForMinutes} minutes)`
+      : `Externally managed reader: ${plan.review.reader.role} (maximum ${plan.review.reader.maximumValidForMinutes} minutes remaining)`,
+    `Source changes by Rehearsal: ${plan.review.reader.sourceChanges ? "export views and temporary roles" : "none"}`,
     `Export schema: ${plan.review.exportSchema}`,
     ...plan.review.relations.map(
       (relation) =>
@@ -516,7 +519,10 @@ export const renderSourceAccessPlan = (plan) =>
     ...(plan.review.assets.length
       ? plan.review.assets.map(
           (asset) =>
-            `  → Storage ${asset.bucket}/${asset.prefix} (${asset.rights})`,
+            `  → Storage ${asset.bucket}/${
+              asset.prefix ??
+              `[private prefix from ${asset.prefixEnvironmentVariable}]`
+            } (${asset.rights})`,
         )
       : ["  ○ No source assets declared"]),
     "",
@@ -574,7 +580,12 @@ export const renderSourceRetirement = ({ mode, plan }) =>
     `Target fingerprint: ${plan.review.targetFingerprint}`,
     `Reader: ${plan.review.readerRole}`,
     `Export schema: ${plan.review.exportSchema}`,
-    ...plan.review.views.map((view) => `  → remove view ${view}`),
+    ...(plan.review.accessMode === "managed"
+      ? plan.review.views.map((view) => `  → remove view ${view}`)
+      : [
+          "  → remove only Rehearsal's local credential and receipt",
+          "  ✓ preserve the provider-owned reader and export views",
+        ]),
     "",
     ...(mode === "preview"
       ? [
@@ -582,7 +593,9 @@ export const renderSourceRetirement = ({ mode, plan }) =>
           `Exact confirmation: --confirm-source-retirement=${plan.digest}`,
         ]
       : [
-          "The exact reader, export views, and local credential files were retired.",
+          plan.review.accessMode === "managed"
+            ? "The exact reader, export views, and local credential files were retired."
+            : "Rehearsal's local credential and receipt were removed. Provider-owned database resources were preserved.",
         ]),
   ].join("\n");
 

package/src/cli/runtime_commands.mjs

@@ -211,6 +211,82 @@ const projectCommandEnvironment = (additional = {}) => ({
   ...additional,
 });
 
+const RUNTIME_STARTUP_FAILURE_PATTERN =
+  /container\b.*\b(?:is not ready|starting|unhealthy)|health(?:check)?\b.*\b(?:failed|starting|unhealthy)|out of memory|\boom\b|no space left|resource temporarily unavailable/iu;
+
+export const classifyManagerFailure = ({
+  action,
+  output,
+  inferredCategory,
+}) => {
+  if (RUNTIME_STARTUP_FAILURE_PATTERN.test(output)) {
+    return "runtime_dependency_failure";
+  }
+  if (
+    action === "migrate" ||
+    (action === "run" &&
+      /migrateRuntime|candidate migration|migration up/iu.test(output))
+  ) {
+    return "migration_candidate_failure";
+  }
+  return inferredCategory;
+};
+
+export const parseDockerCapacity = (output) => {
+  const [cpuText, memoryText, runningText, totalText] = output
+    .trim()
+    .split(/\s+/u);
+  const values = [cpuText, memoryText, runningText, totalText].map(Number);
+  if (!values.every(Number.isFinite)) return null;
+  const [cpus, memoryBytes, runningContainers, containers] = values;
+  return { cpus, memoryBytes, runningContainers, containers };
+};
+
+export const parseColimaMemory = (output) => {
+  const line = output
+    .split("\n")
+    .map((entry) => entry.trim())
+    .find((entry) => entry.startsWith("Mem:"));
+  if (!line) return null;
+  const columns = line.split(/\s+/u);
+  const totalBytes = Number(columns[1]);
+  const availableBytes = Number(columns[6]);
+  if (![totalBytes, availableBytes].every(Number.isFinite)) return null;
+  return { totalBytes, availableBytes };
+};
+
+const diagnosticCommand = (command, args) =>
+  spawnSync(command, args, {
+    encoding: "utf8",
+    env: projectCommandEnvironment(),
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5_000,
+  });
+
+const inspectContainerCapacity = () => {
+  const docker = diagnosticCommand("docker", [
+    "info",
+    "--format",
+    "{{.NCPU}} {{.MemTotal}} {{.ContainersRunning}} {{.Containers}}",
+  ]);
+  const capacity =
+    docker.status === 0 ? parseDockerCapacity(docker.stdout) : null;
+  if (!capacity) return undefined;
+
+  const context = diagnosticCommand("docker", ["context", "show"]);
+  if (context.status !== 0 || context.stdout.trim() !== "colima") {
+    return { engine: "docker-compatible", ...capacity };
+  }
+  const memory = diagnosticCommand("colima", ["ssh", "--", "free", "-b"]);
+  return {
+    engine: "colima",
+    ...capacity,
+    ...(memory.status === 0
+      ? { runtimeMemory: parseColimaMemory(memory.stdout) ?? undefined }
+      : {}),
+  };
+};
+
 export const topologyCommandEnvironment = (topology) =>
   Object.fromEntries(
     topology.targets.map((target) => [
@@ -344,14 +420,15 @@ export const createRuntimeCommands = ({
       const inferred = normalizeRehearsalError(
         new Error(completeOutput || `Rehearsal ${action} failed.`),
       );
-      const category =
-        action === "migrate" ||
-        (action === "run" &&
-          /migrateRuntime|candidate migration|migration up/iu.test(
-            completeOutput,
-          ))
-          ? "migration_candidate_failure"
-          : inferred.category;
+      const category = classifyManagerFailure({
+        action,
+        output: completeOutput,
+        inferredCategory: inferred.category,
+      });
+      const startupFailure = category === "runtime_dependency_failure";
+      const engineCapacity = startupFailure
+        ? inspectContainerCapacity()
+        : undefined;
       const conciseOutput = completeOutput
         .replaceAll(String.fromCodePoint(27), "")
         .split("\n")
@@ -366,10 +443,16 @@ export const createRuntimeCommands = ({
         message: `The local Rehearsal ${action} operation did not complete.`,
         expected: "the isolated runtime operation to finish and verify",
         actual: conciseOutput || `exit ${result.status}`,
-        context: { action },
+        context: { action, ...(engineCapacity ? { engineCapacity } : {}) },
         refused: "The runtime was not reported as trusted.",
         suggestions: [
           "Review the concise failure above, then rerun rehearsal doctor before retrying.",
+          ...(startupFailure
+            ? [
+                "Stop unrelated local stacks or increase Docker/Colima capacity, then retry. Rehearsal will not change engine settings or bypass service health checks.",
+                "Run docker stats --no-stream to identify active containers using the shared engine.",
+              ]
+            : []),
           "Use --debug only when the safe diagnostic detail is needed.",
         ],
         cause: new Error(completeOutput || `exit ${result.status}`),