@rehearsal-db/core 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -5,6 +5,49 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-10-20
+
+### Fixed
+
+- Explain recognized PostgreSQL/Supabase migration failures with bounded native
+  SQLSTATE evidence and safe syntax, schema, constraint, permission, connectivity
+  and timeout guidance. Unsupported or ambiguous evidence remains unknown; raw
+  SQL, provider details, credentials and private rows are not exposed.
+- Preserve the original diagnosis across cleanup and bounded operation history so
+  the CLI and editor can show the same failure after refresh. Failed operations
+  never claim verification or unconditional rollback success.
+- Optionally identify the exact approved PostgreSQL input file by hash, without
+  inventing a failing SQL origin, line or column. Reject invalid UTF-8 before
+  execution rather than submitting replacement-decoded bytes.
+- Point recognized bind failures at the configured local ports, including safe
+  Windows/WSL exclusion-inspection guidance. Do not infer a reservation from every
+  denial or suggest terminating unknown listeners.
+- Keep database-only command guidance separate from optional application launch.
+
+### Documentation and distribution
+
+- Add a main-tutorial existing-row constraint failure, reviewed backfill/fix and
+  verification sequence, plus a same-project VS Code handoff and safe local-copy
+  recovery for unsupported external npm links.
+- Pair with Starter 0.1.22 for actionable persistent failures, safe exact-byte
+  source opening, distinct command/database states and truthful recorded proof.
+- Refresh the separate macOS, Linux and Windows/WSL 2 setup bundles to exact core
+  1.0.2. Native Windows database execution remains unsupported.
+
+## [1.0.1] - 2026-10-19
+
+### Platform compatibility
+
+- Keep macOS Intel/Apple Silicon and Linux execution distinct from Windows desktop
+  access through WSL 2. Require the WSL project's Linux filesystem; document the
+  preview's actual component and runtime limits rather than claiming every OS works.
+- Verify installed package version/discovery on real desktop OS runners and exercise
+  PostgreSQL/dependent targets in an owned Windows 2025 WSL2 Ubuntu distribution.
+  Provision checksum-verified official Node and signed Docker Engine packages without
+  Docker Desktop, a daemon TCP endpoint or new branch-protection requirements.
+- Document native Windows runtime refusal and the Linux/Remote-WSL setup path; version,
+  help and project discovery remain distinct from database-runtime support.
+
 ## [1.0.0] - 2026-10-17
 
 ### Stable compatibility
@@ -772,7 +815,9 @@ not unattended cleanup, and container age is not proof of user inactivity.
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.10...v1.0.0
 [0.1.0-rc.10]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.9...v0.1.0-rc.10
 [0.1.0-rc.9]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.8...v0.1.0-rc.9

package/COMPATIBILITY.md

@@ -32,6 +32,49 @@ default and the release-build runtime. End-of-life and odd-numbered Node.js rele
 not supported. A future release may remove a Node.js line after its upstream end-of-life
 date, with that change called out in the changelog.
 
+## Operating systems and execution location
+
+Core 1.0.1's platform boundary distinguishes the computer running VS Code from the
+operating system actually executing Node, Docker and Rehearsal. The corresponding editor
+changes are delivered with extension 0.1.21. A Windows desktop connected to WSL is not native
+Windows execution.
+
+| Execution environment                                                  | Runtime boundary                                                                                                           |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| macOS, Intel or Apple Silicon                                          | POSIX runtime; supported Node and a local Docker-compatible engine required                                                |
+| Linux                                                                  | POSIX runtime; Ubuntu 24.04 is the primary PostgreSQL/Supabase fixture environment                                         |
+| Windows with WSL 2                                                     | Run Linux Node and Docker inside the distribution, with the project on its Linux filesystem; compatibility preview         |
+| Native Windows Node, PowerShell or Command Prompt                      | Version, help and read-only project discovery remain available; runtime/setup/database operations refuse with WSL guidance |
+| WSL 1, a WSL project on `/mnt/c` or another Windows-mounted filesystem | Not a supported database-runtime environment                                                                               |
+| SSH, Dev Containers, Codespaces or browser-only VS Code                | No end-to-end support claim; different host, filesystem and port-forwarding boundaries need their own verification         |
+| iOS, iPadOS, Android, BSD and other unlisted systems                   | Not supported; installing a JavaScript package does not establish a compatible database engine or desktop extension host   |
+
+Do not bypass native Windows refusal with permission bits or a shell wrapper. Native
+Windows ACLs, process-tree retirement and baseline filesystem behavior are not certified
+by Linux tests. Keep keys, baselines and working files in the WSL Linux home filesystem,
+not a Windows share. The package does not move an existing project automatically.
+See [Windows and WSL setup](docs/getting-started.md#windows-use-a-wsl-2-linux-workspace).
+
+### What platform verification proves
+
+The separate `Platform compatibility` workflow preserves existing release/check names.
+Desktop jobs install the packed package and exercise version/discovery from a path with
+spaces and Unicode on real Linux, macOS and Windows runners. Windows also checks the
+intentional runtime refusal; a passing Windows job is not a working Windows database.
+The Windows 2025 WSL job provisions its own Ubuntu 24.04 distribution, verifies Linux
+execution and filesystem location, then runs the existing real PostgreSQL/dependent-target
+fixtures against a local Unix-socket Docker Engine. It does not install Docker Desktop
+or expose the daemon over TCP. Node uses the official release checksum; Docker packages
+use its signed apt repository. These integrity checks are not independent publisher
+authentication.
+
+A configured workflow is not passing evidence. Reports identify actual OS, architecture,
+installed artifact and exercised boundary. The WSL fixture does not certify native
+Windows runtime, WSL Supabase/Auth/Storage, a native Remote-WSL VS Code session, all Linux
+distributions, assistive technology or every architecture. Editor Node/controller tests
+are separate from real extension-host and browser walkthroughs. Intel/ARM labels and
+Windows/WSL are never interchangeable evidence.
+
 The npm install hook may create project scaffolding only when it proves one application
 root. Ordinary npm application installs are covered. A workspace is automatic only when
 one declaring consumer is already visible in its manifest or lockfile; npm can save a

package/README.md

@@ -16,6 +16,7 @@
 <p align="center">
   <a href="https://ddupasquier.github.io/rehearsal-db/">Read the documentation</a> ·
   <a href="https://www.npmjs.com/package/@rehearsal-db/core">View on npm</a> ·
+  <a href="https://ddupasquier.github.io/rehearsal-db/vscode/">Free VS Code Starter</a> ·
   <a href="https://github.com/Ddupasquier/rehearsal-db">Source on GitHub</a> ·
   <a href="https://github.com/Ddupasquier/rehearsal-db/issues">Report a problem</a>
 </p>
@@ -45,8 +46,14 @@ it through a reviewed privacy policy, and retire the access again. It is never p
 `run`, `reset`, `migrate`, or application launch. Rehearsal is not a backup system or a
 production deployment tool.
 
-> **Pre-1.0 safety note:** use Rehearsal on a branch and keep a working backup of your
-> project.
+The CLI is free and MIT-licensed, with stable releases on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.0.2**;
+install only a version actually published there. Prefer a visual workflow?
+[Install the free VS Code Starter preview](docs/vscode.md). Its included features are
+free indefinitely for personal or commercial development—no account, card, or trial.
+
+Work on a branch and keep a working backup of your project. Rehearsal's local safety
+boundaries do not replace version control or backups.
 
 ## What you need
 
@@ -62,6 +69,12 @@ your migration is intended to change.
 
 ## Quick start
 
+Prefer OS-specific files? Use the [Windows / WSL 2](installers/windows/README.md),
+[macOS](installers/macos/README.md) or [Linux](installers/linux/README.md) setup folder.
+These readable helpers require existing Node.js 24 or 26 and check prerequisites by
+default; installation is an explicit option. They do not install OS tools or start a
+database. See [their exact behavior and release availability](installers/README.md).
+
 From your project directory:
 
 ```bash
@@ -157,18 +170,24 @@ loads.
 
 ## Supported today
 
-| Environment                                      | Support                |
-| ------------------------------------------------ | ---------------------- |
-| Supabase CLI projects                            | Supported              |
-| Ordinary PostgreSQL in local Docker              | Supported              |
-| macOS and Linux                                  | Supported              |
-| WSL                                              | Experimental           |
-| Native Windows                                   | Not yet supported      |
-| Hosted database URLs                             | Intentionally rejected |
-| Optional read-only PostgreSQL source preparation | Explicit opt-in beta   |
-| MySQL, MongoDB, and other database families      | Not yet supported      |
+| Environment                                      | Support                      |
+| ------------------------------------------------ | ---------------------------- |
+| Supabase CLI projects                            | Supported                    |
+| Ordinary PostgreSQL in local Docker              | Supported                    |
+| macOS and Linux                                  | Supported                    |
+| Windows via WSL 2 on its Linux filesystem        | Compatibility preview        |
+| Native Windows runtime                           | Not yet supported; use WSL 2 |
+| Hosted database URLs                             | Intentionally rejected       |
+| Optional read-only PostgreSQL source preparation | Explicit opt-in beta         |
+| MySQL, MongoDB, and other database families      | Not yet supported            |
 
 See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
+Native Windows metadata commands are not database-runtime support. For Windows, follow
+the [WSL 2 setup path](docs/getting-started.md#windows-use-a-wsl-2-linux-workspace):
+Linux Node, project files and Docker must live in the Linux execution environment.
+Core 1.0.1 and editor 0.1.21 add explicit platform guidance/refusal; older immutable
+releases retain their original behavior. Mobile, browser-only and unlisted systems are
+not implied by desktop or Linux compatibility.
 
 ## Documentation
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -78,7 +78,7 @@
         "test:fixture:resources": "npm run build && node scripts/verification/run_scenario.mjs resources",
         "release:verify": "npm run build && node scripts/verification/release_gate.mjs",
         "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
-        "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
+        "check:syntax": "node scripts/verification/check_syntax.mjs",
         "typecheck": "npm run build && tsc --project tsconfig.json",
         "format": "prettier --write .",
         "format:check": "prettier --check .",

package/dist/scripts/install/create_root_config.mjs

@@ -2,10 +2,17 @@
 /** Create safe project-root Rehearsal scaffolding during a local install. */
 import { fileURLToPath } from "node:url";
 import { createInstalledRehearsalScaffold, renderInstalledRehearsalScaffold, } from "../../src/project/install_scaffold.mjs";
+import { inspectHostPlatform } from "../../src/shared/host_platform.mjs";
 const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
 try {
-    const result = await createInstalledRehearsalScaffold({ packageRoot });
-    console.log(renderInstalledRehearsalScaffold(result));
+    const host = await inspectHostPlatform();
+    if (!host.supported) {
+        console.log(`Rehearsal installed without creating project files. ${host.remediation}`);
+    }
+    else {
+        const result = await createInstalledRehearsalScaffold({ packageRoot });
+        console.log(renderInstalledRehearsalScaffold(result));
+    }
 }
 catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/dist/src/cli/failure_output.d.mts

@@ -0,0 +1,3 @@
+/** Preserve fixed original migration guidance without masking aggregate cleanup failure. */
+import { RehearsalError, type RehearsalErrorOverrides } from "../shared/diagnostics.mjs";
+export declare const normalizeCliFailure: (error: unknown, overrides?: RehearsalErrorOverrides) => RehearsalError;

package/dist/src/cli/failure_output.mjs

@@ -0,0 +1,48 @@
+/** Preserve fixed original migration guidance without masking aggregate cleanup failure. */
+import { RehearsalError, normalizeRehearsalError, } from "../shared/diagnostics.mjs";
+import { parseMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
+const aggregateMigrationFailure = (error) => {
+    try {
+        let original = error;
+        for (let depth = 0; depth <= 4; depth += 1) {
+            if (original instanceof AggregateError) {
+                if (depth === 4 || !Array.isArray(original.errors))
+                    return undefined;
+                original = original.errors[0];
+                continue;
+            }
+            if (original instanceof RehearsalError &&
+                original.category !== "operation_cancelled" &&
+                original.context !== null &&
+                typeof original.context === "object" &&
+                !Array.isArray(original.context) &&
+                "migrationFailure" in original.context)
+                return parseMigrationFailureDiagnostic(original.context.migrationFailure);
+            return undefined;
+        }
+    }
+    catch {
+        /* Untrusted metadata is not evidence; retain the aggregate's existing failure. */
+    }
+    return undefined;
+};
+export const normalizeCliFailure = (error, overrides = {}) => {
+    const failure = normalizeRehearsalError(error, overrides);
+    if (!(error instanceof AggregateError))
+        return failure;
+    const migrationFailure = aggregateMigrationFailure(error);
+    if (migrationFailure === undefined)
+        return failure;
+    // Keep outer category/exit and cleanup warning. Project no original/sibling text.
+    return new RehearsalError({
+        category: failure.category,
+        code: failure.code,
+        message: failure.message,
+        expected: failure.expected,
+        actual: failure.actual,
+        context: { migrationFailure },
+        ...(failure.refused === undefined ? {} : { refused: failure.refused }),
+        suggestions: [...migrationFailure.suggestions, ...failure.suggestions],
+        cause: failure.cause,
+    });
+};

package/dist/src/cli/rehearsal.mjs

@@ -8,13 +8,14 @@ import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import * as prompts from "@clack/prompts";
-import { RehearsalError, normalizeRehearsalError, renderHumanError, serializeRehearsalError, } from "../shared/diagnostics.mjs";
+import { RehearsalError, renderHumanError, serializeRehearsalError, } from "../shared/diagnostics.mjs";
 import { acquireProjectOperation, assertInstalledPackageFingerprint, createInstalledPackageFingerprint, } from "../shared/operation_guard.mjs";
 import { commandMutatesProject, parseArguments, resetGuidedFlags, } from "./arguments.mjs";
 import { usage } from "./basic_command_handlers.mjs";
 import { createCliCommandRegistry } from "./cli_commands.mjs";
 import { createCliSessionState, resetCommandSessionState, } from "./command_contract.mjs";
 import { createCommandEmitter } from "./command_output.mjs";
+import { normalizeCliFailure } from "./failure_output.mjs";
 import { createGuidedHome } from "./guided.mjs";
 import { createProjectCommands } from "./project_commands.mjs";
 import { buildRuntimeStackPlan, createRuntimeCommands, runRuntimeStackDoctor, topologyCandidateSummary, topologyCommandEnvironment, } from "./runtime_commands.mjs";
@@ -22,6 +23,7 @@ import { buildRefreshWorkflowPlan, createRefreshWorkflow, } from "./source_comma
 import { installGuidedExitShortcut, useStyledPrompts } from "./terminal.mjs";
 import { runWithOperationCancellation, supportsOperationCancellation, } from "../shared/cancellation.mjs";
 import { withOperationProgress } from "../shared/operation_progress.mjs";
+import { assertSupportedHostPlatform } from "../shared/host_platform.mjs";
 const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
 const projectRoot = process.cwd();
 const managerPath = join(packageRoot, "dist/scripts/runtime/manage_database.mjs");
@@ -94,8 +96,17 @@ const main = async () => {
         !flags.json &&
         process.stdin.isTTY &&
         process.stdout.isTTY;
-    const guided = command === "guide" || wantsAutomaticGuide;
-    const mutating = commandMutatesProject({ command, flags, guided });
+    const guided = !flags.help &&
+        !flags.version &&
+        (command === "guide" || wantsAutomaticGuide);
+    if (!flags.help &&
+        !flags.version &&
+        (guided || !["help", "version", "discover", "doctor"].includes(command))) {
+        await assertSupportedHostPlatform({ projectRoot });
+    }
+    const mutating = !flags.help &&
+        !flags.version &&
+        commandMutatesProject({ command, flags, guided });
     const operation = mutating
         ? await acquireProjectOperation({
             projectRoot,
@@ -207,7 +218,7 @@ try {
     await main();
 }
 catch (error) {
-    const failure = normalizeRehearsalError(error, {
+    const failure = normalizeCliFailure(error, {
         expected: "a safe, versioned, local-only Rehearsal operation",
         actual: errorMessage(error),
         refused: "No further Rehearsal action was performed.",

package/dist/src/cli/runtime_action_handlers.mjs

@@ -168,13 +168,20 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                         : undefined;
                     const renderedHttpProofResults = "httpProofResults" in value ? value.httpProofResults : [];
                     const renderedLifecycle = "lifecycle" in value ? value.lifecycle : undefined;
+                    const hasApplicationLaunch = topology.primary.config.application.readiness !== null;
                     const nextAction = {
                         run: renderedLifecycle?.runtimeState === "stopped"
-                            ? "The runtime was stopped with its database and Storage changes preserved. Run rehearsal start or rehearsal open to resume."
-                            : "Next: run rehearsal open for hands-on testing, then rehearsal verify.",
-                        start: "Next: run rehearsal open for hands-on testing or rehearsal status.",
+                            ? `The runtime was stopped with its database and Storage changes preserved. Run rehearsal start${hasApplicationLaunch ? " or rehearsal open" : ""} to resume.`
+                            : hasApplicationLaunch
+                                ? "Next: run rehearsal open for hands-on testing, then rehearsal verify."
+                                : "The rehearsal command is complete; the database remains running. Next: run rehearsal verify or inspect the local database. This database-only project has no application to open.",
+                        start: hasApplicationLaunch
+                            ? "Next: run rehearsal open for hands-on testing or rehearsal status."
+                            : "The database is running. Next: run rehearsal status or rehearsal verify; no application launch is configured.",
                         migrate: "Next: run rehearsal verify to prove the current runtime.",
-                        reset: "Next: run rehearsal open or rehearsal verify.",
+                        reset: hasApplicationLaunch
+                            ? "Next: run rehearsal open or rehearsal verify."
+                            : "Next: run rehearsal verify or inspect the local database; no application launch is configured.",
                         status: "Next: run rehearsal verify, reset, stop, or discard.",
                         stop: "Next: run rehearsal start when you want to resume.",
                         discard: "The disposable runtime was removed; the immutable baseline remains.",

package/dist/src/cli/runtime_commands.mjs

@@ -14,12 +14,14 @@ import { RehearsalError, normalizeRehearsalError, redactDiagnosticValue, } from
 import { assertInstalledPackageFingerprint } from "../shared/operation_guard.mjs";
 import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
 import { runOwnedProcess } from "../shared/owned_process.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 import { getOwnedOperationProgressId, trackOperationStage, } from "../shared/operation_progress.mjs";
 import { buildRuntimeManagerArguments } from "../targets/target.mjs";
 import { parseRuntimeStatusSnapshot, renderRuntimeStatusSnapshot, } from "../runtime/status.mjs";
 import { applyRuntimePersistence, shouldStopRuntime, } from "../runtime/persistence.mjs";
 import { executeRuntimeTargetStack } from "./runtime_stack_execution.mjs";
-import { summarizeRuntimeManagerFailure } from "./runtime_failure_summary.mjs";
+import { summarizeRuntimeManagerFailure, runtimePortFailureGuidance, } from "./runtime_failure_summary.mjs";
+import { readManagerMigrationFailure } from "../runtime/migration_failure.mjs";
 import { releaseOwnedColimaWhenIdle } from "../runtime/container_engine_ownership.mjs";
 import { inspectRehearsalResources } from "../runtime/resource_inventory.mjs";
 import { assertLocalDockerContext } from "../runtime/local_docker_context.mjs";
@@ -55,27 +57,15 @@ const parseCommand = (source) => {
         throw new Error("Application proof command is empty.");
     return values;
 };
-const projectCommandEnvironment = (additional = {}) => ({
-    ...Object.fromEntries([
-        "CI",
-        "COLORTERM",
-        "FORCE_COLOR",
-        "HOME",
-        "LANG",
-        "LC_ALL",
-        "NO_COLOR",
-        "PATH",
-        "SHELL",
-        "TERM",
-        "TMPDIR",
-        "USER",
-    ].flatMap((key) => process.env[key] === undefined ? [] : [[key, process.env[key]]])),
-    ...additional,
-});
+const projectCommandEnvironment = (additional = {}) => createCleanProcessEnvironment({ overrides: 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 (/^(?:Error:\s*)?The baseline (?:PostgreSQL|Supabase) migration failed \(/mu.test(output))
+        return "baseline_invalid";
+    if (/^(?:Error:\s*)?The confirmed candidate (?:PostgreSQL|Supabase) migration failed \(/mu.test(output))
+        return "migration_candidate_failure";
     if (RUNTIME_STARTUP_FAILURE_PATTERN.test(output) ||
-        /Supabase startup failed \(/u.test(output) ||
+        /(?:PostgreSQL|Supabase) startup failed \(/u.test(output) ||
         /^Error:\s*supabase start(?:\s|$)/imu.test(output)) {
         return "runtime_dependency_failure";
     }
@@ -287,22 +277,31 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
                 inferredCategory: inferred.category,
             });
             const startupFailure = category === "runtime_dependency_failure";
-            const engineCapacity = startupFailure
+            const migrationFailure = readManagerMigrationFailure(completeOutput);
+            const portGuidance = runtimePortFailureGuidance(conciseOutput);
+            const engineCapacity = startupFailure && portGuidance.length === 0
                 ? inspectContainerCapacity()
                 : undefined;
             throw new RehearsalError({
                 category,
                 code: `MANAGER_${action.toUpperCase()}_FAILED`,
-                message: `The local Rehearsal ${action} operation did not complete.`,
+                message: `The local Rehearsal ${action} operation did not complete.${migrationFailure ? ` ${migrationFailure.summary}` : ""}`,
                 expected: "the isolated runtime operation to finish and verify",
                 actual: conciseOutput || `exit ${result.status}`,
-                context: { action, ...(engineCapacity ? { engineCapacity } : {}) },
+                context: {
+                    action,
+                    target: targetName ?? "primary",
+                    ...(migrationFailure ? { migrationFailure } : {}),
+                    ...(engineCapacity ? { engineCapacity } : {}),
+                },
                 refused: "The runtime was not reported as trusted.",
                 suggestions: [
+                    ...(migrationFailure?.suggestions ?? []),
+                    ...portGuidance,
                     "Review the concise failure above, then rerun rehearsal doctor before retrying.",
-                    ...(startupFailure
+                    ...(startupFailure && portGuidance.length === 0
                         ? [
-                            "Stop unrelated local stacks or increase Docker/Colima capacity, then retry. Rehearsal will not change engine settings or bypass service health checks.",
+                            "If startup evidence confirms a resource shortage, stop only stacks you own 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.",
                         ]
                         : []),

package/dist/src/cli/runtime_failure_summary.d.mts

@@ -1 +1,2 @@
+export declare const runtimePortFailureGuidance: (output: string) => readonly string[];
 export declare const summarizeRuntimeManagerFailure: (output: string) => string;

package/dist/src/cli/runtime_failure_summary.mjs

@@ -1,5 +1,17 @@
 /** Keep useful manager failures rather than debug advice and trailing Node stacks. */
 import { redactDiagnosticValue } from "../shared/diagnostics.mjs";
+import { readManagerMigrationFailure, renderMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
+import { portStartupGuidance } from "../targets/port_start_failure.mjs";
+export const runtimePortFailureGuidance = (output) => {
+    const provider = output.match(/^(?:Error:\s*)?(PostgreSQL|Supabase) startup failed \((?:exit -?\d+|process failure)\)\.$/mu)?.[1];
+    const evidence = output
+        .match(/^Reported startup evidence: ([a-z_, ]+)\.$/mu)?.[1]
+        ?.split(/,\s*/u);
+    const port = evidence?.find((value) => value === "port_in_use" || value === "port_unavailable");
+    return provider && (port === "port_in_use" || port === "port_unavailable")
+        ? portStartupGuidance(port, provider === "PostgreSQL" ? "postgresql" : "supabase").split("\n")
+        : [];
+};
 export const summarizeRuntimeManagerFailure = (output) => {
     let nodeSourceContext = false;
     const lines = output
@@ -27,16 +39,22 @@ export const summarizeRuntimeManagerFailure = (output) => {
         .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s"']+/giu, "[REDACTED_URL]")
         .replace(/\b[A-Z][A-Z0-9_]*\s*=\s*[^\s]+/gu, "[REDACTED_ENV]")
         .replace(/(?:\/[A-Za-z0-9_.-]+){2,}(?::\d+(?::\d+)?)?/gu, "[LOCAL_PATH]"));
-    const startup = lines.findIndex((line) => /Supabase startup failed \(/u.test(line));
+    const startup = lines.findIndex((line) => /(?:PostgreSQL|Supabase) startup failed \(/u.test(line));
     const failure = lines.reduce((last, line, index) => (/^[A-Za-z]*Error:/u.test(line) ? index : last), -1);
     const migration = lines.findIndex((line) => /^Error: The (?:confirmed candidate|baseline) (?:PostgreSQL|Supabase) migration failed \(exit (?:-?\d+|unknown); stderr \d+ bytes\)\. SQL and provider output are withheld\.$/u.test(line));
     const rollbackFailed = /The runtime operation failed and its owned runtime could not be removed automatically\./u.test(output);
+    const migrationDiagnostic = migration >= 0 ? readManagerMigrationFailure(lines.join("\n")) : undefined;
     const selected = startup >= 0
         ? lines
-            .slice(startup, startup + 4)
-            .filter((line) => /^(?:Error:\s*)?Supabase startup failed \(|^Reported startup evidence:|^Reported service states:|^Provider logs, paths, environment values and connection URLs are omitted\./u.test(line))
+            .slice(startup, startup + 12)
+            .filter((line) => /^(?:Error:\s*)?(?:PostgreSQL|Supabase) startup failed \(|^Reported startup evidence:|^Reported service states:|^Provider logs, (?:command arguments, )?paths, environment values and connection URLs are omitted\./u.test(line))
         : migration >= 0
-            ? [lines[migration]]
+            ? [
+                lines[migration],
+                ...(migrationDiagnostic
+                    ? [renderMigrationFailureDiagnostic(migrationDiagnostic)]
+                    : []),
+            ]
             : rollbackFailed
                 ? [
                     "Error: The operation failed; the original cause could not be safely summarized.",
@@ -44,10 +62,18 @@ export const summarizeRuntimeManagerFailure = (output) => {
                 : failure >= 0
                     ? lines.slice(failure, failure + 8)
                     : lines.slice(-8);
+    if (startup >= 0)
+        selected.push(...runtimePortFailureGuidance(selected.join("\n")));
     if (rollbackFailed)
         selected.push("Owned rollback cleanup could not be confirmed. Resources may remain; inspect activity and status before retrying. No cleanup success is claimed.");
     if (startup >= 0 &&
         /owned cleanup could not be proved|owned resources were retained|Resources and data were retained|retained resources need review/iu.test(output))
         selected.push("Owned startup cleanup could not be proved; resources and data were retained. Inspect activity and status before retrying.");
+    if (selected.join("\n").length > 2_000 && migrationDiagnostic?.source) {
+        // Human summary stays bounded and retains cleanup warnings; structured output
+        // independently reads the complete, bounded manager frame.
+        const { source: _source, ...diagnostic } = migrationDiagnostic;
+        selected[1] = renderMigrationFailureDiagnostic(diagnostic);
+    }
     return selected.join("\n").slice(0, 2_000);
 };

package/dist/src/cli/runtime_planning.mjs

@@ -1,6 +1,7 @@
 import { buildRehearsalPlan, runRehearsalDoctor } from "../runtime/plan.mjs";
 import { inspectRuntimeTopologyCandidates, loadRuntimeTopology, } from "../runtime/topology.mjs";
 import { redactDiagnosticValue } from "../shared/diagnostics.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 export const buildRuntimeStackPlan = async (planOptions) => {
     const topology = await loadRuntimeTopology(planOptions);
@@ -52,6 +53,11 @@ export const buildRuntimeStackPlan = async (planOptions) => {
     };
 };
 export const runRuntimeStackDoctor = async (planOptions) => {
+    const host = await inspectHostPlatform({
+        projectRoot: planOptions.projectRoot ?? process.cwd(),
+    });
+    if (!host.supported)
+        return runRehearsalDoctor(planOptions);
     let topology;
     try {
         topology = await loadRuntimeTopology(planOptions);

package/dist/src/project/install_scaffold.mjs

@@ -6,6 +6,7 @@ import { access, readFile, readdir, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { applyRehearsalSetup, planRehearsalSetup } from "./setup.mjs";
 import { findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, } from "./configuration.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
 const PACKAGE_NAME = "@rehearsal-db/core";
 const DEPENDENCY_GROUPS = Object.freeze([
     "dependencies",
@@ -224,6 +225,12 @@ export const createInstalledRehearsalScaffold = async ({ packageRoot, environmen
     });
     if (resolution.status !== "resolved")
         return resolution;
+    const host = await inspectHostPlatform({
+        projectRoot: resolution.projectRoot,
+    });
+    if (!host.supported) {
+        return skip(`${host.detail} ${host.remediation}`.replace(/\.$/u, ""));
+    }
     const detected = await inspectDetectedProject({
         projectRoot: resolution.projectRoot,
     });

package/dist/src/project/project_discovery_metadata.mjs

@@ -7,6 +7,7 @@ import { lstat, readFile, readdir } from "node:fs/promises";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { CONFIG_FILENAMES } from "./configuration_discovery.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 const MAX_METADATA_BYTES = 1024 * 1024;
 const execFileAsync = promisify(execFile);
 const inside = (root, path) => {
@@ -112,17 +113,14 @@ export const probeContainerEngineWithoutStarting = async () => {
         await execFileAsync("docker", ["info", "--format", "{{.ServerVersion}}"], {
             timeout: 2_000,
             maxBuffer: 64 * 1024,
-            env: Object.fromEntries([
-                "COLIMA_HOME",
-                "DOCKER_CONFIG",
-                "DOCKER_CONTEXT",
-                "DOCKER_HOST",
-                "HOME",
-                "PATH",
-                "USER",
-            ]
-                .map((key) => [key, process.env[key]])
-                .filter((entry) => Boolean(entry[1]))),
+            env: createCleanProcessEnvironment({
+                passthroughKeys: [
+                    "COLIMA_HOME",
+                    "DOCKER_CONFIG",
+                    "DOCKER_CONTEXT",
+                    "DOCKER_HOST",
+                ],
+            }),
         });
         return "running";
     }

package/dist/src/runtime/migration_failure.d.mts

@@ -0,0 +1,28 @@
+/** Translate provider-native SQLSTATE evidence into fixed, privacy-safe guidance. */
+import { type MigrationFailureSource } from "./migration_failure_source.mjs";
+export type MigrationFailureClassification = "syntax" | "schema" | "constraint" | "permission" | "connectivity" | "timeout_or_cancel" | "unknown";
+export interface MigrationFailureDiagnostic {
+    readonly schemaVersion: 1;
+    readonly provider: "postgresql" | "supabase";
+    readonly classification: MigrationFailureClassification;
+    readonly sqlState: string | null;
+    readonly evidence: "provider_sqlstate" | "unavailable" | "ambiguous";
+    readonly summary: string;
+    readonly suggestions: readonly string[];
+    readonly source?: MigrationFailureSource;
+}
+export declare const migrationFailureDiagnostic: ({ provider, sqlState, evidence, }: {
+    provider: MigrationFailureDiagnostic["provider"];
+    sqlState?: string | null;
+    evidence?: MigrationFailureDiagnostic["evidence"];
+}) => MigrationFailureDiagnostic;
+/** Read only known provider error envelopes, never arbitrary mentions of SQLSTATE. */
+export declare const diagnoseMigrationFailure: ({ provider, stderr, }: {
+    provider: MigrationFailureDiagnostic["provider"];
+    stderr: string;
+}) => MigrationFailureDiagnostic;
+export declare const renderMigrationFailureDiagnostic: (diagnostic: MigrationFailureDiagnostic) => string;
+/** Closed public projection: reject free text or metadata not generated by this owner. */
+export declare const parseMigrationFailureDiagnostic: (value: unknown) => MigrationFailureDiagnostic;
+/** Parse only Rehearsal's fixed migration header and adjacent fixed code line. */
+export declare const readManagerMigrationFailure: (output: string) => MigrationFailureDiagnostic | undefined;