@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

package/dist/services/schema-validation.js

@@ -94,8 +94,11 @@ export function validateSchema(options) {
         throw new AppError("usage", "--schema must be a schema name such as mb-upgrade-review-data", 2);
     }
     const filePath = path.resolve(options.file);
-    const data = readJson(filePath, "input file");
-    const schemaResolution = resolveSchema(options);
+    const data = Object.hasOwn(options, "data") ? options.data : readJson(filePath, "input file");
+    // `data` may have come from stdin or from the prepare phase.  Do not reopen
+    // `options.file` merely to infer the RUN-bound schema: apart from being a
+    // second read of caller input, `<stdin>` is not a filesystem path at all.
+    const schemaResolution = resolveSchema(options, data);
     const schema = readJson(schemaResolution.path, "schema");
     // Ajv's default export only carries the draft-07 meta-schema.  New stage
     // contracts may deliberately use draft 2020-12, so choose the validator
@@ -133,8 +136,8 @@ export function validateSchema(options) {
         errors: []
     };
 }
-function resolveSchema(options) {
-    const bound = resolveRunBoundSchema(options);
+function resolveSchema(options, data) {
+    const bound = resolveRunBoundSchema(options, data);
     if (bound)
         return bound;
     const fileNames = [`${options.schemaName}.schema.json`];
@@ -180,10 +183,9 @@ const historicalSchemaRegistry = {
             checksum: "d9889af7f2c0afb47e2abab330aea3e1750879d0738d87d38d2d20e3fe0403f3"
         }]
 };
-function resolveRunBoundSchema(options) {
+function resolveRunBoundSchema(options, data) {
     if (!options.runRoot || options.schemaDir)
         return null;
-    const data = readJson(path.resolve(options.file), "input file");
     const root = asRecord(data);
     const run = root ? asRecord(objectValue(root, "run")) : undefined;
     const inferredRunId = run ? objectValue(run, "run_id") : objectValue(root ?? {}, "run_id");
@@ -268,13 +270,13 @@ function readJson(file, label) {
         text = fs.readFileSync(file, "utf8");
     }
     catch (error) {
-        throw new AppError("validation", `Cannot read ${label}: ${file}`, 2, { cause: String(error) });
+        throw new AppError(label === "input file" ? "validation" : "schema_registry_invalid", `Cannot read ${label}: ${file}`, label === "input file" ? 2 : 1, { cause: String(error) });
     }
     try {
         return JSON.parse(text);
     }
     catch (error) {
-        throw new AppError("invalid_json", `Invalid JSON in ${label}: ${file}`, 2, { cause: String(error) });
+        throw new AppError(label === "input file" ? "invalid_json" : "schema_registry_invalid", `Invalid JSON in ${label}: ${file}`, label === "input file" ? 2 : 1, { cause: String(error) });
     }
 }
 function formatAjvError(error) {

package/dist/services/scope-writer-cleanup.js

@@ -0,0 +1,27 @@
+import { errorRecord } from "../shared/errors.js";
+/** Cleanup is secondary to the arbiter's known commit outcome. Always visit
+ * every connection, including after a failed rollback or close. */
+export function cleanupScopeWriters(targets) {
+    const errors = [];
+    for (const target of targets) {
+        let failed = false;
+        if (target.rollback) {
+            try {
+                target.db.exec("ROLLBACK");
+            }
+            catch (error) {
+                failed = true;
+                errors.push({ target: target.name, phase: "rollback", message: String(error), error: errorRecord(error) });
+            }
+        }
+        if (target.close === "always" || failed) {
+            try {
+                target.db.close?.();
+            }
+            catch (error) {
+                errors.push({ target: target.name, phase: "close", message: String(error), error: errorRecord(error) });
+            }
+        }
+    }
+    return errors;
+}

package/dist/services/sessions.js

@@ -1,9 +1,9 @@
 import crypto from "node:crypto";
-import fs from "node:fs";
 import { continuationPolicies, flowKinds } from "../domain/contracts.js";
 import { AppError } from "../shared/errors.js";
-import { commandOption, commandPosition, parseLifecycleCommand } from "./lifecycle-command.js";
+import { hookSessionIdentity } from "./hooks.js";
 import { parseJsonObject } from "../shared/json.js";
+import { prepareTextFile } from "../cli/input-preparation.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { cancelLaneWaitersForWorker } from "./lanes.js";
@@ -30,8 +30,8 @@ export function recordFlowSessionObservation(context, input) {
     const open = context.db.get(`SELECT id, run_id, protocol_id FROM flow_session_segments
      WHERE project_id = ? AND session_id = ? AND ended_at IS NULL ORDER BY started_at DESC, id DESC LIMIT 1`, [input.projectId, input.sessionId]);
     const now = context.now();
-    const runId = input.runId ?? null;
-    const protocolId = input.protocolId ?? null;
+    const runId = input.runId === undefined ? open?.run_id ?? null : input.runId;
+    const protocolId = input.protocolId === undefined ? open?.protocol_id ?? null : input.protocolId;
     if (open && open.run_id === runId && open.protocol_id === protocolId) {
         return { changed: false, segment_id: open.id };
     }
@@ -42,27 +42,6 @@ export function recordFlowSessionObservation(context, input) {
      VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?)`, [input.projectId, input.sessionId, runId, protocolId, now, input.cwd ?? null, input.toolName ?? null, input.eventKey]);
     return { changed: true, segment_id: Number(result.lastInsertRowid) };
 }
-export function bindObservedFlowSession(context, project, payload, sessionId) {
-    if (resolveProjectRoot(payload.project_root) !== project.root) {
-        throw new AppError("project_mismatch", "Observed session payload project_root does not match hook cwd project", 1, {
-            expected: project.root,
-            actual: payload.project_root
-        });
-    }
-    const session = upsertFlowSession(context, project, payload, sessionId);
-    if (session.session_kind !== "orchestrator") {
-        const now = context.now();
-        for (const unit of payload.coverage_units ?? []) {
-            if (!unit.job_id)
-                continue;
-            context.db.run(`UPDATE flow_jobs SET status = 'running', worker_session_id = ?, attempts = attempts + 1, started_at = COALESCE(started_at, ?), updated_at = ?
-         WHERE project_id = ? AND run_id = ? AND job_id = ? AND status IN ('pending', 'failed')`, [session.session_id, now, now, project.id, session.run_id ?? "", unit.job_id]);
-        }
-    }
-    if (session.run_id)
-        refreshRunSessionProjection(context, project.id, session.run_id);
-    return session;
-}
 export function registerFlowJob(context, input) {
     const jobId = input.jobId ?? `JOB-${input.runId}-${input.planItemId}`.replace(/[^A-Za-z0-9_-]+/g, "-");
     const now = context.now();
@@ -76,9 +55,33 @@ export function flowJobsForRun(context, projectId, runId) {
     return context.db.all("SELECT * FROM flow_jobs WHERE project_id = ? AND run_id = ? ORDER BY plan_item_id", [projectId, runId]);
 }
 export function registerFlowSession(context, input) {
-    const payload = decodeFlowSessionPayload(input);
+    const payload = input.preparedPayload ?? prepareFlowSessionPayload(input);
     const project = requireProjectByRoot(context, resolveProjectRoot(payload.project_root));
-    const session = upsertFlowSession(context, project, payload, input.sessionId);
+    if (payload.run_id && !context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ?", [project.id, payload.run_id])) {
+        throw new AppError("not_found", `Run is not registered: ${payload.run_id}`, 1, { run_id: payload.run_id, effect: "no_effect" });
+    }
+    const identity = input.hookEventId ? hookSessionIdentity(context, project.id, input.hookEventId) : undefined;
+    if (!identity && input.sessionId && payload.provider_session_id && payload.provider_session_id !== input.sessionId) {
+        throw new AppError("validation", "--session-id conflicts with payload provider_session_id", 2);
+    }
+    const session = upsertFlowSession(context, project, identity ? {
+        ...payload, harness: identity.harness, provider_session_id: identity.providerSessionId,
+        parent_session_id: identity.parentSessionId, agent_id: identity.agentId,
+        provider: identity.provider, model: identity.model, reasoning: identity.reasoning,
+        mode: identity.mode, agent_type: identity.agentType
+    } : { ...payload, ...(input.sessionId ? { provider_session_id: input.sessionId } : {}) }, identity?.sessionId ?? input.sessionId);
+    recordFlowSessionObservation(context, { projectId: project.id, sessionId: session.session_id,
+        runId: session.run_id, protocolId: session.protocol_id, cwd: session.cwd,
+        eventKey: `session-register-${crypto.randomUUID()}` });
+    // Logical Work/job binding belongs to the successful CLI registration, never
+    // to observation of model-supplied payload by a pre-tool hook.
+    if (session.session_kind !== "orchestrator")
+        for (const unit of payload.coverage_units ?? []) {
+            if (!unit.job_id)
+                continue;
+            context.db.run(`UPDATE flow_jobs SET status = 'running', worker_session_id = ?, attempts = attempts + 1, started_at = COALESCE(started_at, ?), updated_at = ?
+       WHERE project_id = ? AND run_id = ? AND job_id = ? AND status IN ('pending', 'failed')`, [session.session_id, context.now(), context.now(), project.id, session.run_id ?? "", unit.job_id]);
+        }
     if (session.run_id)
         appendFlowRunTimelineEvent(context, project.id, session.run_id, { type: "session_bound", session_id: session.session_id });
     if (session.run_id)
@@ -195,52 +198,15 @@ export function updateFlowSessionContinuation(context, projectId, sessionId, act
         refreshRunSessionProjection(context, projectId, session.run_id);
     return nextCount;
 }
-export function flowSessionPayloadFromRegisterCommand(command) {
-    const invocation = typeof command === "string" ? invocationFromCommand(command) : command;
-    if (!invocation)
-        return undefined;
-    if (invocation.operation === "stage_start")
-        return flowSessionPayloadFromStageStartCommand(invocation);
-    if (invocation.operation !== "session_register")
-        return undefined;
-    const payloadBase64 = commandOption(invocation, "payload-base64");
-    const payloadJson = commandOption(invocation, "payload-json");
-    const payloadFile = commandOption(invocation, "payload-file");
-    if (!payloadBase64 && !payloadJson && !payloadFile) {
-        return undefined;
-    }
-    return decodeFlowSessionPayload({ payloadBase64, payloadJson, payloadFile });
-}
-function flowSessionPayloadFromStageStartCommand(invocation) {
-    const projectRoot = commandOption(invocation, "project-root");
-    const stage = commandOption(invocation, "stage");
-    const run = commandPosition(invocation, 0);
-    if (!projectRoot || !stage || !run || run.startsWith("--"))
-        return undefined;
-    return {
-        project_root: projectRoot,
-        flow_kind: ["code", "implementation", "readiness", "merge"].includes(stage) ? "implementation" : "planning",
-        run_id: run,
-        protocol_id: null,
-        worker_id: null,
-        workspace_path: null,
-        continuation_policy: "go_router",
-        session_kind: "orchestrator",
-        current_stage: stage,
-        coverage_units: []
-    };
-}
-function invocationFromCommand(command) {
-    const analysis = parseLifecycleCommand(command);
-    return analysis.kind === "none" ? undefined : analysis.invocation;
-}
-function decodeFlowSessionPayload(input) {
+export function prepareFlowSessionPayload(input) {
+    if ([input.payloadFile, input.payloadBase64, input.payloadJson].filter(value => value !== undefined).length !== 1)
+        throw new AppError("usage", "session register requires exactly one of --payload-file, --payload-base64, or --payload-json", 2);
     if (input.payloadFile) {
-        return normalizeFlowSessionPayload(parseJsonObject(fs.readFileSync(input.payloadFile, "utf8"), "session payload"));
+        return normalizeFlowSessionPayload(parseJsonObject(prepareTextFile(input.payloadFile, "session payload").text, "session payload"));
     }
     if (input.payloadBase64) {
         if (/\$[A-Za-z_{(]/.test(input.payloadBase64)) {
-            throw new AppError("validation", "session register --payload-base64 must be a literal base64 value because Codex PreToolUse hooks run before shell variable expansion; use --payload-file from prompts", 2);
+            throw new AppError("validation", "session register received an unexpanded shell variable as --payload-base64; expand it before invoking the CLI or use --payload-file", 2);
         }
         return normalizeFlowSessionPayload(parseJsonObject(Buffer.from(input.payloadBase64, "base64").toString("utf8"), "session payload"));
     }

package/dist/services/setup.js

@@ -0,0 +1,377 @@
+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) {
+    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 (Object.hasOwn(request, "executor") && request.executor !== null) {
+        try {
+            prepareOperatorProfile(request.executor);
+        }
+        catch {
+            refuse("invalid_request_executor");
+        }
+    }
+    if (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. */
+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) {
+        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");
+    }
+    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);