@deksden-com/dd-flow-cli 0.9.0-beta.143 → 0.9.0-beta.145

package/dist/services/runtime-scope-worker.js

@@ -8,6 +8,7 @@ import { AppError, errorRecord } from "../shared/errors.js";
 import { getResourceDatabase } from "../storage/database.js";
 import { assertManagedProcessLease, confirmManagedProcess, finishManagedProcess, renewManagedProcess, processIsAlive, processStartedAt, registerManagedProcess, resourceHome } from "./managed-processes.js";
 import { managedLeaseMonitor } from "./managed-lease-monitor.js";
+import { physicalStartup } from "./physical-startup.js";
 import { publicRuntimeScopeWorker, requestRuntimeScopeControl, runtimeBudgetStatus, prepareRuntimeScopeFence, parseRuntimeBudget } from "./runtime-budget.js";
 import { controlRuntimeScopeRuns } from "./runtime-scope-control.js";
 import { prepareRuntimeScopeResume, recordRuntimeScopeResume } from "./runtime-scope-resume.js";
@@ -138,8 +139,7 @@ export function prepareRuntimeScopeServing(context, scopeId, generation) {
     }
     return { key, token };
 }
-function requireStartingScopeWorker(db, key, token) {
-    const row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [key, token]);
+function requireStartingScopeWorker(db, key, token, row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [key, token])) {
     if (!row)
         throw new AppError("runtime_scope_owner_unknown", "Scope worker claim changed", 1);
     const worker = JSON.parse(row.metadata_json);
@@ -150,29 +150,55 @@ function requireStartingScopeWorker(db, key, token) {
 export async function serveRuntimeScopeControl(context, scopeId, generation) {
     const { key, token } = prepareRuntimeScopeServing(context, scopeId, generation);
     const db = getResourceDatabase(resourceHome(context));
-    const owner = birth();
-    const worker = db.writeTransaction(() => {
-        const worker = requireStartingScopeWorker(db, key, token);
-        worker.owner = owner;
-        worker.status = "running";
-        db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
-        return worker;
-    });
+    const startup = physicalStartup(context.databaseDeadlineAt);
+    let claimedOwner = undefined;
+    const assertStartupCurrent = () => {
+        const control = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
+        const fence = db.get("SELECT 1 FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [scopeId]);
+        const row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [key, token]);
+        const current = row ? JSON.parse(row.metadata_json) : null;
+        if (!control || JSON.parse(control.metadata_json).generation !== generation || fence || !current || current.token !== token || current.status !== (claimedOwner ? "running" : "starting") || current.owner?.pid !== claimedOwner?.pid || current.owner?.pid_started_at !== claimedOwner?.pid_started_at)
+            throw new AppError("runtime_scope_control_superseded", "Scope startup no longer owns this control", 1);
+    };
+    const starting = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [key, token]);
+    let worker = requireStartingScopeWorker(db, key, token, starting);
+    let retainedMetadata = starting.metadata_json;
+    let claimedByThisServe = false;
+    const persistWorker = () => {
+        const next = JSON.stringify(worker);
+        if (db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ? AND metadata_json = ?", [next, context.now(), key, token, retainedMetadata]).changes !== 1)
+            throw new AppError("runtime_scope_owner_unknown", "Scope owner changed before its retained result could be saved", 1);
+        retainedMetadata = next;
+    };
     let heartbeat;
     let lease;
     // A fence must never be held indefinitely by an observer that cannot obtain
     // fresh provider evidence. A later operator request continues the retained
     // budget; this owner records why it stopped without claiming settlement.
-    const observation = recoveryObservationBudget(worker.snapshot);
-    worker.snapshot = { ...(worker.snapshot ?? {}), recovery_observation: observation.state() };
+    let observationCleanup;
     let cleanupFailure;
     const result = await (async () => {
         try {
+            const owner = await startup.birth(assertStartupCurrent);
+            const claim = db.writeTransaction(() => {
+                assertStartupCurrent();
+                const current = requireStartingScopeWorker(db, key, token);
+                current.owner = owner;
+                current.status = "running";
+                db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(current), context.now(), key, token]);
+                return { worker: current, metadata: JSON.stringify(current) };
+            });
+            worker = claim.worker;
+            retainedMetadata = claim.metadata;
+            claimedOwner = owner;
+            claimedByThisServe = true;
+            const observation = observationCleanup = recoveryObservationBudget(worker.snapshot);
+            worker.snapshot = { ...(worker.snapshot ?? {}), recovery_observation: observation.state() };
             const record = registerManagedProcess(context, { kind: "scope-control", ownerId: key, operationId: `scope-control:${key}:${token}`, ownerPid: process.pid, metadata: { role: "control", scope_id: scopeId, generation } });
             worker.process_id = record.id;
             worker.process_lease_token = record.lease_token;
-            const confirmed = confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid: process.pid, processGroupId: process.pid, ownerPid: process.pid });
-            db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+            const confirmed = await startup.observe(() => confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid: process.pid, processGroupId: process.pid, ownerPid: process.pid }), assertStartupCurrent, record.lease_expires_at);
+            persistWorker();
             lease = managedLeaseMonitor(attemptMs => renewManagedProcess({ ...context, resourceDatabaseMode: "prepared_existing", databaseDeadlineAt: Date.now() + attemptMs }, { id: record.id, leaseToken: record.lease_token }), confirmed.lease_expires_at);
             let timerFailure;
             const assertScopeCurrent = () => {
@@ -233,7 +259,7 @@ export async function serveRuntimeScopeControl(context, scopeId, generation) {
                 await lease.ensureConfirmed(assertScopeCurrent);
                 observation.observe(outcome);
                 worker.snapshot = { ...outcome, recovery_observation: observation.state() };
-                db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+                persistWorker();
                 if (worker.snapshot.drain?.physical_settled === true) {
                     worker.status = "completed";
                     break;
@@ -259,18 +285,19 @@ export async function serveRuntimeScopeControl(context, scopeId, generation) {
             lease?.close();
             if (heartbeat)
                 clearInterval(heartbeat);
-            observation.exhausted();
-            worker.snapshot = { ...(worker.snapshot ?? {}), recovery_observation: observation.state() };
+            observationCleanup?.exhausted();
+            worker.snapshot = { ...(worker.snapshot ?? {}), ...(observationCleanup ? { recovery_observation: observationCleanup.state() } : {}) };
             let persistenceFailure;
             try {
-                db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+                persistWorker();
             }
             catch (error) {
                 persistenceFailure = error;
                 process.stderr.write(`${JSON.stringify({ primary: worker.error, primary_error: worker.snapshot.error, phase: "persist_scope_owner", secondary: errorRecord(error) })}\n`);
             }
             try {
-                if (worker.process_id && worker.process_lease_token)
+                const current = claimedByThisServe && db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [key, token]);
+                if (current && current.metadata_json === retainedMetadata && !persistenceFailure && worker.process_id && worker.process_lease_token)
                     finishManagedProcess(context, { id: worker.process_id, leaseToken: worker.process_lease_token, state: worker.status === "failed" ? "failed" : "stopped", reason: "scope_owner_exited" });
             }
             catch (error) {

package/dist/services/sessions.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { recordFlowSessionObservation } from "./hook-session-observation.js";
 import { continuationPolicies, flowKinds } from "../domain/contracts.js";
 import { AppError } from "../shared/errors.js";
 import { hookSessionIdentity } from "./hooks.js";
@@ -23,25 +24,7 @@ export function publicFlowSession(context, session) {
     delete publicFields.parent_session_id;
     return { ...publicFields, harness_id: identity.harness_id, session_id: identity.session_id, parent_session: parent ? publicSessionIdentity(parent) : null };
 }
-export function recordFlowSessionObservation(context, input) {
-    const duplicate = context.db.get("SELECT id FROM flow_session_segments WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
-    if (duplicate)
-        return { changed: false, segment_id: duplicate.id };
-    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 === 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 };
-    }
-    if (open)
-        context.db.run("UPDATE flow_session_segments SET ended_at = ? WHERE id = ? AND ended_at IS NULL", [now, open.id]);
-    const result = context.db.run(`INSERT INTO flow_session_segments
-      (project_id, session_id, run_id, protocol_id, started_at, ended_at, cwd, tool_name, event_key)
-     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 { recordFlowSessionObservation } from "./hook-session-observation.js";
 export function registerFlowJob(context, input) {
     const jobId = input.jobId ?? `JOB-${input.runId}-${input.planItemId}`.replace(/[^A-Za-z0-9_-]+/g, "-");
     const now = context.now();
@@ -167,11 +150,7 @@ export function stoppedMergeWorkerState(context, projectId, workerId) {
         status: latest?.status ?? null
     };
 }
-export function activeFlowSessionsForProject(context, projectId) {
-    return context.db.all(`SELECT * FROM sessions
-     WHERE project_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')
-     ORDER BY updated_at DESC`, [projectId]);
-}
+export { activeFlowSessionsForProject } from "./hook-session-observation.js";
 export function flowSessionsForProject(context, projectId, filter = {}) {
     if (filter.sessionId) {
         return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND (session_id = ? OR provider_session_id = ?) ORDER BY updated_at DESC", [projectId, filter.sessionId, filter.sessionId]);

package/dist/services/setup.js

@@ -60,7 +60,7 @@ function atomicJson(file, value) {
             fs.unlinkSync(temporary);
     }
 }
-function readSetupRequest(file) {
+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)
@@ -77,7 +77,7 @@ function readSetupRequest(file) {
         || !["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) {
+    if (validateExecutor && Object.hasOwn(request, "executor") && request.executor !== null) {
         try {
             prepareOperatorProfile(request.executor);
         }
@@ -85,7 +85,7 @@ function readSetupRequest(file) {
             refuse("invalid_request_executor");
         }
     }
-    if (Object.hasOwn(request, "profileCreation")) {
+    if (validateExecutor && Object.hasOwn(request, "profileCreation")) {
         try {
             validateProfileCreationIntent(request.profileCreation);
         }
@@ -225,22 +225,72 @@ export function commitSetupOnboarding(home, requestId, selection) {
     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) {
-        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");
-    }
+    if (installation)
+        validateInstallation(root, installation);
     let readiness = installation ? "installed" : "not_installed";
     if (installation) {
         try {

package/dist/services/stage-handlers.js

@@ -9,7 +9,7 @@ import { finishVnextMerge, startVnextMerge } from "./vnext-merge.js";
 import { ResolvedFlowDescriptor } from "./flow-descriptors.js";
 import { vnextStages } from "../domain/stage-catalog.js";
 import { sdlcHandlerIdentities as ids } from "../domain/stage-handler-identities.js";
-import { memoryInitStageHandlers } from "./memory-stage-dispatch.js";
+import { memoryInitStageHandlers, memoryUpgradeStageHandlers } from "./memory-stage-dispatch.js";
 /** Engine-owned code, not a plugin registration surface or executable descriptor expression. */
 export const sdlcStageHandlers = Object.freeze({
     specify: Object.freeze({ ...ids.specify, entry: launchVnextSpecify, finish: finishVnextSpecifyStage }),
@@ -23,8 +23,8 @@ export const sdlcStageHandlers = Object.freeze({
 /** A fresh inventory cannot mutate the registered handler functions. */
 export function bundledHandlerContext(blobs) {
     return {
-        entryHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers)].map(handler => handler.entryId)),
-        finishHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers)].map(handler => handler.finishId)), blobs
+        entryHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers), ...Object.values(memoryUpgradeStageHandlers)].map(handler => handler.entryId)),
+        finishHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers), ...Object.values(memoryUpgradeStageHandlers)].map(handler => handler.finishId)), blobs
     };
 }
 /** Handler identity is also stage/flow scoped: a known CODE handler is not a memory handler. */
@@ -40,8 +40,9 @@ export function admitBundledFlow(input, sha256, blobs) {
             throw new AppError("flow_handler_scope_invalid", "SDLC handlers require the registered seven-stage layout and transitions", 2, { phase: "prepare", effect: "no_effect" });
         }
     }
-    if (flow.descriptor.id === "mb-init") {
-        const stages = Object.keys(memoryInitStageHandlers);
+    if (flow.descriptor.id === "mb-init" || flow.descriptor.id === "mb-upgrade") {
+        const upgrade = flow.descriptor.id === "mb-upgrade";
+        const stages = Object.keys(upgrade ? memoryUpgradeStageHandlers : memoryInitStageHandlers);
         const edges = stages.slice(0, -1).map((from, index) => ({ from, to: stages[index + 1], on: "accepted" }));
         // Historical packs have only accepted transitions; diagnostic VERIFY uses
         // the same REVIEW handler without granting another route or stage.
@@ -59,12 +60,13 @@ export function admitBundledFlow(input, sha256, blobs) {
                 schemaId = JSON.parse(flow.stageBlob(stage.id, "result_schema").toString("utf8")).$id;
             }
             catch { /* Invalid schema cannot authorize this stage handler. */ }
-            if (schemaId !== `dd-flow/mb-init-${stage.id}-result@1`)
+            if (schemaId !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : `dd-flow/mb-init-${stage.id}-result@1`))
                 throw new AppError("flow_handler_scope_invalid", "Memory init stage requires its own registered result schema", 2, { phase: "prepare", effect: "no_effect", stage: stage.id });
         }
     }
     for (const stage of flow.descriptor.stages) {
-        const handlers = flow.descriptor.id === "sdlc" ? Object.values(sdlcStageHandlers) : flow.descriptor.id === "mb-init" ? Object.values(memoryInitStageHandlers) : [];
+        const handlers = flow.descriptor.id === "sdlc" ? Object.values(sdlcStageHandlers) : flow.descriptor.id === "mb-init" ? Object.values(memoryInitStageHandlers)
+            : flow.descriptor.id === "mb-upgrade" ? Object.values(memoryUpgradeStageHandlers) : [];
         const handler = handlers.find(candidate => candidate.stage === stage.id);
         if (!handler || stage.entry_handler !== handler.entryId || stage.finish_handler !== handler.finishId) {
             throw new AppError("flow_handler_scope_invalid", "Registered handlers do not belong to this flow stage", 2, { phase: "prepare", effect: "no_effect", flow_id: flow.descriptor.id, stage: stage.id });

package/dist/services/stage-pause.js

@@ -17,7 +17,7 @@ import { assertRunMutationAllowed } from "./run-recovery.js";
 import { runtimeCommand } from "./runtime-command.js";
 import { prepareAgentOutputFile } from "../storage/agent-output.js";
 import { latestRunVerificationMatrix } from "./verification-matrix.js";
-import { validateAcceptedIntentReview } from "./accepted-intent.js";
+import { acceptedIntentReviewFingerprint, prepareAcceptedIntentSources, validatePreparedAcceptedIntentReview } from "./accepted-intent.js";
 export { flowCommand } from "./runtime-command.js";
 export function prepareStagePause(context, input) {
     if (typeof input.question !== "string" || !input.question.trim())
@@ -116,7 +116,31 @@ export function resumeStageAfterUser(context, input) {
     // reserving SQLite's writer; an unreferenced candidate has no flow authority.
     publishImmutableInput(answerPath, Buffer.from(input.answer), "hitl_answer_conflict");
     const answerPacket = prepareStagePacket(answerPath, Buffer.from(input.answer));
-    context.db.writeTransaction(() => {
+    // Capture the exact continuation inputs and already-issued commands before
+    // accepting the answer. A publication retry must not issue new authority.
+    const retryCommands = lifecycleRetryCommands(context, stage.stage);
+    const resumeSourcePath = path.join(path.dirname(pause.question_path), `resume-${crypto.createHash("sha256").update(`${pause.id}\0${input.answer}`).digest("hex")}.json`);
+    let review;
+    let reviewPreparationError;
+    const previousAnswer = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [project.id, run.id])?.id ?? 0;
+    if (["plan-review", "code-review"].includes(stage.stage)) {
+        try {
+            const home = requireRunHome(run), source = latestRunVerificationMatrix(context, project.id, run.id, stage.stage, "input");
+            const reviewContext = path.join(home, stage.stage === "plan-review" ? "04-plan-review/work-context.json" : "06-code-review/review-context.json");
+            const retainedContext = fs.existsSync(reviewContext) ? JSON.parse(fs.readFileSync(reviewContext, "utf8")) : null;
+            const currentSources = acceptedIntentReviewFingerprint(source?.metadata.accepted_sources) ? prepareAcceptedIntentSources(context, { projectId: project.id, runId: run.id, home, stageDirectory: "intake", marked: true }).sources : [];
+            review = { home, source, retainedContext, currentSources };
+        }
+        catch (error) {
+            if (!(error instanceof AppError))
+                throw error;
+            reviewPreparationError = error;
+        }
+    }
+    return context.db.writeTransaction(() => {
+        const currentAnswer = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [project.id, run.id])?.id ?? 0;
+        if (currentAnswer !== previousAnswer)
+            throw new AppError("runtime_state_changed", "Accepted inputs changed during resume preparation", 1);
         const identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
         if (workSession.session_id !== identity.sessionId) {
             bindSessionForResume(context, work.work_id, identity, now);
@@ -130,49 +154,56 @@ export function resumeStageAfterUser(context, input) {
         acceptStagePacket(context, { projectId: project.id, runId: run.id, stage: stage.stage, prepared: answerPacket });
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
         context.db.afterCommit(() => refreshRunWorkProjection(context, project.id, run.id));
-    });
-    const prompt = evidence.prompt;
-    const retryCommands = lifecycleRetryCommands(context, stage.stage);
-    const intentInstructions = [];
-    if (["plan-review", "code-review"].includes(stage.stage)) {
-        try {
-            const home = requireRunHome(run), source = latestRunVerificationMatrix(context, project.id, run.id, stage.stage, "input");
-            const reviewContext = path.join(home, stage.stage === "plan-review" ? "04-plan-review/work-context.json" : "06-code-review/review-context.json");
-            const retainedContext = fs.existsSync(reviewContext) ? JSON.parse(fs.readFileSync(reviewContext, "utf8")) : null;
-            validateAcceptedIntentReview(context, { projectId: project.id, runId: run.id, home, stage: stage.stage, decisionFrozen: Boolean(retainedContext?.accepted_decision) }, source?.metadata.accepted_sources, retainedContext?.accepted_intent_review_fingerprint);
-        }
-        catch (error) {
-            if (!(error instanceof AppError))
-                throw error;
-            intentInstructions.push(`Accepted-input review boundary: ${error.code}: ${error.message}`);
-            if (error.code === "accepted_intent_review_ack_required")
-                intentInstructions.push(`Apply/classify this own-stage clarification through the existing coordinator correction/repair route. Include this exact field in the decision: ${JSON.stringify({ accepted_intent_acknowledgement: error.details.accepted_intent_acknowledgement })}. Independent reviewer results prove only the earlier retained inputs; do not claim they reviewed the new answer.`);
-            else
-                intentInstructions.push("Do not accept stale independent review as coverage of this answer; report the actionable upstream revision/evidence blocker.");
+        const prompt = evidence.prompt;
+        const intentInstructions = [];
+        if (["plan-review", "code-review"].includes(stage.stage)) {
+            try {
+                if (reviewPreparationError)
+                    throw reviewPreparationError;
+                if (review) {
+                    const id = context.db.get("SELECT id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.pause_id') = ? ORDER BY id DESC LIMIT 1", [project.id, run.id, pause.id]).id;
+                    const identity = `accepted_hitl:${String(id).padStart(12, "0")}:${pause.id}`;
+                    const sources = [...review.currentSources, { role: `${identity}:0-question`, sha256: crypto.createHash("sha256").update(evidence.question).digest("hex") }, { role: `${identity}:1-answer`, sha256: crypto.createHash("sha256").update(input.answer).digest("hex") }];
+                    validatePreparedAcceptedIntentReview(context, { projectId: project.id, runId: run.id, home: review.home, stage: stage.stage, decisionFrozen: Boolean(review.retainedContext?.accepted_decision) }, review.source?.metadata.accepted_sources, review.retainedContext?.accepted_intent_review_fingerprint, sources);
+                }
+            }
+            catch (error) {
+                if (!(error instanceof AppError))
+                    throw error;
+                intentInstructions.push(`Accepted-input review boundary: ${error.code}: ${error.message}`);
+                if (error.code === "accepted_intent_review_ack_required")
+                    intentInstructions.push(`Apply/classify this own-stage clarification through the existing coordinator correction/repair route. Include this exact field in the decision: ${JSON.stringify({ accepted_intent_acknowledgement: error.details.accepted_intent_acknowledgement })}. Independent reviewer results prove only the earlier retained inputs; do not claim they reviewed the new answer.`);
+                else
+                    intentInstructions.push("Do not accept stale independent review as coverage of this answer; report the actionable upstream revision/evidence blocker.");
+            }
         }
-    }
-    const continuation = [
-        prompt.trimEnd(),
-        "",
-        "<hitl_resume>",
-        `- Pause: ${pause.id}`,
-        `- Question source: ${pause.question_path}`,
-        `- Answer source: ${answerPath}`,
-        "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
-        ...intentInstructions,
-        ...(retryCommands.length ? ["- A prior no-effect lifecycle rejection now has these authoritative replacement commands; correct the rejected input and use only these replacements:", ...retryCommands.map(command => `  ${command}`)] : []),
-        "",
-        "<user_question>",
-        evidence.question,
-        "</user_question>",
-        "",
-        "<user_answer>",
-        input.answer,
-        "</user_answer>",
-        "</hitl_resume>",
-        ""
-    ].join("\n");
-    return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
+        const continuation = [
+            prompt.trimEnd(),
+            "",
+            "<hitl_resume>",
+            `- Pause: ${pause.id}`,
+            `- Question source: ${pause.question_path}`,
+            `- Answer source: ${answerPath}`,
+            "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
+            ...intentInstructions,
+            ...(retryCommands.length ? ["- A prior no-effect lifecycle rejection now has these authoritative replacement commands; correct the rejected input and use only these replacements:", ...retryCommands.map(command => `  ${command}`)] : []),
+            "",
+            "<user_question>",
+            evidence.question,
+            "</user_question>",
+            "",
+            "<user_answer>",
+            input.answer,
+            "</user_answer>",
+            "</hitl_resume>",
+            ""
+        ].join("\n");
+        const result = { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, resume_source_path: resumeSourcePath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
+        const scope = context.env.DD_FLOW_INVOCATION_SCOPE ? JSON.parse(context.env.DD_FLOW_INVOCATION_SCOPE) : null;
+        const bytes = Buffer.from(`${JSON.stringify({ invocation_id: context.env.DD_FLOW_CURRENT_INVOCATION ?? null, generation: scope?.generation ?? null, result })}\n`);
+        acceptStagePacket(context, { projectId: project.id, runId: run.id, stage: stage.stage, prepared: { file: resumeSourcePath, bytes, sha256: crypto.createHash("sha256").update(bytes).digest("hex") } });
+        return result;
+    });
 }
 export function stagePauseCommand(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -180,6 +211,39 @@ export function stagePauseCommand(context, input) {
     const questionInputPath = prepareAgentOutputFile(path.join(requireRunHome(run), "works", input.workId, "question-input.md"));
     return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "pause", shortEntityReference(input.runId), "--stage", input.stage, "--work", shortEntityReference(input.workId), "--question-file", questionInputPath, "--project-root", input.projectRoot, "--json"]));
 }
+/** Recover only the exact resume committed with this invocation; never resume again. */
+export function recoverCommittedStageResume(context, input) {
+    const project = requireProjectByRoot(context, input.projectRoot), run = requireRun(context, project.id, input.runId);
+    const work = requireWork(context, project.id, run.id, input.workId);
+    const index = JSON.parse(run.index_json);
+    const current = index.stage_runs.find(stage => stage.stage === input.stage);
+    if (!current || current.status !== "running" || index.current_stage && index.current_stage !== input.stage || work.status !== "running")
+        return null;
+    const resumed = context.db.get("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.work_id') = ? ORDER BY id DESC LIMIT 1", [project.id, run.id, input.stage, work.work_id]);
+    if (!resumed)
+        return null;
+    const acceptedPause = JSON.parse(resumed.payload_json);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.attempt') = ? AND json_extract(payload_json, '$.file') LIKE '%/resume-%.json' ORDER BY id DESC LIMIT 257", [project.id, run.id, input.stage, current.attempt]);
+    if (rows.length > 256)
+        throw new AppError("stage_resume_receipt_invalid", "Resume receipt count exceeds its bound", 1);
+    let result = null;
+    for (const row of rows) {
+        const packet = JSON.parse(row.payload_json);
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (bytes.length > 8 * 1024 * 1024 || bytes.toString("base64") !== packet.base64 || crypto.createHash("sha256").update(bytes).digest("hex") !== packet.sha256)
+            throw new AppError("stage_resume_receipt_invalid", "Resume receipt custody differs from its committed bytes", 1);
+        const retained = JSON.parse(bytes.toString("utf8"));
+        if (retained.invocation_id !== input.id)
+            continue;
+        const value = retained.result;
+        if (retained.generation !== input.generation || !value || value.run_id !== run.id || value.work_id !== work.work_id || value.stage !== input.stage
+            || value.pause_id !== acceptedPause.pause_id || value.answer_path !== acceptedPause.answer_path || value.resume_source_path !== packet.file || typeof value.worker_prompt_markdown !== "string"
+            || result && JSON.stringify(result) !== JSON.stringify(value))
+            throw new AppError("stage_resume_receipt_invalid", "Resume receipt does not match the current invocation and accepted pause", 1);
+        result = value;
+    }
+    return result;
+}
 /** Render separate file-write and lifecycle-call instructions for HITL. */
 export function stagePauseCommandTemplate(command) {
     const questionFile = command.match(/--question-file\s+(?:'([^']*)'|"([^"]*)"|(\S+))/)?.slice(1).find(Boolean) ?? "<question-file-from-command>";

package/dist/services/version-status.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { parse as parseYaml } from "yaml";
-const canonicalOnlyFlowNames = ["mb-init.md", "mb-upgrade.md", "mb-distill.md"];
+export const canonicalOnlyFlowNames = Object.freeze(["mb-init.md", "mb-upgrade.md", "mb-distill.md"]);
 export function resolveStatusProjectRoot(input) {
     if (input.requestedRoot) {
         const absolute = path.resolve(input.requestedRoot);

package/dist/services/vnext-fanout.js

@@ -105,7 +105,7 @@ export function verifiedNativeWorkFailure(context, input) {
 }
 export function fanoutState(input) {
     if (!input.hasWork)
-        return input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
+        return input.registeredEmpty ? "children_settled" : input.dispatch === "none" ? "coordinator_required" : "dispatch_required";
     if (input.capacityRequired && !input.capacityKnown)
         return "capacity_required";
     if (input.created || input.running)
@@ -133,14 +133,17 @@ export function readFanoutDescriptor(stageRoot) {
  * productive assignments, including reviewer/correction waves.
  */
 export function memoryStageFanoutDescriptor(context, input) {
-    if (!["compose", "review"].includes(input.stage))
+    if (!["compose", "upgrade", "review"].includes(input.stage))
         return null;
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = context.db.get("SELECT flow_kind,index_json FROM runs WHERE project_id=? AND id=?", [project.id, input.runId]);
-    if (run?.flow_kind !== "mb-init")
+    if (!run || !["mb-init", "mb-upgrade"].includes(run.flow_kind))
+        return null;
+    const authoringStage = run.flow_kind === "mb-init" ? "compose" : "upgrade";
+    if (input.stage !== authoringStage && input.stage !== "review")
         return null;
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+    if (!bundle || bundle.descriptor.descriptor.id !== run.flow_kind)
         throw new AppError("stage_graph_compatibility_required", "Memory graph requires its admitted RUN bundle", 1);
     const index = JSON.parse(run.index_json);
     if (index.current_stage !== input.stage || !index.stage_runs.some(stage => stage.stage === input.stage && stage.status === "running"))
@@ -153,7 +156,7 @@ export function memoryStageFanoutDescriptor(context, input) {
         if (id === root.workId)
             continue;
         const work = context.db.get("SELECT parent_work_id,result_schema FROM works WHERE project_id=? AND run_id=? AND work_id=?", [project.id, input.runId, id]);
-        const schemas = input.stage === "compose" ? ["dd-flow/memory-composition-work-result@1"] : ["dd-flow/memory-review-work-result@1", "dd-flow/memory-repair-work-result@1"];
+        const schemas = input.stage === authoringStage ? ["dd-flow/memory-composition-work-result@1"] : ["dd-flow/memory-review-work-result@1", "dd-flow/memory-repair-work-result@1"];
         if (!work || work.parent_work_id !== root.workId || !schemas.includes(work.result_schema ?? ""))
             throw new AppError("stage_graph_conflict", "Memory graph contains an unassigned Work", 1);
         const custody = readWorkBatchCustody(context, id);
@@ -161,11 +164,11 @@ export function memoryStageFanoutDescriptor(context, input) {
             || custody.scope.cycle !== scope.cycle || custody.scope.stage !== input.stage || custody.scope.parent_work_id !== root.workId)
             throw new AppError("stage_graph_conflict", "Memory graph contains foreign allocation custody", 1);
     }
-    if (input.stage === "compose") {
+    if (input.stage === authoringStage) {
         const children = context.db.all("SELECT work_id FROM works WHERE project_id=? AND run_id=? AND parent_work_id=?", [project.id, input.runId, root.workId]).filter(work => members.has(work.work_id));
         const registered = context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.composition_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? LIMIT 1", [project.id, input.runId, scope.attempt, scope.cycle]);
         if (children.length || registered) {
-            const registration = selectMemoryCompositionRegistration(context, { ...scope, stage: "compose", parent_work_id: root.workId });
+            const registration = selectMemoryCompositionRegistration(context, { ...scope, stage: authoringStage, parent_work_id: root.workId });
             const ids = new Set(Object.values(registration.work_ids));
             if (ids.size !== children.length || children.some(work => !ids.has(work.work_id)))
                 throw new AppError("stage_graph_conflict", "Memory composition differs from its registered graph", 1);
@@ -185,7 +188,8 @@ export function getVnextFanoutStatus(context, input) {
     const index = JSON.parse(run.index_json);
     const bundle = index.execution_bundle ? readFlowRunExecutionBundle(context, { projectRoot, runId: input.runId }) : null;
     const stageRoot = path.join(run.run_root, bundle ? bundle.descriptor.stage(input.stage).directory : vnextStageDirectory(input.stage));
-    let descriptor = memoryStageFanoutDescriptor(context, input) ?? readFanoutDescriptor(stageRoot);
+    const memoryDescriptor = memoryStageFanoutDescriptor(context, input);
+    let descriptor = memoryDescriptor ?? readFanoutDescriptor(stageRoot);
     // Registration is authoritative even if projection publication was interrupted,
     // or an otherwise review-off stage acquired an aggregate repair graph.
     if (!descriptor && context.db.get("SELECT 1 FROM sqlite_master WHERE name = 'repair_intents'")) {
@@ -211,6 +215,14 @@ export function getVnextFanoutStatus(context, input) {
     const ready = { works: all.works.filter(work => work.ready) };
     const counts = Object.fromEntries(["created", "running", "completed", "failed", "cancelled"].map((status) => [status, all.works.filter((work) => work.status === status).length]));
     const hasWork = all.works.length > 0;
+    // Only SQL-owned memory registration can attest a deliberately empty
+    // graph. A mutable fanout.json must never turn missing Work into success.
+    let registeredEmpty = false;
+    if (memoryDescriptor && input.stage === "upgrade" && !hasWork
+        && context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.composition_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')='upgrade' AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? AND json_extract(payload_json,'$.scope.parent_work_id')=? LIMIT 1", [project.id, input.runId, currentScope.attempt, currentScope.cycle, descriptor.parent_work_id])) {
+        const registered = selectMemoryCompositionRegistration(context, { ...currentScope, stage: "upgrade", parent_work_id: descriptor.parent_work_id });
+        registeredEmpty = Object.keys(registered.work_ids).length === 0;
+    }
     const capacityKnown = capacity.available_slots !== null;
     return {
         ok: true,
@@ -221,7 +233,7 @@ export function getVnextFanoutStatus(context, input) {
             // PLAN-REVIEW has a deterministic dispatcher. CODE and CODE-REVIEW do
             // not: their coordinator first materializes the Work graph from its
             // authoritative prompt. An empty graph is therefore not a success.
-            state: fanoutState({ dispatch: descriptor.dispatch, hasWork, capacityRequired: descriptor.capacity_required, capacityKnown, created: counts.created ?? 0, running: counts.running ?? 0 }),
+            state: fanoutState({ dispatch: descriptor.dispatch, hasWork, registeredEmpty, capacityRequired: descriptor.capacity_required, capacityKnown, created: counts.created ?? 0, running: counts.running ?? 0 }),
             capacity,
             graph_revision: all.works.map(work => ({ work_id: work.work_id, status: work.status, depends_on: work.depends_on })),
             works: { ...counts, ready: ready.works.map((work) => ({ work_id: work.work_id, task: work.task, launch_policy: work.launch_policy, start_command: work.start_command })) }