@rehearsal-db/core 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ a Changelog, and published versions follow Semantic Versioning.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-10-24
+
+### Added
+
+- Optional free local-user workload admission for participating `start`, `reset`,
+  `run` and `migrate` lifecycle phases. Bounded waits, cancellation and explicit
+  dead-holder metadata recovery do not interrupt another project or expire live
+  owners. Read-only `workloads` reports participation, not available host/VM memory.
+  Existing configurations and editor field metadata remain unchanged when omitted.
+  Application proofs, interactive sessions and nonparticipating tools are outside
+  this first lifecycle-only queue; this is not a distributed or hard-memory scheduler.
+
+## [1.2.0] - 2026-10-24
+
+### Added
+
+- An optional `migrationImpact: 1` contract: offline `inspect impact` and explicitly
+  confirmed `measure impact` for one selected, already-verified disposable local
+  sandbox. Bounded read-only snapshot aggregates cover narrow supported row,
+  populated/NULL, duplicate and foreign-key orphan counts; unsupported or incomplete
+  evidence stays unknown. No pending migration is executed, no runtime is started
+  or repaired, and no SQL, object names or row contents are returned. Counts are
+  not sequential simulation, production prediction or a safety verdict. Existing
+  project locking/cancellation is reused without adding a rehearsal gate or CLI fee.
+- An optional versioned `inspect insights` contract for bounded, read-only static
+  migration warnings. Findings bind to exact pending file bytes and the complete
+  existing candidate digest, with fixed explanations and lexical locations.
+  Unsupported, malformed or truncated analysis remains unknown; no detected
+  warning is never SQL validity, database verification or a safety verdict.
+- Project-local input bounds, unchanged leaf/directory identity checks and shared
+  input hash binding. Inspection neither executes SQL nor starts an engine or
+  contacts a database. Existing migration-plan v1 and failure diagnosis remain
+  separate, unchanged contracts.
+
+### Documentation
+
+- Clarify reviewed PostgreSQL/application/full service dependencies and resource
+  measurement limits without adding service exclusions or a new acceptance gate.
+- Distinguish project runtime hooks from native migration-tool history support.
+
 ## [1.1.0] - 2026-10-21
 
 ### Added
@@ -840,7 +880,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.1.0...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.2...v1.1.0
 [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

package/COMPATIBILITY.md

@@ -38,6 +38,46 @@ through the project's existing version manager or use the helper's explicit exec
 path; see [OS setup](installers/README.md). Helpers never install Node or switch a
 project's runtime automatically.
 
+Core 1.2.0 introduced optional capability
+`rehearsalContracts.migrationInsights: 1` and `inspect insights --json`. It preserves
+existing migration-plan v1, baseline formats, digest meaning and failure diagnosis.
+Consumers must check the capability and exact plan/file bindings; absent or
+unavailable static analysis is not safety evidence. Package publication does not
+establish completed editor, accessibility or genuine-provider acceptance.
+
+Core 1.2.0 also introduced optional `rehearsalContracts.migrationImpact: 1` with
+`inspect impact` and `measure impact`. Consumers must explicitly select a configured
+local target and bind measurement consent to the exact whole-plan digest. Preview
+does not contact a database; measurement reads only the current verified sandbox,
+without applying migrations, starting/repairing a runtime or changing database data.
+Aggregate execution requires PostgreSQL 17 or newer with server-side transaction
+deadlines and narrowly supported ordinary-table/built-in semantics; older servers
+remain unknown, with no automatic database upgrade.
+Supabase measurement uses the ownership-proven local container's built-in
+`supabase_admin` socket role so the fixed disk bound and catalog lock can be enforced.
+It does not promote `postgres`, change grants, load credentials or connect remotely.
+Read-only catalog preflight is separate from the count snapshot. Bounded strong
+relation locks precede that snapshot and temporarily block writers and metadata
+changes in the selected disposable sandbox; this is not a nonblocking query promise.
+Counts are decimal strings or `null` with an explicit unknown reason, never a safety
+verdict, sequential simulation or production prediction. Partial/unknown measurement
+uses `not_ready` with the existing not-ready exit `1`; normal rehearsal gates and existing JSON contracts
+are unchanged. This capability does not claim a new database family or additional
+platform/native acceptance.
+Older strict editor activity consumers can reject the new `measure impact` operation
+kind, including a retained completed receipt. Pair this capability with an editor
+consumer explicitly supporting that kind; the CLI does not silently rename the
+operation, relax unknown-kind validation or update an active editor installation.
+
+Core 1.3.0 introduces optional `rehearsalContracts.workloadQueue: 1`: local
+`workloads` inspection, exact-confirmed dead-holder metadata recovery and opt-in
+`resources.workloadQueue` lifecycle admission. Omitted configuration preserves prior
+behavior. Participating clients cooperate within the same OS user, boot and process
+namespace; older clients and other tools do not participate. This does not measure
+available memory, govern standing runtimes or promise a hard machine-capacity budget.
+The existing editor field-metadata contract is unchanged. See
+[resource review policies](docs/configuration.md#resource-review-policies).
+
 ## Operating systems and execution location
 
 Core 1.0.1's platform boundary distinguishes the computer running VS Code from the

package/README.md

@@ -47,7 +47,7 @@ it through a reviewed privacy policy, and retire the access again. It is never p
 production deployment tool.
 
 The CLI is free and MIT-licensed, with stable releases on
-[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.1.0**;
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.3.0**;
 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.
@@ -198,6 +198,7 @@ Start here:
 - [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
+- [Updates](docs/updating.md) — update the CLI or extension without resetting data
 - [Next steps](docs/roadmap.md) — see the current product sequence
 
 Reference:
@@ -214,9 +215,12 @@ Reference:
 - [Standalone workflow and security gates](docs/standalone-workflow.md)
 - [Runtime and local identity policies](docs/runtime-policies.md)
 - [Glossary](docs/glossary.md)
-- [Repository architecture](docs/architecture.md)
 - [Stability and the first stable release](docs/stability.md)
-- [Release process](docs/releasing.md)
+
+For maintainers developing and publishing Rehearsal:
+
+- [Repository architecture](docs/architecture.md)
+- [Maintainer release process](docs/releasing.md)
 
 ## Getting support
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -26,7 +26,10 @@
         "projectDiscovery": 1,
         "resourceInventory": 1,
         "resourceManager": 1,
+        "workloadQueue": 1,
         "migrationReview": 1,
+        "migrationInsights": 1,
+        "migrationImpact": 1,
         "configurationReview": 1,
         "baselineShape": 1
     },

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

@@ -20,6 +20,7 @@ export interface RehearsalCliFlags {
     imagesOnly: boolean;
     cleanupConfirmation: string | undefined;
     stopConfirmation: string | undefined;
+    workloadConfirmation: string | undefined;
     proposalPath: string | undefined;
     sourceAccessConfirmation: string | undefined;
     sourceRetirementConfirmation: string | undefined;

package/dist/src/cli/arguments.mjs

@@ -21,6 +21,7 @@ export const parseArguments = (arguments_) => {
         imagesOnly: false,
         cleanupConfirmation: undefined,
         stopConfirmation: undefined,
+        workloadConfirmation: undefined,
         proposalPath: undefined,
         sourceAccessConfirmation: undefined,
         sourceRetirementConfirmation: undefined,
@@ -56,6 +57,8 @@ export const parseArguments = (arguments_) => {
             flags.cleanupConfirmation = argument.slice("--confirm-cleanup=".length);
         else if (argument.startsWith("--confirm-stop="))
             flags.stopConfirmation = argument.slice("--confirm-stop=".length);
+        else if (argument.startsWith("--confirm-workloads="))
+            flags.workloadConfirmation = argument.slice("--confirm-workloads=".length);
         else if (argument.startsWith("--proposal="))
             flags.proposalPath = argument.slice("--proposal=".length);
         else if (argument.startsWith("--confirm-source-access="))
@@ -114,6 +117,7 @@ export const resetGuidedFlags = (flags) => {
         imagesOnly: false,
         cleanupConfirmation: undefined,
         stopConfirmation: undefined,
+        workloadConfirmation: undefined,
         proposalPath: undefined,
         sourceAccessConfirmation: undefined,
         sourceRetirementConfirmation: undefined,
@@ -150,6 +154,7 @@ export const commandMutatesProject = ({ command, flags, guided, }) => {
         "open",
         "start",
         "migrate",
+        "measure impact",
         "reset",
         "stop",
         "discard",

package/dist/src/cli/basic_command_handlers.mjs

@@ -27,6 +27,8 @@ Commands:
   activity                   Report idle, busy, stale, or invalid operation state
   environments               List owned runtimes and Docker capacity without starting it
   resources                  Browse individual images, volumes, and other local resources
+  workloads                  Inspect participating local lifecycle queue metadata
+  workloads recover --confirm-workloads= Recover reviewed dead-holder metadata only
   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
@@ -35,6 +37,9 @@ Commands:
   inspect baseline           Show verified baseline provenance
   inspect migrations         Classify represented, applied, and candidate migrations
   inspect plan               Review ordered migrations, required dependencies, and warnings
+  inspect insights           Review bounded static SQL warnings; never a safety verdict
+  inspect impact             Preview aggregate measurements for one explicit --target
+  measure impact             Measure reviewed aggregates on that running local sandbox
   start                      Start an existing verified local runtime
   migrate --confirm-candidates= Apply the exact candidate suffix without resetting
   reset                      Restore and verify the immutable local baseline
@@ -48,6 +53,7 @@ Commands:
 
 Options: --help, -h --version, -V --json --verbose --debug --plain
          --config=<path> --target=<provider for setup; configured name for runtime>
+         --confirm-candidates=<whole-plan digest for run, migrate, or measure impact>
          --confirm-source-access=<digest> --confirm-source-retirement=<digest>
          --confirm-refresh=<digest>`;
 export const createBasicCommandHandlers = () => [

package/dist/src/cli/cli_commands.mjs

@@ -5,6 +5,7 @@ import { createCommandRegistry } from "./command_registry.mjs";
 import { createIdentityCommandHandlers } from "./identity_command_handlers.mjs";
 import { createInspectionCommandHandlers } from "./inspection_command_handlers.mjs";
 import { createEditorCommandHandlers } from "./editor_command_handlers.mjs";
+import { createWorkloadCommandHandlers } from "./workload_command_handlers.mjs";
 import { createProjectCommandHandlers } from "./project_command_handlers.mjs";
 import { createRuntimeActionHandlers } from "./runtime_action_handlers.mjs";
 import { createSourceCommandHandlers } from "./source_command_handlers.mjs";
@@ -23,6 +24,7 @@ export const createCliCommandRegistry = ({ projectRoot, projectCommands, runtime
         startRuntimeApplication: runtimeCommands.startRuntimeApplication,
     }),
     ...createInspectionCommandHandlers(),
+    ...createWorkloadCommandHandlers(),
     ...createEditorCommandHandlers(),
     ...createApplicationCommandHandlers({
         openRuntimeApplication: runtimeCommands.openRuntimeApplication,

package/dist/src/cli/editor_command_handlers.mjs

@@ -1,9 +1,33 @@
 /** Versioned, read-only contracts for editor review; never a second runtime engine. */
 import { inspectMigrationReviewPlan } from "../runtime/migration_plan.mjs";
+import { inspectMigrationInsights, renderMigrationInsights, } from "../runtime/migration_insights.mjs";
+import { inspectMigrationImpact, measureMigrationImpact, renderMigrationImpact, } from "../runtime/migration_impact.mjs";
 import { exactCommands, renderedCommand } from "./command_contract.mjs";
 import { applyStopStalePlan, inspectStopStalePlan, stopReviewedStaleTarget, } from "../runtime/stale_environment_plan.mjs";
 import { inspectConfigurationMetadata, reviewConfigurationProposal, } from "../project/configuration_review.mjs";
 export const createEditorCommandHandlers = () => [
+    exactCommands("migration-impact-preview", ["inspect impact"], async ({ planOptions, flags }) => {
+        const data = await inspectMigrationImpact(planOptions, flags.target);
+        return renderedCommand({ data, render: renderMigrationImpact });
+    }),
+    exactCommands("migration-impact-measurement", ["measure impact"], async ({ planOptions, flags }) => {
+        const data = await measureMigrationImpact({
+            options: planOptions,
+            targetName: flags.target,
+            confirmation: flags.confirmation,
+        });
+        const incomplete = ["partial", "unknown"].includes(data.measurementStatus);
+        return renderedCommand({
+            data,
+            render: renderMigrationImpact,
+            status: incomplete ? "not_ready" : "success",
+            ...(incomplete ? { exitCode: 1 } : {}),
+        });
+    }),
+    exactCommands("migration-insights", ["inspect insights"], async ({ planOptions }) => {
+        const data = await inspectMigrationInsights(planOptions);
+        return renderedCommand({ data, render: renderMigrationInsights });
+    }),
     exactCommands("configuration", ["configuration", "configuration review"], async ({ command, planOptions, flags }) => {
         const data = command === "configuration review"
             ? await reviewConfigurationProposal(planOptions, flags.proposalPath ??

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

@@ -80,6 +80,10 @@ export declare const createProjectCommands: ({ projectRoot, runManager, }: {
                     retainBaselineGenerations: number;
                 }>;
                 resources: Readonly<{
+                    workloadQueue?: {
+                        enabled: boolean;
+                        waitTimeoutSeconds: number;
+                    };
                     staleAfterSeconds: number | null;
                     retainedEnvironmentCount: number;
                     maximumBytes: number | null;
@@ -232,6 +236,10 @@ export declare const createProjectCommands: ({ projectRoot, runManager, }: {
                     retainBaselineGenerations: number;
                 }>;
                 resources: Readonly<{
+                    workloadQueue?: {
+                        enabled: boolean;
+                        waitTimeoutSeconds: number;
+                    };
                     staleAfterSeconds: number | null;
                     retainedEnvironmentCount: number;
                     maximumBytes: number | null;

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

@@ -3,28 +3,11 @@ import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
 export { buildRuntimeStackPlan, runRuntimeStackDoctor, topologyCandidateSummary, } from "./runtime_planning.mjs";
 import { loadRuntimeTopology } from "../runtime/topology.mjs";
 import type { InstalledPackageFingerprint } from "../shared/operation_guard.mjs";
-import type { RuntimeStatusSnapshot } from "../runtime/status.mjs";
+import { type ManagerReceipt, type RuntimeAction } from "./runtime_stack_runner.mjs";
 import type { RehearsalCliFlags } from "./arguments.mjs";
 import type { RehearsalErrorCategory } from "../shared/diagnostics.mjs";
 import type { CliSessionState } from "./command_contract.mjs";
 type RuntimeTopology = Awaited<ReturnType<typeof loadRuntimeTopology>>;
-type RuntimeAction = "run" | "start" | "migrate" | "reset" | "status" | "stop" | "discard" | "verify";
-interface ManagerReceipt {
-    readonly action: RuntimeAction;
-    readonly target: string;
-    readonly durationMs: number;
-    readonly output: string;
-    readonly runtimeStatus?: RuntimeStatusSnapshot;
-}
-interface RuntimeStackResult {
-    readonly topology: RuntimeTopology;
-    readonly runtime: ManagerReceipt | Readonly<{
-        action: RuntimeAction;
-        durationMs: number;
-        output: string;
-        targets: readonly ManagerReceipt[];
-    }>;
-}
 export declare const classifyManagerFailure: ({ action, output, inferredCategory, }: {
     action: RuntimeAction;
     output: string;
@@ -165,5 +148,5 @@ export declare const createRuntimeCommands: ({ packageRoot, projectRoot, manager
         flags: RehearsalCliFlags;
         planOptions: RehearsalConfigPathOptions;
         session: CliSessionState;
-    }) => Promise<RuntimeStackResult>;
+    }) => Promise<import("./runtime_stack_runner.mjs").RuntimeStackResult>;
 };

package/dist/src/cli/runtime_commands.mjs

@@ -1,6 +1,5 @@
 /** Orchestrate isolated database runtimes and project-owned application proofs. */
 import { spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
 import { performance } from "node:perf_hooks";
@@ -18,15 +17,11 @@ 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 { applyRuntimePersistence } from "../runtime/persistence.mjs";
+import { createRuntimeStackRunner, } from "./runtime_stack_runner.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";
 import { runtimeConfigurationSha256 } from "../runtime/configuration_binding.mjs";
-import { assertResourcePolicyAllowsStartup, evaluateResourcePolicy, } from "../runtime/resource_policy.mjs";
 import { formatDuration, isHumanTerminal, promptForConfirmation, terminalStyle, useStyledPrompts, } from "./terminal.mjs";
 const parseCommand = (source) => {
     const values = [];
@@ -340,89 +335,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
                     : "runtime-lifecycle",
             target: options.targetName ?? "primary",
         }, () => executeManager(options));
-    const runRuntimeStack = async ({ command, flags, planOptions, session, }) => {
-        const topology = session.runtimeTopology ??
-            (await loadRuntimeTopology(planOptions));
-        const reverse = ["stop", "discard"].includes(command);
-        if (["start", "run", "reset"].includes(command) &&
-            topology.primary.config.resources.maximumBytes !== null) {
-            assertResourcePolicyAllowsStartup(evaluateResourcePolicy({
-                inventory: await inspectRehearsalResources(planOptions),
-                policy: topology.primary.config.resources,
-            }));
-        }
-        const selectedTargets = selectRuntimeTargets(topology.targets, flags.target, command);
-        const targets = reverse ? [...selectedTargets].reverse() : selectedTargets;
-        const engine = command === "status"
-            ? null
-            : assertLocalDockerContext({ cwd: topology.projectRoot });
-        const engineBinding = engine
-            ? { dockerContext: engine.context, dockerIdentity: engine.identity }
-            : {};
-        const operationId = randomUUID();
-        const results = await executeRuntimeTargetStack({
-            targets,
-            cleanupOnFailure: command === "run"
-                ? shouldStopRuntime(topology.primary.config.lifecycle.run)
-                : command === "start" &&
-                    shouldStopRuntime(topology.primary.config.lifecycle.open),
-            execute: async (target) => {
-                const confirmation = session.targetConfirmations?.get(target.configPath);
-                return runManager({
-                    action: command,
-                    flags,
-                    configPath: target.configPath,
-                    ...(confirmation === undefined ? {} : { confirmation }),
-                    ...(topology.targets.length > 1 ? { targetName: target.name } : {}),
-                    operationId,
-                    ...engineBinding,
-                    configSha256: runtimeConfigurationSha256(target.config),
-                });
-            },
-            stop: (target) => runManager({
-                action: "stop",
-                flags,
-                configPath: target.configPath,
-                targetName: target.name,
-                operationId,
-                ...engineBinding,
-                configSha256: runtimeConfigurationSha256(target.config),
-            }),
-        });
-        const release = ["stop", "discard"].includes(command)
-            ? releaseOwnedColimaWhenIdle({
-                projectRoot: topology.projectRoot,
-                targets: topology.targets,
-            })
-            : null;
-        const withRelease = (receipt) => release
-            ? {
-                ...receipt,
-                output: [receipt.output, release.message]
-                    .filter(Boolean)
-                    .join("\n"),
-            }
-            : receipt;
-        if (results.length === 1)
-            return { topology, runtime: withRelease(results[0]) };
-        return {
-            topology,
-            runtime: {
-                action: command,
-                durationMs: Math.round(results.reduce((total, result) => total + result.durationMs, 0) *
-                    100) / 100,
-                output: [
-                    results
-                        .map((result) => `[${result.target}]\n${result.output}`)
-                        .join("\n\n"),
-                    release?.message,
-                ]
-                    .filter(Boolean)
-                    .join("\n\n"),
-                targets: results,
-            },
-        };
-    };
+    const runRuntimeStack = createRuntimeStackRunner(runManager);
     const runApplicationProof = async (planOptions, options = {}) => {
         const { config, projectRoot: configuredRoot } = await loadRehearsalConfig(planOptions);
         return trackOperationStage({ phase: "application-proof", target: options.targetName ?? "primary" }, () => runProjectCommand({

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

@@ -0,0 +1,41 @@
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import { loadRuntimeTopology } from "../runtime/topology.mjs";
+import type { RuntimeStatusSnapshot } from "../runtime/status.mjs";
+import type { RehearsalCliFlags } from "./arguments.mjs";
+import type { CliSessionState } from "./command_contract.mjs";
+type RuntimeTopology = Awaited<ReturnType<typeof loadRuntimeTopology>>;
+export type RuntimeAction = "run" | "start" | "migrate" | "reset" | "status" | "stop" | "discard" | "verify";
+export interface ManagerReceipt {
+    readonly action: RuntimeAction;
+    readonly target: string;
+    readonly durationMs: number;
+    readonly output: string;
+    readonly runtimeStatus?: RuntimeStatusSnapshot;
+}
+export interface RuntimeStackResult {
+    readonly topology: RuntimeTopology;
+    readonly runtime: ManagerReceipt | Readonly<{
+        action: RuntimeAction;
+        durationMs: number;
+        output: string;
+        targets: readonly ManagerReceipt[];
+    }>;
+}
+interface ManagerInvocation {
+    action: RuntimeAction;
+    flags: RehearsalCliFlags;
+    configPath?: string;
+    confirmation?: string;
+    targetName?: string;
+    operationId?: string;
+    dockerContext?: string;
+    dockerIdentity?: string;
+    configSha256?: string;
+}
+export declare const createRuntimeStackRunner: (runManager: (options: ManagerInvocation) => Promise<ManagerReceipt>) => ({ command, flags, planOptions, session, }: {
+    command: RuntimeAction;
+    flags: RehearsalCliFlags;
+    planOptions: RehearsalConfigPathOptions;
+    session: CliSessionState;
+}) => Promise<RuntimeStackResult>;
+export {};

package/dist/src/cli/runtime_stack_runner.mjs

@@ -0,0 +1,104 @@
+/** Coordinate configured runtime stacks separately from application sessions/proofs. */
+import { randomUUID } from "node:crypto";
+import { loadRuntimeTopology, selectRuntimeTargets, } from "../runtime/topology.mjs";
+import { shouldStopRuntime } from "../runtime/persistence.mjs";
+import { releaseOwnedColimaWhenIdle } from "../runtime/container_engine_ownership.mjs";
+import { inspectRehearsalResources } from "../runtime/resource_inventory.mjs";
+import { assertLocalDockerContext } from "../runtime/local_docker_context.mjs";
+import { runtimeConfigurationSha256 } from "../runtime/configuration_binding.mjs";
+import { assertResourcePolicyAllowsStartup, evaluateResourcePolicy, } from "../runtime/resource_policy.mjs";
+import { executeRuntimeTargetStack } from "./runtime_stack_execution.mjs";
+import { withRuntimeWorkloadAdmission } from "./runtime_workload_admission.mjs";
+export const createRuntimeStackRunner = (runManager) => async ({ command, flags, planOptions, session, }) => {
+    const topology = session.runtimeTopology ??
+        (await loadRuntimeTopology(planOptions));
+    const executeStack = async () => {
+        const reverse = ["stop", "discard"].includes(command);
+        if (["start", "run", "reset"].includes(command) &&
+            topology.primary.config.resources.maximumBytes !== null) {
+            assertResourcePolicyAllowsStartup(evaluateResourcePolicy({
+                inventory: await inspectRehearsalResources(planOptions),
+                policy: topology.primary.config.resources,
+            }));
+        }
+        const selectedTargets = selectRuntimeTargets(topology.targets, flags.target, command);
+        const targets = reverse
+            ? [...selectedTargets].reverse()
+            : selectedTargets;
+        const engine = command === "status"
+            ? null
+            : assertLocalDockerContext({ cwd: topology.projectRoot });
+        const engineBinding = engine
+            ? { dockerContext: engine.context, dockerIdentity: engine.identity }
+            : {};
+        const operationId = randomUUID();
+        const results = await executeRuntimeTargetStack({
+            targets,
+            cleanupOnFailure: command === "run"
+                ? shouldStopRuntime(topology.primary.config.lifecycle.run)
+                : command === "start" &&
+                    shouldStopRuntime(topology.primary.config.lifecycle.open),
+            execute: async (target) => {
+                const confirmation = session.targetConfirmations?.get(target.configPath);
+                return runManager({
+                    action: command,
+                    flags,
+                    configPath: target.configPath,
+                    ...(confirmation === undefined ? {} : { confirmation }),
+                    ...(topology.targets.length > 1 ? { targetName: target.name } : {}),
+                    operationId,
+                    ...engineBinding,
+                    configSha256: runtimeConfigurationSha256(target.config),
+                });
+            },
+            stop: (target) => runManager({
+                action: "stop",
+                flags,
+                configPath: target.configPath,
+                targetName: target.name,
+                operationId,
+                ...engineBinding,
+                configSha256: runtimeConfigurationSha256(target.config),
+            }),
+        });
+        const release = ["stop", "discard"].includes(command)
+            ? releaseOwnedColimaWhenIdle({
+                projectRoot: topology.projectRoot,
+                targets: topology.targets,
+            })
+            : null;
+        const withRelease = (receipt) => release
+            ? {
+                ...receipt,
+                output: [receipt.output, release.message]
+                    .filter(Boolean)
+                    .join("\n"),
+            }
+            : receipt;
+        if (results.length === 1)
+            return { topology, runtime: withRelease(results[0]) };
+        return {
+            topology,
+            runtime: {
+                action: command,
+                durationMs: Math.round(results.reduce((total, result) => total + result.durationMs, 0) *
+                    100) / 100,
+                output: [
+                    results
+                        .map((result) => `[${result.target}]\n${result.output}`)
+                        .join("\n\n"),
+                    release?.message,
+                ]
+                    .filter(Boolean)
+                    .join("\n\n"),
+                targets: results,
+            },
+        };
+    };
+    return withRuntimeWorkloadAdmission({
+        policy: topology.primary.config.resources.workloadQueue,
+        command,
+        json: flags.json,
+        execute: executeStack,
+    });
+};

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

@@ -0,0 +1,8 @@
+/** Bind configured lifecycle-only admission without queuing proofs or interactive sessions. */
+import type { RehearsalResourcePolicy } from "../project/configuration_contract.mjs";
+export declare const withRuntimeWorkloadAdmission: <Result>({ policy, command, json, execute, }: {
+    policy: RehearsalResourcePolicy["workloadQueue"];
+    command: string;
+    json: boolean;
+    execute: () => Promise<Result>;
+}) => Promise<Result>;

package/dist/src/cli/runtime_workload_admission.mjs

@@ -0,0 +1,22 @@
+import { getOperationCancellationSignal } from "../shared/cancellation.mjs";
+import { withWorkloadAdmission } from "../runtime/workload_queue.mjs";
+export const withRuntimeWorkloadAdmission = async ({ policy, command, json, execute, }) => {
+    if (!policy?.enabled ||
+        (command !== "start" &&
+            command !== "run" &&
+            command !== "reset" &&
+            command !== "migrate"))
+        return execute();
+    const signal = getOperationCancellationSignal();
+    return withWorkloadAdmission({
+        enabled: true,
+        command,
+        waitTimeoutSeconds: policy.waitTimeoutSeconds ?? 30,
+        ...(signal ? { signal } : {}),
+        onWaiting: () => {
+            if (!json)
+                process.stderr.write("Waiting for another participating local Rehearsal runtime phase. Ctrl+C cancels this request.\n");
+        },
+        execute,
+    });
+};

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

@@ -67,6 +67,10 @@ export declare const loadPreparationContext: (planOptions: RehearsalConfigPathOp
                 retainBaselineGenerations: number;
             }>;
             resources: Readonly<{
+                workloadQueue?: {
+                    enabled: boolean;
+                    waitTimeoutSeconds: number;
+                };
                 staleAfterSeconds: number | null;
                 retainedEnvironmentCount: number;
                 maximumBytes: number | null;
@@ -245,6 +249,10 @@ export declare const buildRefreshWorkflowPlan: (planOptions: RehearsalConfigPath
                 retainBaselineGenerations: number;
             }>;
             resources: Readonly<{
+                workloadQueue?: {
+                    enabled: boolean;
+                    waitTimeoutSeconds: number;
+                };
                 staleAfterSeconds: number | null;
                 retainedEnvironmentCount: number;
                 maximumBytes: number | null;