@deksden-com/dd-flow-cli 0.9.0-beta.135 → 0.9.0-beta.136

package/dist/services/runs.js

@@ -911,6 +911,46 @@ export function setFlowRunRecoveryPaused(context, projectId, runId, paused) {
     const project = requireProjectByRoot(context, run.project_root);
     persistRunState(context, project, run, index);
 }
+/** Reconciliation repairs projections under the same revision CAS as normal
+ * lifecycle writes. Unknown physical ownership never closes child records. */
+export function reconcileStoredFlowRun(context, expected, health, transition, childrenSettled = false) {
+    const run = resolveRun(context, expected.project_id, expected.id);
+    if (run.index_json !== expected.index_json || run.status !== expected.status)
+        throw new AppError("run_revision_changed", "RUN changed during health observation", 1);
+    const index = authoritativeIndex(run), now = context.now();
+    index.health = health;
+    if (transition && !["done", "failed", "cancelled", "discarded"].includes(run.status)) {
+        index.status = transition;
+        if (transition === "failed") {
+            index.verdict = "failed";
+            // Observation time is not the historical exit time. Without a retained
+            // finish receipt, keep timing unknown rather than manufacturing days of work.
+            delete index.completed_at;
+            delete index.finished_at;
+            index.duration_ms = null;
+            index.timing_status = 'legacy_incomplete';
+            closeOpenStagesForOverride(index, "failed", now, false);
+            closeOpenWorksForOverride(context, run.project_id, run.id, "failed", now, false);
+        }
+        else if (childrenSettled && health.state === "owner_lost") {
+            for (const stage of index.stage_runs)
+                if (stage.status === "running") {
+                    stage.status = "paused";
+                    stage.updated_at = now;
+                }
+        }
+    }
+    if (childrenSettled && ["failed", "cancelled", "discarded"].includes(index.status)) {
+        closeOpenStagesForOverride(index, index.status === "failed" ? "failed" : "cancelled", now, false);
+        closeOpenWorksForOverride(context, run.project_id, run.id, index.status === "failed" ? "failed" : "cancelled", now, false);
+        context.db.run("UPDATE sessions SET status = 'stopped', stop_reason = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND status IN ('pending','active','waiting_user','blocked','stopping')", [`run_${index.status}`, now, run.project_id, run.id]);
+        context.db.run("UPDATE check_receipts SET status = 'aborted' WHERE project_id = ? AND run_id = ? AND status = 'running'", [run.project_id, run.id]);
+    }
+    // Health observation is not semantic progress or a new completion timestamp.
+    const project = requireProjectByRoot(context, run.project_root);
+    persistRunState(context, project, run, index, { healthOnly: true });
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.health_reconciled", payload: { run_id: run.id, previous_status: run.status, status: index.status, health } });
+}
 export function prepareFlowRunCompletion(context, input) {
     if (input.manualOverrideReason !== undefined) {
         requiredPlain(input.manualOverrideReason, "override reason");
@@ -1061,15 +1101,21 @@ export function prepareVnextMergeSourceRepairAttempt(context, input) {
     appendRunTimeline(context, project.id, run.id, { at: now, type: "merge_source_repair_prepared", run_id: run.id, merge_request_id: input.mergeRequestId, cycle });
     return { run_id: run.id, cycle };
 }
-function closeOpenStagesForOverride(index, status, now) {
+function closeOpenStagesForOverride(index, status, now, timingKnown = true) {
     const stageStatus = status === "cancelled" ? "skipped" : "failed";
     for (const stage of index.stage_runs) {
-        if (stage.status !== "running" && stage.status !== "pending" && stage.status !== "paused" && stage.status !== "blocked")
+        if (stage.status !== "running" && stage.status !== "paused" && stage.status !== "waiting_for_user" && stage.status !== "blocked")
             continue;
         stage.status = stageStatus;
         stage.updated_at = now;
-        stage.completed_at = now;
-        stage.duration_ms = durationMs(stage.started_at ?? null, now);
+        if (timingKnown) {
+            stage.completed_at = now;
+            stage.duration_ms = durationMs(stage.started_at ?? null, now);
+        }
+        else {
+            delete stage.completed_at;
+            stage.duration_ms = null;
+        }
     }
     index.attempts = index.stage_runs.map((stage) => ({
         stage: stage.stage,
@@ -1077,20 +1123,20 @@ function closeOpenStagesForOverride(index, status, now) {
         root: stage.dir,
         archive: null,
         status: stage.status,
-        started_at: stage.started_at ?? now,
+        started_at: stage.started_at ?? null,
         finished_at: stage.completed_at ?? null
     }));
 }
-function closeOpenWorksForOverride(context, projectId, runId, status, now) {
+function closeOpenWorksForOverride(context, projectId, runId, status, now, timingKnown = true) {
     const workStatus = status === "cancelled" ? "cancelled" : "failed";
     context.db.run(`UPDATE works
-       SET status = ?, updated_at = ?, completed_at = ?
+       SET status = ?, updated_at = ?, completed_at = CASE WHEN ? = 1 THEN ? ELSE completed_at END
      WHERE project_id = ? AND run_id = ?
-       AND status IN ('created', 'running', 'paused')`, [workStatus, now, now, projectId, runId]);
+       AND status IN ('created', 'running', 'paused')`, [workStatus, now, timingKnown ? 1 : 0, now, projectId, runId]);
     context.db.run(`UPDATE work_sessions
-       SET status = ?, updated_at = ?, completed_at = ?
+       SET status = ?, updated_at = ?, completed_at = CASE WHEN ? = 1 THEN ? ELSE completed_at END
      WHERE work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)
-       AND status <> 'completed'`, [workStatus, now, now, projectId, runId]);
+       AND status <> 'completed'`, [workStatus, now, timingKnown ? 1 : 0, now, projectId, runId]);
 }
 function closeRunOrchestrators(context, projectId, run, status, now) {
     if (!["done", "blocked", "cancelled", "failed"].includes(status))
@@ -1327,8 +1373,10 @@ function vnextSpecifyGuidance(run, index) {
 function persistRunState(context, project, run, index, options = {}) {
     // Fenced productive admission is a logical pause, even while physical work
     // drains. Late admitted Stage results must not revive a stopped RUN.
-    if (index.status === "running" && ["draining", "sealed", "resuming"].includes(recoveryGuard(context, project.id, run.id)?.status ?? ""))
+    if (index.status === "running" && (!options.healthOnly || context.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'run_recovery_guards'")) && ["draining", "sealed", "resuming"].includes(recoveryGuard(context, project.id, run.id)?.status ?? ""))
         index.status = "paused";
+    if (!options.healthOnly)
+        delete index.health;
     const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
     context.db.writeTransaction(() => {
         const stored = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, run.id]);
@@ -1344,7 +1392,7 @@ function persistRunState(context, project, run, index, options = {}) {
         if (options.flagRevision)
             history.push(options.flagRevision);
         index.flag_revision_history = history.slice(-32);
-        const updated = context.db.run(`UPDATE runs SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?, updated_at = ?, completed_at = ?
+        const updated = options.healthOnly ? context.db.run("UPDATE runs SET status = ?, verdict = ?, next_action = ?, index_json = ?, updated_at = ?, completed_at = ? WHERE project_id = ? AND id = ? AND index_json = ?", [index.status, index.verdict, index.next_action, JSON.stringify(persistedVnextIndex(index)), index.updated_at, index.completed_at ?? null, project.id, run.id, stored.index_json]) : context.db.run(`UPDATE runs SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?, updated_at = ?, completed_at = ?
        WHERE project_id = ? AND id = ? AND index_json = ?`, [index.status, index.verdict, index.next_action, JSON.stringify(persistedVnextIndex(index)), runtimePath, runtimePath, index.updated_at, index.completed_at ?? null, project.id, run.id, stored.index_json]);
         if (updated.changes !== 1)
             throw new AppError("run_revision_changed", "RUN changed during preparation", 1, { run_id: run.id });
@@ -1431,7 +1479,7 @@ export function publishRunProjections(context, projectId, runId) {
         if (!latest)
             throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
         const index = authoritativeIndex(latest);
-        const mutations = context.db.all("SELECT resulting_revision, result_json, created_at, idempotency_key FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? ORDER BY resulting_revision DESC LIMIT 32", [projectId, runId]);
+        const mutations = context.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'flow_run_flag_mutations'") ? context.db.all("SELECT resulting_revision, result_json, created_at, idempotency_key FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? ORDER BY resulting_revision DESC LIMIT 32", [projectId, runId]) : [];
         const history = mutations.reverse().map((row) => ({
             revision: row.resulting_revision,
             checksum: String(JSON.parse(row.result_json).snapshot_checksum ?? ""),

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/storage/database.js

@@ -5,7 +5,7 @@ import { channel } from "node:diagnostics_channel";
 import { createRequire } from "node:module";
 import { ensureDir } from "./paths.js";
 import { AppError } from "../shared/errors.js";
-import { executeStoreSchema, readStoreWriterContract, registerStoreWriter, STORE_WRITER_VERSION } from "./writer-contract.js";
+import { executeStoreSchema, readStoreWriterContract, registerStoreWriter, registerReconciliationWriter, STORE_WRITER_VERSION } from "./writer-contract.js";
 import { assertImportAdmission } from "./import-guard.js";
 import { withStoreCleanup, rollbackStoreTransaction } from "./native-cleanup.js";
 const workContinuationStorageSql = `
@@ -354,6 +354,8 @@ export function getDatabase(ddFlowHome, mode = "initialize", importPermitId, hoo
     }
     if (mode === "hook" && !exists)
         throw new AppError("hook_storage_unprepared", "Prepare the runtime store before starting native hooks", 1);
+    if (mode === "reconcile" && !exists)
+        throw new AppError("reconciliation_storage_unprepared", "Reconciliation cannot create a runtime store", 1);
     if (!exists || mode === "migrate")
         ensureDir(ddFlowHome);
     const db = mode === "read_existing" ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
@@ -365,7 +367,10 @@ export function getDatabase(ddFlowHome, mode = "initialize", importPermitId, hoo
     }
     if (mode !== "read_existing") {
         try {
-            registerStoreWriter(db);
+            if (mode === "reconcile")
+                registerReconciliationWriter(db);
+            else
+                registerStoreWriter(db);
         }
         catch (error) {
             return closeAfterOpenFailure(db, error);
@@ -379,7 +384,7 @@ export function getDatabase(ddFlowHome, mode = "initialize", importPermitId, hoo
     }
     // Internal additive schema changes must be available to every write command.
     // Higher-level Memory Bank migrations remain explicit in services/migrations.
-    if (mode !== "read_existing") {
+    if (mode !== "read_existing" && mode !== "reconcile") {
         try {
             const initialize = () => { migrate(db); ensureRecoveryStorage(db); ensureLifecycleInvocationStorage(db); };
             if (mode !== "hook") {
@@ -402,6 +407,16 @@ export function getDatabase(ddFlowHome, mode = "initialize", importPermitId, hoo
     }
     if (mode === "read_existing")
         db.exec("PRAGMA query_only = ON");
+    if (mode === "reconcile") {
+        try {
+            db.prepare("SELECT id, project_id, status, verdict, next_action, index_json, updated_at, completed_at FROM runs LIMIT 0");
+            db.prepare("SELECT id, root FROM projects LIMIT 0");
+            db.prepare("SELECT id, event_type, payload_json FROM audit_events LIMIT 0");
+        }
+        catch (error) {
+            return closeAfterOpenFailure(db, error);
+        }
+    }
     db.exec("PRAGMA foreign_keys = ON");
     return databaseFacade(dbPath, mode !== "read_existing", db, undefined, deadline);
 }

package/dist/storage/writer-contract.js

@@ -35,6 +35,14 @@ export function registerStoreWriter(db) {
         throw new AppError("store_writer_incompatible", "This CLI cannot write the store's required contract", 1, { required: current, supported: version });
     db.function("dd_flow_writer_version", () => version);
 }
+/** Health maintenance uses only verified legacy lifecycle columns and never
+ * migrates schema. Keep the retained writer fence, including version 1. */
+export function registerReconciliationWriter(db) {
+    const current = readStoreWriterContract(db);
+    if (current !== null && current !== 1 && current !== version)
+        throw new AppError("store_writer_incompatible", "Unsupported reconciliation writer contract", 1, { required: current, supported: [1, version] });
+    db.function("dd_flow_writer_version", () => current ?? version);
+}
 export function readStoreWriterContract(db) {
     if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table))
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.135",
+  "version": "0.9.0-beta.136",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "packageManager": "pnpm@10.23.0",