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

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

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_git_baseline_invalid", "Interactive needs its actual project/workspace Git baseline", 2, { reason, effect: "no_effect" });
+}
+function logical(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 4096 && !value.includes("\\") && !value.includes("\0")
+        && !path.isAbsolute(value) && value.split("/").every(part => part && part !== "." && part !== ".." && part !== ".git");
+}
+/** Hash regular files incrementally: large assets do not require a second full
+ * in-memory copy. Do not follow symlinks, read FIFOs or invoke Git clean filters. */
+function entry(root, name) {
+    const file = path.join(root, name);
+    let parent = root;
+    for (const part of name.split("/").slice(0, -1)) {
+        parent = path.join(parent, part);
+        try {
+            if (!fs.lstatSync(parent).isDirectory())
+                return { path: name, kind: "missing", mode: null, sha256: null };
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { path: name, kind: "missing", mode: null, sha256: null };
+            throw error;
+        }
+    }
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path: name, kind: "missing", mode: null, sha256: null };
+        throw error;
+    }
+    const mode = stat.mode & 0o7777;
+    if (stat.isSymbolicLink())
+        return { path: name, kind: "link", mode, sha256: hash(fs.readlinkSync(file, { encoding: "buffer" })) };
+    // Gitlinks/submodules are opaque. Their nested working tree is not included
+    // in this parent repository's git-visible scope or a writable-file delta.
+    if (stat.isDirectory())
+        return { path: name, kind: "directory", mode, sha256: null };
+    if (!stat.isFile())
+        refuse("special_file");
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = fs.fstatSync(fd, { bigint: true }), digest = createHash("sha256"), buffer = Buffer.allocUnsafe(256 * 1024);
+        if (before.dev !== BigInt(stat.dev) || before.ino !== BigInt(stat.ino) || !before.isFile())
+            refuse("file_changed_during_capture");
+        let length = 0n;
+        for (;;) {
+            const count = fs.readSync(fd, buffer, 0, buffer.length, null);
+            if (!count)
+                break;
+            digest.update(buffer.subarray(0, count));
+            length += BigInt(count);
+        }
+        const after = fs.fstatSync(fd, { bigint: true });
+        if (length !== before.size || after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs)
+            refuse("file_changed_during_capture");
+        return { path: name, kind: "file", mode, sha256: digest.digest("hex") };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function stamp(root, name) {
+    try {
+        let parent = root;
+        for (const part of name.split("/").slice(0, -1)) {
+            parent = path.join(parent, part);
+            if (!fs.lstatSync(parent).isDirectory())
+                return null;
+        }
+        const value = fs.lstatSync(path.join(root, name), { bigint: true });
+        return [value.dev, value.ino, value.mode, value.size, value.mtimeNs, value.ctimeNs].map(String);
+    }
+    catch (error) {
+        if (["ENOENT", "ENOTDIR"].includes(error.code ?? ""))
+            return null;
+        throw error;
+    }
+}
+function observe(input, retainedPaths = []) {
+    if (!path.isAbsolute(input.gitExecutable))
+        refuse("absolute_git_executable_required");
+    for (const root of [input.projectRoot, input.workspace]) {
+        if (!path.isAbsolute(root) || fs.realpathSync(root) !== root || !fs.lstatSync(root).isDirectory())
+            refuse("canonical_workspace_required");
+    }
+    const env = { ...Object.fromEntries(Object.entries(input.env).filter(([key]) => !key.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0" };
+    const git = (root, args, absent = false) => {
+        const result = spawnSync(input.gitExecutable, ["-c", "core.fsmonitor=false", "-C", root, ...args], { env, timeout: 15000, maxBuffer: 32 * 1024 * 1024 });
+        if (result.error || result.signal || result.status !== 0 && !(absent && [1, 128].includes(result.status ?? -1)))
+            refuse("git_observation_failed");
+        return result.status === 0 ? result.stdout : null;
+    };
+    const text = (root, args, absent = false) => git(root, args, absent)?.toString("utf8").trim() ?? null;
+    const repository = fs.realpathSync(text(input.projectRoot, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+    if (fs.realpathSync(text(input.workspace, ["rev-parse", "--path-format=absolute", "--git-common-dir"])) !== repository
+        || text(input.projectRoot, ["rev-parse", "--show-toplevel"]) !== input.projectRoot
+        || text(input.workspace, ["rev-parse", "--show-toplevel"]) !== input.workspace)
+        refuse("foreign_workspace_repository");
+    if (git(input.workspace, ["ls-files", "--unmerged", "-z"]).length)
+        refuse("unmerged_index");
+    const identity = fs.statSync(input.workspace);
+    const meta = () => {
+        const index = text(input.workspace, ["rev-parse", "--path-format=absolute", "--git-path", "index"]);
+        let indexHash = null;
+        try {
+            indexHash = hash(fs.readFileSync(index));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        return { head: text(input.workspace, ["rev-parse", "--verify", "HEAD"], true), branch: text(input.workspace, ["symbolic-ref", "--quiet", "--short", "HEAD"], true),
+            index_sha256: indexHash, status_base64: git(input.workspace, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignore-submodules=all"]).toString("base64") };
+    };
+    const names = () => {
+        const bytes = git(input.workspace, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]);
+        let value;
+        try {
+            value = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            return refuse("non_utf8_file_name");
+        }
+        const items = [...new Set(value.split("\0").filter(Boolean))].sort();
+        if (items.length > 200_000 || items.some(name => !logical(name)))
+            refuse("unsafe_or_unbounded_inventory");
+        return items;
+    };
+    const before = meta(), visible = names(), paths = [...new Set([...visible, ...retainedPaths])].sort();
+    if (paths.length > 200_000 || paths.some(name => !logical(name)))
+        refuse("unsafe_or_unbounded_inventory");
+    const stamps = paths.map(name => stamp(input.workspace, name)), entries = paths.map(name => entry(input.workspace, name));
+    const currentRoot = fs.statSync(input.workspace);
+    if (identity.dev !== currentRoot.dev || identity.ino !== currentRoot.ino || hybridDigest(stamps) !== hybridDigest(paths.map(name => stamp(input.workspace, name)))
+        || hybridDigest(before) !== hybridDigest(meta()) || hybridDigest(visible) !== hybridDigest(names()))
+        refuse("workspace_changed_during_capture");
+    return { schema_id: "dd-flow/interactive-git-baseline@1", project_root: input.projectRoot, workspace: input.workspace,
+        repository, workspace_identity: { dev: identity.dev, ino: identity.ino }, ...before, visibility: "git-visible-and-retained@1", entries };
+}
+/** Read-only physical baseline, not permission to edit/commit existing dirty
+ * files. The RUN owner must retain this in its admitted bundle before work.
+ * Ignored files and opaque submodule contents are explicitly outside visibility. */
+export class PreparedInteractiveGitBaseline {
+    sha256;
+    #value;
+    constructor(value) {
+        if (Buffer.byteLength(JSON.stringify(value)) > 32 * 1024 * 1024)
+            refuse("unbounded_baseline");
+        this.#value = structuredClone(value);
+        this.sha256 = hash(Buffer.from(JSON.stringify(value)));
+        Object.freeze(this);
+    }
+    static capture(input) { return new PreparedInteractiveGitBaseline(observe(input)); }
+    /** Parsing only. Expected bytes/hash must come from the RUN's admitted bundle,
+     * not a caller's self-hashed replacement or a current project observation. */
+    static restore(bytes, expectedSha256) {
+        if (!bytes.length || bytes.length > 32 * 1024 * 1024 || !/^[a-f0-9]{64}$/.test(expectedSha256) || hash(bytes) !== expectedSha256)
+            refuse("retained_baseline_changed");
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch {
+            return refuse("invalid_retained_baseline");
+        }
+        const checksum = (item) => typeof item === "string" && /^[a-f0-9]{64}$/.test(item);
+        if (!value || Object.keys(value).sort().join() !== "branch,entries,head,index_sha256,project_root,repository,schema_id,status_base64,visibility,workspace,workspace_identity"
+            || value.schema_id !== "dd-flow/interactive-git-baseline@1" || value.visibility !== "git-visible-and-retained@1"
+            || [value.project_root, value.workspace, value.repository].some(item => typeof item !== "string" || !path.isAbsolute(item))
+            || !value.workspace_identity || Object.keys(value.workspace_identity).sort().join() !== "dev,ino"
+            || Object.values(value.workspace_identity).some(item => !Number.isSafeInteger(item) || item < 0)
+            || value.branch !== null && (typeof value.branch !== "string" || !value.branch)
+            || value.head !== null && (typeof value.head !== "string" || !/^[a-f0-9]{40,64}$/.test(value.head))
+            || value.index_sha256 !== null && !checksum(value.index_sha256)
+            || typeof value.status_base64 !== "string" || Buffer.from(value.status_base64, "base64").toString("base64") !== value.status_base64
+            || !Array.isArray(value.entries) || value.entries.length > 200_000)
+            refuse("invalid_retained_baseline");
+        let previous = "";
+        for (const item of value.entries) {
+            if (!item || Object.keys(item).sort().join() !== "kind,mode,path,sha256" || !logical(item.path) || item.path <= previous
+                || !["file", "link", "directory", "missing"].includes(item.kind)
+                || (item.kind === "missing" ? item.mode !== null : !Number.isInteger(item.mode) || item.mode < 0 || item.mode > 0o7777)
+                || (["file", "link"].includes(item.kind) ? !checksum(item.sha256) : item.sha256 !== null))
+                refuse("invalid_retained_inventory");
+            previous = item.path;
+        }
+        const restored = new PreparedInteractiveGitBaseline(value);
+        if (restored.sha256 !== expectedSha256)
+            refuse("retained_baseline_changed");
+        return restored;
+    }
+    snapshot() { return structuredClone(this.#value); }
+    bytes() { return Buffer.from(JSON.stringify(this.#value)); }
+    revalidate(input) {
+        if (PreparedInteractiveGitBaseline.capture(input).sha256 !== this.sha256)
+            refuse("baseline_changed_before_retention");
+    }
+    observeChanges(input, retainedPaths = []) {
+        const current = new PreparedInteractiveGitBaseline(observe(input, [...this.#value.entries.map(item => item.path), ...retainedPaths]));
+        return { current, delta: this.changes(current) };
+    }
+    /** Exact working-file delta relative to entry, not HEAD. Pre-existing dirty
+     * content is not automatically attributed to this interactive RUN. Git/index
+     * movement is reported separately, never silently approved as integration. */
+    changes(current) {
+        const before = this.#value, after = current.#value;
+        if (before.project_root !== after.project_root || before.workspace !== after.workspace || before.repository !== after.repository
+            || hybridDigest(before.workspace_identity) !== hybridDigest(after.workspace_identity) || before.branch !== after.branch)
+            refuse("workspace_identity_changed");
+        const left = new Map(before.entries.map(item => [item.path, item])), right = new Map(after.entries.map(item => [item.path, item]));
+        if ([...left.keys()].some(name => !right.has(name)))
+            refuse("baseline_paths_not_observed");
+        const changes = [...new Set([...left.keys(), ...right.keys()])].sort().flatMap(name => {
+            const old = left.get(name)?.kind === "missing" ? null : left.get(name) ?? null, next = right.get(name)?.kind === "missing" ? null : right.get(name) ?? null;
+            return hybridDigest(old) === hybridDigest(next) ? [] : [{ path: name, before: old, after: next }];
+        });
+        return { baseline_sha256: this.sha256, current_sha256: current.sha256, changes,
+            head_changed: before.head !== after.head, index_changed: before.index_sha256 !== after.index_sha256 };
+    }
+}

package/dist/services/interactive-git-dispatch.js

@@ -0,0 +1,278 @@
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { readInteractiveStageScope } from "./interactive-stage-entry.js";
+import { prepareInteractiveReviewedGitInputs } from "./interactive-finish-integration.js";
+import { readInteractiveWorkGit } from "./interactive-work-start.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readActiveDescriptorStageCoordinator } from "./descriptor-stage-settlement.js";
+import { integrateReviewedProjectFiles } from "./memory-finish-integration.js";
+import { observeReviewedProjectGitIntegration } from "./project-git-integration.js";
+const event = "interactive.integration_operation", phaseEvent = "interactive.integration_intent", anchorPath = '$.variables."interactive.integration"';
+function refuse(reason) {
+    throw new AppError("interactive_git_dispatch_invalid", "Interactive Git requires its original reviewed operation and active coordinator", 2, { reason, effect: "no_effect" });
+}
+function pending(reason) {
+    throw new AppError("interactive_integration_pending", "Reconcile the original Git effect before dispatching again", 2, { reason, effect: "unknown", recoverable: true, next_action: "reconcile_original_integration" });
+}
+function stored(context, scope) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.plan.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+    const phases = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? ORDER BY id LIMIT 3", [scope.projectId, phaseEvent, scope.runId]);
+    const anchor = context.db.get("SELECT json_extract(index_json,?) value FROM runs WHERE project_id=? AND id=?", [anchorPath, scope.projectId, scope.runId])?.value;
+    if (rows.length > 1 || phases.length > 2 || rows.some(row => Buffer.byteLength(row.payload_json) > 96 * 1024 * 1024)
+        || phases.some(row => Buffer.byteLength(row.payload_json) > 16384) || !!rows.length !== !!anchor || !rows.length && phases.length)
+        pending("integration_custody_lost");
+    if (!rows.length)
+        return { operation: null, phases: [] };
+    let operation, intent, value;
+    try {
+        operation = JSON.parse(rows[0].payload_json);
+        intent = phases.map(row => JSON.parse(row.payload_json));
+        value = JSON.parse(anchor);
+    }
+    catch {
+        return pending("integration_custody_invalid");
+    }
+    if (operation?.plan?.schema_id !== "dd-flow/interactive-git-operation@1" || operation.plan.run_id !== scope.runId
+        || operation.identity !== hybridDigest(operation.plan) || value.identity !== operation.identity || hybridDigest(value.phases) !== hybridDigest(intent)
+        || new Set(intent.map(item => item.phase)).size !== intent.length
+        || intent.some(item => item.run_id !== scope.runId || item.identity !== operation.identity || !["commit", "merge"].includes(item.phase)
+            || typeof item.baseline !== "string" || item.baseline !== "" && !/^[a-f0-9]{40,64}$/.test(item.baseline))
+        || intent.length === 2 && (intent[0].phase !== "commit" || intent[1].phase !== "merge"))
+        pending("integration_custody_changed");
+    return { operation, phases: intent };
+}
+function gitReader(context, plan) {
+    const env = { ...Object.fromEntries(Object.entries(context.env).filter(([name]) => !name.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0", GIT_LITERAL_PATHSPECS: "1" };
+    return (args, root = plan.reviewed.policy.scope.workspaceRoot) => {
+        const result = spawnSync(plan.reviewed.policy.git_executable, ["-c", "core.fsmonitor=false", "-C", root, ...args], { env, timeout: 10000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            pending("original_git_readback_failed");
+        return args.includes("-z") ? result.stdout.toString("utf8") : result.stdout.toString("utf8").trim();
+    };
+}
+function assertOwnedHead(context, operation, phases, head) {
+    const { plan } = operation, git = gitReader(context, plan), commit = phases.find(item => item.phase === "commit");
+    if (!commit) {
+        if (head !== (plan.reviewed.policy.policy.initial_head ?? ""))
+            pending("source_head_not_owned");
+    }
+    else if (head !== commit.baseline) {
+        const message = `chore(${plan.run_id.toLowerCase()}): integrate reviewed project changes`;
+        const paths = [...plan.inventory.references, ...plan.inventory.removals].map(ref => ref.path);
+        if (git(["show", "-s", "--format=%P%n%s", head]) !== `${commit.baseline}\n${message}`.trim()
+            || git(["diff-tree", "--root", "--no-commit-id", "--no-renames", "--name-only", "-r", "-z", head]).split("\0").filter(Boolean).some(path => !paths.includes(path)))
+            pending("scoped_commit_not_proven");
+    }
+}
+function selection(plan) {
+    const policy = plan.reviewed.policy;
+    return { projectRoot: policy.scope.projectRoot, workspaceRoot: policy.scope.workspaceRoot,
+        integrationBranch: policy.policy.integration_branch, gitExecutable: policy.git_executable };
+}
+function assertTool(bundle, plan) {
+    const actual = readInteractiveWorkGit(bundle), selected = plan.reviewed.policy;
+    if (actual.git_executable !== selected.git_executable || actual.git_sha256 !== selected.git_sha256)
+        refuse("selected_git_changed");
+}
+function integrationCustody(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const selected = readInteractiveStageScope(context, { ...input, stage: "integration" }, true), reviewed = prepareInteractiveReviewedGitInputs(context, input);
+    const state = stored(context, selected.scope), operation = state.operation;
+    if (!operation || hybridDigest(operation.plan.reviewed) !== hybridDigest(reviewed.original))
+        refuse("original_integration_operation_required");
+    const assertCustody = (writer) => {
+        reviewed.assertCustody(writer);
+        if (hybridDigest(stored(writer, selected.scope)) !== hybridDigest(state))
+            pending("integration_custody_changed");
+    };
+    return { selected, reviewed, state, operation, assertCustody };
+}
+/** Historical operation custody, not current Git observation. Prepare outside
+ * the writer; the returned fence itself reads only retained SQL/bundle data. */
+export function prepareInteractiveIntegrationCustody(context, input) {
+    const retained = integrationCustody(context, input);
+    return { binding: { operation_sha256: retained.operation.identity, phases_sha256: hybridDigest(retained.state.phases) },
+        reviewed: structuredClone(retained.operation.plan.reviewed), assertCustody: retained.assertCustody };
+}
+/** Readback plus SQL custody for terminal acceptance. No dispatch or fresh
+ * operation selection; usable when a process died after the original effect. */
+export function prepareInteractiveFinishIntegration(context, input) {
+    const { selected, reviewed, state, operation, assertCustody } = integrationCustody(context, input), { plan } = operation;
+    const observe = () => {
+        assertTool(selected.bundle, plan);
+        assertCustody(context);
+        if (plan.reviewed.empty) {
+            if (state.phases.length)
+                pending("empty_run_has_git_intent");
+            reviewed.observeBeforeDispatch().revalidate();
+            return { schema_id: "dd-flow/interactive-finish-integration@1", operation_sha256: operation.identity, no_op: true, git: null };
+        }
+        const git = observeReviewedProjectGitIntegration(selection(plan), context.env, plan.inventory.references, plan.inventory.removals);
+        if (git.repository !== plan.reviewed.policy.policy.repository || git.workspace_branch !== plan.reviewed.policy.policy.workspace_branch)
+            refuse("policy_repository_or_branch_changed");
+        assertOwnedHead(context, operation, state.phases, git.workspace_head);
+        const merge = state.phases.find(item => item.phase === "merge");
+        if (merge && git.integration_head !== git.workspace_head && git.integration_head !== merge.baseline
+            && gitReader(context, plan)(["show", "-s", "--format=%P", git.integration_head], plan.reviewed.policy.scope.projectRoot) !== `${merge.baseline} ${git.workspace_head}`)
+            pending("scoped_merge_not_proven");
+        reviewed.assertReviewedSources();
+        assertCustody(context);
+        return { schema_id: "dd-flow/interactive-finish-integration@1", operation_sha256: operation.identity, no_op: false, git };
+    };
+    const observation = observe();
+    return { binding: { operation_sha256: operation.identity, phases_sha256: hybridDigest(state.phases) },
+        reviewed: structuredClone(plan.reviewed), value: () => structuredClone(observation), assertCustody, revalidate: () => {
+            if (context.db.isOwnedWriteTransaction?.())
+                refuse("physical_revalidation_outside_writer_required");
+            if (hybridDigest(observe()) !== hybridDigest(observation))
+                pending("integration_readback_changed");
+        } };
+}
+/** Existing scoped Git executor, with original selected index bytes retained
+ * before effects and each phase anchored separately. Never push/stash/reset,
+ * repeat an unresolved phase or rediscover a new agreement after commit. */
+export function integrateInteractiveFinish(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const selected = readInteractiveStageScope(context, { ...input, stage: "integration" }, true), { scope, bundle } = selected;
+    const reviewed = prepareInteractiveReviewedGitInputs(context, input);
+    const authority = (writer) => {
+        assertRunMutationAllowed(writer, scope.projectId, scope.runId);
+        const run = writer.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+        const index = JSON.parse(run.index_json);
+        if (run.status !== "running" || index.current_stage !== "integration"
+            || !index.stage_runs.some((stage) => stage.stage === "integration" && stage.status === "running"))
+            refuse("active_integration_required");
+        const stage = readDescriptorStageInput(writer, scope, bundle), actor = readActiveDescriptorStageCoordinator(writer, scope, bundle);
+        if (stage.input.predecessor?.stage !== "review" || hybridDigest(stage.input.predecessor.result) !== hybridDigest(reviewed.original.review_result))
+            refuse("accepted_review_predecessor_required");
+        if (writer.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId, actor.work_id]))
+            refuse("active_child_work");
+        return { stage, actor };
+    };
+    let state = stored(context, scope);
+    const replayed = Boolean(state.operation);
+    if (!state.operation) {
+        const owner = authority(context), admission = reviewed.prepareOriginalInputsAgreement(input.agreement);
+        const inventory = { references: reviewed.original.inventory.references, removals: reviewed.original.inventory.removals.map((ref) => {
+                const head = admission.original_inputs.find(item => item.path === ref.path).head;
+                if (!head)
+                    return ref;
+                if (head.git_mode !== "100644" && head.git_mode !== "100755")
+                    refuse("regular_original_removal_required");
+                return { ...ref, sha256: head.sha256, git_mode: head.git_mode };
+            }) };
+        const plan = { schema_id: "dd-flow/interactive-git-operation@1", run_id: input.runId, reviewed: reviewed.original, ...owner, inventory,
+            admission: { agreement: admission.agreement, original_inputs: admission.original_inputs.map(({ workspace, ...item }) => {
+                    const { base64: _retainedWorkspaceBytes, ...reference } = workspace;
+                    void _retainedWorkspaceBytes;
+                    return { ...item, workspace: reference };
+                }) } };
+        const operation = { identity: hybridDigest(plan), plan };
+        if (Buffer.byteLength(JSON.stringify(operation)) > 96 * 1024 * 1024)
+            refuse("integration_operation_exceeds_bound");
+        const sources = reviewed.observeBeforeDispatch();
+        sources.revalidate();
+        context.db.writeTransaction(() => {
+            reviewed.assertCustody(context);
+            sources.assertCustody(context);
+            if (hybridDigest(authority(context)) !== hybridDigest(owner))
+                refuse("integration_authority_changed");
+            const current = stored(context, scope);
+            if (current.operation) {
+                if (current.operation.identity !== operation.identity)
+                    pending("integration_operation_changed");
+                return;
+            }
+            appendAudit(context, { projectId: scope.projectId, eventType: event, payload: operation });
+            context.db.run("UPDATE runs SET index_json=json_set(index_json,?,json(?)) WHERE project_id=? AND id=?", [anchorPath, JSON.stringify({ identity: operation.identity, phases: [] }), scope.projectId, scope.runId]);
+        });
+        state = stored(context, scope);
+    }
+    const operation = state.operation, { plan } = operation;
+    if (hybridDigest(plan.reviewed) !== hybridDigest(reviewed.original))
+        refuse("accepted_integration_inputs_changed");
+    if (input.agreement !== undefined) {
+        const retained = plan.admission.agreement;
+        if (!retained || hybridDigest(input.agreement) !== hybridDigest({ basis: retained.basis, reason: retained.reason, include_existing_paths: retained.include_existing_paths }))
+            refuse("original_git_agreement_changed");
+    }
+    try {
+        const proof = prepareInteractiveFinishIntegration(context, input);
+        proof.revalidate();
+        return { integrated: true, replayed, integration: proof.value() };
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || !["project_git_integration_invalid", "memory_git_integration_invalid"].includes(error.code))
+            throw error;
+    }
+    if (hybridDigest(authority(context)) !== hybridDigest({ stage: plan.stage, actor: plan.actor }))
+        refuse("integration_authority_changed");
+    if (state.phases.length) {
+        if (state.phases.length !== 1 || state.phases[0].phase !== "commit"
+            || plan.reviewed.policy.scope.projectRoot === plan.reviewed.policy.scope.workspaceRoot)
+            pending("original_git_phase_unresolved");
+        const head = gitReader(context, plan)(["rev-parse", "HEAD"]);
+        if (head === state.phases[0].baseline) {
+            // A selected index-only cleanup need not create a commit. Prove its
+            // source postcondition, then permit only the still-unissued merge.
+            try {
+                observeReviewedProjectGitIntegration({ ...selection(plan), projectRoot: plan.reviewed.policy.scope.workspaceRoot,
+                    integrationBranch: plan.reviewed.policy.policy.workspace_branch }, context.env, plan.inventory.references, plan.inventory.removals);
+            }
+            catch {
+                pending("original_commit_not_proven");
+            }
+        }
+        assertOwnedHead(context, operation, state.phases, head);
+    }
+    else
+        reviewed.observeBeforeDispatch().revalidate();
+    let dispatched = false;
+    try {
+        integrateReviewedProjectFiles(selection(plan), context.env, plan.inventory.references, input.runId, (phase, baseline, action) => {
+            assertTool(bundle, plan);
+            const prior = stored(context, scope);
+            if (prior.phases.some(item => item.phase === phase))
+                pending("original_git_phase_unresolved");
+            const before = phase === "commit" ? reviewed.observeBeforeDispatch() : null;
+            if (before)
+                before.revalidate();
+            else
+                assertOwnedHead(context, operation, prior.phases, gitReader(context, plan)(["rev-parse", "HEAD"]));
+            context.db.writeTransaction(() => {
+                reviewed.assertCustody(context);
+                before?.assertCustody(context);
+                if (hybridDigest(authority(context)) !== hybridDigest({ stage: plan.stage, actor: plan.actor }))
+                    refuse("integration_authority_changed");
+                const current = stored(context, scope);
+                if (current.operation?.identity !== operation.identity || current.phases.some(item => item.phase === phase)
+                    || phase === "commit" && current.phases.length)
+                    pending("original_git_phase_unresolved");
+                const intent = { identity: operation.identity, run_id: input.runId, phase, baseline };
+                appendAudit(context, { projectId: scope.projectId, eventType: phaseEvent, payload: intent });
+                context.db.run("UPDATE runs SET index_json=json_set(index_json,?,json(?)) WHERE project_id=? AND id=?", [anchorPath, JSON.stringify({ identity: operation.identity, phases: [...current.phases, intent] }), scope.projectId, scope.runId]);
+            });
+            dispatched = true;
+            // Intent recording is not permission to overwrite an index or task that
+            // changed during that writer. Recheck immediately before the effect.
+            before?.revalidate();
+            reviewed.assertCustody(context);
+            if (hybridDigest(authority(context)) !== hybridDigest({ stage: plan.stage, actor: plan.actor }))
+                refuse("integration_authority_changed");
+            action();
+        }, plan.reviewed.policy.policy, plan.inventory.removals);
+        const proof = prepareInteractiveFinishIntegration(context, input);
+        proof.revalidate();
+        return { integrated: true, replayed: false, integration: proof.value() };
+    }
+    catch (error) {
+        if (dispatched)
+            pending(error instanceof AppError ? error.code : "git_operation_failed");
+        throw error;
+    }
+}

package/dist/services/interactive-input-delivery.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readInteractiveUserInputs, readInteractiveInputDelivery, retainInteractiveUserInput } from "./interactive-user-inputs.js";
+import { prepareRunControllerAnswer, answerRunController } from "./run-controller.js";
+function refuse(reason) {
+    throw new AppError("interactive_input_delivery_invalid", "Interactive delivery requires its original input and exact controller pause", 2, { reason, effect: "no_effect" });
+}
+function pending(input, delivery) {
+    throw new AppError("interactive_input_delivery_pending", "User input is retained; reconcile its original controller answer without retargeting", 1, { effect: "committed", recoverable: true, request_id: input.requestId, delivery, next_action: "retry_exact_interactive_input" });
+}
+/** No new dispatcher. Retain the user bytes, then queue the ordinary HITL answer.
+ * The original pause target survives loss between those two existing owners. */
+export function deliverInteractiveUserInput(context, scope, bundle, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const before = readInteractiveUserInputs(context, scope, bundle), prior = before.turns.find(turn => turn.request_id === input.requestId);
+    // Validate exact raw replay through its existing owner before observing or
+    // queuing any controller operation. Changed retry bytes are still no-effect.
+    if (prior)
+        retainInteractiveUserInput(context, scope, bundle, input);
+    const select = () => {
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+        if (bundle.execution.settings.execution !== "managed" || !context.db.get("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='run_controllers'"))
+            return null;
+        const stage = index.stage_runs?.filter((item) => item.stage === index.current_stage).at(-1);
+        if (index.current_stage !== "interactive" || !stage || !["paused", "waiting_for_user"].includes(stage.status) || !stage.pause?.id)
+            return null;
+        const controllers = context.db.all("SELECT controller_id FROM run_controllers WHERE project_id=? AND run_id=? AND status NOT IN ('completed','cancelled','superseded')", [scope.projectId, scope.runId]);
+        if (controllers.length > 1)
+            refuse("ambiguous_controller");
+        const controller = controllers[0];
+        if (!controller)
+            return null;
+        // An already queued answer will wake the same coordinator, which must read
+        // the complete retained input set. Do not queue a second answer to its pause.
+        if (context.db.get("SELECT 1 FROM run_controller_operations WHERE controller_id=? AND json_extract(input_json,'$.action')='user_answer' AND json_extract(input_json,'$.pause_id')=?", [controller.controller_id, stage.pause.id]))
+            return null;
+        return { controller_id: controller.controller_id, pause_id: stage.pause.id,
+            request_id: `interactive-${hybridDigest({ run_id: scope.runId, request_id: input.requestId })}` };
+    };
+    const target = prior ? readInteractiveInputDelivery(context, scope, bundle, input.requestId) : context.db.readSnapshot(select);
+    let prepared;
+    const answer = target ? { projectRoot: input.projectRoot, runId: scope.runId, requestId: target.request_id,
+        pauseId: target.pause_id, answerFile: input.intakeFile } : null;
+    if (target && answer) {
+        try {
+            prepared = prepareRunControllerAnswer(context, answer);
+            const operationId = `${target.controller_id}:answer:${target.request_id}`;
+            if (prepared.operationId !== operationId)
+                refuse("original_controller_changed");
+            if (prepared.kind === "create") {
+                if (!prepared.bytes.equals(Buffer.from(input.bytes)))
+                    refuse("prepared_user_bytes_changed");
+            }
+            else {
+                const operation = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id=?", [operationId]);
+                const value = operation ? JSON.parse(operation.input_json) : null;
+                if (!value || value.action !== "user_answer" || value.pause_id !== target.pause_id
+                    || value.sha256 !== createHash("sha256").update(input.bytes).digest("hex"))
+                    refuse("original_answer_changed");
+            }
+        }
+        catch (error) {
+            if (prior)
+                return pending(input, target);
+            throw error;
+        }
+    }
+    const retained = retainInteractiveUserInput(context, scope, bundle, { requestId: input.requestId, kind: input.kind,
+        bytes: input.bytes, expectedInputsSha256: input.expectedInputsSha256, delivery: target });
+    if (!target || !answer || !prepared)
+        return { ...retained, delivery: { kind: "retained_only" } };
+    try {
+        const queued = answerRunController(context, answer, prepared);
+        return { ...retained, delivery: { kind: "controller_answer", pause_id: target.pause_id, ...queued } };
+    }
+    catch {
+        return pending(input, target);
+    }
+}