@deksden-com/dd-flow-cli 0.9.0-beta.75 → 0.9.0-beta.79

package/dist/services/runs.js

@@ -37,7 +37,14 @@ const allowedRunFlowKinds = [
     "review",
     "custom"
 ];
-export function startFlowRun(context, input) {
+export function prepareFlowRunStart(context, input) {
+    const subjectId = requiredPlain(input.subjectId, "subject-id");
+    const subjectType = requiredPlain(input.subjectType, "subject-type");
+    const slug = normalizeSlug(input.slug);
+    for (const [name, value] of [["task profile", input.taskProfile], ["protocol overrides", input.protocolOverrides], ["RUN overrides", input.runOverrides]]) {
+        if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value)))
+            throw new AppError("validation", `${name} must be a JSON object`, 2);
+    }
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const flowKind = parseRunFlowKind(input.flowKind);
     const vnext = flowKind === "vnext_protocolize" || flowKind === "vnext_specify";
@@ -48,12 +55,7 @@ export function startFlowRun(context, input) {
     const flowContract = input.flowKind === "mb-upgrade"
         ? loadUpgradeFlowContract(context, projectRoot)
         : loadProjectFlowContract(projectRoot);
-    registerProject(context, { root: projectRoot });
-    const project = requireProjectByRoot(context, projectRoot);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot ?? projectRoot);
-    const slug = normalizeSlug(input.slug);
-    const runId = nextRunId(context, project.id, slug);
-    const { shortId } = parseFullEntityId(runId);
     const now = context.now();
     const flowFlags = resolveFlowFlags(flowContract, {
         flowKind,
@@ -64,6 +66,14 @@ export function startFlowRun(context, input) {
         snapshotRevision: 1,
         now
     });
+    return { projectRoot, flowKind, routingInput, executionProfile, workspaceRoot, slug, subjectId, subjectType, now, flowFlags };
+}
+export function startFlowRun(context, input, prepared = prepareFlowRunStart(context, input)) {
+    const { projectRoot, flowKind, routingInput, executionProfile, workspaceRoot, slug, subjectId, subjectType, now, flowFlags } = prepared;
+    registerProject(context, { root: projectRoot });
+    const project = requireProjectByRoot(context, projectRoot);
+    const runId = nextRunId(context, project.id, slug);
+    const { shortId } = parseFullEntityId(runId);
     const runHome = projectRunHome(context.ddFlowHome, project.id, runId);
     const runDirRelative = path.posix.join("runs", runId);
     const runtimePath = projectRunJsonPath(context.ddFlowHome, project.id, runId);
@@ -73,8 +83,8 @@ export function startFlowRun(context, input) {
         short_id: shortId,
         flow_kind: flowKind,
         subject: {
-            id: requiredPlain(input.subjectId, "subject-id"),
-            title: requiredPlain(input.subjectId, "subject-id")
+            id: subjectId,
+            title: subjectId
         },
         project: {
             id: project.id,
@@ -147,7 +157,7 @@ export function startFlowRun(context, input) {
         project.root,
         workspaceRoot,
         flowKind,
-        requiredPlain(input.subjectType, "subject-type"),
+        subjectType,
         index.subject.id,
         index.status,
         index.verdict,
@@ -323,9 +333,12 @@ export function getFlowRunVariables(context, input) {
     return { ok: true, run_id: run.id, variables };
 }
 export function setFlowRunVariable(context, input) {
+    return setRunVariable(context, input, input.value, prepareFlowRunVariable(context, input));
+}
+export function prepareFlowRunVariable(context, input) {
     if (!input.key.startsWith("user."))
         throw new AppError("validation", "Only user.* RUN variables may be set directly", 2, { key: input.key });
-    return setRunVariable(context, input, input.value);
+    return prepareRunVariable(context, input);
 }
 /** Controllers own policy.* and runtime.* values; agents never call this directly. */
 export function setRuntimeRunVariable(context, input) {
@@ -334,21 +347,7 @@ export function setRuntimeRunVariable(context, input) {
     return setRunVariable(context, input, input.value);
 }
 export function setFlowRunConfig(context, input) {
-    if (input.key !== "plan_review.mode" && input.key !== "code_review.mode") {
-        throw new AppError("validation", `Unknown RUN config key: ${input.key}`, 2);
-    }
-    if (!["auto", "off", "standard", "deep"].includes(input.value)) {
-        throw new AppError("validation", "--value for review mode must be auto, off, standard, or deep", 2);
-    }
-    const reason = requiredPlain(input.reason, "reason");
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const run = resolveRun(context, project.id, input.runId);
-    assertRunMutationAllowed(context, project.id, run.id);
-    const index = authoritativeIndex(run);
-    const stageName = input.key === "plan_review.mode" ? "plan-review" : "code-review";
-    if (index.stage_runs.some((stage) => stage.stage === stageName)) {
-        throw new AppError("invalid_run_config_state", `${input.key} is frozen after ${stageName} starts`, 2, { run_id: run.id });
-    }
+    const { reason, project, run, index } = prepareFlowRunConfig(context, input);
     const now = context.now();
     const settings = runSettings(index);
     const previous = input.key === "plan_review.mode" ? settings.plan_review : settings.code_review;
@@ -366,6 +365,24 @@ export function setFlowRunConfig(context, input) {
     appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_config_set", run_id: run.id, key: input.key, value: mode, source, reason });
     return { ok: true, run_id: run.id, settings: runSettings(index), idempotent: false };
 }
+export function prepareFlowRunConfig(context, input) {
+    if (input.key !== "plan_review.mode" && input.key !== "code_review.mode") {
+        throw new AppError("validation", `Unknown RUN config key: ${input.key}`, 2);
+    }
+    if (!["auto", "off", "standard", "deep"].includes(input.value)) {
+        throw new AppError("validation", "--value for review mode must be auto, off, standard, or deep", 2);
+    }
+    const reason = requiredPlain(input.reason, "reason");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
+    const index = authoritativeIndex(run);
+    const stageName = input.key === "plan_review.mode" ? "plan-review" : "code-review";
+    if (index.stage_runs.some((stage) => stage.stage === stageName)) {
+        throw new AppError("invalid_run_config_state", `${input.key} is frozen after ${stageName} starts`, 2, { run_id: run.id });
+    }
+    return { reason, project, run, index };
+}
 /** Freeze an automatic review request once from already accepted policy or PLAN facts. */
 export function freezeFlowRunReviewMode(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -535,17 +552,22 @@ export function listFlowRuns(context, input) {
         .map(flowRunSummary);
     return { ok: true, project, runs };
 }
-export function attachFlowRunStage(context, input) {
+export function prepareFlowRunStageAttachment(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
-    const now = context.now();
     const stage = requiredPlain(input.stage, "stage");
-    const dir = requiredStageDir(input.dir);
+    const dir = prepareStageDirectory(input.dir);
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
     assertVnextStageStart(run, index, stage, status, existing);
+    return { project, run, index, stage, dir, status, existing };
+}
+export function attachFlowRunStage(context, input) {
+    // Mutable stage state is re-read immediately before archiving/persisting.
+    const { project, run, index, stage, dir, status, existing } = prepareFlowRunStageAttachment(context, input);
+    const now = context.now();
     if (status === "running" && existing) {
         archiveExistingStageAttempt(context, project.id, run.id, runArtifactRoot(run), dir);
     }
@@ -587,7 +609,17 @@ export function attachFlowRunStage(context, input) {
 export function withStageSettlement(context, operation) {
     return context.db.writeTransaction(operation);
 }
-export function completeFlowRunStage(context, input) {
+export function prepareFlowRunStageCompletion(context, input) {
+    for (const [name, value] of Object.entries({ stageReport: input.stageReport, data: input.data, dataSchemaId: input.dataSchemaId, report: input.report })) {
+        if (value !== undefined)
+            requiredPlain(value, name);
+    }
+    if (input.aliases !== undefined) {
+        if (!Array.isArray(input.aliases))
+            throw new AppError("validation", "artifact aliases must be an array", 2);
+        for (const alias of input.aliases)
+            requiredPlain(alias, "artifact alias");
+    }
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     if (["done", "failed", "skipped"].includes(input.status))
@@ -595,13 +627,17 @@ export function completeFlowRunStage(context, input) {
     else
         assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
-    const now = context.now();
     const stage = requiredPlain(input.stage, "stage");
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${stage}`, 1, { run_id: run.id, stage });
     }
+    return { project, run, index, stage, status, existing };
+}
+export function completeFlowRunStage(context, input) {
+    const { project, run, index, stage, status, existing } = prepareFlowRunStageCompletion(context, input);
+    const now = context.now();
     const stageRun = {
         ...existing,
         status,
@@ -717,7 +753,11 @@ export function resumeFlowRunStage(context, input) {
     return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
 }
 /** Pause the current stage for a non-user runtime blocker. */
-export function blockFlowRunStage(context, input) {
+export function prepareFlowRunStageBlock(context, input) {
+    if (!["engine", "harness", "environment"].includes(input.kind) || typeof input.retryable !== "boolean")
+        throw new AppError("validation", "stage block requires a valid kind and boolean retryable", 2);
+    requiredPlain(input.code, "code");
+    requiredPlain(input.summary, "summary");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
@@ -726,6 +766,10 @@ export function blockFlowRunStage(context, input) {
     const stageRun = index.stage_runs.find((item) => item.stage === stage);
     if (!stageRun || stageRun.status !== "running")
         throw new AppError("invalid_stage_state", "Only a running stage can be blocked", 1, { run_id: run.id, stage, status: stageRun?.status ?? "missing" });
+    return { project, run, index, stage, stageRun };
+}
+export function blockFlowRunStage(context, input, prepared = prepareFlowRunStageBlock(context, input)) {
+    const { project, run, index, stage, stageRun } = prepared;
     const now = context.now();
     stageRun.status = "blocked";
     stageRun.updated_at = now;
@@ -743,7 +787,7 @@ export function blockFlowRunStage(context, input) {
     return { run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
 }
 /** Continue the same stage after its non-user blocker was repaired externally. */
-export function unblockFlowRunStage(context, input) {
+export function prepareFlowRunStageUnblock(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
@@ -752,8 +796,11 @@ export function unblockFlowRunStage(context, input) {
     const stageRun = index.stage_runs.find((item) => item.stage === stage);
     if (!stageRun || stageRun.status !== "blocked" || !stageRun.blocker || stageRun.blocker.work_id !== input.workId)
         throw new AppError("invalid_stage_state", "Stage unblock requires its matching runtime blocker", 1, { run_id: run.id, stage, work_id: input.workId, status: stageRun?.status ?? "missing" });
+    return { project, run, index, stage, stageRun, blocker: stageRun.blocker };
+}
+export function unblockFlowRunStage(context, input, prepared = prepareFlowRunStageUnblock(context, input)) {
+    const { project, run, index, stage, stageRun, blocker } = prepared;
     const now = context.now();
-    const blocker = stageRun.blocker;
     const blockedMs = durationMs(blocker.blocked_at, now) ?? 0;
     stageRun.status = "running";
     stageRun.updated_at = now;
@@ -793,12 +840,20 @@ export function setFlowRunRecoveryPaused(context, projectId, runId, paused) {
     const project = requireProjectByRoot(context, run.project_root);
     persistRunState(context, project, run, index);
 }
-export function completeFlowRun(context, input) {
+export function prepareFlowRunCompletion(context, input) {
+    if (input.manualOverrideReason !== undefined) {
+        requiredPlain(input.manualOverrideReason, "override reason");
+        if (!["cancelled", "failed"].includes(input.status))
+            throw new AppError("validation", "Manual RUN override may only cancel or fail a RUN", 2);
+    }
+    if (input.verdict !== undefined)
+        requiredPlain(input.verdict, "verdict");
+    if (input.nextAction !== undefined)
+        requiredPlain(input.nextAction, "next action");
     const project = requireProjectByRoot(context, input.manualOverrideReason ? canonicalPath(input.projectRoot, false) : resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
-    const now = context.now();
     const status = parseRunStatus(input.status);
     if (!['done', 'cancelled', 'failed'].includes(status)) {
         throw new AppError('validation', 'completeFlowRun accepts only done, cancelled, or failed; use stage block/unblock for a recoverable blocker', 2, { status });
@@ -808,6 +863,11 @@ export function completeFlowRun(context, input) {
         if (activeWork)
             throw new AppError("active_work", "RUN cannot complete while Work remains active", 2, { run_id: run.id, work_id: activeWork.work_id, status: activeWork.status });
     }
+    return { project, run, index, status };
+}
+export function completeFlowRun(context, input) {
+    const { project, run, index, status } = prepareFlowRunCompletion(context, input);
+    const now = context.now();
     if (input.manualOverrideReason && (status === "cancelled" || status === "failed")) {
         closeOpenStagesForOverride(index, status, now);
         closeOpenWorksForOverride(context, project.id, run.id, status, now);
@@ -1273,11 +1333,15 @@ function materializedRunVariables(index) {
         ...(index.variables ?? {})
     };
 }
-function setRunVariable(context, input, value) {
+function prepareRunVariable(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
+    return { project, run, index };
+}
+function setRunVariable(context, input, value, prepared = prepareRunVariable(context, input)) {
+    const { project, run, index } = prepared;
     if (index.variables?.[input.key] === value)
         return { ok: true, run_id: run.id, key: input.key, value, idempotent: true };
     index.variables = { ...(index.variables ?? {}), [input.key]: value };
@@ -1328,10 +1392,12 @@ function readRuntimeSnapshot(file) {
 function authoritativeIndex(run) {
     try {
         const state = JSON.parse(run.index_json);
+        if (!state || typeof state !== "object" || Array.isArray(state) || !Array.isArray(state.stage_runs))
+            throw new Error("RUN index must contain stage_runs");
         return { ...state, schema_id: runSchemaId };
     }
     catch (error) {
-        throw new AppError("validation", "RUN mechanical state in SQLite is missing or invalid", 2, { run_id: run.id, cause: String(error) });
+        throw new AppError("runtime_state_invalid", "RUN mechanical state in SQLite is missing or invalid", 1, { run_id: run.id, cause: String(error) });
     }
 }
 function sanitizeTimelineValue(value, key) {
@@ -1486,7 +1552,7 @@ function parseStageStatus(value) {
     }
     return value;
 }
-function requiredStageDir(value) {
+export function prepareStageDirectory(value) {
     const dir = requiredPlain(value, "dir");
     if (!/^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(dir)) {
         throw new AppError("validation", "--dir must use NN-stage-slug format", 2, { dir });
@@ -1494,6 +1560,8 @@ function requiredStageDir(value) {
     return dir;
 }
 function requiredPlain(value, label) {
+    if (typeof value !== "string")
+        throw new AppError("validation", `${label} must be a string`, 2);
     const trimmed = value.trim();
     if (!trimmed) {
         throw new AppError("validation", `${label} must not be empty`, 2);
@@ -1501,6 +1569,8 @@ function requiredPlain(value, label) {
     return trimmed;
 }
 function normalizeSlug(value) {
+    if (typeof value !== "string")
+        throw new AppError("validation", "--slug must be a string", 2);
     const slug = value
         .normalize("NFKD")
         .replace(/[\u0300-\u036f]/g, "")
@@ -1518,6 +1588,8 @@ function resolveWorkspaceRoot(workspaceRoot) {
     if (!fs.existsSync(absolute)) {
         throw new AppError("not_found", `Workspace root does not exist: ${absolute}`, 1);
     }
+    if (!fs.statSync(absolute).isDirectory())
+        throw new AppError("validation", "Workspace root must be a directory", 2, { workspace_root: absolute });
     return fs.realpathSync(absolute);
 }
 /** Move one completed stage attempt and update only known durable path columns.

package/dist/services/runtime-budget.js

@@ -1,28 +1,49 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
 import { setTimeout as delay } from "node:timers/promises";
-import { getResourceDatabase } from "../storage/database.js";
+import { getResourceDatabase, withResourceReadSnapshot } from "../storage/database.js";
 import { AppError } from "../shared/errors.js";
 import { harnessKey } from "./harness-config.js";
 import { managedProcessBinding, resourceHome, processIsAlive } from "./managed-processes.js";
 import { recoveryRuntimeAdmission } from "./run-recovery-runtime.js";
+import { prepareTextFile, prepareJsonFile, prepareError } from "../cli/input-preparation.js";
 const digest = (value) => crypto.createHash("sha256").update(value).digest("hex");
 export function validateRuntimeScopeManifest(value, scopeId) {
     const item = value;
     if (!item || typeof item !== "object" || Array.isArray(item) || Object.keys(item).some(key => !["schema_id", "scope_id", "manifest_path", "manifest_sha256", "execution_ids"].includes(key)) || item.schema_id !== "dd-flow/runtime-scope-manifest@1" || item.scope_id !== scopeId || typeof item.manifest_path !== "string" || !path.isAbsolute(item.manifest_path) || typeof item.manifest_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(item.manifest_sha256) || !Array.isArray(item.execution_ids) || item.execution_ids.some(id => typeof id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(id)) || new Set(item.execution_ids).size !== item.execution_ids.length)
         throw new AppError("runtime_scope_manifest_invalid", "Scope manifest requires frozen source identity and unique execution IDs", 2);
-    const bytes = fs.readFileSync(item.manifest_path, "utf8");
+    const bytes = prepareTextFile(item.manifest_path, "scope manifest").text;
     if (digest(bytes) !== item.manifest_sha256)
         throw new AppError("runtime_scope_manifest_changed", "EVAL manifest no longer matches its frozen identity", 1);
-    const source = JSON.parse(bytes);
+    let source;
+    try {
+        source = JSON.parse(bytes);
+    }
+    catch {
+        throw new AppError("runtime_scope_manifest_corrupt", "Retained EVAL manifest contains invalid JSON", 1);
+    }
+    if (!source || typeof source !== "object" || Array.isArray(source))
+        throw new AppError("runtime_scope_manifest_corrupt", "Retained EVAL manifest must be an object", 1);
     if (source.run_id !== scopeId || !Array.isArray(source.executions) || JSON.stringify(source.executions.map(execution => execution?.id)) !== JSON.stringify(item.execution_ids))
         throw new AppError("runtime_scope_manifest_invalid", "Scope execution inventory does not match the retained EVAL manifest", 2);
-    return { schema_id: item.schema_id, scope_id: scopeId, manifest_path: item.manifest_path, manifest_sha256: item.manifest_sha256, execution_ids: item.execution_ids };
+    return { schema_id: item.schema_id, scope_id: scopeId, manifest_path: item.manifest_path, manifest_sha256: item.manifest_sha256, execution_ids: [...item.execution_ids] };
 }
 export function publicRuntimeScopeWorker(worker) {
     return { status: worker.status, generation: worker.generation, process_id: worker.process_id ?? null, owner_pid: worker.owner?.pid ?? null, error: worker.error ?? null, snapshot: worker.snapshot ?? null };
 }
+/** Captured manifests are runtime authority, not a fresh CLI argument. */
+export function validateRetainedRuntimeScopeManifest(value, scopeId) {
+    try {
+        return validateRuntimeScopeManifest(value, scopeId);
+    }
+    catch (error) {
+        if (error instanceof AppError && error.exitCode === 2)
+            throw new AppError("runtime_scope_manifest_corrupt", "Retained scope manifest is invalid or unavailable", 1, { scope_id: scopeId, cause_code: error.code });
+        throw error;
+    }
+}
 /** Prepared native owners cannot send the first recovery Turn until the scope
  * arbiter publishes their exact release. Fence disappearance alone is not ACK. */
 export async function waitForRuntimeScopeRecovery(context, input, assertOwner) {
@@ -63,30 +84,56 @@ export async function waitForRuntimeScopeRecovery(context, input, assertOwner) {
 }
 /** Admission intent only. A persisted request is not physical settlement.
  * The resource registry arbitrates all runtime homes in the selected EVAL. */
-export function requestRuntimeScopeControl(context, scopeId, requestId, mode, manifest) {
-    parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: scopeId, per_harness: {} }));
-    if (!requestId || requestId.length > 256 || !["pause", "stop"].includes(mode))
-        throw new AppError("runtime_budget_invalid", "Scope control requires a bounded request identity and pause or stop", 2);
+export function prepareRuntimeScopeControl(scopeId, requestId, mode, manifest, context) {
+    prepareRuntimeScopeFence(scopeId, requestId);
+    if (!["pause", "stop"].includes(mode))
+        throw new AppError("runtime_budget_invalid", "Scope control requires pause or stop", 2);
+    const file = context && path.join(resourceHome(context), "runtime.sqlite");
+    if (file && fs.existsSync(file)) {
+        const db = new DatabaseSync(file, { readOnly: true });
+        try {
+            db.exec("PRAGMA busy_timeout = 4000");
+            // Another process may have created the file but not its first schema yet.
+            // No table means no retained receipt; execute rechecks after initialization.
+            const ready = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'managed_resources'").get();
+            const prior = ready ? db.prepare("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-request' AND resource_key = ?").get(digest(JSON.stringify([scopeId, requestId]))) : undefined;
+            if (prior)
+                return { receipt: scopeControlReceipt(prior.metadata_json, mode) };
+        }
+        finally {
+            db.close();
+        }
+    }
+    return { manifest: manifest === undefined ? undefined : validateRuntimeScopeManifest(manifest, scopeId) };
+}
+function scopeControlReceipt(json, mode) {
+    const receipt = JSON.parse(json);
+    if (receipt.requested_mode !== mode)
+        throw new AppError("runtime_scope_control_conflict", "Scope request identity was already used for another mode", 1);
+    return receipt;
+}
+export function requestRuntimeScopeControl(context, scopeId, requestId, mode, manifest, prepared = prepareRuntimeScopeControl(scopeId, requestId, mode, manifest, context)) {
+    if (prepared.receipt)
+        return prepared.receipt;
+    const declaration = prepared.manifest;
     const db = getResourceDatabase(resourceHome(context));
     const requestKey = digest(JSON.stringify([scopeId, requestId]));
     db.beginWriteTransaction();
     try {
-        if (manifest !== undefined) {
-            const declaration = validateRuntimeScopeManifest(manifest, scopeId), payload = JSON.stringify(declaration);
+        const prior = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-request' AND resource_key = ?", [requestKey]);
+        if (prior) {
+            const receipt = scopeControlReceipt(prior.metadata_json, mode);
+            db.exec("COMMIT");
+            return receipt;
+        }
+        if (declaration !== undefined) {
+            const payload = JSON.stringify(declaration);
             const saved = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-manifest' AND resource_key = ?", [scopeId]);
             if (saved && saved.metadata_json !== payload)
                 throw new AppError("runtime_scope_manifest_changed", "Scope already belongs to another frozen EVAL manifest", 1);
             if (!saved)
                 db.run("INSERT INTO managed_resources (resource_kind,resource_key,owner_id,lease_token,lease_expires_at,process_id,metadata_json,created_at,updated_at) VALUES ('scope-manifest',?,?,?,?,NULL,?,?,?)", [scopeId, scopeId, declaration.manifest_sha256, context.now(), payload, context.now(), context.now()]);
         }
-        const prior = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-request' AND resource_key = ?", [requestKey]);
-        if (prior) {
-            const receipt = JSON.parse(prior.metadata_json);
-            if (receipt.requested_mode !== mode)
-                throw new AppError("runtime_scope_control_conflict", "Scope request identity was already used for another mode", 1);
-            db.exec("COMMIT");
-            return receipt;
-        }
         if (db.get("SELECT 1 FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [scopeId]))
             throw new AppError("runtime_scope_stopped", "Terminal EVAL cancellation cannot become recoverable control", 1);
         const current = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
@@ -130,31 +177,43 @@ export function scopeLocalProcessRole(record) {
 }
 /** Local checks and EVAL observers share the scope fence, not provider capacity. */
 export function admitRuntimeCheck(context, id, leaseToken) {
-    const db = getResourceDatabase(resourceHome(context));
-    db.beginWriteTransaction();
+    if (typeof id !== "string" || !id.trim() || typeof leaseToken !== "string" || !leaseToken.trim())
+        throw new AppError("validation", "Check admission requires a process ID and lease token", 2);
+    const db = getResourceDatabase(resourceHome(context), "read_existing");
     try {
-        const record = db.get("SELECT * FROM managed_processes WHERE id = ?", [id]);
+        // One statement observes the owner and both admission fences together,
+        // without taking a writer lock or initializing an absent registry.
+        const record = db.get(`SELECT p.*,
+      EXISTS(SELECT 1 FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = json_extract(p.metadata_json, '$.budget.scope_id')) AS scope_fenced,
+      (SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = json_extract(p.metadata_json, '$.budget.scope_id')) AS scope_control
+      FROM managed_processes p WHERE p.id = ?`, [id]);
         if (!record || record.lease_token !== leaseToken || !["eval-baseline", "eval-observer", "check"].includes(record.kind) || record.state !== "running" || !processIsAlive(record))
             throw new AppError("process_ownership_unknown", "Local process requires its confirmed live owner", 1);
-        const metadata = JSON.parse(record.metadata_json);
-        const budget = parseRuntimeBudget(metadata.budget ? JSON.stringify(metadata.budget) : undefined);
-        if (!budget || (record.kind !== "check" ? scopeLocalProcessRole(record) === null : metadata.role !== "check" || !record.check_id))
-            throw new AppError("runtime_budget_invalid", "Local process requires a retained EVAL scope and operation", 2);
-        assertScopeAdmission(context, budget.scope_id);
-        db.exec("COMMIT");
+        let budget;
+        try {
+            const metadata = JSON.parse(record.metadata_json);
+            const retained = parseRuntimeBudget(metadata.budget ? JSON.stringify(metadata.budget) : undefined);
+            if (!retained || (record.kind !== "check" ? scopeLocalProcessRole(record) === null : metadata.role !== "check" || !record.check_id))
+                throw new Error("Missing retained EVAL scope or operation");
+            budget = retained;
+        }
+        catch (error) {
+            throw new AppError("runtime_artifact_invalid", "Local process has invalid retained scope or operation metadata", 1, { process_id: record.id, cause: String(error) });
+        }
+        if (record.scope_fenced)
+            throw new AppError("runtime_scope_stopped", "This runtime scope no longer admits productive dispatch", 1, { scope_id: budget.scope_id });
+        if (record.scope_control)
+            throw new AppError("runtime_scope_controlled", "This runtime scope is under operator control", 1, { control: JSON.parse(record.scope_control) });
         return { admitted: true, process_id: record.id, scope_id: budget.scope_id };
     }
-    catch (error) {
-        db.exec("ROLLBACK");
-        throw error;
+    finally {
+        db.close?.();
     }
 }
 /** Scope selection uses retained registration, never a current profile or PID search. */
 export function runtimeBudgetStatus(context, scopeId) {
     parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: scopeId, per_harness: {} }));
-    const db = getResourceDatabase(resourceHome(context));
-    db.exec("SAVEPOINT runtime_scope_status");
-    try {
+    return withResourceReadSnapshot(resourceHome(context), db => {
         const fence = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [scopeId]);
         const control = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
         const processes = db.all("SELECT * FROM managed_processes WHERE json_extract(metadata_json, '$.budget.scope_id') = ? ORDER BY id", [scopeId]);
@@ -173,21 +232,18 @@ export function runtimeBudgetStatus(context, scopeId) {
         const worker = workerGeneration ? db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ?", [digest(JSON.stringify([scopeId, workerGeneration]))]) : null;
         const drain = intent ? db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-drain' AND resource_key = ?", [digest(JSON.stringify([scopeId, intent.generation]))]) : null;
         const result = { scope_id: scopeId, dispatch_blocked: Boolean(fence || control), fence: fence ? JSON.parse(fence.metadata_json) : null, control: intent, worker: worker ? publicRuntimeScopeWorker(JSON.parse(worker.metadata_json)) : null, drain: drain ? JSON.parse(drain.metadata_json) : null, manifest: manifest ? JSON.parse(manifest.metadata_json) : null, resume: resume ? { ...resume, dispatch_blocked: Boolean(fence || control), current: resume.status === "released" ? releaseCurrent : !fence && intent?.generation === resume.generation } : null, release: release ? { ...release, current: releaseCurrent } : null, processes, provider_turns: providerTurns };
-        db.exec("RELEASE runtime_scope_status");
         return result;
-    }
-    catch (error) {
-        db.exec("ROLLBACK TO runtime_scope_status");
-        db.exec("RELEASE runtime_scope_status");
-        throw error;
-    }
+    });
 }
 /** Persist admission shutdown independently of client/process lease expiry.
  * This is a dispatch fence, not evidence that the existing native tree stopped. */
-export function fenceRuntimeBudget(context, scopeId, requestId) {
+export function prepareRuntimeScopeFence(scopeId, requestId) {
     parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: scopeId, per_harness: {} }));
-    if (!requestId || requestId.length > 256)
-        throw new AppError("runtime_budget_invalid", "Scope fence requires a bounded request identity", 2);
+    if (typeof requestId !== "string" || !requestId.trim() || requestId.length > 256)
+        throw new AppError("runtime_budget_invalid", "Scope control requires a nonempty request identity of at most 256 characters", 2);
+}
+export function fenceRuntimeBudget(context, scopeId, requestId) {
+    prepareRuntimeScopeFence(scopeId, requestId);
     const db = getResourceDatabase(resourceHome(context));
     db.beginWriteTransaction();
     try {
@@ -323,9 +379,25 @@ function scopeRecoveryLoadAllowed(context, scopeId, record, input) {
       AND json_extract(o.input_json, '$.request_id') = ? AND json_extract(o.input_json, '$.control_id') = ctl.control_id`, [source.control_id, record.owner_id, record.project_id, record.run_id, source.recovery_id, source.resume_request_id]);
     return Boolean(prepared) && recoveryRuntimeAdmission(context, record, { stateDir: metadata.state_dir, daemonId: input.daemonId, operationId: input.operationId, operation: input.operation, nativeSessionId: input.sessionId });
 }
-/** Release uses the daemon's durable reply or fresh whole-tree observation.
- * Unknown/error replies and client timeouts are deliberately not release proof. */
-export function releaseProviderTurns(context, record, input) {
+export function prepareProviderTurnRelease(input) {
+    if (Boolean(input.operationId) === Boolean(input.observationFile))
+        return prepareError(new AppError("usage", "Provide exactly one of --operation-id or --observation-file", 2));
+    if (!input.observationFile)
+        return { observation: null };
+    // This file is a retained daemon receipt, not model-authored input. Broken
+    // receipt syntax/schema is infrastructure failure, never a retryable typo.
+    let observed;
+    try {
+        observed = prepareJsonFile(input.observationFile, "budget observation").value;
+    }
+    catch {
+        throw new AppError("runtime_budget_evidence_invalid", "Cannot read valid JSON from the daemon budget observation", 1);
+    }
+    if (!observed || typeof observed !== "object" || Array.isArray(observed) || typeof observed.daemon_id !== "string" || typeof observed.session_id !== "string" || !observed.session_id || typeof observed.settled !== "boolean" || !Array.isArray(observed.operation_ids) || observed.operation_ids.some(id => typeof id !== "string" || !id))
+        throw new AppError("runtime_budget_evidence_invalid", "Budget observation has an invalid receipt shape", 1);
+    return { observation: observed };
+}
+export function releaseProviderTurns(context, record, input, prepared = prepareProviderTurnRelease(input)) {
     const metadata = JSON.parse(record.metadata_json);
     if (!metadata.state_dir)
         throw new AppError("process_ownership_unknown", "Budget release has no retained state directory", 1);
@@ -338,8 +410,8 @@ export function releaseProviderTurns(context, record, input) {
         const parent = path.resolve(metadata.state_dir, "budget-observations");
         if (path.dirname(path.resolve(input.observationFile)) !== parent)
             throw new AppError("runtime_budget_evidence_invalid", "Budget observation is outside its daemon directory", 2);
-        const observed = JSON.parse(fs.readFileSync(input.observationFile, "utf8"));
-        if (observed.daemon_id !== input.daemonId || observed.settled !== true || typeof observed.session_id !== "string" || !observed.session_id || !Array.isArray(observed.operation_ids) || observed.operation_ids.some(id => typeof id !== "string" || !id))
+        const observed = prepared.observation;
+        if (!observed || observed.daemon_id !== input.daemonId || observed.settled !== true)
             throw new AppError("runtime_budget_evidence_invalid", "Budget release requires fresh settled Session evidence", 1);
         sessionId = observed.session_id;
         operationIds = observed.operation_ids;

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

@@ -4,7 +4,7 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { getResourceDatabase } from "../storage/database.js";
 import { resourceHome } from "./managed-processes.js";
-import { validateRuntimeScopeManifest } from "./runtime-budget.js";
+import { validateRetainedRuntimeScopeManifest } from "./runtime-budget.js";
 /** Archive a complete append-only prefix, not a claim that no later evidence
  * can arrive. The caller holds the registry transaction; never take the EVAL
  * journal lock here (its writer may itself be waiting for the registry).
@@ -34,7 +34,7 @@ export function captureScopeJournal(context, control, manifest) {
     if (request?.data?.request_id !== control.request_id || request.data.mode !== control.requested_mode)
         throw new AppError("runtime_scope_control_superseded", "EVAL journal belongs to another control request", 1);
     const manifestBytes = fs.readFileSync(manifest.manifest_path, "utf8");
-    validateRuntimeScopeManifest(manifest, control.scope_id);
+    validateRetainedRuntimeScopeManifest(manifest, control.scope_id);
     const hash = (value) => crypto.createHash("sha256").update(value).digest("hex");
     if (hash(manifestBytes) !== manifest.manifest_sha256 || !fs.readFileSync(source).subarray(0, prefix.length).equals(prefix))
         throw new AppError("runtime_scope_journal_changed", "EVAL source changed during capture", 1);

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

@@ -5,7 +5,7 @@ import { createContext } from "../runtime/context.js";
 import { getResourceDatabase } from "../storage/database.js";
 import { AppError } from "../shared/errors.js";
 import { finishManagedProcess, managedLeaseReleased, managedProcessBinding, managedProcessStatus, processTreeIsAlive, resourceHome, stopManagedProcess } from "./managed-processes.js";
-import { requestRuntimeScopeControl, runtimeBudgetStatus, scopeLocalProcessRole, validateRuntimeScopeManifest } from "./runtime-budget.js";
+import { requestRuntimeScopeControl, runtimeBudgetStatus, scopeLocalProcessRole, validateRetainedRuntimeScopeManifest } from "./runtime-budget.js";
 import { nativeInventoryVersion, recordRunControlIntent, retainedDaemonOperations, runControlStatus } from "./run-control.js";
 import { requestRunControl } from "./run-control-worker.js";
 import { adapterSessionId } from "./harness-adapter.js";
@@ -92,7 +92,7 @@ export function retainScopeDrain(context, control, processes, runs, native, prob
         let manifest = null, journal = null, manifestReason = "scope_manifest_required";
         if (latest.manifest) {
             try {
-                manifest = validateRuntimeScopeManifest(latest.manifest, control.scope_id);
+                manifest = validateRetainedRuntimeScopeManifest(latest.manifest, control.scope_id);
                 journal = captureScopeJournal(context, control, manifest);
                 manifestReason = "scope_operation_reconciliation_required";
             }