@rehearsal-db/core 0.1.0-rc.9 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,50 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## [Unreleased]
 
+### 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
+
+- Establish the documented CLI, configuration, policy, baseline, TypeScript and
+  JSON contracts as the 1.x compatibility boundary. This preserves rc.10's database,
+  authentication and restore behavior.
+- Keep the complete MIT CLI free. The separately distributed Free Starter editor,
+  future Pro plans and additional database families do not expand the core support
+  matrix or change its safety boundaries.
+
+### Fixed
+
+- Report unknown CLI commands and options as invalid input (exit 2), rather than
+  letting words in the input or help text misclassify them as migration or baseline
+  failures. The command remains refused and supported-command help is retained.
+
+## [0.1.0-rc.10] - 2026-10-17
+
+### Fixed
+
+- Interactive Ctrl+C and Ctrl+Z retire owned work without leaving an invoking npm
+  job suspended. Terminal mode and input consumption are restored after cleanup;
+  startup and unanswered migration confirmations cancel safely, and unrelated jobs
+  are untouched.
+
+### Documentation
+
+- Stable promotion is evidence-based after owner review: complete the release and
+  consumer acceptance checks rather than waiting a fixed number of calendar days.
+  Exact-artifact, security, data-preservation and human publishing approvals remain.
+
 ## [0.1.0-rc.9] - 2026-10-17
 
 ### Fixed
@@ -740,7 +784,14 @@ 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/v0.1.0-rc.4...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.0...HEAD
+[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
+[0.1.0-rc.8]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.7...v0.1.0-rc.8
+[0.1.0-rc.7]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.6...v0.1.0-rc.7
+[0.1.0-rc.6]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.5...v0.1.0-rc.6
+[0.1.0-rc.5]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.4...v0.1.0-rc.5
 [0.1.0-rc.4]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.3...v0.1.0-rc.4
 [0.1.0-rc.3]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.2...v0.1.0-rc.3
 [0.1.0-rc.2]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.1...v0.1.0-rc.2

package/COMPATIBILITY.md

@@ -1,10 +1,15 @@
 # Rehearsal compatibility policy
 
-Rehearsal begins at `0.x`. Minor releases may contain breaking changes, but every
-intentional break must be called out in the changelog with a migration path. Patch
-releases must remain backward compatible within their minor line.
+Starting with `1.0.0`, documented public contracts are backward compatible throughout
+the `1.x` line. Minor releases may add compatible capabilities; patch releases fix
+defects. An intentional breaking change requires a new major version, a changelog
+entry and a migration path.
 
-The following are compatibility contracts for published 0.x releases:
+Historical `0.x` releases allowed intentional breaking changes in minor versions,
+with changelog and migration guidance. Their patch releases remain compatible within
+their minor line. Existing artifacts and granted license rights are unchanged.
+
+The following are compatibility contracts for published releases:
 
 - configuration property names, types, defaults, validation, and schema version;
 - baseline format and checksum meaning;
@@ -17,16 +22,59 @@ A change to any of those requires either a compatible extension or a deliberate
 transition. Rehearsal must never silently reinterpret an old config, baseline, digest,
 or successful verification receipt.
 
-The first `1.0.0` release requires external beta evidence, a support policy, and a settled
-public API. Supporting additional database families, package managers, or operating
-systems is not implied by the 0.x contract.
+The first `1.0.0` release requires external beta evidence, a support policy and the
+settled public API described in [the stability policy](docs/stability.md). Supporting
+additional database families, package managers or operating systems is not implied.
 
 Rehearsal supports maintained even-numbered Node.js release lines that pass its CI
-matrix. Beta.13 supports Node.js 22, 24, and 26; Node.js 24 LTS is the recommended
+matrix. Rehearsal 1.0 supports Node.js 22, 24, and 26; Node.js 24 LTS is the recommended
 default and the release-build runtime. End-of-life and odd-numbered Node.js releases are
 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.1**;
+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/SECURITY.md

@@ -9,9 +9,11 @@ Report suspected vulnerabilities through the
 in this repository. A GitHub account is required. Do not open a
 public issue containing an exploit, secret, hosted target, or source record.
 
-Supported security updates cover the latest released 0.x minor during beta. A security
-fix may deliberately tighten configuration or refuse a workflow that an earlier beta
-accepted. During beta, reports apply to the latest published release and current `main`.
+Security updates target the latest released 1.x version. Update to the latest 1.x
+release to receive fixes; older release candidates are not a maintained security line.
+Reports concerning current `main` and prereleases are also welcome. A security fix may
+tighten validation or refuse an unsafe workflow; it must not silently reinterpret
+existing data or claim that a refused operation succeeded.
 
 The threat boundary and remaining responsibilities live in
 [docs/security-model.md](docs/security-model.md). Every

package/SUPPORT.md

@@ -3,8 +3,7 @@
 Use GitHub Issues for reproducible defects and setup problems that include a synthetic
 reproduction. Include operating system, architecture, Node version, Supabase CLI version,
 Docker engine, the failing command, safe diagnostics, and the smallest reproduction.
-The first beta does not yet maintain a separate public discussion or feature-request
-channel.
+Search existing reports before opening a new issue.
 
 Run `npx rehearsal support` or choose **Get help** in the guide to collect the environment
 and readiness portion without assembling it by hand. The report intentionally excludes
@@ -15,6 +14,8 @@ Do not include credentials, connection strings, source rows, baseline artifacts,
 URLs, or proprietary migrations. Report security problems through private vulnerability
 reporting as described in [SECURITY.md](SECURITY.md).
 
-The package is pre-release. The supported matrix is defined in
+The supported matrix and 1.x compatibility boundary are defined in
 [COMPATIBILITY.md](COMPATIBILITY.md); unsupported environments are welcome as clearly
 labelled experiments but cannot be treated as verified behavior.
+
+Support is community-based; no response-time guarantee or production SLA is offered.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "0.1.0-rc.9",
+    "version": "1.0.1",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -76,9 +76,9 @@
         "test:fixture:standalone": "npm run build && node scripts/verification/run_scenario.mjs standalone",
         "test:fixture:privacy": "npm run build && node scripts/verification/run_scenario.mjs privacy",
         "test:fixture:resources": "npm run build && node scripts/verification/run_scenario.mjs resources",
-        "release:verify": "node scripts/verification/release_gate.mjs",
+        "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/application/interactive_task.d.mts

@@ -1,12 +1,8 @@
 /** Run identity discovery while an owned local application remains available. */
 import type { EventEmitter } from "node:events";
+import { type TerminalInput } from "../shared/terminal_input.mjs";
 import { type ApplicationDiagnostics, type ApplicationSession, type ApplicationSessionSignal } from "./session.mjs";
 type SignalTarget = Pick<EventEmitter, "prependListener" | "removeListener">;
-interface SessionInput {
-    readonly isTTY?: boolean;
-    prependListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
-    removeListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
-}
 /**
  * A terminal interruption aborts the task and retires the owned process group.
  * A completed task leaves the session running so its caller can deliberately
@@ -16,7 +12,7 @@ export declare const runApplicationSessionTask: <Value>({ session, task, signalT
     session: ApplicationSession;
     task: (signal: AbortSignal) => Promise<Value>;
     signalTarget?: SignalTarget;
-    input?: SessionInput;
+    input?: TerminalInput | null;
     onReady?: (ready: ApplicationSession["ready"]) => void;
 }) => Promise<Readonly<{
     completed: true;

package/dist/src/application/interactive_task.mjs

@@ -1,4 +1,5 @@
 /** Run identity discovery while an owned local application remains available. */
+import { acquireTerminalInput, } from "../shared/terminal_input.mjs";
 import { summarizeProjectCommandFailure, } from "./session.mjs";
 const SESSION_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGTSTP"];
 /**
@@ -23,19 +24,10 @@ export const runApplicationSessionTask = async ({ session, task, signalTarget =
     for (const [signal, handler] of handlers) {
         signalTarget.prependListener(signal, handler);
     }
-    const onInput = (chunk) => {
-        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        if (bytes.includes(0x03)) {
-            finishInterruption({ kind: "interrupted", signal: "SIGINT" });
-        }
-        else if (bytes.includes(0x1a)) {
-            finishInterruption({ kind: "interrupted", signal: "SIGTSTP" });
-        }
-    };
-    if (input?.isTTY)
-        input.prependListener("data", onInput);
+    let releaseInput = () => undefined;
     const abortController = new AbortController();
     try {
+        releaseInput = acquireTerminalInput(input, (signal) => finishInterruption({ kind: "interrupted", signal }));
         onReady(session.ready);
         const outcome = await Promise.race([
             interruption,
@@ -77,7 +69,6 @@ export const runApplicationSessionTask = async ({ session, task, signalTarget =
         for (const [signal, handler] of handlers) {
             signalTarget.removeListener(signal, handler);
         }
-        if (input?.isTTY)
-            input.removeListener("data", onInput);
+        releaseInput();
     }
 };

package/dist/src/application/session.d.mts

@@ -3,7 +3,8 @@ import { spawn } from "node:child_process";
 import type { EventEmitter } from "node:events";
 import { waitForApplicationIdle } from "./activity_monitor.mjs";
 import type { ApplicationActivity } from "./activity_contract.mjs";
-declare const SESSION_SIGNALS: string[];
+import { type TerminalInput } from "../shared/terminal_input.mjs";
+declare const SESSION_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP", "SIGTSTP"];
 type SessionSignal = (typeof SESSION_SIGNALS)[number];
 export type ApplicationSessionSignal = SessionSignal;
 export interface ApplicationReadiness {
@@ -29,11 +30,6 @@ interface ChildExit {
     readonly status: number | null;
     readonly signal: NodeJS.Signals | null;
 }
-interface SessionInput {
-    readonly isTTY?: boolean;
-    prependListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
-    removeListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
-}
 interface EnvironmentInput {
     readonly files: Readonly<Record<string, string>> & {
         readonly primary: string;
@@ -66,7 +62,7 @@ export declare const summarizeProjectCommandFailure: ({ error, status, signal, s
     stdoutByteCount?: number;
     stderrByteCount?: number;
 }) => string;
-export declare const startApplicationSession: ({ command, cwd, files, mappings, readiness, inheritedEnvironment, spawnImplementation, fetchImplementation, signalTarget, portPreflight, }: EnvironmentInput & {
+export declare const startApplicationSession: ({ command, cwd, files, mappings, readiness, inheritedEnvironment, spawnImplementation, fetchImplementation, signalTarget, input, portPreflight, }: EnvironmentInput & {
     command: string;
     cwd: string;
     readiness: ApplicationReadiness;
@@ -74,6 +70,7 @@ export declare const startApplicationSession: ({ command, cwd, files, mappings,
     spawnImplementation?: typeof spawn;
     fetchImplementation?: typeof fetch;
     signalTarget?: SignalTarget;
+    input?: TerminalInput | null;
     portPreflight?: (readiness: ApplicationReadiness) => Promise<void>;
 }) => Promise<ApplicationSession>;
 /**
@@ -83,7 +80,7 @@ export declare const startApplicationSession: ({ command, cwd, files, mappings,
 export declare const holdApplicationSession: ({ session, signalTarget, input, onReady, activity, idleTimeoutSeconds, idleMonitorImplementation, onActivityAvailability, }: {
     session: ApplicationSession;
     signalTarget?: SignalTarget;
-    input?: SessionInput;
+    input?: TerminalInput | null;
     onReady?: (ready: ApplicationSession["ready"]) => void;
     activity?: ApplicationActivity | null;
     idleTimeoutSeconds?: number | null;

package/dist/src/application/session.mjs

@@ -7,6 +7,8 @@ import { createCleanProcessEnvironment, isLoopbackUrl, } from "../shared/process
 import { assertApplicationPortAvailable } from "./port_preflight.mjs";
 import { waitForApplicationIdle } from "./activity_monitor.mjs";
 import { stopOwnedPosixProcessGroup } from "./process_group.mjs";
+import { acquireTerminalInput, } from "../shared/terminal_input.mjs";
+import { createOperationCancelledError, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
 const ENV_KEY = /^[A-Z][A-Z0-9_]*$/u;
 const MAX_DIAGNOSTIC_BYTES = 64 * 1024;
 const SESSION_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGTSTP"];
@@ -188,7 +190,7 @@ const stopOwnedChild = async (child) => {
             throw new Error("Owned application process group did not stop within its shutdown bound. No unrelated process was targeted.");
     }
 };
-export const startApplicationSession = async ({ command, cwd, files, mappings, readiness, inheritedEnvironment = process.env, spawnImplementation = spawn, fetchImplementation = fetch, signalTarget = process, portPreflight = (value) => assertApplicationPortAvailable({ url: value?.url }), }) => {
+export const startApplicationSession = async ({ command, cwd, files, mappings, readiness, inheritedEnvironment = process.env, spawnImplementation = spawn, fetchImplementation = fetch, signalTarget = process, input = process.stdin, portPreflight = (value) => assertApplicationPortAvailable({ url: value?.url }), }) => {
     const mapped = await buildApplicationEnvironment({ files, mappings });
     const [program, ...args] = parseCommand(command);
     await portPreflight(readiness);
@@ -228,13 +230,22 @@ export const startApplicationSession = async ({ command, cwd, files, mappings, r
     });
     let interruptStartup = () => undefined;
     const interruption = new Promise((_, reject) => {
-        interruptStartup = (signal) => reject(new Error(`Application startup was interrupted by ${signal}.`));
+        interruptStartup = (signal) => reject(createOperationCancelledError(signal));
     });
-    const startupHandlers = new Map(SESSION_SIGNALS.map((signal) => [signal, () => interruptStartup(signal)]));
+    let releaseInput = null;
+    const startupHandlers = new Map(SESSION_SIGNALS.map((signal) => [
+        signal,
+        () => {
+            if (!releaseInput || releaseInput.isCurrentOwner())
+                interruptStartup(signal);
+        },
+    ]));
     for (const [signal, handler] of startupHandlers) {
         signalTarget.prependListener(signal, handler);
     }
     try {
+        releaseInput = acquireTerminalInput(input, interruptStartup);
+        throwIfOperationCancelled();
         const ready = await Promise.race([
             waitForReadiness({
                 readiness,
@@ -255,13 +266,19 @@ export const startApplicationSession = async ({ command, cwd, files, mappings, r
         });
     }
     catch (error) {
-        await stopApplication();
+        try {
+            await stopApplication();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "Application startup failed and its owned process could not be stopped.");
+        }
         throw error;
     }
     finally {
         for (const [signal, handler] of startupHandlers) {
             signalTarget.removeListener(signal, handler);
         }
+        releaseInput?.();
     }
 };
 /**
@@ -278,26 +295,23 @@ export const holdApplicationSession = async ({ session, signalTarget = process,
     const interruption = new Promise((resolve) => {
         finishInterruption = resolve;
     });
+    let releaseInput = null;
     const handlers = new Map(SESSION_SIGNALS.map((signal) => [
         signal,
-        () => finishInterruption({ kind: "interrupted", signal }),
+        () => {
+            if (!releaseInput || releaseInput.isCurrentOwner())
+                finishInterruption({ kind: "interrupted", signal });
+        },
     ]));
     for (const [signal, handler] of handlers) {
         signalTarget.prependListener(signal, handler);
     }
-    const onInput = (chunk) => {
-        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        if (bytes.includes(0x03)) {
-            finishInterruption({ kind: "interrupted", signal: "SIGINT" });
-        }
-        else if (bytes.includes(0x1a)) {
-            finishInterruption({ kind: "interrupted", signal: "SIGTSTP" });
-        }
-    };
-    if (input?.isTTY)
-        input.prependListener("data", onInput);
     const activityController = new AbortController();
+    let operationFailed = false;
+    let operationError;
     try {
+        releaseInput = acquireTerminalInput(input, (signal) => finishInterruption({ kind: "interrupted", signal }));
+        throwIfOperationCancelled();
         if (idleTimeoutSeconds !== null &&
             (!activity ||
                 !Number.isSafeInteger(idleTimeoutSeconds) ||
@@ -338,20 +352,31 @@ export const holdApplicationSession = async ({ session, signalTarget = process,
             },
         });
     }
+    catch (error) {
+        operationFailed = true;
+        operationError = error;
+        throw error;
+    }
     finally {
         activityController.abort();
         try {
             // npm can forward the terminal's SIGINT after the CLI receives it.
             // Keep our handlers installed until the owned process group is fully
             // stopped so a duplicate signal cannot terminate Rehearsal mid-cleanup.
-            await session.stop();
+            try {
+                await session.stop();
+            }
+            catch (cleanupError) {
+                if (operationFailed)
+                    throw new AggregateError([operationError, cleanupError], "Application session failed and its owned process could not be stopped.");
+                throw cleanupError;
+            }
         }
         finally {
             for (const [signal, handler] of handlers) {
                 signalTarget.removeListener(signal, handler);
             }
-            if (input?.isTTY)
-                input.removeListener("data", onInput);
+            releaseInput?.();
         }
     }
 };

package/dist/src/cli/arguments.mjs

@@ -1,4 +1,5 @@
 /** Parse and classify the stable Rehearsal command-line contract. */
+import { RehearsalError } from "../shared/diagnostics.mjs";
 export const parseArguments = (arguments_) => {
     const flags = {
         json: false,
@@ -86,7 +87,13 @@ export const parseArguments = (arguments_) => {
         else if (argument.startsWith("--image-id="))
             (flags.imageIds ??= []).push(argument.slice("--image-id=".length));
         else if (argument.startsWith("--"))
-            throw new Error(`Unknown Rehearsal option: ${argument}.`);
+            throw new RehearsalError({
+                category: "configuration_invalid",
+                code: "CONFIGURATION_INVALID",
+                message: `Unknown Rehearsal option: ${argument}.`,
+                refused: "No Rehearsal command was executed.",
+                suggestions: ["Run rehearsal --help to list supported options."],
+            });
         else
             positionals.push(argument);
     }

package/dist/src/cli/rehearsal.mjs

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import * as prompts from "@clack/prompts";
-import { normalizeRehearsalError, renderHumanError, serializeRehearsalError, } from "../shared/diagnostics.mjs";
+import { RehearsalError, normalizeRehearsalError, 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";
@@ -22,6 +22,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");
@@ -70,7 +71,13 @@ const executeCommand = async ({ command, flags, planOptions, guided, }) => {
         state,
     });
     if (!result) {
-        throw new Error(`Unknown Rehearsal command: ${command}.\n\n${usage()}`);
+        throw new RehearsalError({
+            category: "configuration_invalid",
+            code: "CONFIGURATION_INVALID",
+            message: `Unknown Rehearsal command: ${command}.\n\n${usage()}`,
+            refused: "No Rehearsal command was executed.",
+            suggestions: ["Run rehearsal --help to list supported commands."],
+        });
     }
     const exitCode = emitCommand({ command, flags, result });
     if (exitCode !== undefined)
@@ -88,8 +95,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,
@@ -141,12 +157,18 @@ const main = async () => {
                                 removeGuidedExitShortcut = null;
                             }
                             try {
-                                await executeCommand({
+                                const executeSelected = () => executeCommand({
                                     command: selected,
                                     flags,
                                     planOptions,
                                     guided: true,
                                 });
+                                if (opensApplication) {
+                                    await runWithOperationCancellation({ task: executeSelected });
+                                }
+                                else {
+                                    await executeSelected();
+                                }
                             }
                             finally {
                                 if (opensApplication) {