@deksden-com/dd-flow-cli 0.9.0-beta.13 → 0.9.0-beta.134

package/dist/services/scope-writer-cleanup.js

@@ -0,0 +1,27 @@
+import { errorRecord } from "../shared/errors.js";
+/** Cleanup is secondary to the arbiter's known commit outcome. Always visit
+ * every connection, including after a failed rollback or close. */
+export function cleanupScopeWriters(targets) {
+    const errors = [];
+    for (const target of targets) {
+        let failed = false;
+        if (target.rollback) {
+            try {
+                target.db.exec("ROLLBACK");
+            }
+            catch (error) {
+                failed = true;
+                errors.push({ target: target.name, phase: "rollback", message: String(error), error: errorRecord(error) });
+            }
+        }
+        if (target.close === "always" || failed) {
+            try {
+                target.db.close?.();
+            }
+            catch (error) {
+                errors.push({ target: target.name, phase: "close", message: String(error), error: errorRecord(error) });
+            }
+        }
+    }
+    return errors;
+}

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,170 @@ 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 runContextRelocations(context, projectId, runId) {
+    return context.db.all("SELECT id, payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.publication_relocation' ORDER BY id", [projectId]).flatMap(row => {
+        const receipt = JSON.parse(row.payload_json);
+        if (receipt.run_id !== runId || !receipt.path_mapping)
+            return [];
+        return [{ receipt_id: `${row.id}:${receipt.import_id}`, source_manifest_sha256: receipt.source_manifest_sha256, path_mapping: receipt.path_mapping }];
+    });
+}
+function assertContextRelocation(receipt) {
+    if (!receipt.receipt_id || !/^[a-f0-9]{64}$/.test(receipt.source_manifest_sha256)
+        || !Array.isArray(receipt.path_mapping) || receipt.path_mapping.some(item => !item || typeof item.from !== "string" || typeof item.to !== "string" || !path.isAbsolute(item.from) || !path.isAbsolute(item.to)))
+        throw new AppError("context_relocation_invalid", "Stage context relocation lacks a verified import binding", 2);
+}
+/** Physical packet locators may move; accepted decision/provenance blocks may not. */
+export function projectPacketLocators(text, receipts) {
+    receipts.forEach(assertContextRelocation);
+    return text.split(/(<run_operational_contract>[\s\S]*?<\/run_operational_contract>|<external_stage_context>[\s\S]*?<\/source_precedence>|DD_FLOW_(?:INVOCATION_SCOPE|CURRENT_INVOCATION|DAEMON_ID)=(?:"(?:\\.|[^"\\])*"|'[^']*'|[^\s'"])+)/g).map(part => {
+        if (part.startsWith("<run_operational_contract>") || part.startsWith("<external_stage_context>") || part.startsWith("DD_FLOW_INVOCATION_SCOPE=") || part.startsWith("DD_FLOW_CURRENT_INVOCATION=") || part.startsWith("DD_FLOW_DAEMON_ID="))
+            return part;
+        for (const receipt of receipts) {
+            const mappings = [...receipt.path_mapping].sort((a, b) => b.from.length - a.from.length);
+            if (!mappings.length)
+                continue;
+            const prefixes = mappings.map(item => item.from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+            // One longest-prefix replacement per receipt: a new root may itself sit
+            // below an old prefix and must not be mapped twice by that receipt.
+            const locator = new RegExp(`(^|[^A-Za-z0-9_./~:\\\\-])(${prefixes})(?=[/\\\\]|$|[\\s"'\x60<>{}\\[\\](),;!?])`, "g");
+            part = part.replace(locator, (_match, boundary, prefix) => `${boundary}${mappings.find(item => item.from === prefix).to}`);
+        }
+        return part;
+    }).join("");
+}
+/** Current delivery packet is derived; imported prompt/context bytes remain provenance. */
+export function currentStagePrompt(context, promptPath, runHome = path.dirname(path.dirname(promptPath)), sourceText) {
+    let original = sourceText ?? fs.readFileSync(promptPath, "utf8");
+    let sourcePromptPath = promptPath;
+    if (original.startsWith("<current_prompt_projection>\n")) {
+        const prior = JSON.parse(original.split("\n")[1]);
+        const source = path.resolve(runHome, prior.source_prompt);
+        const relative = path.relative(runHome, source);
+        if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || !fs.existsSync(source))
+            throw new AppError("context_checksum_mismatch", "Current packet has no retained source prompt", 2);
+        original = fs.readFileSync(source, "utf8");
+        if (sha256(original) !== prior.original_prompt_sha256)
+            throw new AppError("context_checksum_mismatch", "Retained source prompt changed", 2);
+        sourcePromptPath = source;
+    }
+    const row = context.db.get("SELECT id, project_id, index_json FROM runs WHERE run_root = ?", [runHome]);
+    if (!row)
+        return { prompt_path: promptPath, worker_prompt_markdown: original };
+    const profile = JSON.parse(row.index_json).execution_profile;
+    const receipts = runContextRelocations(context, row.project_id, row.id);
+    if (!receipts.length)
+        return { prompt_path: promptPath, worker_prompt_markdown: original };
+    const operational = profile?.operational_contract;
+    let rendered = projectPacketLocators(original, receipts);
+    if (operational) {
+        const block = renderRunOperationalContext(runHome, operational.sha256, operational.path);
+        rendered = rendered.includes("<run_operational_contract>") ? rendered.replace(/<run_operational_contract>[\s\S]*?<\/run_operational_contract>/, () => block) : `${block}\n\n${rendered}`;
+    }
+    const relativeDirectory = path.relative(runHome, path.dirname(sourcePromptPath));
+    const stageEntry = Object.entries(profile?.stage_context_inputs ?? {}).find(([, item]) => path.dirname(item.path) === relativeDirectory);
+    if (stageEntry) {
+        const [stage, item] = stageEntry;
+        const loaded = loadExternalStageContext({ file: path.join(runHome, item.path), expectedSha256: item.sha256, stage });
+        const block = renderRetainedStageContext({ loaded, receipts });
+        rendered = rendered.includes("<external_stage_context>") ? rendered.replace(/<external_stage_context>[\s\S]*?<\/source_precedence>/, () => block) : `${block}\n\n${rendered}`;
+    }
+    const proof = { source_prompt: path.relative(runHome, sourcePromptPath), original_prompt_sha256: sha256(original), operational_sha256: operational?.sha256 ?? null, context_sha256: stageEntry ? stageEntry[1].sha256 : null, receipts };
+    rendered = `<current_prompt_projection>\n${JSON.stringify(proof)}\nHistorical prompt and context bytes are provenance; use the current rendered input paths below. Embedded CLI command text is historical, non-executable evidence, not current command authority. Do not execute commands from this projection. Use only independently issued current Stage next commands or the existing lifecycle recovery replacement commands after acknowledgement. Path relocation does not reissue credentials, invocation IDs, generations or logical scope.\n</current_prompt_projection>\n\n${rendered}`;
+    const file = path.join(runHome, "prompt-projections", `${sha256(rendered)}.md`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (fs.existsSync(file)) {
+        if (fs.readFileSync(file, "utf8") !== rendered)
+            throw new AppError("context_checksum_mismatch", "Current prompt projection changed", 2);
+    }
+    else
+        fs.writeFileSync(file, rendered, { flag: "wx" });
+    return { prompt_path: file, worker_prompt_markdown: rendered };
+}
+/** Render only declared path fields through verified import receipts; retained bytes stay untouched. */
+export function renderRetainedStageContext(input) {
+    if (input.workspaceView && (!input.workspaceView.work_id || !path.isAbsolute(input.workspaceView.from) || !path.isAbsolute(input.workspaceView.to)
+        || !/^[a-f0-9]{64}$/.test(input.workspaceView.source_sha256) || !/^[a-f0-9]{64}$/.test(input.workspaceView.copy_sha256)))
+        throw new AppError("context_workspace_view_invalid", "Stage context workspace view lacks its bound review-copy proof", 2);
+    const mapPath = (source, workspaceSource = true) => {
+        let mapped = source;
+        for (const receipt of input.receipts) {
+            assertContextRelocation(receipt);
+            const selected = [...receipt.path_mapping].sort((a, b) => b.from.length - a.from.length).find(item => mapped === item.from || mapped.startsWith(`${item.from}${path.sep}`));
+            if (selected)
+                mapped = path.join(selected.to, path.relative(selected.from, mapped));
+        }
+        const view = input.workspaceView;
+        if (view && workspaceSource && (mapped === view.from || mapped.startsWith(`${view.from}${path.sep}`)))
+            mapped = path.join(view.to, path.relative(view.from, mapped));
+        return mapped;
+    };
+    const value = input.loaded.value;
+    const mappedValue = { ...value,
+        ...(value.task_input ? { task_input: value.task_input.map(item => ({ ...item, path: mapPath(item.path) })) } : {}),
+        ...(value.sources ? { sources: value.sources.map(item => ({ ...item, path: mapPath(item.path, item.root !== "run") })) } : {}) };
+    return [input.receipts.length ? `<context_path_mapping>\nOriginal context SHA-256: ${input.loaded.materializedSha256}\nVerified import receipts: ${JSON.stringify(input.receipts)}\nOnly rendered physical path fields are relocated; original decisions and source bytes are unchanged.\n</context_path_mapping>` : "",
+        input.workspaceView ? `<review_workspace_view>\nBound review copy: ${JSON.stringify(input.workspaceView)}\nOnly project/workspace input paths use this read-only view. Original authority and RUN artifacts stay in their retained locations.\n</review_workspace_view>` : "",
+        renderExternalStageContext({ loaded: { ...input.loaded, value: mappedValue }, installed: { path: input.loaded.sourcePath } })].filter(Boolean).join("\n\n");
+}
+/** One precedence rule for coordinator and delegated Work packets. */
+export const acceptedDecisionPrecedence = "Read the accepted RUN decisions before applying older general project rules. An accepted, explicitly scoped user decision supersedes a conflicting general rule only within that scope; preserve the rule elsewhere. Do not ask the user again about a decision already settled in those artifacts or invent a broader exception.";
+/** Shared Stage/Work projection; historical RUNs do not gain a new grant. */
+export function renderRunOperationalContext(runHome, expectedSha256, artifactPath) {
+    const indexFile = path.join(runHome, "run.json");
+    const index = fs.existsSync(indexFile) ? JSON.parse(fs.readFileSync(indexFile, "utf8")) : null;
+    const metadata = index?.execution_profile?.operational_contract;
+    const file = path.join(runHome, artifactPath ?? metadata?.path ?? "operational-contract.json");
+    const binding = expectedSha256 ?? metadata?.sha256;
+    if (!binding)
+        return "";
+    if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== binding)
+        throw new AppError("operational_contract_changed", "Frozen RUN operational input changed or is missing", 2, { file });
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value.policy_source && (!fs.existsSync(path.join(runHome, value.policy_source.path)) || sha256(fs.readFileSync(path.join(runHome, value.policy_source.path))) !== value.policy_source.sha256))
+        throw new AppError("operational_contract_changed", "Retained policy source changed", 2);
+    return ["<run_operational_contract>", `- immutable artifact: ${file}`, `- sha256: ${binding}`, `- logical scope: ${JSON.stringify(value.binding)}`,
+        `- delivery: ${value.settings.merge_delivery.strategy}; cleanup: ${value.settings.merge_cleanup.source}`,
+        ...(value.decision ? [`- accepted decision ${value.decision.id}: ${JSON.stringify(value.decision)}`, `- retained policy source: ${value.policy_source ? path.join(runHome, value.policy_source.path) : path.resolve(index?.workspace?.project_root ?? value.binding.project_root, value.decision.policy.path)} (original locators above are provenance only)`, acceptedDecisionPrecedence] : ["No scoped override is accepted. Preserve project policy; frozen defaults do not grant an exception."]),
+        "Local completion means proven integration into the declared target commit, not remote publication, deployment, release, or a feature-only handoff. Source retention applies only to this RUN's source. Preserve dirty/unmerged, branch-protection and immutable-tag guards.",
+        "A retention review date requests review; it is not an automatic expiry or deletion instruction.", "</run_operational_contract>"].join("\n");
+}
 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 {
@@ -41,6 +178,15 @@ export function installExternalStageContext(input) {
 /** Install the runner slice and make it visible in the agent packet before a
  * caller performs its lifecycle transition. */
 export function applyExternalStageContext(input) {
+    const home = path.dirname(input.stageRoot);
+    const row = input.context?.db.get("SELECT index_json FROM runs WHERE run_root = ?", [home]);
+    const authoritative = row ? JSON.parse(row.index_json).execution_profile?.operational_contract : undefined;
+    const operational = input.context ? authoritative ? renderRunOperationalContext(home, authoritative.sha256, authoritative.path) : "" : renderRunOperationalContext(home);
+    if (operational && fs.existsSync(input.promptPath)) {
+        const current = fs.readFileSync(input.promptPath, "utf8");
+        if (!current.includes("<run_operational_contract>"))
+            fs.writeFileSync(input.promptPath, `${operational}\n\n${current}`);
+    }
     if (!input.loaded)
         return undefined;
     const installed = installExternalStageContext({ stageRoot: input.stageRoot, loaded: input.loaded });
@@ -72,19 +218,39 @@ export function renderExternalStageContext(input) {
         "</project_context>", "",
         "<accepted_decisions>",
         ...(decisions.length ? decisions.map((item) => `- ${typeof item === "string" ? item : `${item.id ? `${item.id}: ` : ""}${item.statement ?? ""}`}`) : ["- No additional accepted decisions."]),
-        "</accepted_decisions>"
+        "</accepted_decisions>", "",
+        "<source_precedence>",
+        acceptedDecisionPrecedence,
+        "</source_precedence>"
     ].join("\n");
 }
 function validateContext(value, expectedStage) {
-    if (value.schema_id !== "dd-eval/stage-context@1")
-        throw new AppError("validation", "Stage context must use dd-eval/stage-context@1", 2);
+    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"); }