@rehearsal-db/core 0.1.0-rc.2 → 0.1.0-rc.4

package/CHANGELOG.md

@@ -5,6 +5,58 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-rc.4] - 2026-10-11
+
+### Added
+
+- `discover --json` exposes a versioned, read-only Project Profile for editor clients,
+  separating proven facts, evidence-backed suggestions, and decisions that remain with
+  the user.
+- Project discovery reports bounded application, package-manager, migration, target,
+  runtime, baseline-retention, configuration, and local-address metadata without reading
+  environment files, contacting databases, starting containers, or executing project code.
+- Public TypeScript contracts now cover discovery results, retained baseline generations,
+  application readiness, cleanup policy, and structured PostgreSQL and Supabase runtime
+  state consumed by the Rehearsal VS Code extension.
+
+### Changed
+
+- Plans and status results expose the additional bounded metadata required for a
+  project-aware editor experience while retaining core ownership of all safety checks and
+  mutating operations.
+- Documentation now includes the supported VS Code integration boundary, privacy model,
+  compatibility floor, and safe automatic-refresh behavior.
+
+## [0.1.0-rc.3] - 2026-10-10
+
+### Added
+
+- `status --json` now exposes bounded, target-scoped runtime state without requiring
+  editor clients to parse human-formatted process output.
+- `activity --json` reports idle, busy, stale, invalid, and unavailable project-operation
+  state without exposing lock tokens, process arguments, credentials, or private paths.
+- Supported mutating operations now have an explicit cancellation contract: owned child
+  groups receive one bounded shutdown request, rollback and lock cleanup complete before
+  exit `130`, and unrelated processes and Docker resources remain untouched.
+- Root configuration can now choose `stop-after-run` for bounded automated checks and
+  `stop-on-application-exit` for bounded hands-on sessions. Both modes stop only the
+  configured Rehearsal targets while preserving database and Storage volumes, applied
+  migrations, and sandbox edits for the next `start` or `open`.
+- Plans, JSON results, terminal receipts, generated configuration comments, and the
+  lifecycle guide now report the selected persistence mode and resulting runtime state.
+
+### Changed
+
+- Transient application and helper processes are cleaned up before an opted-in runtime
+  stop after success, proof failure, readiness timeout, or supported interruption. The
+  compatibility default remains `keep-until-stop` for both `run` and `open`.
+
+### Fixed
+
+- Read-only runtime inspection now works when a VS Code extension launches the CLI
+  through Electron's executable in Node mode. That mode is preserved only for
+  Rehearsal's nested runtime manager and is not exposed to project-owned commands.
+
 ## [0.1.0-rc.2] - 2026-10-09
 
 ### Changed
@@ -575,7 +627,9 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
   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.2...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.4...HEAD
+[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
 [0.1.0-rc.1]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.18...v0.1.0-rc.1
 [0.1.0-beta.18]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.17...v0.1.0-beta.18

package/README.md

@@ -116,7 +116,9 @@ source-owner approval; see [Standalone workflow](docs/standalone-workflow.md).
 
 `npx rehearsal open` starts and verifies the existing local runtime, keeps the configured
 app available until you press `Ctrl+C`, and preserves database and Storage changes for
-the next session.
+the next session. Set `lifecycle.open` to `stop-on-application-exit` when you also want
+its database targets stopped afterward; `lifecycle.run: "stop-after-run"` gives automated
+checks the same bounded, non-destructive behavior.
 
 For an approved production-shaped copy, the optional sequence is `source plan`, `source
 apply`, `refresh`, and `source retire`. `refresh` verifies the replacement before it
@@ -164,6 +166,7 @@ Start here:
 
 - [Documentation home](docs/index.md) — choose the shortest path for your goal
 - [Getting started](docs/getting-started.md) — set up your own project
+- [VS Code extension](docs/vscode.md) — use the project-aware visual workbench
 - [Safe hands-on tutorial](docs/tutorial.md) — try the full flow in a disposable project
 - [Troubleshooting](docs/troubleshooting.md) — fix common setup problems
 - [Next steps](docs/roadmap.md) — see the current product sequence

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "0.1.0-rc.2",
+    "version": "0.1.0-rc.4",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -22,6 +22,9 @@
     "bin": {
         "rehearsal": "dist/src/cli/rehearsal.mjs"
     },
+    "rehearsalContracts": {
+        "projectDiscovery": 1
+    },
     "exports": {
         ".": {
             "types": "./types/configuration.d.mts",

package/dist/scripts/runtime/manage_database.mjs

@@ -6,11 +6,20 @@
 import { loadRehearsalConfig } from "../../src/project/configuration.mjs";
 import { parseRuntimeInvocation } from "../../src/targets/target.mjs";
 import { runRuntimeTarget } from "../../src/targets/driver.mjs";
-const invocation = parseRuntimeInvocation();
-const { config } = await loadRehearsalConfig({
-    projectRoot: process.cwd(),
-    ...(invocation.configPath === undefined
-        ? {}
-        : { configPath: invocation.configPath }),
-});
-await runRuntimeTarget(config.runtime.target);
+import { runWithOperationCancellation } from "../../src/shared/cancellation.mjs";
+const run = async () => {
+    const invocation = parseRuntimeInvocation();
+    const { config } = await loadRehearsalConfig({
+        projectRoot: process.cwd(),
+        ...(invocation.configPath === undefined
+            ? {}
+            : { configPath: invocation.configPath }),
+    });
+    await runRuntimeTarget(config.runtime.target);
+};
+if (process.env.REHEARSAL_CANCELLABLE_OPERATION === "1") {
+    await runWithOperationCancellation({ task: run });
+}
+else {
+    await run();
+}

package/dist/src/baseline/artifact.d.mts

@@ -66,6 +66,17 @@ export interface BaselinePrunePlan {
     readonly retained: string[];
     readonly removed: string[];
 }
+export interface BaselineGenerationSummary {
+    readonly generationId: string;
+    readonly createdAt: string | null;
+    readonly active: boolean;
+    readonly formatVersion: 1 | 2;
+    readonly rowCount: number;
+    readonly tableCount: number;
+    readonly migrationCount: number;
+    readonly migrationCutoff: string;
+    readonly storageAssetCount: number;
+}
 export declare const createBaselineGenerationId: ({ now, }?: {
     now?: Date;
 }) => string;
@@ -91,6 +102,9 @@ export declare const removeStagedBaselineGeneration: ({ artifactRoot, generation
 export declare const resolveActiveBaselinePaths: ({ artifactRoot, }: {
     artifactRoot: string;
 }) => Promise<ActiveBaselinePaths>;
+export declare const inspectBaselineGenerations: ({ artifactRoot, }: {
+    artifactRoot: string;
+}) => Promise<readonly BaselineGenerationSummary[]>;
 export declare const verifyActiveBaseline: ({ artifactRoot, }: {
     artifactRoot: string;
 }) => Promise<BaselineManifest>;

package/dist/src/baseline/artifact.mjs

@@ -46,6 +46,12 @@ const assertGenerationId = (value) => {
     }
     return value;
 };
+const generationCreatedAt = (generationId) => {
+    const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z-/u.exec(generationId);
+    return match
+        ? `${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}Z`
+        : null;
+};
 const assertArtifactRoot = (artifactRoot) => {
     const resolved = resolve(artifactRoot);
     if (basename(resolved) !== ".rehearsal" || resolved === sep) {
@@ -364,6 +370,50 @@ export const resolveActiveBaselinePaths = async ({ artifactRoot, }) => {
         schemaPath: join(generationDirectory, "production-schema.sql"),
     };
 };
+export const inspectBaselineGenerations = async ({ artifactRoot, }) => {
+    const root = assertArtifactRoot(artifactRoot);
+    const active = basename((await resolveActiveBaselinePaths({ artifactRoot: root }))
+        .generationDirectory);
+    const generationsRoot = join(root, generationsDirectoryName);
+    await verifyNoSymlink(generationsRoot, "The Rehearsal generations directory");
+    const entries = await readdir(generationsRoot, { withFileTypes: true });
+    if (entries.length > 1_000) {
+        throw new Error("The Rehearsal baseline generation limit was exceeded.");
+    }
+    const summaries = [];
+    for (const entry of entries.sort((left, right) => right.name.localeCompare(left.name))) {
+        if (!entry.isDirectory() || !generationPattern.test(entry.name))
+            continue;
+        const generationDirectory = assertInsideRoot(root, join(generationsRoot, entry.name));
+        await verifyNoSymlink(generationDirectory, "A Rehearsal baseline generation");
+        const manifest = parseManifest(await readFile(join(generationDirectory, "baseline-manifest.json"), "utf8"));
+        if (manifest.generationId !== entry.name ||
+            ![1, 2].includes(manifest.formatVersion) ||
+            !Number.isSafeInteger(manifest.rowCount) ||
+            manifest.rowCount < 0 ||
+            !isObject(manifest.tableCounts) ||
+            !isObject(manifest.migrations) ||
+            !isObject(manifest.storageAssets) ||
+            typeof manifest.migrationCutoff !== "string") {
+            throw new Error(`Rehearsal baseline generation ${entry.name} has an invalid manifest.`);
+        }
+        summaries.push({
+            generationId: entry.name,
+            createdAt: generationCreatedAt(entry.name),
+            active: entry.name === active,
+            formatVersion: manifest.formatVersion,
+            rowCount: manifest.rowCount,
+            tableCount: Object.keys(manifest.tableCounts).length,
+            migrationCount: Object.keys(manifest.migrations).length,
+            migrationCutoff: manifest.migrationCutoff,
+            storageAssetCount: Object.keys(manifest.storageAssets).length,
+        });
+    }
+    if (!summaries.some(({ active: isActive }) => isActive)) {
+        throw new Error("The active Rehearsal baseline generation is unavailable.");
+    }
+    return Object.freeze(summaries.map((summary) => Object.freeze(summary)));
+};
 export const verifyActiveBaseline = async ({ artifactRoot, }) => {
     const paths = await resolveActiveBaselinePaths({ artifactRoot });
     const { generationDirectory } = paths;

package/dist/src/cli/application_command_handlers.mjs

@@ -14,10 +14,10 @@ export const createApplicationCommandHandlers = ({ openRuntimeApplication, }) =>
             onReady: (ready) => {
                 const lines = [
                     `Application: ${ready.url}`,
-                    "The verified database runtime stays running and keeps your local changes.",
+                    "The configured lifecycle policy will preserve your local database and Storage changes.",
                     guided
                         ? "Press Ctrl+C to close the app and return here, or Ctrl+Z to exit Rehearsal."
-                        : "Press Ctrl+C or Ctrl+Z to close the app. Rehearsal will leave the database runtime running.",
+                        : "Press Ctrl+C or Ctrl+Z to close the app. Rehearsal will then apply the configured lifecycle policy.",
                 ];
                 if (useStyledPrompts(flags)) {
                     prompts.note(lines.join("\n"), "SANDBOX READY");
@@ -35,6 +35,7 @@ export const createApplicationCommandHandlers = ({ openRuntimeApplication, }) =>
                 data.started.output,
                 data.verified.output,
                 ...data.preparations.map((preparation) => preparation.output),
+                data.lifecycle.stop?.output,
             ]
                 .filter(Boolean)
                 .join("\n");
@@ -44,8 +45,12 @@ export const createApplicationCommandHandlers = ({ openRuntimeApplication, }) =>
             render: (result) => [
                 "SANDBOX APP CLOSED",
                 `Application stopped after ${result.application.stoppedBy}.`,
-                "The database runtime and its local database and Storage changes were preserved.",
-                "Run rehearsal open to return, rehearsal verify to check it, or rehearsal stop to stop the databases.",
+                result.lifecycle.runtimeState === "stopped"
+                    ? `Lifecycle ${result.lifecycle.mode} stopped the database runtime; its local database and Storage changes were preserved.`
+                    : `Lifecycle ${result.lifecycle.mode} left the database runtime running; its local database and Storage changes were preserved.`,
+                result.lifecycle.runtimeState === "stopped"
+                    ? "Run rehearsal start or rehearsal open to resume."
+                    : "Run rehearsal open to return, rehearsal verify to check it, or rehearsal stop to stop the databases.",
             ].join("\n"),
         });
     }),

package/dist/src/cli/basic_command_handlers.mjs

@@ -20,7 +20,9 @@ Commands:
   identity claim --identity= --confirm-identity= Apply the exact local association
   identity connect [--identity=] Keep the app open, detect sign-in, and connect once
   doctor                     Check whether Rehearsal is safe and ready
+  discover                   Inspect project metadata and explain setup suggestions
   support                    Print a safe, copy-ready support report
+  activity                   Report idle, busy, stale, or invalid operation state
   explain                    Show the immutable execution plan
   run --dry-run              Alias the exact explain plan without mutations
   run --confirm-candidates=  Execute reset, migration, and verification locally

package/dist/src/cli/inspection_command_handlers.mjs

@@ -1,10 +1,55 @@
 /** Read-only readiness, support, planning, and inspection command handlers. */
 import { collectRehearsalSupportReport } from "../project/support_report.mjs";
+import { discoverProjectProfile } from "../project/project_discovery.mjs";
 import { inspectRehearsalBaseline, inspectRehearsalMigrations, } from "../runtime/plan.mjs";
 import { buildRuntimeStackPlan, runRuntimeStackDoctor, topologyCandidateSummary, } from "./runtime_commands.mjs";
 import { renderBaseline, renderCandidates, renderDoctor, renderMigrations, renderPlan, renderSupportReport, } from "./renderers.mjs";
 import { exactCommands, renderedCommand } from "./command_contract.mjs";
+import { inspectProjectOperationState } from "../shared/operation_guard.mjs";
 export const createInspectionCommandHandlers = () => [
+    exactCommands("discover", ["discover"], async ({ planOptions }) => {
+        const data = await discoverProjectProfile({
+            projectRoot: planOptions.projectRoot ?? process.cwd(),
+        });
+        return renderedCommand({
+            data,
+            render: (result) => [
+                `PROJECT PROFILE — READ ONLY`,
+                `Detected: ${result.detected.length}`,
+                `Suggested: ${result.suggested.length}`,
+                `Your decision: ${result.decisions.length}`,
+                `Configuration: ${result.configuration.state.replaceAll("_", " ")}`,
+                "",
+                "Run rehearsal discover --json for evidence and proposed configuration fields.",
+            ].join("\n"),
+        });
+    }),
+    exactCommands("activity", ["activity"], async ({ planOptions }) => {
+        const data = await inspectProjectOperationState({
+            projectRoot: planOptions.projectRoot ?? process.cwd(),
+        });
+        return renderedCommand({
+            data,
+            render: (result) => {
+                if (result.state === "idle")
+                    return "Rehearsal activity: idle.";
+                if (result.state === "invalid") {
+                    return "Rehearsal activity: invalid lock state. No lock was changed; finish or diagnose the owning operation before retrying a mutation.";
+                }
+                const label = result.state === "busy" ? "busy" : "stale";
+                return [
+                    `Rehearsal activity: ${label}.`,
+                    `Operation: ${result.operation.kind}`,
+                    `Started: ${result.operation.startedAt}`,
+                    result.operation.rehearsalVersion
+                        ? `Rehearsal: ${result.operation.rehearsalVersion}`
+                        : null,
+                ]
+                    .filter(Boolean)
+                    .join("\n");
+            },
+        });
+    }),
     exactCommands("doctor", ["doctor"], async ({ guided, flags, planOptions }) => {
         const data = await runRuntimeStackDoctor(planOptions);
         return renderedCommand({

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

@@ -17,7 +17,7 @@ type RunManager = (input: {
     flags: RehearsalCliFlags;
     configPath?: string;
     targetName?: string;
-}) => unknown;
+}) => Promise<unknown>;
 interface ProjectCommandInput {
     readonly flags: RehearsalCliFlags;
     readonly planOptions: RehearsalConfigPathOptions;
@@ -67,6 +67,10 @@ export declare const createProjectCommands: ({ projectRoot, runManager, }: {
                 containerRuntime: Readonly<{
                     autoStartColima: boolean;
                 }>;
+                lifecycle: Readonly<{
+                    run: "keep-until-stop" | "stop-after-run";
+                    open: "keep-until-stop" | "stop-on-application-exit";
+                }>;
                 cleanup: Readonly<{
                     retainBaselineGenerations: number;
                 }>;
@@ -191,6 +195,10 @@ export declare const createProjectCommands: ({ projectRoot, runManager, }: {
                 containerRuntime: Readonly<{
                     autoStartColima: boolean;
                 }>;
+                lifecycle: Readonly<{
+                    run: "keep-until-stop" | "stop-after-run";
+                    open: "keep-until-stop" | "stop-on-application-exit";
+                }>;
                 cleanup: Readonly<{
                     retainBaselineGenerations: number;
                 }>;

package/dist/src/cli/project_commands.mjs

@@ -128,7 +128,7 @@ export const createProjectCommands = ({ projectRoot, runManager, }) => {
                         projectRoot,
                         configPath: target.configPath,
                         removeRuntime: async () => {
-                            runManager({
+                            await runManager({
                                 action: "discard",
                                 flags,
                                 configPath: target.configPath,
@@ -151,7 +151,7 @@ export const createProjectCommands = ({ projectRoot, runManager, }) => {
                 : { confirmation: flags.cleanupConfirmation }),
             ...planOptions,
             removeRuntime: async () => {
-                runManager({ action: "discard", flags });
+                await runManager({ action: "discard", flags });
             },
         });
         return { mode: "written", plan, applied };

package/dist/src/cli/rehearsal.mjs

@@ -20,6 +20,7 @@ import { createProjectCommands } from "./project_commands.mjs";
 import { buildRuntimeStackPlan, createRuntimeCommands, runRuntimeStackDoctor, topologyCandidateSummary, topologyCommandEnvironment, } from "./runtime_commands.mjs";
 import { buildRefreshWorkflowPlan, createRefreshWorkflow, } from "./source_commands.mjs";
 import { installGuidedExitShortcut, useStyledPrompts } from "./terminal.mjs";
+import { runWithOperationCancellation, supportsOperationCancellation, } from "../shared/cancellation.mjs";
 const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
 const projectRoot = process.cwd();
 const managerPath = join(packageRoot, "dist/scripts/runtime/manage_database.mjs");
@@ -89,83 +90,94 @@ const main = async () => {
     const guided = command === "guide" || wantsAutomaticGuide;
     const mutating = commandMutatesProject({ command, flags, guided });
     const operation = mutating
-        ? await acquireProjectOperation({ projectRoot, command })
+        ? await acquireProjectOperation({
+            projectRoot,
+            command: guided ? "guide" : command,
+        })
         : null;
-    if (operation) {
-        activePackageFingerprint = createInstalledPackageFingerprint({
-            packageRoot,
-        });
-    }
-    try {
-        if (!guided) {
-            await executeCommand({ command, flags, planOptions, guided: false });
-            return;
-        }
-        if (!process.stdin.isTTY || !process.stdout.isTTY) {
-            throw new Error("The guided home screen requires an interactive terminal. Run rehearsal --help to list scriptable commands.");
-        }
-        flags.guided = true;
-        const installExitShortcut = () => installGuidedExitShortcut(flags, {
-            beforeExit: () => operation?.releaseSync(),
-        });
-        let removeGuidedExitShortcut = installExitShortcut();
-        if (useStyledPrompts(flags)) {
-            prompts.intro("REHEARSAL · Safe local migration testing");
+    const run = async () => {
+        if (operation) {
+            activePackageFingerprint = createInstalledPackageFingerprint({
+                packageRoot,
+            });
         }
         try {
-            while (true) {
-                resetGuidedFlags(flags);
-                resetCommandSessionState(state);
-                const selected = await runGuidedHome({ flags, planOptions });
-                if (!selected)
-                    break;
-                if (selected === "home")
-                    continue;
-                const opensApplication = selected === "open";
-                if (opensApplication) {
-                    removeGuidedExitShortcut?.();
-                    removeGuidedExitShortcut = null;
+            if (!guided) {
+                await executeCommand({ command, flags, planOptions, guided: false });
+                return;
+            }
+            if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                throw new Error("The guided home screen requires an interactive terminal. Run rehearsal --help to list scriptable commands.");
+            }
+            flags.guided = true;
+            const installExitShortcut = () => installGuidedExitShortcut(flags, {
+                beforeExit: () => operation?.releaseSync(),
+            });
+            let removeGuidedExitShortcut = installExitShortcut();
+            if (useStyledPrompts(flags)) {
+                prompts.intro("REHEARSAL · Safe local migration testing");
+            }
+            try {
+                while (true) {
+                    resetGuidedFlags(flags);
+                    resetCommandSessionState(state);
+                    const selected = await runGuidedHome({ flags, planOptions });
+                    if (!selected)
+                        break;
+                    if (selected === "home")
+                        continue;
+                    const opensApplication = selected === "open";
+                    if (opensApplication) {
+                        removeGuidedExitShortcut?.();
+                        removeGuidedExitShortcut = null;
+                    }
+                    try {
+                        await executeCommand({
+                            command: selected,
+                            flags,
+                            planOptions,
+                            guided: true,
+                        });
+                    }
+                    finally {
+                        if (opensApplication) {
+                            removeGuidedExitShortcut = installExitShortcut();
+                        }
+                    }
+                    if (flags.exitGuidedSession)
+                        break;
                 }
+            }
+            finally {
+                removeGuidedExitShortcut?.();
+            }
+            if (useStyledPrompts(flags)) {
+                prompts.outro("See you at the next rehearsal.");
+            }
+            else {
+                console.log("See you at the next rehearsal.");
+            }
+        }
+        finally {
+            if (operation) {
                 try {
-                    await executeCommand({
-                        command: selected,
-                        flags,
-                        planOptions,
-                        guided: true,
+                    assertInstalledPackageFingerprint({
+                        packageRoot,
+                        expected: activePackageFingerprint,
                     });
                 }
                 finally {
-                    if (opensApplication) {
-                        removeGuidedExitShortcut = installExitShortcut();
-                    }
+                    activePackageFingerprint = null;
+                    await operation.release();
                 }
-                if (flags.exitGuidedSession)
-                    break;
             }
         }
-        finally {
-            removeGuidedExitShortcut?.();
-        }
-        if (useStyledPrompts(flags)) {
-            prompts.outro("See you at the next rehearsal.");
-        }
-        else {
-            console.log("See you at the next rehearsal.");
-        }
+    };
+    if (operation && !guided && supportsOperationCancellation(command)) {
+        await runWithOperationCancellation({ task: run });
     }
-    finally {
-        if (operation) {
-            try {
-                assertInstalledPackageFingerprint({
-                    packageRoot,
-                    expected: activePackageFingerprint,
-                });
-            }
-            finally {
-                activePackageFingerprint = null;
-                await operation.release();
-            }
-        }
+    else {
+        await run();
     }
 };
 try {

package/dist/src/cli/runtime_action_handlers.mjs

@@ -1,6 +1,7 @@
 /** Database runtime action handlers shared by guided and scripted CLI flows. */
 import * as prompts from "@clack/prompts";
 import { buildApplicationEnvironment, runHttpProofs, startApplicationSession, } from "../application/session.mjs";
+import { applyRuntimePersistence } from "../runtime/persistence.mjs";
 import { exactCommands, renderedCommand, silentCommand, } from "./command_contract.mjs";
 import { topologyCommandEnvironment, topologyEnvironmentFiles, } from "./runtime_commands.mjs";
 import { formatDuration, isHumanTerminal, terminalStyle, useStyledPrompts, } from "./terminal.mjs";
@@ -42,17 +43,20 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
             });
             const { runtime, topology } = stack;
             const stackEnvironment = topologyCommandEnvironment(topology);
-            const preparations = ["run", "reset", "migrate"].includes(command)
-                ? prepareDependentTargets({
-                    topology,
-                    environment: stackEnvironment,
-                })
-                : [];
+            let preparations = [];
             let applicationProof;
             let dependentProofs = [];
             let httpProofResults = [];
             let applicationReadiness;
-            if (command === "run") {
+            const completeFollowups = async () => {
+                preparations = ["run", "reset", "migrate"].includes(command)
+                    ? await prepareDependentTargets({
+                        topology,
+                        environment: stackEnvironment,
+                    })
+                    : [];
+                if (command !== "run")
+                    return;
                 const applicationConfig = topology.primary.config.application;
                 const mappedApplicationEnvironment = Object.keys(applicationConfig.environmentVariables).length
                     ? await buildApplicationEnvironment({
@@ -111,7 +115,19 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                 else if (isHumanTerminal(flags)) {
                     console.log(`${terminalStyle(flags, "32", "✓")} Project proofs passed.`);
                 }
-            }
+            };
+            const persistence = command === "run"
+                ? await applyRuntimePersistence({
+                    mode: topology.primary.config.lifecycle.run,
+                    operation: completeFollowups,
+                    stop: async () => (await runRuntimeStack({
+                        command: "stop",
+                        flags,
+                        planOptions,
+                        session: state,
+                    })).runtime,
+                })
+                : (await completeFollowups(), null);
             const data = command === "run"
                 ? {
                     runtime,
@@ -120,6 +136,7 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                     applicationProof,
                     applicationReadiness,
                     httpProofResults,
+                    lifecycle: persistence.lifecycle,
                 }
                 : preparations.length
                     ? { ...runtime, preparations }
@@ -130,6 +147,7 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                     ...preparations.map((preparation) => preparation.output),
                     ...dependentProofs.map((proof) => proof.output),
                     applicationProof?.output,
+                    persistence?.lifecycle.stop?.output,
                 ]
                     .filter(Boolean)
                     .join("\n");
@@ -145,8 +163,11 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                         ? value.applicationReadiness
                         : undefined;
                     const renderedHttpProofResults = "httpProofResults" in value ? value.httpProofResults : [];
+                    const renderedLifecycle = "lifecycle" in value ? value.lifecycle : undefined;
                     const nextAction = {
-                        run: "Next: run rehearsal open for hands-on testing, then rehearsal verify.",
+                        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.",
                         migrate: "Next: run rehearsal verify to prove the current runtime.",
                         reset: "Next: run rehearsal open or rehearsal verify.",
@@ -171,6 +192,9 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                                 ? `✓ Application became ready at ${renderedApplicationReadiness.url}`
                                 : null,
                             ...renderedHttpProofResults.map((proof) => `✓ ${proof.kind} HTTP proof passed: ${proof.name}`),
+                            renderedLifecycle
+                                ? `✓ Lifecycle ${renderedLifecycle.mode}: runtime ${renderedLifecycle.runtimeState}; data preserved`
+                                : null,
                             "",
                             "Technical output is available from Show details in the guide.",
                         ]
@@ -189,6 +213,9 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                             ? `Application readiness passed: ${renderedApplicationReadiness.url}`
                             : null,
                         ...renderedHttpProofResults.map((proof) => `${proof.kind} HTTP proof passed: ${proof.name}`),
+                        renderedLifecycle
+                            ? `Lifecycle ${renderedLifecycle.mode}: runtime ${renderedLifecycle.runtimeState}; data preserved.`
+                            : null,
                         nextAction ? "" : null,
                         nextAction,
                     ]