@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

package/dist/services/setup.js

@@ -0,0 +1,427 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
+import { admitReleaseManifest } from "./release-manifest.js";
+import { validateReleasePayloadIdentity } from "./release-payload.js";
+import { publishReleaseCache, verifyPublishedReleaseCache } from "./release-cache.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { authenticateReleaseEnvelope } from "./release-envelope.js";
+import { prepareOperatorProfile, validateProfileCreationIntent, commitProfileCreation, readOperatorProfiles } from "./operator-profiles.js";
+/** Production ingress authenticates the source before constructing any installation authority. */
+export function installAuthenticatedRelease(home, input) {
+    const authenticated = authenticateReleaseEnvelope(input.envelope, input.trustedProducers, input.compatibility);
+    return installRelease(home, { requestId: input.requestId, action: input.action,
+        manifest: authenticated.manifest, manifestBytes: authenticated.manifestBytes, authority: authenticated.authority,
+        canonArchive: input.canonArchive, engineArchive: input.engineArchive,
+        ...(input.executor !== undefined ? { executor: input.executor } : {}),
+        ...(input.profileCreation !== undefined ? { profileCreation: input.profileCreation } : {}),
+        ...(input.deferredOnboarding ? { deferredOnboarding: true } : {}),
+        ...(input.onCheckpoint ? { onCheckpoint: input.onCheckpoint } : {}) });
+}
+function refuse(reason, effect = "no_effect") {
+    throw new AppError("setup_conflict", "Setup request cannot proceed", 1, { reason, phase: "setup", effect, help: "setup", next_action: "dd-flow setup status --json" });
+}
+const bytesDigest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function manifestFromBytes(bytes) {
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return refuse("invalid_manifest_bytes");
+    }
+}
+function regularJson(file) {
+    if (!fs.lstatSync(file).isFile())
+        refuse("unsafe_setup_file");
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return refuse("invalid_setup_file");
+    }
+}
+function atomicJson(file, value) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+        try {
+            fs.writeFileSync(fd, JSON.stringify(value));
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}
+function readSetupRequest(file, validateExecutor = true) {
+    const value = regularJson(file);
+    const required = ["schema_id", "request_id", "identity", "previous_selection", "phase", "installation"];
+    if (!value || typeof value !== "object" || Array.isArray(value)
+        || required.some(key => !Object.hasOwn(value, key))
+        || Object.keys(value).some(key => ![...required, "executor", "profileCreation", "deferredOnboarding"].includes(key)))
+        refuse("invalid_request_record");
+    const request = value;
+    if (Object.hasOwn(request, "deferredOnboarding") && (request.deferredOnboarding !== true || Object.hasOwn(request, "executor") || Object.hasOwn(request, "profileCreation")))
+        refuse("invalid_deferred_onboarding");
+    if (request.schema_id !== "dd-flow/setup-request@1"
+        || typeof request.request_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(request.request_id)
+        || typeof request.identity !== "string" || !/^[a-f0-9]{64}$/.test(request.identity)
+        || request.previous_selection !== null && (typeof request.previous_selection !== "string" || !/^[a-f0-9]{64}$/.test(request.previous_selection))
+        || !["prepared", "canon_cached", "engine_cached", "profiles_saved", "committed"].includes(request.phase)
+        || !request.installation || typeof request.installation !== "object" || Array.isArray(request.installation))
+        refuse("invalid_request_record");
+    if (validateExecutor && Object.hasOwn(request, "executor") && request.executor !== null) {
+        try {
+            prepareOperatorProfile(request.executor);
+        }
+        catch {
+            refuse("invalid_request_executor");
+        }
+    }
+    if (validateExecutor && Object.hasOwn(request, "profileCreation")) {
+        try {
+            validateProfileCreationIntent(request.profileCreation);
+        }
+        catch {
+            refuse("invalid_request_profile_creation");
+        }
+        if (!request.executor || hybridDigest(request.executor) !== hybridDigest(request.profileCreation.profile))
+            refuse("request_profile_executor_mismatch");
+    }
+    return request;
+}
+/** Read retained executor consent for an exact retry, without installation or profile effects.
+ * Full source/installation request identity is still checked by installRelease.
+ */
+export function readRetainedSetupExecutor(home, requestId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("invalid_request");
+    const root = path.resolve(home), directory = path.join(root, "setup-requests");
+    for (const candidate of [root, directory])
+        if (fs.existsSync(candidate) && !fs.lstatSync(candidate).isDirectory())
+            refuse("unsafe_setup_directory");
+    const file = path.join(directory, `${requestId}.json`);
+    if (!fs.existsSync(file))
+        return null;
+    const request = readSetupRequest(file);
+    if (request.request_id !== requestId)
+        refuse("request_identity_conflict");
+    if (!Object.hasOwn(request, "executor"))
+        return null;
+    return { executor: structuredClone(request.executor ?? null),
+        ...(request.profileCreation ? { profileCreation: structuredClone(request.profileCreation) } : {}) };
+}
+/** A deferred request is immutable installation consent, not an implicit skip. */
+export function hasDeferredSetupOnboarding(home, requestId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("invalid_request");
+    const root = path.resolve(home), directory = path.join(root, "setup-requests");
+    for (const candidate of [root, directory])
+        if (fs.existsSync(candidate) && !fs.lstatSync(candidate).isDirectory())
+            refuse("unsafe_setup_directory");
+    const file = path.join(directory, `${requestId}.json`);
+    if (!fs.existsSync(file))
+        return false;
+    const request = readSetupRequest(file);
+    if (request.request_id !== requestId)
+        refuse("request_identity_conflict");
+    return request.deferredOnboarding === true;
+}
+function deferredRequest(home, requestId) {
+    if (!hasDeferredSetupOnboarding(home, requestId))
+        refuse("onboarding_not_deferred");
+    const request = readSetupRequest(path.join(path.resolve(home), "setup-requests", `${requestId}.json`));
+    if (request.phase !== "committed")
+        refuse("installation_not_committed");
+    return request;
+}
+/** Retained consent allows recovery without asking again or importing current defaults. */
+export function readSetupOnboarding(home, requestId) {
+    const request = deferredRequest(home, requestId);
+    const directory = path.join(path.resolve(home), "setup-onboarding");
+    if (fs.existsSync(directory) && !fs.lstatSync(directory).isDirectory())
+        refuse("unsafe_onboarding_directory");
+    const file = path.join(directory, `${requestId}.json`);
+    if (!fs.existsSync(file))
+        return null;
+    const receipt = regularJson(file);
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)
+        || Object.keys(receipt).some(key => !["schema_id", "request_id", "installation_identity", "phase", "executor", "profileCreation"].includes(key))
+        || receipt.schema_id !== "dd-flow/setup-onboarding@1" || receipt.request_id !== requestId
+        || receipt.installation_identity !== request.identity || !["selected", "committed"].includes(receipt.phase)
+        || !Object.hasOwn(receipt, "executor"))
+        refuse("invalid_onboarding_receipt");
+    try {
+        if (receipt.executor !== null)
+            prepareOperatorProfile(receipt.executor);
+        if (receipt.profileCreation !== undefined) {
+            validateProfileCreationIntent(receipt.profileCreation);
+            if (!receipt.executor || hybridDigest(receipt.executor) !== hybridDigest(receipt.profileCreation.profile))
+                refuse("onboarding_profile_mismatch");
+        }
+    }
+    catch {
+        refuse("invalid_onboarding_receipt");
+    }
+    return structuredClone(receipt);
+}
+/** Persist human consent before profile effects; replay never restores later profile edits. */
+export function commitSetupOnboarding(home, requestId, selection) {
+    const request = deferredRequest(home, requestId), root = path.resolve(home);
+    const executor = selection.executor === null ? null : prepareOperatorProfile(selection.executor);
+    if (selection.profileCreation) {
+        validateProfileCreationIntent(selection.profileCreation);
+        if (!executor || hybridDigest(executor) !== hybridDigest(selection.profileCreation.profile))
+            refuse("onboarding_profile_mismatch");
+    }
+    const candidate = { schema_id: "dd-flow/setup-onboarding@1", request_id: requestId,
+        installation_identity: request.identity, phase: "selected", executor,
+        ...(selection.profileCreation ? { profileCreation: selection.profileCreation } : {}) };
+    const lease = acquireInstallationLock(path.join(root, "setup.lock"), hybridDigest({ request_id: requestId, identity: request.identity }));
+    let failure, result;
+    try {
+        const retained = readSetupOnboarding(root, requestId);
+        if (retained && hybridDigest({ ...retained, phase: "selected" }) !== hybridDigest(candidate))
+            refuse("onboarding_selection_conflict");
+        if (retained?.phase === "committed")
+            result = retained;
+        else {
+            if (hybridDigest(readSetupStatus(root).installation) !== hybridDigest(request.installation))
+                refuse("onboarding_installation_changed");
+            const directory = path.join(root, "setup-onboarding");
+            fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const file = path.join(directory, `${requestId}.json`);
+            if (!retained)
+                atomicJson(file, candidate);
+            if (candidate.profileCreation)
+                commitProfileCreation(root, candidate.profileCreation);
+            result = { ...candidate, phase: "committed" };
+            atomicJson(file, result);
+        }
+    }
+    catch (error) {
+        failure = error instanceof AppError ? error : new AppError("setup_onboarding_interrupted", "Installed release is retained; executor onboarding requires reconciliation", 1, { phase: "executor_onboarding", effect: "unknown", request_id: requestId, help: "setup", next_action: "Replay the exact setup request" });
+    }
+    finally {
+        try {
+            lease.release();
+        }
+        catch {
+            if (failure)
+                failure.details.cleanup = "not_confirmed";
+            else
+                failure = new AppError("setup_cleanup_failed", "Onboarding owner cleanup requires reconciliation", 1, { effect: "unknown", cleanup: "not_confirmed", request_id: requestId, help: "setup" });
+        }
+    }
+    if (failure)
+        throw failure;
+    return result;
+}
+/** Read-only global readiness. No SQLite connection, migration, project registration or probes. */
+function validateInstallation(root, installation) {
+    if (!installation.manifest || typeof installation.manifest_bytes_base64 !== "string" || validateHybridShape("release-manifest", installation.manifest).length ||
+        installation.canon_root !== path.join(root, "release-cache", "canon", installation.manifest.canon.version, "payload") ||
+        installation.engine_root !== path.join(root, "release-cache", "engine", installation.manifest.engine.version, "payload"))
+        refuse("invalid_installation_selection");
+    const bytes = Buffer.from(installation.manifest_bytes_base64, "base64");
+    if (bytes.toString("base64") !== installation.manifest_bytes_base64 || bytesDigest(bytes) !== installation.manifest_sha256 ||
+        hybridDigest(manifestFromBytes(bytes)) !== hybridDigest(installation.manifest))
+        refuse("invalid_installation_selection");
+}
+/** Independently committed canonical data, never activation or old code
+ * admission. A missing old engine cache is irrelevant to comparing documents.
+ * Same canon commit/version with different archive bytes is not disambiguated
+ * by picking the newest CLI or whichever request happens to be listed first.
+ */
+export function readCommittedCanonRelease(home, version, commit, expectedInstallationSha256) {
+    const root = path.resolve(home), directory = path.join(root, "setup-requests");
+    if (!/^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/.test(version) || !/^[a-f0-9]{40}$/.test(commit)
+        || expectedInstallationSha256 !== undefined && !/^[a-f0-9]{64}$/.test(expectedInstallationSha256))
+        refuse("invalid_canonical_baseline_selection");
+    for (const target of [root, directory])
+        if (fs.existsSync(target) && !fs.lstatSync(target).isDirectory())
+            refuse("unsafe_setup_directory");
+    if (!fs.existsSync(directory))
+        return null;
+    const matches = [];
+    for (const name of fs.readdirSync(directory).filter(name => name.endsWith(".json")).sort()) {
+        const request = readSetupRequest(path.join(directory, name), false);
+        if (`${request.request_id}.json` !== name)
+            refuse("request_identity_conflict");
+        if (request.phase !== "committed" || request.installation.manifest?.canon?.version !== version || request.installation.manifest.canon.commit !== commit)
+            continue;
+        if (expectedInstallationSha256 !== undefined && request.installation.manifest_sha256 !== expectedInstallationSha256)
+            continue;
+        validateInstallation(root, request.installation);
+        const binding = { installation: request.installation,
+            ...(Object.hasOwn(request, "executor") ? { executor: request.executor } : {}),
+            ...(request.profileCreation ? { profileCreation: request.profileCreation } : {}),
+            ...(request.deferredOnboarding ? { deferredOnboarding: true } : {}) };
+        if (!["install", "update"].some(action => hybridDigest({ action, ...binding }) === request.identity))
+            refuse("request_identity_conflict");
+        matches.push(request.installation);
+    }
+    if (!matches.length)
+        return null;
+    if (new Set(matches.map(installation => `${installation.manifest.canon.archive.sha256}:${installation.manifest.canon.archive.bytes}`)).size !== 1)
+        refuse("ambiguous_canonical_baseline");
+    const selected = matches.sort((left, right) => left.manifest_sha256.localeCompare(right.manifest_sha256, "en"))[0];
+    try {
+        verifyPublishedReleaseCache(path.dirname(selected.canon_root), selected.manifest.canon.archive);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return structuredClone(selected);
+}
+export function readSetupStatus(home) {
+    const root = path.resolve(home);
+    if (fs.existsSync(root) && !fs.lstatSync(root).isDirectory())
+        refuse("unsafe_setup_home");
+    const file = path.join(root, "installation.json");
+    const installation = fs.existsSync(file) ? regularJson(file) : null;
+    if (installation)
+        validateInstallation(root, installation);
+    let readiness = installation ? "installed" : "not_installed";
+    if (installation) {
+        try {
+            verifyPublishedReleaseCache(path.dirname(installation.canon_root), installation.manifest.canon.archive);
+            verifyPublishedReleaseCache(path.dirname(installation.engine_root), installation.manifest.engine.archive);
+        }
+        catch {
+            readiness = "degraded";
+        }
+    }
+    const existingStorage = fs.existsSync(path.join(root, "db.sqlite"));
+    return { installation, installation_readiness: readiness,
+        storage_readiness: existingStorage ? "unknown_requires_diagnostic" : "not_initialized",
+        runtime_readiness: "unknown_requires_qualification",
+        next_action: !installation ? "dd-flow setup --help" : existingStorage ? "dd-flow migration plan --help" : "dd-flow engine doctor --json",
+        ...(existingStorage ? { storage_continuation: { kind: "storage_admission",
+                status: "requires_diagnostic", reason: "existing_storage_not_inspected",
+                help_command: "dd-flow migration plan --help", automatic_migration: false } } : {}) };
+}
+/** Exact-request installation transaction. Selected immutable caches do not affect existing RUNs. */
+export function installRelease(home, input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(input.requestId) || !["install", "update"].includes(input.action))
+        refuse("invalid_request");
+    const executor = input.executor === undefined ? undefined : input.executor === null ? null : prepareOperatorProfile(input.executor);
+    const executorBinding = executor === undefined ? {} : { executor: structuredClone(executor) };
+    if (input.deferredOnboarding !== undefined && (input.deferredOnboarding !== true || executor !== undefined || input.profileCreation !== undefined))
+        refuse("invalid_deferred_onboarding");
+    const onboardingBinding = input.deferredOnboarding ? { deferredOnboarding: true } : {};
+    if (input.profileCreation !== undefined) {
+        validateProfileCreationIntent(input.profileCreation);
+        if (!executor || hybridDigest(executor) !== hybridDigest(input.profileCreation.profile))
+            refuse("profile_executor_mismatch");
+    }
+    const profileBinding = input.profileCreation === undefined ? {} : { profileCreation: structuredClone(input.profileCreation) };
+    const manifest = admitReleaseManifest(input.manifest, input.authority);
+    if (!Buffer.isBuffer(input.manifestBytes) || hybridDigest(manifestFromBytes(input.manifestBytes)) !== hybridDigest(manifest))
+        refuse("manifest_bytes_mismatch");
+    // Both archives must be valid before even creating the home or publishing the first cache.
+    validateReleasePayloadIdentity(manifest, input.canonArchive, input.engineArchive);
+    const root = path.resolve(home), requests = path.join(root, "setup-requests"), lock = path.join(root, "setup.lock");
+    const installation = { manifest, manifest_sha256: bytesDigest(input.manifestBytes), manifest_bytes_base64: input.manifestBytes.toString("base64"),
+        canon_root: path.join(root, "release-cache", "canon", manifest.canon.version, "payload"),
+        engine_root: path.join(root, "release-cache", "engine", manifest.engine.version, "payload") };
+    const identity = hybridDigest({ action: input.action, installation, ...executorBinding, ...profileBinding, ...onboardingBinding });
+    readSetupStatus(root);
+    for (const directory of [root, requests]) {
+        if (fs.existsSync(directory) && !fs.lstatSync(directory).isDirectory())
+            refuse("unsafe_setup_directory");
+    }
+    if (input.profileCreation) {
+        const existingFile = path.join(requests, `${input.requestId}.json`);
+        const retained = fs.existsSync(existingFile) ? readSetupRequest(existingFile) : null;
+        if (retained?.phase !== "committed") {
+            const revision = readOperatorProfiles(root).revision;
+            if (revision !== input.profileCreation.before.revision && revision !== input.profileCreation.after.revision)
+                refuse("profile_selection_changed");
+        }
+    }
+    fs.mkdirSync(requests, { recursive: true, mode: 0o700 });
+    const lease = acquireInstallationLock(lock, hybridDigest({ request_id: input.requestId, identity }));
+    let failure;
+    const perform = () => {
+        const file = path.join(requests, `${input.requestId}.json`);
+        const current = readSetupStatus(root).installation;
+        let request = { schema_id: "dd-flow/setup-request@1", request_id: input.requestId, identity,
+            previous_selection: current ? hybridDigest(current) : null, phase: "prepared", installation, ...executorBinding, ...profileBinding, ...onboardingBinding };
+        if (fs.existsSync(file)) {
+            request = readSetupRequest(file);
+            if (request.schema_id !== "dd-flow/setup-request@1" || request.request_id !== input.requestId || request.identity !== identity || hybridDigest(request.installation) !== hybridDigest(installation))
+                refuse("request_identity_conflict");
+            if (request.deferredOnboarding !== input.deferredOnboarding)
+                refuse("request_onboarding_conflict");
+            if (hybridDigest({ executor: request.executor ?? null, present: Object.hasOwn(request, "executor") }) !==
+                hybridDigest({ executor: executor ?? null, present: executor !== undefined }))
+                refuse("request_executor_conflict");
+            if (hybridDigest({ profileCreation: request.profileCreation ?? null }) !== hybridDigest({ profileCreation: input.profileCreation ?? null }))
+                refuse("request_profile_creation_conflict");
+            if (!["prepared", "canon_cached", "engine_cached", "profiles_saved", "committed"].includes(request.phase))
+                refuse("invalid_request_phase");
+        }
+        // Replay still revalidates retained payload bytes; it never reactivates an older selection.
+        if (request.phase === "committed") {
+            publishReleaseCache(root, "canon", manifest.canon.version, manifest.canon.archive, input.canonArchive);
+            publishReleaseCache(root, "engine", manifest.engine.version, manifest.engine.archive, input.engineArchive);
+            return { ok: true, replayed: true, installation: request.installation, ...executorBinding };
+        }
+        const selectedDigest = current ? hybridDigest(current) : null;
+        if (selectedDigest !== request.previous_selection && selectedDigest !== hybridDigest(installation))
+            refuse("selection_changed_since_request");
+        if (input.action === "install" && current && selectedDigest !== hybridDigest(installation))
+            refuse("existing_installation_requires_update");
+        const checkpoint = (phase) => {
+            request.phase = phase;
+            atomicJson(file, request);
+            input.onCheckpoint?.(phase);
+        };
+        checkpoint("prepared");
+        publishReleaseCache(root, "canon", manifest.canon.version, manifest.canon.archive, input.canonArchive);
+        checkpoint("canon_cached");
+        publishReleaseCache(root, "engine", manifest.engine.version, manifest.engine.archive, input.engineArchive);
+        checkpoint("engine_cached");
+        if (request.profileCreation) {
+            commitProfileCreation(root, request.profileCreation);
+            checkpoint("profiles_saved");
+        }
+        atomicJson(path.join(root, "installation.json"), installation);
+        checkpoint("committed");
+        return { ok: true, replayed: false, installation, ...executorBinding };
+    };
+    let result;
+    try {
+        result = perform();
+    }
+    catch (error) {
+        failure = error instanceof AppError ? error : new AppError("setup_interrupted", "Setup request requires reconciliation", 1, { phase: "setup", effect: "unknown", request_id: input.requestId, next_action: "Replay the exact setup request", help: "setup" });
+    }
+    finally {
+        try {
+            lease.release();
+        }
+        catch {
+            // Cleanup is secondary to the retained operation result. Never leak a
+            // raw filesystem cause or erase the original failure with an unlink error.
+            if (failure)
+                failure.details.cleanup = "not_confirmed";
+            else
+                failure = new AppError("setup_cleanup_failed", "Setup owner cleanup requires reconciliation", 1, { phase: "setup", effect: "unknown", cleanup: "not_confirmed", request_id: input.requestId,
+                    next_action: "Inspect dd-flow setup status --json; replay the exact request after its owner exits", help: "setup" });
+        }
+    }
+    if (failure)
+        throw failure;
+    return result;
+}

package/dist/services/stage-blocker.js

@@ -1,19 +1,24 @@
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { blockFlowRunStage, unblockFlowRunStage } from "./runs.js";
+import { blockFlowRunStage, unblockFlowRunStage, prepareFlowRunStageBlock, prepareFlowRunStageUnblock } from "./runs.js";
 import { flowCommand } from "./stage-pause.js";
 import { refreshRunWorkProjection } from "./work-registry.js";
-export function blockStageForRuntime(context, input) {
+export function prepareStageRuntimeBlock(context, input) {
+    if (typeof input.code !== "string" || !input.code.trim() || typeof input.summary !== "string" || !input.summary.trim())
+        throw new AppError("validation", "stage block requires a code and summary", 2);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "running")
         throw new AppError("invalid_work_state", "Only a running Work can be blocked", 1, { work_id: work.work_id, status: work.status });
-    if (!input.code.trim() || !input.summary.trim())
-        throw new AppError("validation", "stage block requires a code and summary", 2);
-    const state = blockFlowRunStage(context, { ...input, projectRoot });
+    const flow = prepareFlowRunStageBlock(context, { ...input, projectRoot });
+    return { projectRoot, project, work, flow };
+}
+export function blockStageForRuntime(context, input) {
+    const { projectRoot, project, work, flow } = prepareStageRuntimeBlock(context, input);
+    const state = blockFlowRunStage(context, { ...input, projectRoot }, flow);
     const now = context.now();
     context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
     refreshRunWorkProjection(context, project.id, work.run_id);
@@ -30,14 +35,19 @@ export function blockStageForRuntime(context, input) {
         state
     };
 }
-export function unblockStageAfterRuntimeRepair(context, input) {
+export function prepareStageRuntimeUnblock(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "paused")
         throw new AppError("invalid_work_state", "stage unblock requires its paused Work", 1, { work_id: work.work_id, status: work.status });
-    const state = unblockFlowRunStage(context, { projectRoot, runId: work.run_id, stage: input.stage, workId: work.work_id });
+    const flow = prepareFlowRunStageUnblock(context, { ...input, projectRoot, runId: work.run_id });
+    return { projectRoot, project, work, flow };
+}
+export function unblockStageAfterRuntimeRepair(context, input) {
+    const { projectRoot, project, work, flow } = prepareStageRuntimeUnblock(context, input);
+    const state = unblockFlowRunStage(context, { projectRoot, runId: work.run_id, stage: input.stage, workId: work.work_id }, flow);
     const now = context.now();
     context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
     refreshRunWorkProjection(context, project.id, work.run_id);