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

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

@@ -6,7 +6,7 @@ import { createContext } from "../runtime/context.js";
 import { AppError } from "../shared/errors.js";
 import { getResourceDatabase } from "../storage/database.js";
 import { managedProcessBinding, processIsAlive, processTreeIsAlive, resourceHome } from "./managed-processes.js";
-import { runtimeBudgetStatus, scopeLocalProcessRole, validateRuntimeScopeManifest } from "./runtime-budget.js";
+import { runtimeBudgetStatus, scopeLocalProcessRole, validateRetainedRuntimeScopeManifest, prepareRuntimeScopeFence } from "./runtime-budget.js";
 import { nativeInventoryVersion, retainedDaemonOperations } from "./run-control.js";
 import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
 import { recordControllerResume, resumeRunController } from "./run-controller-recovery.js";
@@ -163,7 +163,7 @@ function publishScopeRelease(context, intent, runs, native) {
     const db = getResourceDatabase(resourceHome(context));
     if (runs.some(run => run.prepared !== true) || native.some(owner => owner?.prepared !== true))
         throw new AppError("runtime_scope_preparation_required", "Every owned RUN and native Session must be prepared", 1);
-    const manifest = validateRuntimeScopeManifest(intent.manifest, intent.scope_id);
+    const manifest = validateRetainedRuntimeScopeManifest(intent.manifest, intent.scope_id);
     const artifactRow = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-capture' AND resource_key = ?", [intent.capture_key]);
     const artifact = artifactRow ? JSON.parse(artifactRow.metadata_json) : null;
     const journal = path.join(path.dirname(manifest.manifest_path), "events.jsonl");
@@ -482,11 +482,14 @@ async function retireScopeNative(context, intent, source, assertCurrent) {
 }
 /** Freeze the preparation plan under the same arbiter as stop. This accepts
  * ownership work, not productive dispatch; only all-role release may unfence. */
-export function recordRuntimeScopeResume(context, input) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !Number.isSafeInteger(input.generation) || input.generation < 1 || !/^[a-f0-9]{64}$/.test(input.captureKey))
+export function prepareRuntimeScopeResumeInput(input) {
+    prepareRuntimeScopeFence(input.scopeId, input.requestId);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.requestId) || !Number.isSafeInteger(input.generation) || input.generation < 1 || typeof input.captureKey !== "string" || !/^[a-f0-9]{64}$/.test(input.captureKey))
         throw new AppError("runtime_scope_resume_invalid", "Scope resume requires its exact generation, capture and request identity", 2);
-    const db = getResourceDatabase(resourceHome(context)), key = hash(JSON.stringify([input.scopeId, input.requestId]));
-    db.beginWriteTransaction();
+}
+export function prepareRuntimeScopeResumeRequest(context, input) {
+    prepareRuntimeScopeResumeInput(input);
+    const db = getResourceDatabase(resourceHome(context), "read_existing"), key = hash(JSON.stringify([input.scopeId, input.requestId]));
     try {
         const latest = runtimeBudgetStatus(context, input.scopeId);
         const control = latest.control;
@@ -497,7 +500,6 @@ export function recordRuntimeScopeResume(context, input) {
                 throw new AppError("runtime_scope_resume_conflict", "Resume request identity was used for another source", 1);
             const active = latest.resume;
             const sameRequest = active?.generation === input.generation && active.request_id === input.requestId;
-            db.exec("COMMIT");
             return { ...receipt, ...(sameRequest ? active : {}), ...(sameRequest && active.status === "released" ? { release: latest.release } : {}), current: sameRequest && active.current === true, reused: true };
         }
         if (latest.fence || control?.generation !== input.generation)
@@ -509,7 +511,7 @@ export function recordRuntimeScopeResume(context, input) {
         const drain = drainRow ? JSON.parse(drainRow.metadata_json) : null;
         if (drain?.scope_id !== input.scopeId || drain.generation !== input.generation || drain.requested_mode !== control.requested_mode || drain.physical_settled !== true || drain.capture?.journal?.artifact_key !== input.captureKey || drain.capture.journal.trailing_bytes !== 0 || !Array.isArray(drain.capture.run_captures) || drain.capture.run_captures.some((run) => run.status !== "verified"))
             throw new AppError("runtime_scope_capture_required", "Resume requires a complete all-role drain and verified RUN captures", 1);
-        const manifest = validateRuntimeScopeManifest(drain.capture.manifest, input.scopeId);
+        const manifest = validateRetainedRuntimeScopeManifest(drain.capture.manifest, input.scopeId);
         if (JSON.stringify(manifest) !== JSON.stringify(latest.manifest))
             throw new AppError("runtime_scope_manifest_changed", "Resume scope manifest changed after capture", 1);
         const bindings = latest.processes.map(record => managedProcessBinding(record, resourceHome(context)));
@@ -530,12 +532,32 @@ export function recordRuntimeScopeResume(context, input) {
             throw new AppError("runtime_scope_journal_changed", "Resume requires the current immutable EVAL journal capture", 1);
         const runs = drain.capture.run_captures.map((run) => ({ ...run, resume_request_id: `scope-resume:${hash(JSON.stringify([input.scopeId, input.generation, input.requestId, run.runtime_home, run.project_id, run.run_id]))}` }));
         const receipt = { scope_id: input.scopeId, generation: input.generation, request_id: input.requestId, source_request_id: control.request_id, capture_key: input.captureKey, status: "preparing", dispatch_blocked: true, manifest, process_bindings: bindings, runs, native: drain.capture.native_bindings, probes: drain.capture.probe_operations, requested_at: context.now() };
-        const payload = JSON.stringify(receipt), now = context.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-resume-request',?,?,?,?,NULL,?,?,?)", [key, input.scopeId, key, 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-resume',?,?,?,?,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", [input.scopeId, input.scopeId, key, now, payload, now, now]);
-        db.exec("COMMIT");
         return { ...receipt, current: true, reused: false };
     }
+    finally {
+        db.close?.();
+    }
+}
+export function recordRuntimeScopeResume(context, input) {
+    const prepared = prepareRuntimeScopeResumeRequest(context, input);
+    if (prepared.reused)
+        return prepared;
+    const db = getResourceDatabase(resourceHome(context)), key = hash(JSON.stringify([input.scopeId, input.requestId]));
+    db.beginWriteTransaction();
+    try {
+        // Recheck mutable capture/ownership authority under the existing arbiter.
+        const result = prepareRuntimeScopeResumeRequest(context, input);
+        if (!result.reused) {
+            const receipt = { ...result };
+            delete receipt.current;
+            delete receipt.reused;
+            const payload = JSON.stringify(receipt), now = context.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-resume-request',?,?,?,?,NULL,?,?,?)", [key, input.scopeId, key, 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-resume',?,?,?,?,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", [input.scopeId, input.scopeId, key, now, payload, now, now]);
+        }
+        db.exec("COMMIT");
+        return result;
+    }
     catch (error) {
         db.exec("ROLLBACK");
         throw error;

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

@@ -7,7 +7,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { AppError } from "../shared/errors.js";
 import { getResourceDatabase } from "../storage/database.js";
 import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, processIsAlive, processStartedAt, registerManagedProcess, resourceHome } from "./managed-processes.js";
-import { publicRuntimeScopeWorker, requestRuntimeScopeControl, runtimeBudgetStatus } from "./runtime-budget.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";
 import { recoveryObservationBudget, renewRecoveryObservation, withRecoveryObservation } from "./recovery-observation-budget.js";
@@ -30,15 +30,29 @@ function birth() {
         throw new AppError("runtime_scope_owner_unknown", "Scope owner birth identity is unavailable", 1);
     return { pid: process.pid, pid_started_at: started };
 }
-export async function reconcileRuntimeScopeControl(context, scopeId, generation, requestId) {
-    const control = runtimeBudgetStatus(context, scopeId).control;
-    if (!control || control.generation !== generation)
-        throw new AppError("runtime_scope_control_superseded", "Reconciliation requires the current controlled scope generation", 1);
+export function prepareRuntimeScopeReconciliation(context, scopeId, generation, requestId) {
+    prepareRuntimeScopeFence(scopeId, requestId);
+    if (!Number.isSafeInteger(generation) || generation < 1)
+        throw new AppError("validation", "Scope reconciliation requires a positive integer generation", 2);
     renewRecoveryObservation({}, requestId);
+    const db = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        const row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
+        const control = row ? JSON.parse(row.metadata_json) : null;
+        if (!control || control.generation !== generation)
+            throw new AppError("runtime_scope_control_superseded", "Reconciliation requires the current controlled scope generation", 1);
+        return control;
+    }
+    finally {
+        db.close?.();
+    }
+}
+export async function reconcileRuntimeScopeControl(context, scopeId, generation, requestId) {
+    const control = prepareRuntimeScopeReconciliation(context, scopeId, generation, requestId);
     return launchRuntimeScopeControl(context, scopeId, control.request_id, control.requested_mode, undefined, requestId);
 }
-export async function launchRuntimeScopeControl(context, scopeId, requestId, mode, manifest, reconcileId, resumeId) {
-    const control = requestRuntimeScopeControl(context, scopeId, requestId, mode, manifest), db = getResourceDatabase(resourceHome(context)), key = keyFor(scopeId, control.generation);
+export async function launchRuntimeScopeControl(context, scopeId, requestId, mode, manifest, reconcileId, resumeId, prepared) {
+    const control = requestRuntimeScopeControl(context, scopeId, requestId, mode, manifest, prepared), db = getResourceDatabase(resourceHome(context)), key = keyFor(scopeId, control.generation);
     let worker;
     db.beginWriteTransaction();
     try {
@@ -103,19 +117,38 @@ export async function launchRuntimeScopeControl(context, scopeId, requestId, mod
     const retained = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ?", [key]);
     return { scope_id: scopeId, control, current: true, settled: false, worker: publicRuntimeScopeWorker(JSON.parse(retained.metadata_json)) };
 }
+export function prepareRuntimeScopeServing(context, scopeId, generation) {
+    parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: scopeId, per_harness: {} }));
+    if (!Number.isSafeInteger(generation) || generation < 1)
+        throw new AppError("validation", "Scope worker requires a positive integer generation", 2);
+    const token = context.env.DD_FLOW_SCOPE_CONTROL_TOKEN;
+    if (!token)
+        throw new AppError("runtime_scope_owner_unknown", "Scope worker requires its launch token", 1);
+    const key = keyFor(scopeId, generation), db = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        requireStartingScopeWorker(db, key, token);
+    }
+    finally {
+        db.close?.();
+    }
+    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]);
+    if (!row)
+        throw new AppError("runtime_scope_owner_unknown", "Scope worker claim changed", 1);
+    const worker = JSON.parse(row.metadata_json);
+    if (worker.owner || worker.status !== "starting")
+        throw new AppError("runtime_scope_already_owned", "Scope control already has a physical owner", 1);
+    return worker;
+}
 export async function serveRuntimeScopeControl(context, scopeId, generation) {
-    if (!Number.isSafeInteger(generation) || generation < 1 || !context.env.DD_FLOW_SCOPE_CONTROL_TOKEN)
-        throw new AppError("runtime_scope_owner_unknown", "Scope worker requires its launch token and generation", 1);
-    const db = getResourceDatabase(resourceHome(context)), key = keyFor(scopeId, generation), token = context.env.DD_FLOW_SCOPE_CONTROL_TOKEN;
+    const { key, token } = prepareRuntimeScopeServing(context, scopeId, generation);
+    const db = getResourceDatabase(resourceHome(context));
     let worker;
     db.beginWriteTransaction();
     try {
-        const 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);
-        worker = JSON.parse(row.metadata_json);
-        if (worker.owner || worker.status !== "starting")
-            throw new AppError("runtime_scope_already_owned", "Scope control already has a physical owner", 1);
+        worker = requireStartingScopeWorker(db, key, token);
         worker.owner = birth();
         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]);

package/dist/services/runtime-service.js

@@ -7,22 +7,23 @@ import { requireProjectByRoot } from "./projects.js";
 import { resolveRun } from "./runs.js";
 import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
 import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, processTreeIsAlive, registerManagedProcess, reservePorts, resourceHome, stopManagedProcess } from "./managed-processes.js";
-/** Foreground supervisor: the tool may yield while this command owns the service.
- * Its ready receipt is emitted immediately; a separate stop ends this command.
- * Readiness is infrastructure evidence, never a successful scenario verdict. */
-export async function startRuntimeService(context, input) {
+export function prepareRuntimeService(context, input) {
     if (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)
         throw new AppError("validation", "Readiness timeout must be positive and finite", 2);
-    if (!input.command.trim() || !input.ports.length || input.ports.some(name => !/^[a-z][a-z0-9_]*$/.test(name)) || new Set(input.ports).size !== input.ports.length || !input.ports.includes(input.readyPort) || !input.readyPath.startsWith("/") || input.readyPath.startsWith("//"))
+    if (typeof input.command !== "string" || !input.command.trim() || !Array.isArray(input.ports) || !input.ports.length || input.ports.some(name => typeof name !== "string" || !/^[a-z][a-z0-9_]*$/.test(name)) || new Set(input.ports).size !== input.ports.length || !input.ports.includes(input.readyPort) || typeof input.readyPath !== "string" || !input.readyPath.startsWith("/") || input.readyPath.startsWith("//"))
         throw new AppError("validation", "Declare unique lowercase port names, a ready-port from that list and a local /ready-path", 2);
     const project = requireProjectByRoot(context, path.resolve(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     if (!run?.run_root || !run.workspace_root)
         throw new AppError("not_found", "Registered RUN with a materialized workspace is required", 2);
-    input = { ...input, runId: run.id };
     const generation = assertRunMutationAllowed(context, project.id, run.id);
+    return { project, run, runHome: run.run_root, generation };
+}
+export async function startRuntimeService(context, input) {
+    const { project, run, runHome, generation } = prepareRuntimeService(context, input);
+    input = { ...input, runId: run.id };
     const id = `PROC-${crypto.randomUUID()}`;
-    const directory = path.join(run.run_root, "runtime", id);
+    const directory = path.join(runHome, "runtime", id);
     fs.mkdirSync(directory, { recursive: true });
     const record = registerManagedProcess(context, { id, kind: "runtime-service", ownerId: `run:${input.runId}`, ownerPid: process.pid, runId: input.runId, projectId: project.id, stdoutPath: path.join(directory, "stdout.log"), stderrPath: path.join(directory, "stderr.log"), metadata: { command: input.command } });
     const receiptPath = path.join(directory, "service.json");

package/dist/services/schema-validation.js

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

package/dist/services/sessions.js

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

package/dist/services/stage-blocker.js

@@ -1,19 +1,24 @@
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { blockFlowRunStage, unblockFlowRunStage } from "./runs.js";
+import { blockFlowRunStage, unblockFlowRunStage, prepareFlowRunStageBlock, prepareFlowRunStageUnblock } from "./runs.js";
 import { flowCommand } from "./stage-pause.js";
 import { refreshRunWorkProjection } from "./work-registry.js";
-export function blockStageForRuntime(context, input) {
+export function prepareStageRuntimeBlock(context, input) {
+    if (typeof input.code !== "string" || !input.code.trim() || typeof input.summary !== "string" || !input.summary.trim())
+        throw new AppError("validation", "stage block requires a code and summary", 2);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "running")
         throw new AppError("invalid_work_state", "Only a running Work can be blocked", 1, { work_id: work.work_id, status: work.status });
-    if (!input.code.trim() || !input.summary.trim())
-        throw new AppError("validation", "stage block requires a code and summary", 2);
-    const state = blockFlowRunStage(context, { ...input, projectRoot });
+    const flow = prepareFlowRunStageBlock(context, { ...input, projectRoot });
+    return { projectRoot, project, work, flow };
+}
+export function blockStageForRuntime(context, input) {
+    const { projectRoot, project, work, flow } = prepareStageRuntimeBlock(context, input);
+    const state = blockFlowRunStage(context, { ...input, projectRoot }, flow);
     const now = context.now();
     context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
     refreshRunWorkProjection(context, project.id, work.run_id);
@@ -30,14 +35,19 @@ export function blockStageForRuntime(context, input) {
         state
     };
 }
-export function unblockStageAfterRuntimeRepair(context, input) {
+export function prepareStageRuntimeUnblock(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "paused")
         throw new AppError("invalid_work_state", "stage unblock requires its paused Work", 1, { work_id: work.work_id, status: work.status });
-    const state = unblockFlowRunStage(context, { projectRoot, runId: work.run_id, stage: input.stage, workId: work.work_id });
+    const flow = prepareFlowRunStageUnblock(context, { ...input, projectRoot, runId: work.run_id });
+    return { projectRoot, project, work, flow };
+}
+export function unblockStageAfterRuntimeRepair(context, input) {
+    const { projectRoot, project, work, flow } = prepareStageRuntimeUnblock(context, input);
+    const state = unblockFlowRunStage(context, { projectRoot, runId: work.run_id, stage: input.stage, workId: work.work_id }, flow);
     const now = context.now();
     context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
     refreshRunWorkProjection(context, project.id, work.run_id);

package/dist/services/stage-context.js

@@ -2,33 +2,42 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
+import { prepareFileBytes, prepareJsonText, prepareOutputFile } from "../cli/input-preparation.js";
 export function loadExternalStageContext(input) {
-    const sourcePath = path.resolve(input.file);
-    if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isFile())
-        throw new AppError("not_found", "Stage context file is missing", 2, { context_file: sourcePath });
-    const bytes = fs.readFileSync(sourcePath);
+    const { file: sourcePath, bytes } = prepareFileBytes(input.file, "Stage context");
     const materializedSha256 = sha256(bytes);
     if (materializedSha256 !== input.expectedSha256)
         throw new AppError("context_checksum_mismatch", "Stage context checksum does not match --context-sha256", 2, { context_file: sourcePath, expected_sha256: input.expectedSha256, actual_sha256: materializedSha256 });
-    const value = parseJsonObject(bytes.toString("utf8"), "stage context");
+    const value = prepareJsonText(bytes.toString("utf8"), { file: sourcePath, label: "Stage context" }).value;
     validateContext(value, input.stage);
-    return { value, sourcePath, materializedSha256 };
+    return { value, sourcePath, materializedSha256, bytes };
 }
-/** Installs exactly one immutable external context for a stage attempt. */
-export function installExternalStageContext(input) {
-    fs.mkdirSync(input.stageRoot, { recursive: true });
+export function prepareExternalStageContext(input) {
+    const destination = externalStageContextDestination(input);
+    if (!fs.existsSync(destination))
+        prepareOutputFile(destination);
+    return destination;
+}
+function externalStageContextDestination(input) {
     const destination = path.join(input.stageRoot, "stage-context.json");
     if (fs.existsSync(destination)) {
         const existing = sha256(fs.readFileSync(destination));
         if (existing !== input.loaded.materializedSha256)
             throw new AppError("stage_context_replacement", "A different stage context is already installed for this Stage", 2, { stage_context: destination, expected_sha256: input.loaded.materializedSha256, actual_sha256: existing });
     }
-    else {
+    return destination;
+}
+/** Installs exactly one immutable external context for a stage attempt. */
+export function installExternalStageContext(input) {
+    // Publication may follow earlier effects. Recheck immutable identity here,
+    // but never reclassify a late output failure as a no-effect input rejection.
+    const destination = externalStageContextDestination(input);
+    fs.mkdirSync(input.stageRoot, { recursive: true });
+    if (!fs.existsSync(destination)) {
         // The receipt is the hash of the runner-materialized bytes, not of a
         // convenient reserialization.  Preserve those exact bytes as evidence.
         const temporary = `${destination}.${process.pid}.tmp`;
-        fs.copyFileSync(input.loaded.sourcePath, temporary);
+        fs.writeFileSync(temporary, input.loaded.bytes);
         fs.renameSync(temporary, destination);
     }
     return {
@@ -76,15 +85,32 @@ export function renderExternalStageContext(input) {
     ].join("\n");
 }
 function validateContext(value, expectedStage) {
+    const object = (item) => Boolean(item && typeof item === "object" && !Array.isArray(item));
+    const text = (item) => typeof item === "string" && Boolean(item.trim());
+    if (!object(value))
+        throw new AppError("validation", "Stage context must be an object", 2);
     if (value.schema_id !== "dd-flow/stage-context@1" && value.schema_id !== "dd-eval/stage-context@1")
         throw new AppError("validation", "Stage context must use dd-flow/stage-context@1", 2);
     if (value.stage !== expectedStage)
         throw new AppError("validation", "Stage context does not match --stage", 2, { expected_stage: expectedStage, context_stage: value.stage });
-    if (!value.objective?.trim())
+    if (!text(value.objective))
         throw new AppError("validation", "Stage context objective is required", 2);
-    for (const source of value.sources ?? []) {
-        if (!source.role?.trim() || !source.path?.trim() || !source.reason?.trim())
-            throw new AppError("validation", "Every stage context source needs role, path and reason", 2);
+    for (const key of ["task_input", "sources", "accepted_decisions", "dynamic_roles"]) {
+        if (value[key] === undefined)
+            continue;
+        if (!Array.isArray(value[key]))
+            throw new AppError("validation", `Stage context ${key} must be an array`, 2);
+        for (const item of value[key]) {
+            const valid = key === "accepted_decisions" ? text(item) || object(item) && (text(item.id) || text(item.statement)) && [item.id, item.statement].every(field => field === undefined || text(field))
+                : object(item) && text(item.role) && (key === "dynamic_roles" ? item.reason === undefined || text(item.reason)
+                    : text(item.path) && (key === "sources" ? text(item.reason) && (item.required === undefined || typeof item.required === "boolean") && (item.root === undefined || typeof item.root === "string" && ["project", "workspace", "run"].includes(item.root)) : item.sha256 === undefined || text(item.sha256)));
+            if (!valid)
+                throw new AppError("validation", `Invalid stage context ${key} item`, 2, { parameter: key });
+        }
+    }
+    for (const key of ["semantic_package_sha256", "context_slice_sha256"]) {
+        if (value[key] !== undefined && !text(value[key]))
+            throw new AppError("validation", `Stage context ${key} must be a nonempty string`, 2);
     }
 }
 function sha256(value) { return crypto.createHash("sha256").update(value).digest("hex"); }