@deksden-com/dd-flow-cli 0.9.0-beta.151 → 0.9.0-beta.155

package/dist/services/hooks.js

@@ -319,7 +319,11 @@ export function handleCodexHook(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle && !continuationCommand(command))
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
-    const parentProviderSessionId = rawChildProviderSessionId ? codexNativeParentId(payload, rawChildProviderSessionId) : null;
+    const parentProviderSessionId = rawChildProviderSessionId
+        ? context.codexHookProof?.sessionId === rawChildProviderSessionId
+            ? context.codexHookProof.parentSessionId
+            : codexNativeParentId(payload, rawChildProviderSessionId)
+        : null;
     // Resume legitimately receives an answer through stdin. It is matched by
     // immutable lifecycle arguments below; never reject or rewrite that pipe.
     const bootstrapStageStart = lifecycle?.bootstrapStageStart;
@@ -415,7 +419,18 @@ export function handleCodexHook(context, input) {
         const toolCallId = stringValue(payload.tool_use_id) ?? stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
         if (!daemonId || !rootProviderSessionId || !providerSessionId || !toolCallId)
             throw new AppError("codex_identity_missing", "Managed Codex lifecycle hook has no complete native invocation identity", 1, { invocation_id: invocationId });
-        const executionCwd = assignedLifecycleCwd(context, project.root, lifecycle, providerSessionId, command, stringValue(payload.cwd), { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId, toolCallId }, "codex-desktop");
+        let executionCwd;
+        try {
+            executionCwd = assignedLifecycleCwd(context, project.root, lifecycle, providerSessionId, command, stringValue(payload.cwd), { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId, toolCallId }, "codex-desktop");
+        }
+        catch (error) {
+            // A proven external Work is not its Stage coordinator. Deny the tool
+            // normally; a policy refusal is not a broken native hook or a receipt.
+            if (!(error instanceof AppError) || error.code !== "work_stage_boundary")
+                throw error;
+            return { ...common, observed: false, reason: error.code, hookSpecificOutput: { hookEventName: "PreToolUse",
+                    permissionDecision: "deny", permissionDecisionReason: error.message } };
+        }
         const receipt = observeLifecycleInvocation(context, {
             currentEventKey: eventKey,
             ...(invocationId ? { id: invocationId } : {}),
@@ -741,6 +756,12 @@ function assignedLifecycleCwd(context, projectRoot, facts, providerSessionId, co
     if ((!facts && !auxiliary) || facts?.analysis.supported === false)
         return undefined;
     const proven = identity && harness ? managedNativeInvocationScope(context, projectRoot, identity, harness) : null;
+    if (proven && (facts?.invocation.operation.startsWith("stage_") || facts?.invocation.operation.startsWith("delivery_")) && !facts.bootstrapStageStart
+        && context.db.get("SELECT 1 FROM sqlite_master WHERE type='table' AND name='work_launches'")) {
+        const worker = context.db.get("SELECT w.work_id FROM works w JOIN work_launches l ON l.work_id=w.work_id JOIN work_sessions ws ON ws.work_id=w.work_id JOIN sessions s ON s.session_id=ws.session_id AND s.project_id=w.project_id JOIN projects p ON p.id=w.project_id WHERE p.root=? AND w.run_id=? AND s.harness=? AND s.provider_session_id=? AND l.status IN ('launching','start_requested') LIMIT 1", [proven.projectRoot, proven.runId, harness, providerSessionId]);
+        if (worker)
+            throw new AppError("work_stage_boundary", "This external Work cannot issue coordinator Stage or delivery commands. Complete only its assigned Work; after successful work finish, end this Turn. The coordinator continues the Stage.", 1, { phase: "prepare", effect: "no_effect", recoverable: false });
+    }
     const constraint = proven ?? (identity ? { projectRoot, daemonId: identity.daemonId, rootSessionId: identity.rootSessionId } : undefined);
     const issuedRunId = facts && !facts.runId && !facts.workId && !facts.bootstrapStageStart && constraint ? observedLifecycleInvocation(context, command, constraint, identity ? { identity } : undefined)?.scope.runId : null;
     if (facts?.invocation.operation.startsWith("stage_") && !facts.bootstrapStageStart && !facts.runId && !issuedRunId)
@@ -885,7 +906,10 @@ function handleControlledToolEvent(context, input, event, harness) {
     // Syntax refusal precedes assignment/cwd lookup: an unsupported AST cannot
     // supply a route or execution authority, including a short public Stage call.
     const shellRefusal = lifecycle?.analysis.supported === false;
-    const nativeIdentity = { daemonId, rootSessionId: nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId };
+    const proof = context.nativeHookProof;
+    if (proof && (proof.harness !== harness || proof.daemonId !== daemonId || proof.sessionId !== providerSessionId || proof.toolCallId !== toolCallId))
+        throw new AppError("native_hook_unproven", "Verified native Work callback differs from its physical identity", 1);
+    const nativeIdentity = { daemonId, rootSessionId: proof?.rootSessionId ?? nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId };
     const provenScope = lifecycle && !shellRefusal ? managedNativeInvocationScope(context, expectedRoot, nativeIdentity, harness) : null;
     const issuedRunId = lifecycle && !lifecycle.runId && !lifecycle.workId && !lifecycle.bootstrapStageStart
         ? observedLifecycleInvocation(context, command, provenScope ?? { projectRoot: expectedRoot, daemonId, rootSessionId: nativeIdentity.rootSessionId }, { identity: nativeIdentity })?.scope.runId : null;
@@ -939,7 +963,7 @@ function handleControlledToolEvent(context, input, event, harness) {
         let inserted = false;
         const receipt = observeLifecycleInvocation(context, {
             currentEventKey: baseKey,
-            command, harness, projectId: project.id, ...(!shellRefusal && workspaceBound ? { executionCwd: expectedCwd } : {}), identity: { daemonId, rootSessionId: nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId },
+            command, harness, projectId: project.id, ...(!shellRefusal && workspaceBound ? { executionCwd: expectedCwd } : {}), identity: nativeIdentity,
             recordReceipt: scope => { inserted = persist(scope); return baseKey; }
         });
         const admitted = { ...result(inserted), ...lifecycleObservationResult(receipt), ...(receipt.invocationId ? { invocation_id: receipt.invocationId } : {}) };
@@ -1066,6 +1090,7 @@ function lifecycleFacts(command) {
     const workStart = invocation.operation === "work_start";
     const workFinish = invocation.operation === "work_finish";
     const workFail = invocation.operation === "work_fail";
+    const delivery = invocation.operation.startsWith("delivery_");
     return {
         analysis,
         invocation,
@@ -1076,8 +1101,8 @@ function lifecycleFacts(command) {
         workStart, workFinish, workFail,
         bootstrapStageStart: stageStart && commandHasOption(invocation, "bootstrap"),
         commandProjectRoot: commandOption(invocation, "project-root"),
-        stageName: stageStart || stageFinish || stagePause || stageResume ? commandOption(invocation, "stage") : undefined,
-        runId: stageStart || stageFinish || stagePause || stageResume ? commandPosition(invocation, 0) : undefined,
+        stageName: stageStart || stageFinish || stagePause || stageResume || delivery ? commandOption(invocation, "stage") : undefined,
+        runId: stageStart || stageFinish || stagePause || stageResume || delivery ? commandPosition(invocation, 0) : undefined,
         workId: stagePause || stageResume ? commandOption(invocation, "work") : workStart || workFinish || workFail ? commandPosition(invocation, 0) : undefined,
         contextSha256: commandOption(invocation, "context-sha256")
     };

package/dist/services/hybrid-contracts.js

@@ -2,6 +2,8 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { Ajv } from "ajv/dist/ajv.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
 /** Static E1 contracts only. No ingress, dispatch or runtime defaults are changed. */
 export const hybridContractNames = [
     "release-manifest", "harness-catalog", "model-catalog", "discovery-result",
@@ -249,7 +251,7 @@ export function validateHybridContract(name, input, context = {}) {
             fail("foreign_bundle_canon", "/canon");
         if (hybridDigest(data.project_pack) !== hybridDigest(context.bundleProvenance.project_pack))
             fail("foreign_bundle_project_pack", "/project_pack");
-        if ((data.flow_id === "mb-audit" || data.flow_id === "project-review") !== (data.project_pack === null))
+        if ((isSourceSnapshotFlow(data.flow_id) || data.flow_id === "mb-fix" || isDeliveryFlow(data.flow_id)) !== (data.project_pack === null))
             fail("invalid_bundle_project_pack_role", "/project_pack");
         const memoryFlow = data.flow_id === "mb-init" || data.flow_id === "mb-upgrade";
         if (memoryFlow && context.bootstrapIdentity?.projectRoot !== context.bundleProjectRoot)
@@ -289,6 +291,9 @@ export function validateHybridContract(name, input, context = {}) {
             }
         };
         const descriptor = loaded(data.descriptor), settings = loaded(data.execution_settings), profiles = loaded(data.profile_settings);
+        if (data.flow_id === "interactive" && (!descriptor || record(descriptor).origin !== "project"
+            || record(data.project_pack).source_commit !== record(data.canon).commit))
+            fail("foreign_project_flow_provenance", "/project_pack");
         // Execution receipts are evidence references, not just trusted facts. They
         // must survive reopening the RUN inside the same frozen blob inventory.
         for (const reference of [record(settings).attached_session_receipt,

package/dist/services/installed-flow-source.js

@@ -8,7 +8,7 @@ import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
 import { admitBundledFlow } from "./stage-handlers.js";
 import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
 const limit = 1024 * 1024;
-const flowIds = ["mb-init", "mb-upgrade", "mb-audit", "project-review"];
+const flowIds = ["mb-init", "mb-upgrade", "mb-audit", "project-review", "mb-distill", "mb-fix", "review-fix", "release", "deploy", "publish"];
 const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
 function refuse(reason) {
     throw new AppError("installed_flow_source_invalid", "Installed flow source is not the selected verified canon", 1, { reason, phase: "prepare", effect: "no_effect" });
@@ -117,6 +117,41 @@ export class PreparedInstalledFlowSource {
                 JSON.parse(content.toString("utf8"));
                 blobs.set(workSchema, Buffer.from(content));
             }
+            if (flowId === "mb-fix" || flowId === "review-fix") {
+                for (const logical of [`dd-flow/${flowId}/hybrid/index.md`, "mbb/frontmatter-standards.md", "mbb/cross-references.md", "mbb/named-deferrals-guide.md"]) {
+                    const content = readBoundedReleaseFile(containedFile(memoryRoot, logical), limit), name = `support/${logical}`;
+                    if (!content.length || (total += content.length) > 32 * limit || folded.has(name.toLowerCase()))
+                        refuse("invalid_support_inventory");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    folded.set(name.toLowerCase(), name);
+                    blobs.set(name, Buffer.from(content));
+                }
+            }
+            if (flowId === "mb-distill") {
+                // Both lenses need their actual comparison baseline, not only titles.
+                const directories = ["mbb", "mbb/aspects", "mbb/templates", "dd-flow/common", "dd-flow/vnext",
+                    "dd-flow/plan", "dd-flow/code", "dd-flow/merge", "dd-flow/workers", "dd-flow/def",
+                    "dd-flow/mb-distill/aspects", "dd-flow/mb-distill/process-aspects"];
+                const support = [...directories.flatMap(logical => {
+                        const source = containedFile(memoryRoot, logical);
+                        directory(source);
+                        return fs.readdirSync(source).filter(name => name.endsWith(".md")).sort().map(name => `${logical}/${name}`);
+                    }), "dd-flow/mb-audit.md", "dd-flow/mb-upgrade/index.md"];
+                for (const logical of support) {
+                    const content = readBoundedReleaseFile(containedFile(memoryRoot, logical), limit), name = `support/${logical}`;
+                    if (!content.length || (total += content.length) > 32 * limit || folded.has(name.toLowerCase()))
+                        refuse("invalid_support_inventory");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    folded.set(name.toLowerCase(), name);
+                    blobs.set(name, Buffer.from(content));
+                }
+                const workSchema = "schemas/distill-work-result.schema.json";
+                const content = readBoundedReleaseFile(containedFile(flowRoot, workSchema), limit);
+                if (!content.length || (total += content.length) > 32 * limit || folded.has(workSchema.toLowerCase()))
+                    refuse("invalid_support_inventory");
+                JSON.parse(content.toString("utf8"));
+                blobs.set(workSchema, Buffer.from(content));
+            }
             // Verify compressed/expanded archive identity again after collecting bytes.
             // A coherent descriptor+prompt edit cannot become a new trusted selection.
             const final = readSetupStatus(home);
@@ -167,7 +202,7 @@ export class PreparedInstalledFlowSource {
                 || typeof value.canon.version !== "string" || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.canon.version)
                 || !value.descriptor || Object.keys(value.descriptor).sort().join() !== "path,sha256"
                 || !flowIds.some(id => value.descriptor.path === `${id}/flow-descriptor.json`) || typeof value.descriptor.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.descriptor.sha256)
-                || !Array.isArray(value.blobs) || value.blobs.length < 1 || value.blobs.length > 129)
+                || !Array.isArray(value.blobs) || value.blobs.length < 1 || value.blobs.length > 512)
                 refuse("invalid_retained_source");
             const blobs = new Map(), folded = new Set();
             let total = 0;

package/dist/services/interactive-attached-session.js

@@ -0,0 +1,215 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { parse } from "shell-quote";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { hookSessionIdentity } from "./hooks.js";
+import { prepareOperatorProfile } from "./operator-profiles.js";
+import { findProjectByRoot } from "./projects.js";
+import { parseCommandArgs } from "./lifecycle-command.js";
+const eventType = "interactive.attached_session";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_attached_session_required", "Interactive needs its current trusted attached Session; choose managed execution explicitly otherwise", 2, { phase: "prepare", effect: "no_effect", reason, next_action: "provide_matching_attached_session_or_choose_managed" });
+}
+function checkedScope(scope) {
+    if (!scope || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(scope.requestId)
+        || [scope.projectRoot, scope.workspace].some(value => typeof value !== "string" || !path.isAbsolute(value)))
+        refuse("invalid_scope");
+    try {
+        if ([scope.projectRoot, scope.workspace].some(value => fs.realpathSync(value) !== value))
+            refuse("noncanonical_scope");
+    }
+    catch {
+        refuse("workspace_unavailable");
+    }
+}
+function project(context, scope) {
+    const value = findProjectByRoot(context, scope.projectRoot);
+    if (!value)
+        refuse("registered_project_required");
+    return value;
+}
+function launchArguments(context, command) {
+    let dynamic = false;
+    const entries = parse(command, () => { dynamic = true; return ""; });
+    if (dynamic || entries.some(entry => typeof entry !== "string") || /[`\n\r]/.test(command))
+        refuse("standalone_launch_required");
+    const words = entries;
+    let index = 0;
+    if (words[0]?.startsWith("DD_FLOW_HOME=")) {
+        if (words[0].slice("DD_FLOW_HOME=".length) !== context.ddFlowHome)
+            refuse("launch_home_mismatch");
+        index++;
+    }
+    if (path.basename(words[index] ?? "") === "node" && path.basename(words[index + 1] ?? "") === "cli.js")
+        index++;
+    else if (path.basename(words[index] ?? "") !== "dd-flow")
+        refuse("standalone_launch_required");
+    return words.slice(index + 1);
+}
+function checkLaunchCommand(context, scope, command) {
+    const args = parseCommandArgs(launchArguments(context, command)), option = (key) => args.options.get(key);
+    if (args.positional.join(" ") !== "flow interactive" || option("help") || option("execution")?.some(value => value !== "attached")
+        || option("request-id")?.length !== 1 || option("request-id")[0] !== scope.requestId
+        || option("project-root")?.length !== 1 || option("project-root")[0] !== scope.projectRoot
+        || (option("workspace") ? option("workspace").length !== 1 || option("workspace")[0] !== scope.workspace : scope.workspace !== scope.projectRoot))
+        refuse("launch_scope_mismatch");
+}
+function binding(context, scope, selected, source, fresh) {
+    if (!source || typeof source.eventKey !== "string" || !source.eventKey || typeof source.command !== "string"
+        || !source.command.trim() || Buffer.byteLength(source.command) > 32 * 1024)
+        refuse("exact_launch_receipt_required");
+    checkLaunchCommand(context, scope, source.command);
+    const profile = prepareOperatorProfile(selected), selectedProject = project(context, scope);
+    const event = context.db.get("SELECT id,event_name,status,sanitized_summary,created_at FROM hook_events WHERE project_id=? AND event_key=?", [selectedProject.id, source.eventKey]);
+    if (!event || event.event_name !== "PreToolUse" || event.status !== (fresh ? "observed" : "claimed"))
+        refuse("unavailable_launch_receipt");
+    const age = Date.parse(context.now()) - Date.parse(event.created_at);
+    // Reuse the existing hook admission horizon; historical restore does not
+    // pretend that the original launch event proves a currently live Session.
+    if (fresh && (!Number.isFinite(age) || age < 0 || age > 60_000))
+        refuse("stale_launch_receipt");
+    let summary;
+    try {
+        summary = JSON.parse(event.sanitized_summary);
+    }
+    catch {
+        return refuse("exact_launch_receipt_required");
+    }
+    if ((summary?.command ?? summary?.tool_input?.command) !== source.command)
+        refuse("launch_command_mismatch");
+    const identity = hookSessionIdentity(context, selectedProject.id, source.eventKey);
+    if (identity.parentSessionId || !identity.providerSessionId || identity.harness !== runtimeHarness(profile))
+        refuse("root_session_mismatch");
+    if (identity.cwd !== scope.workspace)
+        refuse("session_workspace_mismatch");
+    if (identity.provider !== profile.provider || identity.model !== profile.model || identity.reasoning !== profile.reasoning
+        || identity.mode !== profile.mode)
+        refuse("session_profile_mismatch");
+    return { schema_id: "dd-flow/interactive-attached-session@1", scope: structuredClone(scope), profile,
+        hook_event_id: event.id, event_key: source.eventKey, command: source.command, harness: identity.harness,
+        provider_session_id: identity.providerSessionId, session_id: identity.sessionId, daemon_id: identity.daemonId, observed_at: event.created_at };
+}
+function retained(context, scope) {
+    const selectedProject = project(context, scope);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.binding.scope.requestId')=? LIMIT 2", [selectedProject.id, eventType, scope.requestId]);
+    if (rows.length > 1)
+        refuse("ambiguous_attached_binding");
+    if (!rows.length)
+        return null;
+    if (Buffer.byteLength(rows[0].payload_json) > 256 * 1024)
+        refuse("invalid_attached_binding");
+    let value;
+    try {
+        value = JSON.parse(rows[0].payload_json);
+    }
+    catch {
+        return refuse("invalid_attached_binding");
+    }
+    if (!value || !value.binding || !value.binding.scope || Object.keys(value).sort().join() !== "binding,sha256" || hybridDigest(value.binding.scope) !== hybridDigest(scope)
+        || hash(Buffer.from(JSON.stringify(value.binding))) !== value.sha256)
+        refuse("attached_binding_changed");
+    const actual = binding(context, scope, value.binding.profile, { eventKey: value.binding.event_key, command: value.binding.command }, false);
+    if (hybridDigest(actual) !== hybridDigest(value.binding))
+        refuse("attached_receipt_changed");
+    return value;
+}
+/** Produces generic execution receipt facts from the trusted hook ledger, not
+ * model-authored receipt JSON or ambient Session/model environment variables.
+ * This does not create a RUN or prove independent review/delegation capacity. */
+export class PreparedInteractiveAttachedSession {
+    sha256;
+    #binding;
+    constructor(value) {
+        this.#binding = structuredClone(value);
+        this.sha256 = hash(Buffer.from(JSON.stringify(value)));
+        Object.freeze(this);
+    }
+    static prepare(context, scope, profile, source) {
+        checkedScope(scope);
+        if (retained(context, scope))
+            refuse("restore_retained_attached_binding");
+        return new PreparedInteractiveAttachedSession(binding(context, scope, profile, source, true));
+    }
+    /** Discover only an exact current argv observation. Same request/root/profile
+     * with a different intake or selector is not evidence for this invocation. */
+    static prepareCurrent(context, scope, profile, args) {
+        checkedScope(scope);
+        if (!Array.isArray(args) || args.length > 1024 || args.some(arg => typeof arg !== "string" || arg.includes("\0"))
+            || args[0] !== "flow" || args[1] !== "interactive")
+            refuse("exact_launch_receipt_required");
+        if (retained(context, scope))
+            refuse("restore_retained_attached_binding");
+        const selectedProject = project(context, scope), matches = [];
+        const rows = context.db.all("SELECT event_key,sanitized_summary FROM hook_events WHERE project_id=? AND event_name='PreToolUse' AND status='observed' AND created_at>=? ORDER BY id DESC LIMIT 129", [selectedProject.id, new Date(Date.parse(context.now()) - 60_000).toISOString()]);
+        if (rows.length > 128)
+            refuse("launch_observation_window_exceeds_bound");
+        for (const row of rows) {
+            if (typeof row.sanitized_summary !== "string" || Buffer.byteLength(row.sanitized_summary) > 64 * 1024)
+                continue;
+            let summary;
+            try {
+                summary = JSON.parse(row.sanitized_summary);
+            }
+            catch {
+                continue;
+            }
+            const command = summary?.command ?? summary?.tool_input?.command;
+            if (typeof command !== "string" || Buffer.byteLength(command) > 32 * 1024)
+                continue;
+            try {
+                if (hybridDigest(launchArguments(context, command)) !== hybridDigest(args))
+                    continue;
+                matches.push(binding(context, scope, profile, { eventKey: row.event_key, command }, true));
+            }
+            catch (error) {
+                if (!(error instanceof AppError) || error.code !== "interactive_attached_session_required")
+                    throw error;
+            }
+        }
+        if (matches.length !== 1)
+            refuse(matches.length ? "ambiguous_launch_receipt" : "unavailable_launch_receipt");
+        return new PreparedInteractiveAttachedSession(matches[0]);
+    }
+    static restore(context, scope) {
+        checkedScope(scope);
+        const value = retained(context, scope);
+        if (!value)
+            refuse("attached_binding_missing");
+        return new PreparedInteractiveAttachedSession(value.binding);
+    }
+    snapshot() { return structuredClone(this.#binding); }
+    evidence() {
+        const value = this.#binding, bytes = Buffer.from(JSON.stringify(value));
+        const reference = { path: "receipts/interactive-attached-session.json", sha256: this.sha256 };
+        const receipts = new Map([[this.sha256, { kind: "attached-session-binding", ...value.scope,
+                    harness: value.profile.harness, profileRevision: hybridDigest(value.profile) }]]);
+        return { reference, bytes, receipts };
+    }
+    /** Pair hook claim and custody with the caller's request/RUN writer. */
+    retainPreparedSql(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        const value = this.#binding, prior = retained(context, value.scope);
+        if (prior) {
+            if (prior.sha256 !== this.sha256)
+                refuse("attached_binding_changed");
+            return { changed: false };
+        }
+        const current = binding(context, value.scope, value.profile, { eventKey: value.event_key, command: value.command }, true);
+        if (hybridDigest(current) !== hybridDigest(value))
+            refuse("attached_receipt_changed");
+        const selectedProject = project(context, value.scope);
+        const claimed = context.db.run("UPDATE hook_events SET status='claimed',claimed_at=? WHERE id=? AND project_id=? AND status='observed'", [context.now(), value.hook_event_id, selectedProject.id]);
+        if (claimed.changes !== 1)
+            refuse("launch_receipt_consumed");
+        appendAudit(context, { projectId: selectedProject.id, eventType, payload: { binding: value, sha256: this.sha256 } });
+        if (retained(context, value.scope)?.sha256 !== this.sha256)
+            refuse("attached_readback_failed");
+        return { changed: true };
+    }
+}

package/dist/services/interactive-baseline-custody.js

@@ -0,0 +1,54 @@
+import { AppError } from "../shared/errors.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { readInteractiveBundleData } from "./interactive-bundle-data.js";
+const logical = "runtime/git-baseline.json";
+function refuse(reason) {
+    throw new AppError("interactive_baseline_custody_invalid", "Interactive requires its own retained entry baseline", 2, { reason, effect: "no_effect" });
+}
+function selected(context, scope, bundle, file = logical) {
+    if (bundle.manifest.flow_id !== "interactive" || bundle.manifest.run_id !== scope.runId)
+        refuse("interactive_bundle_required");
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    return readInteractiveBundleData(bundle, file);
+}
+/** Initial physical observation, not RUN allocation or mutation authority. The
+ * factory must revalidate before retaining these bytes and starting work. */
+export function prepareInteractiveGitBaseline(input) {
+    const baseline = PreparedInteractiveGitBaseline.capture(input);
+    return { path: logical, sha256: baseline.sha256, bytes: baseline.bytes(), baseline };
+}
+/** SQL/in-memory fence for Stage acceptance: no project/Git/filesystem lookup,
+ * profile selection, fresh capture or adoption of a caller's replacement JSON. */
+export function assertInteractiveGitBaselineCustody(context, scope, bundle, expectedSha256) {
+    if (selected(context, scope, bundle).sha256 !== expectedSha256)
+        refuse("baseline_binding_changed");
+}
+/** Historical custody uses the frozen execution scope. Current physical scope
+ * and supported relocation must be admitted separately before subsequent work. */
+export function readPreparedInteractiveGitBaseline(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const { bytes, reference, sha256 } = selected(context, scope, bundle);
+        const baseline = PreparedInteractiveGitBaseline.restore(bytes, sha256), value = baseline.snapshot();
+        const frozen = bundle.execution.snapshot().scope;
+        if (value.project_root !== frozen.projectRoot || value.workspace !== frozen.workspace)
+            refuse("baseline_scope_changed");
+        return { baseline, sha256,
+            reference: { root: "run", path: `execution-bundle/${logical}`, sha256: reference.sha256 } };
+    });
+}
+export function assertInteractiveBeforeVersionsCustody(context, scope, bundle, expectedSha256) {
+    if (selected(context, scope, bundle, "runtime/before-versions.json").sha256 !== expectedSha256)
+        refuse("before_versions_binding_changed");
+}
+/** Initial before-images selected from this same RUN/baseline. Later per-turn
+ * before-images require their own accepted Work/packet custody, not bundle edits. */
+export function readPreparedInteractiveBeforeVersions(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const baseline = readPreparedInteractiveGitBaseline(context, scope, bundle);
+        const { bytes, reference, sha256 } = selected(context, scope, bundle, "runtime/before-versions.json");
+        return { value: restoreInteractiveBeforeVersions(bytes, sha256, baseline.baseline), sha256,
+            reference: { root: "run", path: "execution-bundle/runtime/before-versions.json", sha256: reference.sha256 } };
+    });
+}

package/dist/services/interactive-before-versions.js

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+function refuse(reason) {
+    throw new AppError("interactive_before_versions_invalid", "Interactive must retain selected original versions before changing them", 2, { reason, effect: "no_effect" });
+}
+function safe(name) {
+    return typeof name === "string" && !!name && name.length <= 4096 && !path.posix.isAbsolute(name) && !path.win32.isAbsolute(name)
+        && !name.includes("\\") && !name.includes("\0") && name.split("/").every(part => part && part !== "." && part !== ".."
+        && ![".git", ".dd-flow", "node_modules"].includes(part.normalize("NFC").toLowerCase()) && localEnvironmentAllowed(part));
+}
+function absent(root, logical) {
+    let current = root;
+    const parts = logical.split("/");
+    for (let index = 0; index < parts.length; index++) {
+        current = path.join(current, parts[index]);
+        try {
+            const stat = fs.lstatSync(current);
+            if (index === parts.length - 1 || !stat.isDirectory())
+                refuse("unobserved_existing_source");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+    }
+}
+function rootIdentity(baseline) {
+    const value = baseline.snapshot(), actual = fs.lstatSync(value.workspace);
+    if (!actual.isDirectory() || fs.realpathSync(value.workspace) !== value.workspace
+        || actual.dev !== value.workspace_identity.dev || actual.ino !== value.workspace_identity.ino)
+        refuse("workspace_identity_changed");
+    return value;
+}
+/** Before-image evidence, not write approval. Reuses the existing bounded,
+ * private-file-aware source reader. No backup file, Git object, RUN or project
+ * mutation is created; the request/Work owner must retain these bytes first. */
+export class PreparedInteractiveBeforeVersions {
+    sha256;
+    #value;
+    #baseline;
+    #observed;
+    constructor(value, baseline, observed) {
+        if (Buffer.byteLength(JSON.stringify(value)) > 96 * 1024 * 1024)
+            refuse("before_versions_exceed_bound");
+        this.#value = structuredClone(value);
+        this.#baseline = baseline;
+        this.#observed = observed;
+        this.sha256 = createHash("sha256").update(JSON.stringify(value)).digest("hex");
+        Object.freeze(this);
+    }
+    static capture(baseline, paths) {
+        if (!(baseline instanceof PreparedInteractiveGitBaseline) || !Array.isArray(paths) || paths.length > 20_000
+            || paths.some(name => !safe(name)) || new Set(paths).size !== paths.length)
+            refuse("invalid_selected_paths");
+        const source = rootIdentity(baseline), byPath = new Map(source.entries.map(item => [item.path, item]));
+        const entries = [], files = [];
+        for (const name of [...paths].sort()) {
+            const before = byPath.get(name);
+            if (!before || before.kind === "missing") {
+                absent(source.workspace, name);
+                entries.push({ path: name, kind: "missing", mode: null, sha256: null, base64: null });
+            }
+            else {
+                if (before.kind !== "file")
+                    refuse("regular_file_scope_required");
+                const actual = fs.lstatSync(path.join(source.workspace, name));
+                if (!actual.isFile() || actual.nlink !== 1 || (actual.mode & 0o7777) !== before.mode)
+                    refuse("before_version_changed");
+                files.push(name);
+                entries.push({ path: name, kind: "file", mode: before.mode, sha256: before.sha256, base64: null });
+            }
+        }
+        const observed = ObservedMemorySources.capture({ workspace: source.workspace }, files.map(name => ({ root: "workspace", path: name })));
+        const hashes = observed.hashes();
+        for (const item of entries.filter(item => item.kind === "file")) {
+            if (hashes.get(memorySourceKey("workspace", item.path)) !== item.sha256)
+                refuse("before_version_changed");
+            item.base64 = observed.bytes({ root: "workspace", path: item.path }).toString("base64");
+        }
+        const prepared = new PreparedInteractiveBeforeVersions({ schema_id: "dd-flow/interactive-before-versions@1",
+            baseline_sha256: baseline.sha256, workspace: source.workspace, entries }, baseline, observed);
+        prepared.revalidate();
+        return prepared;
+    }
+    snapshot() { return structuredClone(this.#value); }
+    bytes() { return Buffer.from(JSON.stringify(this.#value)); }
+    reference() { return { path: "runtime/before-versions.json", sha256: this.sha256 }; }
+    revalidate() {
+        rootIdentity(this.#baseline);
+        this.#observed.revalidate();
+        for (const item of this.#value.entries) {
+            if (item.kind === "missing")
+                absent(this.#value.workspace, item.path);
+            else {
+                const stat = fs.lstatSync(path.join(this.#value.workspace, item.path));
+                if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o7777) !== item.mode)
+                    refuse("before_version_changed");
+            }
+        }
+    }
+}
+/** Historical parsing against an independently selected retained baseline.
+ * Never re-read the now-edited project to reconstruct its original content. */
+export function restoreInteractiveBeforeVersions(bytes, expectedSha256, baseline) {
+    if (!(baseline instanceof PreparedInteractiveGitBaseline) || !bytes.length || bytes.length > 96 * 1024 * 1024
+        || createHash("sha256").update(bytes).digest("hex") !== expectedSha256)
+        refuse("retained_before_versions_changed");
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_retained_before_versions");
+    }
+    const original = baseline.snapshot(), byPath = new Map(original.entries.map(item => [item.path, item]));
+    if (!value || Object.keys(value).sort().join() !== "baseline_sha256,entries,schema_id,workspace"
+        || value.schema_id !== "dd-flow/interactive-before-versions@1" || value.baseline_sha256 !== baseline.sha256
+        || value.workspace !== original.workspace || !Array.isArray(value.entries) || value.entries.length > 20_000)
+        refuse("retained_before_scope_changed");
+    let previous = "", total = 0;
+    for (const item of value.entries) {
+        if (!item || Object.keys(item).sort().join() !== "base64,kind,mode,path,sha256" || !safe(item.path) || item.path <= previous)
+            refuse("invalid_retained_before_versions");
+        const before = byPath.get(item.path);
+        if (item.kind === "missing") {
+            if (before && before.kind !== "missing" || item.mode !== null || item.sha256 !== null || item.base64 !== null)
+                refuse("retained_absence_changed");
+        }
+        else {
+            if (item.kind !== "file" || before?.kind !== "file" || item.mode !== before.mode || item.sha256 !== before.sha256 || typeof item.base64 !== "string")
+                refuse("retained_original_changed");
+            const content = Buffer.from(item.base64, "base64");
+            total += content.length;
+            if (content.length > 16 * 1024 * 1024 || total > 64 * 1024 * 1024 || content.toString("base64") !== item.base64
+                || createHash("sha256").update(content).digest("hex") !== before.sha256)
+                refuse("retained_original_changed");
+        }
+        previous = item.path;
+    }
+    return structuredClone(value);
+}