@deksden-com/dd-flow-cli 0.9.0-beta.8 → 0.9.0-beta.81

package/dist/services/runtime-budget.js

@@ -0,0 +1,434 @@
+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, 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 = 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);
+    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] };
+}
+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) {
+    const db = getResourceDatabase(resourceHome(context));
+    for (;;) {
+        assertOwner();
+        const snapshot = (() => {
+            db.exec("SAVEPOINT scope_recovery_release");
+            try {
+                return {
+                    fence: db.get("SELECT 1 FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [input.scopeId]),
+                    latest: db.get("SELECT MAX(json_extract(metadata_json, '$.generation')) AS generation FROM managed_resources WHERE resource_kind = 'scope-control-request' AND owner_id = ?", [input.scopeId]),
+                    control: db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [input.scopeId]),
+                    release: db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-resume-release' AND resource_key = ?", [digest(JSON.stringify([input.scopeId, input.generation]))])
+                };
+            }
+            finally {
+                db.exec("RELEASE scope_recovery_release");
+            }
+        })();
+        if (snapshot.fence)
+            throw new AppError("runtime_scope_stopped", "Terminal cancellation superseded scope recovery", 1);
+        const { latest, control: row, release } = snapshot;
+        if (latest?.generation !== input.generation)
+            throw new AppError("runtime_scope_control_superseded", "Prepared recovery belongs to a retired EVAL generation", 1);
+        if (row) {
+            if (JSON.parse(row.metadata_json).generation !== input.generation)
+                throw new AppError("runtime_scope_control_superseded", "A newer EVAL control superseded prepared recovery", 1);
+            await delay(100);
+            continue;
+        }
+        const receipt = release ? JSON.parse(release.metadata_json) : null;
+        if (receipt?.scope_id !== input.scopeId || receipt.generation !== input.generation || !Array.isArray(receipt.run_operations) || !receipt.run_operations.some(item => item.runtime_home === context.ddFlowHome && item.controller_id === input.controllerId && item.operation_id === input.operationId))
+            throw new AppError("runtime_scope_release_unproven", "Prepared recovery has no matching atomic EVAL release", 1);
+        assertOwner();
+        return;
+    }
+}
+/** Admission intent only. A persisted request is not physical settlement.
+ * The resource registry arbitrates all runtime homes in the selected EVAL. */
+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 {
+        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()]);
+        }
+        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]);
+        const head = current ? JSON.parse(current.metadata_json) : null;
+        if (head?.requested_mode === "stop" && mode === "pause")
+            throw new AppError("runtime_scope_control_conflict", "Pause cannot weaken an existing stop", 1);
+        const retained = db.get("SELECT MAX(json_extract(metadata_json, '$.generation')) AS generation FROM managed_resources WHERE resource_kind = 'scope-control-request' AND owner_id = ?", [scopeId]);
+        const generation = Math.max(head?.generation ?? 0, retained?.generation ?? 0) + 1;
+        if (!Number.isSafeInteger(generation))
+            throw new AppError("runtime_scope_control_conflict", "Scope generation is exhausted", 1);
+        const now = context.now();
+        const receipt = { scope_id: scopeId, request_id: requestId, generation, requested_mode: mode, status: "requested", dispatch_blocked: true, requested_at: now };
+        const payload = JSON.stringify(receipt);
+        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-control-request',?,?,?,?,NULL,?,?,?)", [requestKey, scopeId, requestKey, now, payload, now, now]);
+        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-control',?,?,?,?,NULL,?,?,?) ON CONFLICT(resource_kind,resource_key) DO UPDATE SET lease_token = excluded.lease_token, metadata_json = excluded.metadata_json, updated_at = excluded.updated_at", [scopeId, scopeId, requestKey, now, payload, now, now]);
+        db.exec("COMMIT");
+        return receipt;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+function assertScopeAdmission(context, scopeId) {
+    const db = getResourceDatabase(resourceHome(context));
+    if (db.get("SELECT 1 FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [scopeId]))
+        throw new AppError("runtime_scope_stopped", "This runtime scope no longer admits productive dispatch", 1, { scope_id: scopeId });
+    const control = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
+    if (control)
+        throw new AppError("runtime_scope_controlled", "This runtime scope is under operator control", 1, { control: JSON.parse(control.metadata_json) });
+}
+/** Local observers never inherit a Subject RUN, Session or provider turn slot. */
+export function scopeLocalProcessRole(record) {
+    const role = record.kind === "eval-baseline" ? "probe" : record.kind === "eval-observer" ? "observer" : null;
+    const metadata = JSON.parse(record.metadata_json);
+    if (!role || metadata.role !== role || metadata.state_dir || !record.operation_id)
+        return null;
+    if (role === "observer" && (record.owner_id !== metadata.budget?.scope_id || !record.operation_id.startsWith(`${record.owner_id}:observer:`) || !/^[a-f0-9]{64}$/.test(record.operation_id.slice(`${record.owner_id}:observer:`.length)) || record.project_id || record.run_id || record.work_id || record.check_id))
+        return null;
+    return role;
+}
+/** Local checks and EVAL observers share the scope fence, not provider capacity. */
+export function admitRuntimeCheck(context, id, leaseToken) {
+    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 {
+        // 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);
+        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 };
+    }
+    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: {} }));
+    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]);
+        const manifest = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-manifest' AND resource_key = ?", [scopeId]);
+        const resumeRow = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-resume' AND resource_key = ?", [scopeId]);
+        const resume = resumeRow ? JSON.parse(resumeRow.metadata_json) : null;
+        const releaseRow = resume?.status === "released" ? db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-resume-release' AND resource_key = ?", [digest(JSON.stringify([scopeId, resume.generation]))]) : null;
+        const release = releaseRow ? JSON.parse(releaseRow.metadata_json) : null;
+        const lastRequest = release ? db.get("SELECT MAX(json_extract(metadata_json, '$.generation')) AS generation FROM managed_resources WHERE resource_kind = 'scope-control-request' AND owner_id = ?", [scopeId]) : null;
+        const releaseCurrent = Boolean(release && !fence && !control && release.scope_id === scopeId && release.generation === resume.generation && release.request_id === resume.request_id && lastRequest?.generation === resume.generation);
+        // Retained turns remain obligations even after their process exits or its
+        // lease expires. Only explicit reconciliation releases them.
+        const providerTurns = db.all("SELECT resource_key, process_id, metadata_json FROM managed_resources WHERE resource_kind = 'provider-turn' AND json_extract(metadata_json, '$.scope_id') = ? ORDER BY resource_key", [scopeId]).map(row => ({ ...JSON.parse(row.metadata_json), turn_id: row.resource_key, process_id: row.process_id }));
+        const intent = control ? JSON.parse(control.metadata_json) : null;
+        const workerGeneration = intent?.generation ?? (releaseCurrent ? release.generation : null);
+        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 };
+        return result;
+    });
+}
+/** Persist admission shutdown independently of client/process lease expiry.
+ * This is a dispatch fence, not evidence that the existing native tree stopped. */
+export function prepareRuntimeScopeFence(scopeId, requestId) {
+    parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: scopeId, per_harness: {} }));
+    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 {
+        const existing = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [scopeId]);
+        const now = context.now();
+        const receipt = existing ? JSON.parse(existing.metadata_json)
+            : { scope_id: scopeId, request_id: requestId, dispatch_blocked: true, fenced_at: now };
+        if (!existing)
+            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 ('provider-fence',?,?,?,?,NULL,?,?,?)", [scopeId, scopeId, digest(requestId), now, JSON.stringify(receipt), now, now]);
+        db.exec("COMMIT");
+        return receipt;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+export function runtimeBudgetForRun(context, projectId, runId) {
+    const retained = context.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'run_controllers'")
+        ? context.db.get("SELECT manifest_json FROM run_controllers WHERE project_id = ? AND run_id = ? ORDER BY created_at DESC, controller_id DESC LIMIT 1", [projectId, runId]) : undefined;
+    if (!retained)
+        return parseRuntimeBudget(context.env.DD_FLOW_RUNTIME_BUDGET);
+    const manifest = JSON.parse(retained.manifest_json);
+    return parseRuntimeBudget(manifest.budget ? JSON.stringify(manifest.budget) : undefined);
+}
+export function parseRuntimeBudget(raw) {
+    if (raw === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new AppError("runtime_budget_invalid", "Runtime budget must be one JSON object", 2);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !["schema_id", "scope_id", "per_harness"].includes(key)) || value.schema_id !== "dd-flow/runtime-budget@1"
+        || typeof value.scope_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.scope_id) || !value.per_harness || typeof value.per_harness !== "object" || Array.isArray(value.per_harness))
+        throw new AppError("runtime_budget_invalid", "Runtime budget requires a stable scope and per-harness limits", 2);
+    const limits = {};
+    for (const [name, limit] of Object.entries(value.per_harness).sort(([left], [right]) => left.localeCompare(right))) {
+        const key = harnessKey(name);
+        if (name !== key || !Number.isSafeInteger(limit) || limit < 1 || limit > 1024)
+            throw new AppError("runtime_budget_invalid", "Budget keys must be canonical harness names and limits positive integers up to 1024", 2);
+        limits[key] = limit;
+    }
+    return { schema_id: "dd-flow/runtime-budget@1", scope_id: value.scope_id, per_harness: limits };
+}
+/** A host-registry transaction arbitrates all roots in this experiment, not
+ * just the CLI clients currently observing them. Expiry never frees a slot. */
+export function reserveProviderTurn(context, record, input) {
+    const metadata = JSON.parse(record.metadata_json);
+    const budget = parseRuntimeBudget(metadata.budget === undefined ? undefined : JSON.stringify(metadata.budget));
+    if (!budget)
+        return { admitted: true };
+    if (!metadata.harness || !metadata.state_dir || !input.operationId || !["session.create", "session.prompt", "session.start", "session.fork", "session.resume"].includes(input.operation))
+        throw new AppError("runtime_budget_invalid", "Budget admission requires a frozen harness and productive operation", 2);
+    const harness = harnessKey(metadata.harness), limit = budget.per_harness[harness] ?? 1;
+    const db = getResourceDatabase(resourceHome(context));
+    const key = digest(JSON.stringify([record.id, input.operationId]));
+    const policy = JSON.stringify(budget), now = context.now();
+    db.beginWriteTransaction();
+    try {
+        const current = db.get("SELECT * FROM managed_processes WHERE id = ?", [record.id]);
+        if (current?.lease_token !== record.lease_token || current.state !== "running")
+            throw new AppError("process_ownership_unknown", "Budget owner changed before admission", 1);
+        try {
+            assertScopeAdmission(context, budget.scope_id);
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || error.code !== "runtime_scope_controlled" || !scopeRecoveryLoadAllowed(context, budget.scope_id, record, input))
+                throw error;
+        }
+        const frozen = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'provider-budget' AND resource_key = ?", [budget.scope_id]);
+        if (frozen && frozen.metadata_json !== policy)
+            throw new AppError("runtime_budget_conflict", "This experiment already froze different concurrency limits", 1);
+        if (!frozen)
+            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 ('provider-budget', ?, ?, ?, ?, NULL, ?, ?, ?)", [budget.scope_id, budget.scope_id, digest(policy), now, policy, now, now]);
+        const prior = db.get("SELECT resource_key, metadata_json, lease_token FROM managed_resources WHERE resource_kind = 'provider-turn' AND resource_key = ?", [key]);
+        if (prior) {
+            if (prior.lease_token !== record.lease_token)
+                throw new AppError("process_ownership_unknown", "Retained budget claim belongs to another physical owner", 1);
+            db.exec("COMMIT");
+            return { admitted: true, budget_scope: budget.scope_id, reused: true };
+        }
+        const active = db.get("SELECT count(*) AS count FROM managed_resources WHERE resource_kind = 'provider-turn' AND json_extract(metadata_json, '$.scope_id') = ? AND json_extract(metadata_json, '$.harness') = ?", [budget.scope_id, harness]).count;
+        if (active >= limit) {
+            db.exec("COMMIT");
+            return { admitted: false, reason: "provider_capacity", budget_scope: budget.scope_id, harness, limit, active };
+        }
+        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 ('provider-turn', ?, ?, ?, ?, ?, ?, ?, ?)", [key, record.owner_id, record.lease_token, record.lease_expires_at, record.id, JSON.stringify({ scope_id: budget.scope_id, harness, operation_id: input.operationId, operation: input.operation, session_id: input.sessionId ?? null, state_dir: metadata.state_dir }), now, now]);
+        db.exec("COMMIT");
+        return { admitted: true, budget_scope: budget.scope_id, harness, limit, active: active + 1 };
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+function scopeRecoveryLoadAllowed(context, scopeId, record, input) {
+    const metadata = JSON.parse(record.metadata_json);
+    if (input.operation !== "session.resume" || !input.daemonId || !metadata.state_dir || metadata.dd_flow_home !== context.ddFlowHome || !processIsAlive(record))
+        return false;
+    const db = getResourceDatabase(resourceHome(context));
+    const control = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
+    const row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-resume' AND resource_key = ?", [scopeId]);
+    const intent = row ? JSON.parse(row.metadata_json) : null;
+    if (!control || intent?.scope_id !== scopeId || intent.generation !== JSON.parse(control.metadata_json).generation || intent.status !== "preparing" || !Array.isArray(intent.runs))
+        return false;
+    if (!record.run_id) {
+        const loadRow = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-resume-native-load' AND resource_key = ?", [input.operationId]);
+        const load = loadRow ? JSON.parse(loadRow.metadata_json) : null;
+        if (!load || load.scope_id !== scopeId || load.generation !== intent.generation || load.request_id !== intent.request_id || load.status !== "dispatching" || load.process_id !== record.id || load.daemon_id !== input.daemonId || load.session_id !== input.sessionId)
+            return false;
+        const source = intent.native?.find((item) => item.process_id === load.source_process_id);
+        if (!source || source.state_dir !== metadata.state_dir || source.runtime_owner?.owner_id !== record.owner_id || !source.sessions?.some((item) => item.session_id === input.sessionId))
+            return false;
+        const parentRow = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-resume-native' AND resource_key = ?", [digest(JSON.stringify([scopeId, intent.generation, source.process_id]))]);
+        const parent = parentRow ? JSON.parse(parentRow.metadata_json) : null;
+        return parent?.status === "restarted" && parent.restart_receipt?.daemon_id === input.daemonId && JSON.stringify(parent.replacement_binding) === JSON.stringify(managedProcessBinding(record, resourceHome(context)));
+    }
+    if (!record.project_id)
+        return false;
+    const source = intent.runs.find((run) => run.runtime_home === context.ddFlowHome && run.project_id === record.project_id && run.run_id === record.run_id);
+    if (!source || !context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'run_controller_operations'"))
+        return false;
+    const prepared = context.db.get(`SELECT 1 FROM run_controller_operations o
+    JOIN run_controllers c ON c.controller_id = o.controller_id
+    JOIN run_controls ctl ON ctl.control_id = ? AND ctl.project_id = c.project_id AND ctl.run_id = c.run_id
+    JOIN run_recovery_guards g ON g.recovery_id = ctl.recovery_id
+    WHERE c.controller_id = ? AND c.project_id = ? AND c.run_id = ? AND c.generation = g.generation
+      AND o.generation = g.generation AND o.status = 'accepted' AND ctl.status = 'resuming' AND g.status = 'resuming'
+      AND ctl.recovery_id = ? AND json_extract(o.input_json, '$.action') = 'control_resume'
+      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 });
+}
+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);
+    const state = JSON.parse(fs.readFileSync(path.join(metadata.state_dir, "daemon.json"), "utf8"));
+    if ((state.daemon_id ?? state.config?.daemonId) !== input.daemonId || state.resource_process?.id !== record.id || state.resource_process.lease_token !== record.lease_token)
+        throw new AppError("process_ownership_unknown", "Budget release belongs to another daemon generation", 1);
+    let sessionId = null;
+    let operationIds;
+    if (input.observationFile) {
+        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 = 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;
+    }
+    else {
+        if (!input.operationId)
+            throw new AppError("runtime_budget_evidence_invalid", "Budget release requires an operation or observation", 2);
+        const directory = path.join(metadata.state_dir, "operations", digest(input.operationId));
+        const requested = JSON.parse(fs.readFileSync(path.join(directory, "requested.json"), "utf8"));
+        const result = JSON.parse(fs.readFileSync(path.join(directory, "result.json"), "utf8"));
+        if (requested.daemon_id !== input.daemonId || requested.operation_id !== input.operationId || !["session.create", "session.fork"].includes(requested.operation ?? "") || result.state !== "completed")
+            throw new AppError("runtime_budget_evidence_invalid", "Only a completed Session creation can release without a tree observation", 1);
+        operationIds = [input.operationId];
+    }
+    const db = getResourceDatabase(resourceHome(context));
+    let released = 0;
+    for (const operationId of operationIds)
+        released += db.run("DELETE FROM managed_resources WHERE resource_kind = 'provider-turn' AND process_id = ? AND lease_token = ? AND json_extract(metadata_json, '$.operation_id') = ? AND (? IS NULL OR json_extract(metadata_json, '$.session_id') = ?)", [record.id, record.lease_token, operationId, sessionId, sessionId]).changes;
+    return { ok: true, released };
+}

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

@@ -0,0 +1,50 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { getResourceDatabase } from "../storage/database.js";
+import { resourceHome } from "./managed-processes.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).
+ */
+export function captureScopeJournal(context, control, manifest) {
+    const source = path.join(path.dirname(manifest.manifest_path), "events.jsonl");
+    const bytes = fs.readFileSync(source), prefix = bytes.subarray(0, bytes.lastIndexOf(10) + 1), text = prefix.toString("utf8");
+    if (!prefix.length || !Buffer.from(text).equals(prefix))
+        throw new AppError("runtime_scope_journal_invalid", "EVAL journal has no complete valid UTF-8 prefix", 1);
+    const events = text.slice(0, -1).split("\n").map(line => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            throw new AppError("runtime_scope_journal_invalid", "EVAL journal contains a malformed complete record", 1);
+        }
+    });
+    let request;
+    for (const [index, event] of events.entries()) {
+        if (!event || event.specversion !== "1.0" || typeof event.id !== "string" || !event.id || event.runid !== control.scope_id || typeof event.type !== "string" || event.data?.sequence !== index + 1)
+            throw new AppError("runtime_scope_journal_invalid", "EVAL journal scope or sequence is inconsistent", 1);
+        if (event.type === "dev.dd.eval.cancel_requested")
+            throw new AppError("runtime_scope_control_superseded", "Terminal cancellation supersedes recoverable capture", 1);
+        if (event.type === "dev.dd.eval.control.requested")
+            request = event;
+    }
+    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");
+    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);
+    const sha256 = hash(prefix), key = hash(JSON.stringify([control.scope_id, control.generation, manifest.manifest_sha256, sha256]));
+    const payload = JSON.stringify({ scope_id: control.scope_id, generation: control.generation, manifest, manifest_bytes: manifestBytes, journal_source: source, journal_bytes: text });
+    const registry = getResourceDatabase(resourceHome(context));
+    const prior = registry.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-capture' AND resource_key = ?", [key]);
+    if (prior && prior.metadata_json !== payload)
+        throw new AppError("runtime_scope_capture_changed", "Retained EVAL capture no longer matches its content identity", 1);
+    if (!prior)
+        registry.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-control-capture',?,?,?,?,NULL,?,?,?)", [key, control.scope_id, key, context.now(), payload, context.now(), context.now()]);
+    return { artifact_key: key, source, sha256, byte_length: prefix.length, event_count: events.length, request_sequence: request.data.sequence, consistency: "append_only_prefix", trailing_bytes: bytes.length - prefix.length };
+}