@rehearsal-db/core 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable Rehearsal package changes are documented here. The format follows Keep
 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
@@ -866,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,14 +38,14 @@ 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.
 
-The 1.2.0 source candidate adds optional capability
+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. This candidate version and its
-setup target do not establish publication or completed editor/native acceptance.
+unavailable static analysis is not safety evidence. Package publication does not
+establish completed editor, accessibility or genuine-provider acceptance.
 
-Further source work adds optional `rehearsalContracts.migrationImpact: 1` with
+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,
@@ -62,13 +62,22 @@ changes in the selected disposable sandbox; this is not a nonblocking query prom
 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 unpublished source capability does not claim a new editor UI,
-new database family or additional platform/native acceptance.
+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.2.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.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.2.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,6 +26,7 @@
         "projectDiscovery": 1,
         "resourceInventory": 1,
         "resourceManager": 1,
+        "workloadQueue": 1,
         "migrationReview": 1,
         "migrationInsights": 1,
         "migrationImpact": 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,

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

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/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;

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

@@ -0,0 +1,2 @@
+import { type CommandDefinition } from "./command_contract.mjs";
+export declare const createWorkloadCommandHandlers: () => readonly CommandDefinition[];

package/dist/src/cli/workload_command_handlers.mjs

@@ -0,0 +1,38 @@
+/** Inspect/recover queue metadata without needing Docker, config or a project lock. */
+import { inspectWorkloads, recoverWorkloads, withWorkloadDiagnostics, } from "../runtime/workload_queue.mjs";
+import { exactCommands, renderedCommand, } from "./command_contract.mjs";
+import { RehearsalError } from "../shared/diagnostics.mjs";
+export const createWorkloadCommandHandlers = () => [
+    exactCommands("workloads", ["workloads"], async () => renderedCommand({
+        data: await withWorkloadDiagnostics(() => inspectWorkloads()),
+        render: (result) => [
+            "LOCAL WORKLOAD QUEUE — READ ONLY",
+            "Participating lifecycle phases only. Host/VM capacity is not measured.",
+            ...result.entries.map((entry) => `${entry.command} · ${entry.phase} · owner ${entry.owner} · PID ${entry.pid}${entry.recoveryRequired ? " · recovery required" : ""}`),
+            result.entries.length
+                ? ""
+                : "No participating workload is queued or held.",
+            ...(result.recoveryDigest
+                ? [
+                    "A dead holder may have surviving children. Check its owned commands before recovery.",
+                    `After checking: rehearsal workloads recover --confirm-workloads=${result.recoveryDigest}`,
+                    "Recovery clears exactly reviewed queue metadata; it does not stop processes or change databases.",
+                ]
+                : []),
+        ]
+            .filter(Boolean)
+            .join("\n"),
+    })),
+    exactCommands("workloads-recover", ["workloads recover"], async ({ flags }) => {
+        if (!flags.workloadConfirmation)
+            throw new RehearsalError({
+                category: "configuration_invalid",
+                code: "CONFIGURATION_INVALID",
+                message: "Inspect rehearsal workloads and review dead holders before using --confirm-workloads=<digest>. Check their owned commands first; recovery does not stop surviving children.",
+            });
+        return renderedCommand({
+            data: await withWorkloadDiagnostics(() => recoverWorkloads(flags.workloadConfirmation)),
+            render: (result) => `Recovered ${result.recovered} reviewed dead workload holder(s). No process, container or database was changed.`,
+        });
+    }),
+];

package/dist/src/project/configuration_contract.d.mts

@@ -4,6 +4,11 @@ export type RunPersistenceMode = "keep-until-stop" | "stop-after-run";
 export type OpenPersistenceMode = "keep-until-stop" | "stop-on-application-exit";
 export type ApplicationRequiredService = "database" | "auth" | "storage" | "postgrest" | "gateway" | "mail" | "studio" | "realtime" | "edge-functions" | "analytics" | "image-transforms";
 export interface RehearsalResourcePolicy {
+    /** Cooperatively serialize participating local runtime lifecycle phases. */
+    workloadQueue?: {
+        enabled: boolean;
+        waitTimeoutSeconds?: number;
+    };
     /** Review cutoff based on container start/stop, not application or database use. */
     staleAfterSeconds?: number | null;
     /** Advisory limit; retained databases are never automatically deleted. */

package/dist/src/project/configuration_normalization.d.mts

@@ -54,6 +54,10 @@ export declare const normalizeRehearsalConfig: (input: unknown) => Readonly<{
         retainBaselineGenerations: number;
     }>;
     resources: Readonly<{
+        workloadQueue?: {
+            enabled: boolean;
+            waitTimeoutSeconds: number;
+        };
         staleAfterSeconds: number | null;
         retainedEnvironmentCount: number;
         maximumBytes: number | null;

package/dist/src/project/configuration_resolution.d.mts

@@ -54,6 +54,10 @@ export declare const loadRehearsalConfig: ({ projectRoot, configPath, }?: Rehear
             retainBaselineGenerations: number;
         }>;
         resources: Readonly<{
+            workloadQueue?: {
+                enabled: boolean;
+                waitTimeoutSeconds: number;
+            };
             staleAfterSeconds: number | null;
             retainedEnvironmentCount: number;
             maximumBytes: number | null;

package/dist/src/project/configuration_resource_policy.d.mts

@@ -3,6 +3,10 @@ import type { ApplicationRequiredService } from "./configuration_contract.mjs";
 import { type PlainObject } from "./configuration_validation.mjs";
 export declare const APPLICATION_REQUIRED_SERVICES: readonly ["database", "auth", "storage", "postgrest", "gateway", "mail", "studio", "realtime", "edge-functions", "analytics", "image-transforms"];
 export declare const normalizeResourcePolicy: (resources: PlainObject) => Readonly<{
+    workloadQueue?: {
+        enabled: boolean;
+        waitTimeoutSeconds: number;
+    };
     staleAfterSeconds: number | null;
     retainedEnvironmentCount: number;
     maximumBytes: number | null;