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

package/dist/services/interactive-mutation-scope.js

@@ -0,0 +1,231 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readPreparedInteractiveBeforeVersions, readPreparedInteractiveGitBaseline } from "./interactive-baseline-custody.js";
+import { PreparedInteractiveBeforeVersions, restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { readInteractiveUserInputs } from "./interactive-user-inputs.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { readInteractiveWorkHistory, assertInteractiveCorrectionHistory } from "./interactive-work-history.js";
+const eventType = "interactive.mutation_scope";
+const digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+function refuse(reason) {
+    throw new AppError("interactive_mutation_scope_invalid", "Interactive scope requires delivered user input and original before-images", 2, { reason, effect: "no_effect", ...(reason === "current_scope_required" ? { phase: "prepare", recoverable: true } : {}) });
+}
+function pathsValid(paths) {
+    if (!Array.isArray(paths) || paths.length > 20_000 || paths.some(value => typeof value !== "string" || !value.trim())
+        || new Set(paths).size !== paths.length || hybridDigest(paths) !== hybridDigest([...paths].sort()))
+        refuse("ordered_unique_paths_required");
+}
+/** Delivered-input custody only; the agent still assesses what it authorizes. */
+export function assertInteractiveUserBasis(basis, inputs) {
+    if (!basis || Object.keys(basis).sort().join() !== "event_id,role,sha256" || !Number.isSafeInteger(basis.event_id) || basis.event_id < 0 || !digest(basis.sha256))
+        refuse("delivered_user_basis_required");
+    const delivered = basis.role === "request" ? basis.event_id === 0 && basis.sha256 === inputs.initial_request.sha256
+        : inputs.messages.some(source => ["turn", "answer", "finish"].includes(source.role) && source.role === basis.role && source.event_id === basis.event_id && source.sha256 === basis.sha256);
+    if (!delivered)
+        refuse("delivered_user_basis_required");
+}
+/** SQL-only custody, not semantic approval. A later user message invalidates
+ * active scope until the coordinator explicitly reassesses the full input set. */
+export function readInteractiveMutationScope(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const baseline = readPreparedInteractiveGitBaseline(context, scope, bundle);
+        const initial = readPreparedInteractiveBeforeVersions(context, scope, bundle);
+        const inputs = readInteractiveUserInputs(context, scope, bundle);
+        const versions = new Map(initial.value.entries.map(item => [item.path, item]));
+        const approved = new Set(), requests = new Set(), records = [];
+        let revision = hybridDigest({ bundle: bundle.sha256, baseline: baseline.sha256, before: initial.sha256 }), total = 0;
+        const rows = context.db.all("SELECT id,payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? ORDER BY id LIMIT 129", [scope.projectId, eventType, scope.runId]);
+        if (rows.length > 128)
+            refuse("too_many_scope_decisions");
+        for (const row of rows) {
+            total += Buffer.byteLength(row.payload_json);
+            if (total > 128 * 1024 * 1024)
+                refuse("unbounded_scope_history");
+            let value;
+            try {
+                value = JSON.parse(row.payload_json);
+            }
+            catch {
+                return refuse("invalid_scope_custody");
+            }
+            if (!value || Object.keys(value).sort().join() !== "basis,before_sha256,before_versions,bundle_sha256,paths,previous_sha256,reason,request_id,run_id,schema_id,user_inputs_sha256"
+                || value.schema_id !== "dd-flow/interactive-mutation-scope@1" || value.run_id !== scope.runId || value.bundle_sha256 !== bundle.sha256
+                || typeof value.request_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.request_id) || requests.has(value.request_id)
+                || !digest(value.user_inputs_sha256) || typeof value.reason !== "string" || !value.reason.trim() || value.reason.length > 64 * 1024
+                || value.previous_sha256 !== revision)
+                refuse("invalid_scope_custody");
+            pathsValid(value.paths);
+            assertInteractiveUserBasis(value.basis, inputs);
+            if (value.basis.event_id >= row.id || value.basis.role === "finish" && value.paths.some(name => !approved.has(name)))
+                refuse("scope_not_supported_by_prior_user_input");
+            const original = restoreInteractiveBeforeVersions(Buffer.from(JSON.stringify(value.before_versions)), value.before_sha256, baseline.baseline);
+            const missing = value.paths.filter(name => !versions.has(name));
+            if (hybridDigest(original.entries.map(item => item.path)) !== hybridDigest(missing))
+                refuse("before_scope_changed");
+            for (const item of original.entries)
+                versions.set(item.path, item);
+            for (const name of value.paths) {
+                if (!versions.has(name))
+                    refuse("before_version_required");
+                approved.add(name);
+            }
+            requests.add(value.request_id);
+            records.push(value);
+            revision = hybridDigest({ previous: revision, record: value });
+        }
+        const current = records.at(-1) ?? null, needsRefresh = !current || current.user_inputs_sha256 !== inputs.sha256;
+        return { baseline: baseline.baseline, inputs, records, revision, before_versions: [...versions.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
+            ever_approved_paths: [...approved].sort(), active_paths: needsRefresh ? [] : [...current.paths], needs_scope_refresh: needsRefresh };
+    });
+}
+/** A coordinator's bounded interpretation of actual user input, not an agent
+ * replacement spec or proof of applicability. Dispatch, current file state,
+ * hardening and independent review still belong to ordinary Stage/Work owners. */
+export class PreparedInteractiveMutationScope {
+    #scope;
+    #bundle;
+    #record;
+    #before;
+    constructor(scope, bundle, record, before) {
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#record = structuredClone(record);
+        this.#before = before;
+        Object.freeze(this);
+    }
+    static prepare(context, scope, bundle, proposal) {
+        if (!proposal || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(proposal.requestId) || !digest(proposal.expectedInputsSha256)
+            || typeof proposal.reason !== "string" || !proposal.reason.trim() || proposal.reason.length > 64 * 1024)
+            refuse("invalid_scope_proposal");
+        pathsValid(proposal.paths);
+        const current = readInteractiveMutationScope(context, scope, bundle), prior = current.records.find(item => item.request_id === proposal.requestId);
+        if (prior) {
+            if (prior.user_inputs_sha256 !== proposal.expectedInputsSha256 || hybridDigest(prior.paths) !== hybridDigest(proposal.paths)
+                || hybridDigest(prior.basis) !== hybridDigest(proposal.basis) || prior.reason !== proposal.reason)
+                refuse("scope_request_conflict");
+            return new PreparedInteractiveMutationScope(scope, bundle, prior, null);
+        }
+        if (proposal.expectedInputsSha256 !== current.inputs.sha256)
+            refuse("user_inputs_changed");
+        assertInteractiveUserBasis(proposal.basis, current.inputs);
+        const known = new Set(current.before_versions.map(item => item.path));
+        const before = PreparedInteractiveBeforeVersions.capture(current.baseline, proposal.paths.filter(name => !known.has(name)));
+        const record = { schema_id: "dd-flow/interactive-mutation-scope@1", run_id: scope.runId, bundle_sha256: bundle.sha256,
+            request_id: proposal.requestId, user_inputs_sha256: proposal.expectedInputsSha256, basis: structuredClone(proposal.basis), reason: proposal.reason,
+            paths: [...proposal.paths], before_versions: before.snapshot(), before_sha256: before.sha256, previous_sha256: current.revision };
+        return new PreparedInteractiveMutationScope(scope, bundle, record, before);
+    }
+    snapshot() { return structuredClone(this.#record); }
+    revalidate() { this.#before?.revalidate(); }
+    retain(context) {
+        this.revalidate();
+        return context.db.writeTransaction(() => this.retainPreparedSql(context), "interactive.retainMutationScope");
+    }
+    /** Pair with an actual Stage/Work acceptance writer after outside-writer
+     * physical revalidation. No filesystem observation inside this method. */
+    retainPreparedSql(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        const current = readInteractiveMutationScope(context, this.#scope, this.#bundle), value = this.#record;
+        const prior = current.records.find(item => item.request_id === value.request_id);
+        if (prior) {
+            if (hybridDigest(prior) !== hybridDigest(value))
+                refuse("scope_request_conflict");
+            return { changed: false, scope: current };
+        }
+        assertRunMutationAllowed(context, this.#scope.projectId, this.#scope.runId);
+        if (current.revision !== value.previous_sha256 || current.inputs.sha256 !== value.user_inputs_sha256)
+            refuse("scope_changed_before_acceptance");
+        const run = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle), index = JSON.parse(run.index_json);
+        const stage = index.stage_runs?.filter((item) => item.stage === index.current_stage).at(-1);
+        if (index.current_stage === "review")
+            assertInteractiveCorrectionHistory(readInteractiveWorkHistory(context, this.#scope, this.#bundle), stage?.attempt ?? "try-001");
+        if (!["running", "waiting_for_user"].includes(run.status) || !["preflight", "interactive", "consolidation", "hardening", "review"].includes(index.current_stage)
+            || !stage || !["running", "waiting_for_user", "paused"].includes(stage.status))
+            refuse("scope_stage_required");
+        if (current.inputs.finish_requested) {
+            // Hardening may add a file needed by the original delivered task without
+            // re-asking permission. Applicability is agent-owned and reviewed against
+            // the full current inputs; the finish action alone adds no new scope.
+            if (value.basis.role === "finish" && value.paths.some(name => !current.ever_approved_paths.includes(name)))
+                refuse("finish_does_not_expand_scope");
+        }
+        else if (!["preflight", "interactive"].includes(index.current_stage) || value.basis.role === "finish")
+            refuse("scope_stage_required");
+        appendAudit(context, { projectId: this.#scope.projectId, eventType, payload: value });
+        return { changed: true, scope: readInteractiveMutationScope(context, this.#scope, this.#bundle) };
+    }
+}
+/** Physical working-tree evidence before integration, not semantic approval or
+ * permission to stage/commit. Observe outside the writer, then fence the same
+ * user/scope revision inside the ordinary Stage/Work acceptance transaction. */
+export class PreparedInteractiveWorkspaceChanges {
+    sha256;
+    #scope;
+    #bundle;
+    #selection;
+    #input;
+    #observed;
+    #retainedPaths;
+    constructor(scope, bundle, selection, input, retainedPaths) {
+        if (selection.needs_scope_refresh)
+            refuse("current_scope_required");
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#selection = selection;
+        this.#input = { ...input, env: { ...input.env } };
+        this.#retainedPaths = [...retainedPaths];
+        // Retain explicitly selected paths even when project ignore rules hide new
+        // files. Git visibility alone must not turn an approved edit into no delta.
+        this.#observed = selection.baseline.observeChanges(this.#input, [...selection.active_paths, ...this.#retainedPaths]);
+        const { delta } = this.#observed, allowed = new Set(selection.active_paths);
+        const originals = new Map(selection.before_versions.map(item => [item.path, item]));
+        if (delta.head_changed || delta.index_changed)
+            refuse("git_movement_requires_integration");
+        for (const change of delta.changes) {
+            if (!allowed.has(change.path))
+                refuse("working_change_outside_scope");
+            const original = originals.get(change.path);
+            if (!original || (change.before ? original.kind !== "file" || original.sha256 !== change.before.sha256 || original.mode !== change.before.mode
+                : original.kind !== "missing"))
+                refuse("working_change_before_version_missing");
+            if (change.after && change.after.kind !== "file")
+                refuse("regular_file_scope_required");
+            if (change.after && fs.lstatSync(path.join(this.#input.workspace, change.path)).nlink !== 1)
+                refuse("linked_working_change");
+        }
+        this.sha256 = hybridDigest(this.snapshot());
+        Object.freeze(this);
+    }
+    static prepare(context, scope, bundle, input, retainedPaths = []) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_observation_outside_writer_required");
+        return new PreparedInteractiveWorkspaceChanges(scope, bundle, readInteractiveMutationScope(context, scope, bundle), input, retainedPaths);
+    }
+    snapshot() {
+        return { schema_id: "dd-flow/interactive-workspace-changes@1", run_id: this.#scope.runId,
+            bundle_sha256: this.#bundle.sha256, scope_revision: this.#selection.revision,
+            user_inputs_sha256: this.#selection.inputs.sha256, delta: structuredClone(this.#observed.delta) };
+    }
+    currentSnapshot() { return this.#observed.current.snapshot(); }
+    revalidate() {
+        const observed = this.#selection.baseline.observeChanges(this.#input, [...this.#selection.active_paths, ...this.#retainedPaths]);
+        if (observed.current.sha256 !== this.#observed.current.sha256)
+            refuse("working_changes_changed_before_acceptance");
+        for (const change of observed.delta.changes)
+            if (change.after && fs.lstatSync(path.join(this.#input.workspace, change.path)).nlink !== 1)
+                refuse("linked_working_change");
+    }
+    assertCustody(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        const current = readInteractiveMutationScope(context, this.#scope, this.#bundle);
+        if (current.needs_scope_refresh || current.revision !== this.#selection.revision
+            || current.inputs.sha256 !== this.#selection.inputs.sha256 || current.baseline.sha256 !== this.#selection.baseline.sha256)
+            refuse("working_changes_scope_changed");
+    }
+}

package/dist/services/interactive-request.js

@@ -0,0 +1,287 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareInteractiveRunBundle } from "./interactive-run-bundle.js";
+import { PreparedInteractiveAttachedSession } from "./interactive-attached-session.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { runBundleAuthorityMetadata } from "./runs.js";
+import { readRunStartRequest, runStartPayloadLimit } from "./run-start-custody.js";
+import { nextDescriptorRunId, PreparedDescriptorRunStart } from "./descriptor-run-start.js";
+import { bundledHandlerContext } from "./stage-handlers.js";
+import { PreparedProjectFlowSource } from "./project-flow-source.js";
+import { readInteractiveBundleData } from "./interactive-bundle-data.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { PreparedInteractiveBeforeVersions, restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { observeMemoryGitPolicySelection } from "./memory-init-git-policy.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+const event = "interactive.request", hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+function refuse(reason) {
+    throw new AppError("interactive_request_invalid", "Interactive requires the original retained request and its own RUN", 2, { reason, effect: "no_effect" });
+}
+function selection(input) {
+    return hybridDigest({ source: input.source.sha256, execution: input.execution.sha256, engine: input.engine.manifestSha256,
+        baseline: input.baseline.sha256, before: input.beforeVersions.sha256, request: input.requestText,
+        git: input.gitExecutable, policy: input.gitPolicy, receipts: [...input.receipts ?? []],
+        ...(input.launchSelection !== undefined ? { launch_selection: input.launchSelection } : {}),
+        receipt_bytes: [...input.receiptBytes ?? []].map(([key, bytes]) => [key, Buffer.from(bytes).toString("base64")]) });
+}
+/** Allocation can choose a different free RUN ID without changing any selected
+ * task data. Only the engine binding's RUN field is allocation-local. */
+function bundleSelection(manifest, scope) {
+    return hybridDigest({ flow_id: manifest.flow_id, scope, descriptor: manifest.descriptor,
+        execution_settings: manifest.execution_settings, profile_settings: manifest.profile_settings,
+        engine_manifest: manifest.engine_manifest, engine_binding_path: manifest.engine_binding.path,
+        canon: manifest.canon, project_pack: manifest.project_pack, bootstrap_receipts: manifest.bootstrap_receipts,
+        inventory: manifest.inventory.filter(item => item.path !== manifest.engine_binding.path) });
+}
+function decode(value, limit) {
+    if (typeof value !== "string" || value.length > Math.ceil(limit / 3) * 4)
+        refuse("invalid_request_bytes");
+    const bytes = Buffer.from(value, "base64");
+    if (!bytes.length || bytes.length > limit || bytes.toString("base64") !== value)
+        refuse("invalid_request_bytes");
+    return bytes;
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_request_json");
+    }
+}
+/** SQL/data only, including when called by the allocation writer. Full engine,
+ * compiled schema and physical workspace admission happens outside the writer. */
+export function readInteractiveRequest(context, { projectRoot, requestId }) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("invalid_request_id");
+    const scope = { projectRoot, requestId }, project = context.db.get("SELECT id FROM projects WHERE root=? AND status='active'", [projectRoot]);
+    if (!project)
+        refuse("project_not_registered");
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.scope.requestId')=? LIMIT 2", [project.id, event, requestId]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > runStartPayloadLimit)
+        refuse("ambiguous_or_unbounded_request");
+    const value = json(Buffer.from(rows[0].payload_json));
+    if (!value || Object.keys(value).sort().join() !== "admission_json,admission_sha256,blobs,bound_at,bundle_selection_sha256,manifest_base64,manifest_sha256,project_id,schema_id,scope,selection_sha256,source_sha256"
+        || value.schema_id !== "dd-flow/interactive-request@1" || value.project_id !== project.id || hybridDigest(value.scope) !== hybridDigest(scope)
+        || ![value.selection_sha256, value.bundle_selection_sha256, value.source_sha256, value.manifest_sha256, value.admission_sha256].every(digest)
+        || typeof value.bound_at !== "string" || !Number.isFinite(Date.parse(value.bound_at))
+        || typeof value.admission_json !== "string" || Buffer.byteLength(value.admission_json) > 1024 * 1024
+        || !Array.isArray(value.blobs) || value.blobs.length > 4096)
+        refuse("request_scope_changed");
+    const bytes = decode(value.manifest_base64, 1024 * 1024), manifest = json(bytes);
+    const admission = json(Buffer.from(value.admission_json));
+    if (hash(bytes) !== value.manifest_sha256 || hybridDigest(admission) !== value.admission_sha256
+        || !manifest || manifest.schema_id !== "dd-flow/execution-bundle@1" || manifest.flow_id !== "interactive"
+        || !Array.isArray(manifest.inventory) || manifest.inventory.length !== value.blobs.length
+        || manifest.inventory.some(item => !item || typeof item.path !== "string" || !digest(item.sha256))
+        || typeof manifest.engine_binding?.path !== "string"
+        || !Array.isArray(manifest.bootstrap_receipts) || manifest.bootstrap_receipts.length
+        || !admission?.executionScope || admission.executionScope.projectRoot !== projectRoot || admission.executionScope.requestId !== requestId
+        || bundleSelection(manifest, admission.executionScope) !== value.bundle_selection_sha256)
+        refuse("retained_bundle_changed");
+    const refs = new Map(manifest.inventory.map(item => [item.path, item.sha256])), names = new Set();
+    let total = 0;
+    for (const item of value.blobs) {
+        if (!item || Object.keys(item).sort().join() !== "base64,path" || typeof item.path !== "string" || names.has(item.path))
+            refuse("retained_blob_inventory_changed");
+        const content = decode(item.base64, 1024 * 1024);
+        total += content.length;
+        if (total > 32 * 1024 * 1024 || hash(content) !== refs.get(item.path))
+            refuse("retained_blob_changed");
+        names.add(item.path);
+    }
+    return value;
+}
+/** Compare supplied launch selectors with retained raw intent, not today's
+ * aliases/defaults or a newly observed equivalent model. Omission preserves the
+ * original selection. This reads only the independently validated request. */
+export function assertInteractiveLaunchReplay(context, scope, supplied) {
+    const request = readInteractiveRequest(context, scope);
+    if (!request)
+        refuse("original_request_required");
+    const blob = (name) => {
+        const selected = request.blobs.find(item => item.path === name);
+        if (!selected)
+            refuse("original_launch_selection_required");
+        return Buffer.from(selected.base64, "base64");
+    };
+    const admission = json(Buffer.from(request.admission_json));
+    if (supplied.workspace !== undefined && supplied.workspace !== admission.executionScope.workspace
+        || supplied.requestText !== undefined && !Buffer.from(supplied.requestText).equals(blob("runtime/source-request.md")))
+        refuse("launch_inputs_changed");
+    if (supplied.gitPolicy !== undefined) {
+        const frozen = json(blob("runtime/git-policy.json"));
+        if (hybridDigest(supplied.gitPolicy) !== hybridDigest({ route: frozen.policy.route, integrationBranch: frozen.policy.integration_branch }))
+            refuse("launch_inputs_changed");
+    }
+    const selectors = supplied.launchSelection;
+    if (selectors && Object.keys(selectors).length) {
+        const original = json(blob("runtime/launch-selection.json"));
+        if (Object.entries(selectors).some(([key, value]) => !Object.hasOwn(original, key)
+            || hybridDigest(value) !== hybridDigest(original[key])))
+            refuse("launch_inputs_changed");
+    }
+    return request;
+}
+/** Called with compiled bundle admission already complete. No filesystem or
+ * handler/schema loading: this fence also protects the allocation transaction. */
+export function assertInteractiveRequestBundle(context, projectId, bundle) {
+    const frozen = bundle.execution.snapshot(), request = readInteractiveRequest(context, frozen.scope);
+    if (!request || request.project_id !== projectId || bundle.manifest.flow_id !== "interactive"
+        || bundleSelection(bundle.manifest, frozen.scope) !== request.bundle_selection_sha256)
+        refuse("request_bundle_changed");
+    const binding = json(bundle.blob(bundle.manifest.engine_binding.path));
+    const original = request.blobs.find(item => item.path === bundle.manifest.engine_binding.path);
+    const initial = original ? json(Buffer.from(original.base64, "base64")) : null;
+    if (!initial || binding.run_id !== bundle.manifest.run_id || binding.bound_at !== request.bound_at
+        || hybridDigest({ ...binding, run_id: null }) !== hybridDigest({ ...initial, run_id: null }))
+        refuse("allocation_binding_changed");
+}
+/** Freeze once before allocation. Attached hook claim and request insertion
+ * share one writer; replay never creates another claim, RUN or input capture. */
+export function retainInteractiveRequest(context, input, attached) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const frozen = input.execution.snapshot(), scope = { projectRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId };
+    const project = requireProjectByRoot(context, scope.projectRoot), chosen = selection(input), prior = readInteractiveRequest(context, scope);
+    if (prior) {
+        if (prior.selection_sha256 !== chosen)
+            refuse("request_changed");
+        return prior;
+    }
+    if (readRunStartRequest(context, project.id, scope.requestId))
+        refuse("foreign_run_request");
+    if (frozen.settings.execution === "attached") {
+        if (!(attached instanceof PreparedInteractiveAttachedSession) || hybridDigest(attached.snapshot().scope) !== hybridDigest(frozen.scope)
+            || hybridDigest(attached.evidence().reference) !== hybridDigest(frozen.settings.attached_session_receipt))
+            refuse("trusted_attached_selection_required");
+    }
+    else if (attached)
+        refuse("foreign_attached_selection");
+    const bundle = prepareInteractiveRunBundle(context, input), metadata = runBundleAuthorityMetadata(bundle);
+    const value = { schema_id: "dd-flow/interactive-request@1", project_id: project.id, scope,
+        selection_sha256: chosen, bundle_selection_sha256: bundleSelection(bundle.manifest, frozen.scope), source_sha256: input.source.sha256,
+        bound_at: input.boundAt, manifest_base64: bundle.manifestBytes().toString("base64"), manifest_sha256: bundle.sha256,
+        admission_json: metadata.admissionJson, admission_sha256: metadata.anchor.admission_sha256,
+        blobs: bundle.manifest.inventory.map(ref => ({ path: ref.path, base64: bundle.blob(ref.path).toString("base64") })) };
+    if (Buffer.byteLength(JSON.stringify(value)) > runStartPayloadLimit)
+        refuse("request_exceeds_bound");
+    return context.db.writeTransaction(() => {
+        const current = readInteractiveRequest(context, scope);
+        if (current) {
+            if (current.selection_sha256 !== chosen)
+                refuse("request_changed");
+            return current;
+        }
+        if (readRunStartRequest(context, project.id, scope.requestId))
+            refuse("foreign_run_request");
+        attached?.retainPreparedSql(context);
+        appendAudit(context, { projectId: project.id, eventType: event, payload: value });
+        const retained = readInteractiveRequest(context, scope);
+        if (!retained)
+            refuse("request_readback_missing");
+        return retained;
+    }, "interactive.retainRequest");
+}
+/** Restore initial data from request custody, never current defaults, files or
+ * global canon. Generic admission still checks actual selected engine bytes. */
+function restoreBundle(request) {
+    const admission = json(Buffer.from(request.admission_json));
+    if (!Array.isArray(admission.receipts) || admission.receipts.some(item => !Array.isArray(item) || item.length !== 2 || !digest(item[0]))
+        || new Set(admission.receipts.map(item => item[0])).size !== admission.receipts.length)
+        refuse("invalid_retained_execution_receipts");
+    return RetainedExecutionBundle.admit(decode(request.manifest_base64, 1024 * 1024), request.manifest_sha256, new Map(request.blobs.map(item => [item.path, Buffer.from(item.base64, "base64")])), { ...admission, receipts: new Map(admission.receipts), descriptorContext: bundledHandlerContext(new Map()) });
+}
+function bindRunId(bundle, runId) {
+    if (bundle.manifest.run_id === runId)
+        return bundle;
+    const manifest = structuredClone(bundle.manifest), admission = bundle.admission();
+    const binding = json(bundle.blob(manifest.engine_binding.path));
+    binding.run_id = runId;
+    const bytes = Buffer.from(JSON.stringify(binding)), sha256 = hash(bytes);
+    const blobs = new Map(manifest.inventory.map(ref => [ref.path, bundle.blob(ref.path)]));
+    blobs.set(manifest.engine_binding.path, bytes);
+    manifest.run_id = runId;
+    manifest.engine_binding.sha256 = sha256;
+    for (const ref of manifest.inventory)
+        if (ref.path === manifest.engine_binding.path)
+            ref.sha256 = sha256;
+    const encoded = Buffer.from(JSON.stringify(manifest));
+    return RetainedExecutionBundle.admit(encoded, hash(encoded), blobs, { ...admission, runId, engineBindingSha256: sha256 });
+}
+function revalidateBeforeAllocation(context, request, bundle) {
+    const scope = bundle.execution.snapshot().scope, manifestBytes = bundle.blob("project-pack/manifest.json");
+    const pack = json(manifestBytes);
+    if (!Array.isArray(pack.included_files))
+        refuse("invalid_retained_project_pack");
+    const source = PreparedProjectFlowSource.restoreRetained({ schema_id: "dd-flow/project-flow-source@1",
+        scope: { projectRoot: scope.projectRoot, workspace: scope.workspace, flowId: "interactive" },
+        blobs: ["project-pack/manifest.json", ...pack.included_files].map(name => ({ path: name, base64: bundle.blob(name).toString("base64") })) }, request.source_sha256);
+    if (hybridDigest(source.projectPackProvenance()) !== hybridDigest(bundle.manifest.project_pack))
+        refuse("retained_project_pack_changed");
+    bundle.engine().admitInteractiveFlow(source);
+    if (bundle.execution.settings.execution === "attached") {
+        const attached = PreparedInteractiveAttachedSession.restore(context, scope);
+        if (hybridDigest(attached.evidence().reference) !== hybridDigest(bundle.execution.settings.attached_session_receipt))
+            refuse("retained_attached_selection_changed");
+    }
+    revalidateInteractiveEntryWorkspace(context, bundle);
+}
+/** Shared RUN-start physical fence. Git porcelain can remain unchanged while
+ * an already-dirty file's content changes, so status alone is insufficient. */
+export function revalidateInteractiveEntryWorkspace(context, bundle) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("physical_revalidation_outside_writer_required");
+    if (bundle.manifest.flow_id !== "interactive")
+        refuse("interactive_bundle_required");
+    const scope = bundle.execution.snapshot().scope;
+    const policy = json(bundle.blob("runtime/git-policy.json"));
+    if (hybridDigest(policy.scope) !== hybridDigest({ requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace })
+        || hash(readBoundedReleaseFile(policy.git_executable, 64 * 1024 * 1024)) !== policy.git_sha256)
+        refuse("retained_git_selection_changed");
+    const observed = observeMemoryGitPolicySelection(context.env, { scope: policy.scope, gitExecutable: policy.git_executable,
+        selection: { route: policy.policy.route, integrationBranch: policy.policy.integration_branch } });
+    if (hybridDigest(observed) !== hybridDigest(policy.policy))
+        refuse("git_policy_changed_before_allocation");
+    const retained = readInteractiveBundleData(bundle, "runtime/git-baseline.json"), before = readInteractiveBundleData(bundle, "runtime/before-versions.json");
+    const baseline = PreparedInteractiveGitBaseline.restore(retained.bytes, retained.sha256);
+    const versions = restoreInteractiveBeforeVersions(before.bytes, before.sha256, baseline);
+    // Physical equality check only. Retained before-images remain authoritative;
+    // later current bytes cannot replace the original evidence on retry.
+    const current = (() => {
+        try {
+            return PreparedInteractiveBeforeVersions.capture(baseline, versions.entries.map(item => item.path));
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            return refuse("before_versions_unavailable_before_allocation");
+        }
+    })();
+    if (current.sha256 !== before.sha256)
+        refuse("before_versions_changed_before_allocation");
+    baseline.revalidate({ projectRoot: scope.projectRoot, workspace: scope.workspace, gitExecutable: policy.git_executable, env: context.env });
+}
+export function startInteractiveRun(context, scope) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const request = readInteractiveRequest(context, scope);
+    if (!request)
+        refuse("original_request_required");
+    const allocation = readRunStartRequest(context, request.project_id, scope.requestId);
+    if (allocation) {
+        if (allocation.payload.initial_index.flow_kind !== "interactive")
+            refuse("foreign_run_request");
+        return PreparedDescriptorRunStart.restore(context, scope).apply(context);
+    }
+    const bundle = bindRunId(restoreBundle(request), nextDescriptorRunId(context, { ...scope, slug: "interactive" }));
+    assertInteractiveRequestBundle(context, request.project_id, bundle);
+    revalidateBeforeAllocation(context, request, bundle);
+    return PreparedDescriptorRunStart.prepare(context, { bundle }).apply(context);
+}

package/dist/services/interactive-run-bundle.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { PreparedProjectFlowSource } from "./project-flow-source.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { PreparedInteractiveBeforeVersions, restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { putInteractiveBundleData } from "./interactive-bundle-data.js";
+import { observeMemoryGitPolicySelection } from "./memory-init-git-policy.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { nextDescriptorRunId } from "./descriptor-run-start.js";
+import { bundledHandlerContext } from "./stage-handlers.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const encode = (value) => Buffer.from(JSON.stringify(value));
+function refuse(reason) {
+    throw new AppError("interactive_run_bundle_invalid", "Interactive requires its original request, project pack, workspace and execution selection", 2, { reason, effect: "no_effect" });
+}
+/** Initial assembly only, outside the writer. Creates no RUN, workspace or
+ * Session and grants no file/Git mutation. The request owner must retain this
+ * exact bundle before allocation; retries restore it, never recapture state. */
+export function prepareInteractiveRunBundle(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    if (!(input.source instanceof PreparedProjectFlowSource) || !(input.execution instanceof FrozenGenericExecution)
+        || !(input.engine instanceof AdmittedFrozenEngine) || !(input.baseline instanceof PreparedInteractiveGitBaseline)
+        || !(input.beforeVersions instanceof PreparedInteractiveBeforeVersions) || !Number.isFinite(Date.parse(input.boundAt)))
+        refuse("unprepared_selection");
+    if (typeof input.requestText !== "string" || !input.requestText.trim() || Buffer.byteLength(input.requestText) > 64 * 1024)
+        refuse("original_request_required");
+    const frozen = input.execution.snapshot(), flow = input.source.resolveRegisteredFlow(), sourceScope = input.source.scope();
+    if (frozen.settings.flow_id !== "interactive" || flow.descriptor.id !== "interactive" || flow.descriptor.origin !== "project"
+        || flow.sha256 !== frozen.settings.descriptor_sha256)
+        refuse("flow_selection_changed");
+    const baseline = input.baseline.snapshot();
+    if (sourceScope.projectRoot !== frozen.scope.projectRoot || sourceScope.workspace !== frozen.scope.workspace
+        || baseline.project_root !== frozen.scope.projectRoot || baseline.workspace !== frozen.scope.workspace)
+        refuse("workspace_selection_changed");
+    // Before-images from another baseline are not interchangeable, even when the
+    // selected paths happen to match. Empty initial images are valid before scope.
+    restoreInteractiveBeforeVersions(input.beforeVersions.bytes(), input.beforeVersions.sha256, input.baseline);
+    input.engine.admitInteractiveFlow(input.source);
+    if (!path.isAbsolute(input.gitExecutable))
+        refuse("absolute_git_executable_required");
+    const gitExecutable = fs.realpathSync(input.gitExecutable), gitSha256 = hash(readBoundedReleaseFile(gitExecutable, 64 * 1024 * 1024));
+    const gitScope = { requestId: frozen.scope.requestId, projectRoot: frozen.scope.projectRoot, workspaceRoot: frozen.scope.workspace };
+    const policy = observeMemoryGitPolicySelection(context.env, { scope: gitScope, gitExecutable, selection: input.gitPolicy });
+    if (policy.repository !== baseline.repository || policy.workspace_branch !== baseline.branch || policy.initial_head !== baseline.head)
+        refuse("git_policy_baseline_changed");
+    const manifest = input.engine.manifest(), checksum = manifest.integrity.checksum;
+    if (typeof checksum !== "string")
+        refuse("engine_identity_missing");
+    const runId = nextDescriptorRunId(context, { projectRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, slug: "interactive" });
+    const binding = { schema_id: "dd-flow/run-engine-binding@1", run_id: runId,
+        project_root: frozen.scope.projectRoot, bound_at: input.boundAt, source: "run_creation", reason: "Request-bound interactive work with explicit same-RUN finish",
+        engine: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
+            integrity_checksum: checksum, snapshot_root: manifest.snapshot_root }, probe: { status: "not_required", command: null } };
+    const blobs = input.source.blobs();
+    const put = (logical, bytes) => {
+        if ([...blobs.keys()].some(name => name.toLowerCase() === logical.toLowerCase()) || !bytes.length || bytes.length > 1024 * 1024)
+            refuse("bundle_path_collision_or_size");
+        blobs.set(logical, bytes);
+        return { path: logical, sha256: hash(bytes) };
+    };
+    put("runtime/source-request.md", Buffer.from(input.requestText));
+    if (input.launchSelection !== undefined) {
+        if (!input.launchSelection || typeof input.launchSelection !== "object" || Array.isArray(input.launchSelection)
+            || Object.keys(input.launchSelection).some(key => !["rootProfile", "stageProfiles", "workProfiles", "execution", "stageSessionMode", "delegation"].includes(key)))
+            refuse("invalid_launch_selection");
+        // Raw selectors are replay intent, not execution authority. FrozenGenericExecution
+        // remains the only owner of resolved profiles and Session/delegation settings.
+        put("runtime/launch-selection.json", encode(input.launchSelection));
+    }
+    put("runtime/git-policy.json", encode({ schema_id: "dd-flow/interactive-git-policy@1", scope: gitScope,
+        git_executable: gitExecutable, git_sha256: gitSha256, policy }));
+    for (const reference of [frozen.settings.attached_session_receipt, frozen.settings.delegation.native_capacity_receipt]) {
+        if (!reference)
+            continue;
+        const bytes = input.receiptBytes?.get(reference.sha256);
+        if (!bytes || hash(bytes) !== reference.sha256 || !input.receipts?.has(reference.sha256))
+            refuse("execution_receipt_missing");
+        put(reference.path, Buffer.from(bytes));
+    }
+    const profiles = { schema_id: "dd-flow/profile-settings@1", profiles: frozen.profiles, aliases: {}, default_profile: null };
+    const profile = put("runtime/profiles.json", encode({ ...profiles, revision: hybridDigest(profiles) }));
+    const execution = put("runtime/execution.json", encode(frozen.settings));
+    const engineBinding = put("runtime/engine-binding.json", encode(binding));
+    const engineManifest = put("runtime/engine-manifest.json", input.engine.manifestBytes());
+    putInteractiveBundleData(blobs, "runtime/git-baseline.json", input.baseline.bytes());
+    putInteractiveBundleData(blobs, "runtime/before-versions.json", input.beforeVersions.bytes());
+    const provenance = { canon: input.source.canonProvenance(), project_pack: input.source.projectPackProvenance() };
+    const bundle = { schema_id: "dd-flow/execution-bundle@1", run_id: runId, flow_id: "interactive",
+        descriptor: input.source.descriptorReference(), execution_settings: execution, profile_settings: profile,
+        engine_binding: engineBinding, engine_manifest: engineManifest, bootstrap_receipts: [], ...provenance,
+        inventory: [...blobs].map(([logical, bytes]) => ({ path: logical, sha256: hash(bytes) })) };
+    input.source.revalidate();
+    input.beforeVersions.revalidate();
+    input.baseline.revalidate({ projectRoot: frozen.scope.projectRoot, workspace: frozen.scope.workspace, gitExecutable, env: context.env });
+    if (hash(readBoundedReleaseFile(gitExecutable, 64 * 1024 * 1024)) !== gitSha256)
+        refuse("selected_git_changed");
+    const bytes = encode(bundle);
+    return RetainedExecutionBundle.admit(bytes, hash(bytes), blobs, { runId, executionScope: frozen.scope,
+        bundleProjectRoot: frozen.scope.projectRoot, descriptorSha256: flow.sha256, engineChecksum: checksum,
+        engineBindingSha256: engineBinding.sha256, engineManifestSha256: engineManifest.sha256,
+        descriptorContext: bundledHandlerContext(new Map()), bundleProvenance: provenance, receipts: input.receipts ?? new Map() });
+}