@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/retained-native-hook.js

@@ -0,0 +1,274 @@
+import crypto from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir } from "node:fs/promises";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { canonicalPath } from "../storage/paths.js";
+import { lifecycleCommandFromPayload } from "./lifecycle-command.js";
+import { matchesIssuedNativeCommand, observedLifecycleInvocation } from "./lifecycle-invocations.js";
+import { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+import { requireProjectByRoot } from "./project-registry.js";
+import { handleAgyEvent, handleCodexHook, handleDroidEvent, handleOpenCodeEvent, handleGrokEvent, handleZcodeEvent } from "./hooks.js";
+import { withDaemonProgressObserver } from "../harness-runtime/lib/daemon-observation.mjs";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+const sha256 = (value) => crypto.createHash("sha256").update(value).digest("hex");
+const diagnostics = new WeakMap();
+async function regularJson(file) {
+    try {
+        const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            if (!(await handle.stat()).isFile())
+                return null;
+            return object(JSON.parse(await handle.readFile("utf8")));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (["ENOENT", "ELOOP", "ENOTDIR"].includes(error.code ?? "") || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+async function realDirectory(directory) {
+    try {
+        const info = await lstat(directory);
+        return info.isDirectory() && !info.isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function payloadCommand(binding) {
+    const payload = object(binding.native_payload);
+    if (!payload)
+        return undefined;
+    if (binding.source_harness === "codex-desktop")
+        return lifecycleCommandFromPayload(payload) ?? undefined;
+    if (binding.source_harness === "grok-acp") {
+        const native = object(payload.tool_input ?? payload.toolInput);
+        const command = native?.command ?? native?.cmd ?? payload.command;
+        return typeof command === "string" ? command : undefined;
+    }
+    if (binding.source_harness === "zcode-acp") {
+        const update = object(object(payload.params)?.update), native = object(update?.rawInput);
+        const command = native?.command ?? native?.cmd;
+        return typeof command === "string" ? command : undefined;
+    }
+    const input = object(payload.input);
+    const command = input?.command ?? input?.cmd ?? input?.CommandLine;
+    return typeof command === "string" ? command : undefined;
+}
+/** The directory is only a locator. The owning daemon must attest the exact
+ * binding from its verified native-delivery map before it becomes a receipt. */
+export async function reconcileRetainedNativeHook(context, input) {
+    const { scope, invocationId } = input;
+    const diagnostic = (phase, error, binding) => {
+        if (!input.onDiagnostic)
+            return;
+        const supplied = error instanceof Error || object(error) ? error.code : undefined;
+        const code = typeof supplied === "string" && /^[A-Za-z][A-Za-z0-9_]{0,95}$/.test(supplied) ? supplied : "native_hook_verification_unavailable";
+        // Diagnostics never become execution authority or activity. Keep identifiers
+        // and a typed cause, not native messages/configs that can contain credentials.
+        const value = { phase, code, invocation_id: invocationId,
+            ...(typeof binding?.request_id === "string" ? { request_id: binding.request_id } : {}),
+            ...(typeof binding?.operation_id === "string" ? { operation_id: binding.operation_id } : {}) };
+        const seen = diagnostics.get(context) ?? new Set(), key = JSON.stringify(value);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        diagnostics.set(context, seen);
+        input.onDiagnostic(value);
+    };
+    if (!scope.runId || context.env.DD_FLOW_DAEMON_ID !== scope.daemonId)
+        return false;
+    let owner = null;
+    try {
+        owner = object(JSON.parse(context.env.DD_FLOW_RUNTIME_OWNER ?? "null"));
+    }
+    catch {
+        return false;
+    }
+    const stateDir = owner?.state_dir || context.env.DD_FLOW_CODEX_STATE_DIR || context.env.DD_AGY_STATE_DIR || context.env.DD_GROK_STATE_DIR || context.env.DD_ZCODE_STATE_DIR;
+    if (typeof stateDir !== "string" || !path.isAbsolute(stateDir) || !await realDirectory(stateDir))
+        return false;
+    // This is an optional additional observation source. A missing, retiring or
+    // unbound daemon must leave the existing hook path intact, never grant it
+    // authority and never turn an otherwise valid legacy delivery into a failure.
+    let owned;
+    let metadata;
+    try {
+        const state = readNativeDaemonState(stateDir);
+        if ((state.daemon_id ?? state.config?.daemonId) !== scope.daemonId) {
+            diagnostic("owner", { code: "daemon_owner_mismatch" });
+            return false;
+        }
+        const project = requireProjectByRoot(context, scope.projectRoot);
+        owned = requireManagedDaemonBinding(context, { stateDir, projectId: project.id, runId: scope.runId });
+        metadata = JSON.parse(owned.process.metadata_json);
+    }
+    catch (error) {
+        diagnostic("owner", error);
+        return false;
+    }
+    if (metadata.run_generation !== scope.generation) {
+        diagnostic("owner", { code: "run_generation_mismatch" });
+        return false;
+    }
+    const operations = path.join(stateDir, "operations");
+    if (!await realDirectory(operations))
+        return false;
+    const candidates = [];
+    for (const entry of await readdir(operations, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^[a-f0-9]{64}$/.test(entry.name))
+            continue;
+        const directory = path.join(operations, entry.name), hooks = path.join(directory, "hooks");
+        if (!await realDirectory(hooks))
+            continue;
+        const requested = await regularJson(path.join(directory, "requested.json"));
+        if (!requested || requested.schema_id !== "dd-flow/daemon-operation@1" || typeof requested.operation_id !== "string"
+            || sha256(requested.operation_id) !== entry.name || requested.daemon_id !== scope.daemonId
+            || requested.owner_id !== owned.process.owner_id || !["session.create", "session.start", "session.prompt"].includes(String(requested.operation))
+            || requested.session_id && requested.session_id !== scope.rootSessionId)
+            continue;
+        for (const hook of await readdir(hooks, { withFileTypes: true })) {
+            if (!hook.isFile() || !/^[A-Za-z0-9-]{1,128}\.json$/.test(hook.name))
+                continue;
+            const binding = await regularJson(path.join(hooks, hook.name));
+            if (!binding || binding.schema_id !== "dd-flow/hook-request@1" || binding.request_id !== hook.name.slice(0, -5)
+                || binding.daemon_id !== scope.daemonId || binding.operation_id !== requested.operation_id
+                || binding.root_provider_session_id !== scope.rootSessionId || !["codex-desktop", "antigravity-cli", "grok-acp", "zcode-acp", "opencode-server", "droid-cli"].includes(String(binding.source_harness))
+                || typeof binding.provider_session_id !== "string" || !binding.provider_session_id
+                || !(binding.parent_provider_session_id === null || typeof binding.parent_provider_session_id === "string")
+                || typeof binding.tool_call_id !== "string" || !binding.tool_call_id || binding.event !== "PreToolUse"
+                || typeof binding.native_command !== "string" || binding.command_sha256 !== sha256(binding.native_command)
+                || payloadCommand(binding) !== binding.native_command || !matchesIssuedNativeCommand(context, invocationId, binding.native_command))
+                continue;
+            candidates.push(binding);
+        }
+    }
+    const verified = [];
+    for (const binding of candidates) {
+        try {
+            const module = binding.source_harness === "codex-desktop"
+                ? await import("../harness-runtime/lib/dd-codex-daemon.mjs")
+                : binding.source_harness === "grok-acp" ? await import("../harness-runtime/lib/dd-grok-daemon.mjs")
+                    : binding.source_harness === "zcode-acp" ? await import("../harness-runtime/lib/dd-zcode-daemon.mjs")
+                        // @ts-expect-error Executable adapter assets have no duplicate typed API.
+                        : binding.source_harness === "opencode-server" ? await import("../harness-runtime/lib/dd-opencode-daemon.mjs")
+                            // @ts-expect-error Executable adapter assets have no duplicate typed API.
+                            : binding.source_harness === "droid-cli" ? await import("../harness-runtime/lib/dd-droid-daemon.mjs")
+                                : await import("../harness-runtime/lib/dd-agy-daemon.mjs");
+            const proof = await withDaemonProgressObserver(progress => {
+                if (typeof progress.native_request_id === 'string' && typeof progress.observed_at === 'string')
+                    input.onProgress?.({ cursor: `${binding.request_id}:${progress.native_request_id}`, observed_at: Date.parse(progress.observed_at) });
+            }, () => module.callDaemon(stateDir, "hook.verify", { daemonId: scope.daemonId, requestId: binding.request_id, binding }, 5_000));
+            if (binding.native_admission === "assigned_work_start") {
+                const resolved = object(proof.nativeHookBinding);
+                if (proof.verified !== true || JSON.stringify(proof.registeredHookBinding) !== JSON.stringify(binding) || !resolved
+                    || !["antigravity-cli", "opencode-server", "droid-cli"].includes(String(binding.source_harness))
+                    || resolved.native_ancestry !== "confirmed" || typeof resolved.native_cwd !== "string" || !path.isAbsolute(resolved.native_cwd)
+                    || !(resolved.parent_provider_session_id === null || typeof resolved.parent_provider_session_id === "string")
+                    || ["request_id", "operation_id", "daemon_id", "turn_generation", "source_harness", "root_provider_session_id", "provider_session_id",
+                        "tool_call_id", "event", "native_command", "command_sha256", "native_creator", "native_admission"].some(key => resolved[key] !== binding[key])
+                    || payloadCommand(resolved) !== binding.native_command) {
+                    diagnostic("verify", { code: "native_hook_unproven" }, binding);
+                    continue;
+                }
+                verified.push(resolved);
+            }
+            else if (proof.verified === true && JSON.stringify(proof.nativeHookBinding) === JSON.stringify(binding))
+                verified.push(binding);
+            else
+                diagnostic("verify", { code: "native_hook_unproven" }, binding);
+        }
+        catch (error) {
+            diagnostic("verify", error, binding);
+        }
+    }
+    // Exact old tool delivery belongs to its immutable prior attempt. A public
+    // command may be identical in a fresh no-effect successor; do not repeatedly
+    // select its predecessor and starve the new native callback.
+    const eligible = verified.filter(binding => observedLifecycleInvocation(context, binding.native_command, scope, { identity: {
+            daemonId: scope.daemonId, rootSessionId: scope.rootSessionId, sessionId: binding.provider_session_id,
+            parentSessionId: binding.parent_provider_session_id, toolCallId: binding.tool_call_id
+        } })?.id === invocationId);
+    if (!eligible.length)
+        return false;
+    const identity = (binding) => JSON.stringify([binding.source_harness, binding.daemon_id, binding.root_provider_session_id,
+        binding.provider_session_id, binding.parent_provider_session_id, binding.native_cwd]);
+    if (new Set(eligible.map(identity)).size !== 1)
+        throw new AppError("invocation_ambiguous", "More than one native executor supplied this issued Work command", 1, { effect: "no_effect", invocation_id: invocationId });
+    const binding = eligible[0], payload = object(binding.native_payload);
+    if (binding.source_harness === "codex-desktop") {
+        const proof = object(binding.codex_proof);
+        if (!proof || proof.daemonId !== scope.daemonId || proof.rootSessionId !== scope.rootSessionId
+            || proof.sessionId !== binding.provider_session_id || proof.parentSessionId !== binding.parent_provider_session_id
+            || proof.toolCallId !== binding.tool_call_id || typeof proof.projectRoot !== "string"
+            || canonicalPath(proof.projectRoot) !== canonicalPath(scope.projectRoot) || typeof proof.ddFlowHome !== "string"
+            || canonicalPath(proof.ddFlowHome) !== canonicalPath(context.ddFlowHome))
+            return false;
+        const prior = context.codexHookProof;
+        try {
+            context.codexHookProof = { daemonId: scope.daemonId, rootSessionId: scope.rootSessionId,
+                sessionId: binding.provider_session_id, parentSessionId: binding.parent_provider_session_id,
+                toolCallId: binding.tool_call_id, projectRoot: proof.projectRoot, command: binding.native_command };
+            handleCodexHook(context, { event: "PreToolUse", projectRoot: scope.projectRoot, stdin: JSON.stringify(payload) });
+        }
+        finally {
+            if (prior)
+                context.codexHookProof = prior;
+            else
+                delete context.codexHookProof;
+        }
+    }
+    else if (binding.source_harness === "grok-acp") {
+        const identity = object(object(payload._meta)?.ddGrok);
+        if (!identity || identity.daemonId !== scope.daemonId || identity.rootProviderSessionId !== scope.rootSessionId
+            || identity.parentProviderSessionId !== binding.parent_provider_session_id
+            || (payload.session_id ?? payload.sessionId) !== binding.provider_session_id
+            || (payload.tool_use_id ?? payload.toolUseId ?? payload.tool_call_id) !== binding.tool_call_id)
+            return false;
+        handleGrokEvent(context, { projectRoot: scope.projectRoot, stdin: JSON.stringify(payload) });
+    }
+    else if (binding.source_harness === "zcode-acp") {
+        const controlled = object(object(payload._meta)?.ddZcode), update = object(object(payload.params)?.update), native = object(object(update?._meta)?.zcodeRuntime);
+        if (!controlled || controlled.daemonId !== scope.daemonId || controlled.rootProviderSessionId !== scope.rootSessionId
+            || controlled.parentProviderSessionId !== binding.parent_provider_session_id || native?.source !== "subagent"
+            || native.childSessionId !== binding.provider_session_id || native.childToolCallId !== binding.tool_call_id
+            || typeof update?.toolCallId !== "string" || !update.toolCallId || typeof native.nativeTurnId !== "string" || !native.nativeTurnId)
+            return false;
+        handleZcodeEvent(context, { projectRoot: scope.projectRoot, stdin: JSON.stringify(payload) });
+    }
+    else if (binding.native_admission === "assigned_work_start") {
+        const harness = binding.source_harness, session = object(payload.session);
+        if (payload.daemon_id !== scope.daemonId || (harness === "antigravity-cli" ? payload.conversation_id !== binding.provider_session_id
+            || (payload.parent_conversation_id ?? null) !== binding.parent_provider_session_id || payload.event_id !== binding.tool_call_id
+            : !session || session.provider_session_id !== binding.provider_session_id || (session.parent_provider_session_id ?? null) !== binding.parent_provider_session_id
+                || payload.tool_call_id !== binding.tool_call_id))
+            return false;
+        const prior = context.nativeHookProof;
+        try {
+            context.nativeHookProof = { harness, daemonId: scope.daemonId, rootSessionId: scope.rootSessionId, sessionId: binding.provider_session_id,
+                toolCallId: binding.tool_call_id };
+            const handle = harness === "antigravity-cli" ? handleAgyEvent : harness === "droid-cli" ? handleDroidEvent : handleOpenCodeEvent;
+            handle(context, { projectRoot: scope.projectRoot, stdin: JSON.stringify(payload) });
+        }
+        finally {
+            if (prior)
+                context.nativeHookProof = prior;
+            else
+                delete context.nativeHookProof;
+        }
+    }
+    else {
+        if (payload.daemon_id !== scope.daemonId || payload.conversation_id !== binding.provider_session_id
+            || (payload.parent_conversation_id ?? null) !== binding.parent_provider_session_id || payload.event_id !== binding.tool_call_id)
+            return false;
+        handleAgyEvent(context, { projectRoot: scope.projectRoot, stdin: JSON.stringify(payload) });
+    }
+    return true;
+}

package/dist/services/review-copy.js

@@ -0,0 +1,165 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { ignoredWorkspacePaths } from "./code-checks.js";
+import { localEnvironmentAllowed, ownedWorkspaceHookPath, projectServicePathFilter, workspaceGitFiles } from "./workspace-files.js";
+export function reviewerSourceInputs(root, aspectIds) {
+    const criteria = [...new Set(aspectIds)].sort().map(id => {
+        if (!/^[a-z][a-z0-9_-]*$/.test(id))
+            throw new AppError("review_criterion_invalid", "Assigned aspect has an invalid identity", 1, { aspect_id: id });
+        return `.memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects/${id}.md`;
+    });
+    const orientation = [".memory-bank/index.md", ".memory-bank/spec/engineering/index.md", ".memory-bank/spec/engineering/coding-standards.md"].filter(relative => fs.existsSync(path.join(root, relative)));
+    return [...criteria, ...orientation].map(relative => {
+        const file = path.join(root, relative);
+        if (!fs.existsSync(file))
+            throw new AppError("review_criterion_missing", "Assigned reviewer criterion is missing", 1, { path: relative });
+        const inside = path.relative(fs.realpathSync(root), fs.realpathSync(file));
+        if (inside === ".." || inside.startsWith(`..${path.sep}`) || !fs.statSync(file).isFile())
+            throw new AppError("review_criterion_invalid", "Reviewer source must be a file in its workspace", 1, { path: relative });
+        return { path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
+    });
+}
+export function reviewerSourceInstruction(root, aspectIds) {
+    const inputs = reviewerSourceInputs(root, aspectIds);
+    return ["Read the assigned canonical criterion files and the available project orientation below before independent review. Apply each criterion's scope; a small behavior change is not by itself a reason to omit testing or evidence. These starting inputs do not limit relevant project investigation. Do not edit them.", ...inputs.map(input => `- ${path.join(root, input.path)} (SHA256 ${input.sha256})`)].join("\n");
+}
+export function reviewEnvironmentAllowed(file) {
+    // Relative evidence names are scoped to the project: a private parent also
+    // makes its children private. Absolute filesystem traversal checks each
+    // directory separately, without classifying ancestors outside the workspace.
+    return path.isAbsolute(file) || path.win32.isAbsolute(file)
+        ? localEnvironmentAllowed(file)
+        : file.split(/[\\/]/).every(part => localEnvironmentAllowed(part));
+}
+export function reviewSourcePaths(root, explicitInputs = [], base = "HEAD") {
+    const inventory = workspaceGitFiles(root, ["--cached", "--others", "--exclude-standard"]);
+    if (inventory === null)
+        return null;
+    const serviceAllowed = projectServicePathFilter(root, explicitInputs);
+    const hasHead = spawnSync("git", ["-C", root, "rev-parse", "--verify", "HEAD"], { encoding: "utf8" }).status === 0;
+    if (base === "unborn" && hasHead)
+        throw new AppError("review_git_evidence_failed", "Unborn review baseline no longer matches the workspace", 1, { workspace_root: root });
+    const hasBase = base === "unborn" ? false : base !== "HEAD" || hasHead;
+    const changes = hasBase ? spawnSync("git", ["-C", root, "diff", "--name-status", "-z", "--find-renames", base, "--"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }) : null;
+    if (changes && (changes.status !== 0 || changes.error))
+        throw new AppError("review_git_evidence_failed", "Could not classify renamed review paths", 1, { workspace_root: root, cause: changes.error?.message ?? changes.stderr });
+    const fields = changes?.stdout.split("\0").filter(Boolean) ?? [], tainted = new Set();
+    for (let index = 0; index < fields.length;) {
+        const status = fields[index++];
+        if (/^[RC]/.test(status)) {
+            const before = fields[index++], after = fields[index++];
+            if (!reviewEnvironmentAllowed(before) || !reviewEnvironmentAllowed(after)) {
+                tainted.add(before);
+                tainted.add(after);
+            }
+        }
+        else
+            index += 1;
+    }
+    return [...new Set([...inventory, ...explicitInputs])]
+        .filter(relative => reviewEnvironmentAllowed(relative) && !tainted.has(relative) && serviceAllowed(path.join(root, relative)))
+        .sort();
+}
+export function reviewSourceFilter(root, explicitInputs = [], base = "HEAD") {
+    const selected = reviewSourcePaths(root, explicitInputs, base);
+    const serviceAllowed = projectServicePathFilter(root, explicitInputs);
+    const retained = new Set(selected?.map(relative => path.resolve(root, relative)) ?? []);
+    const branches = new Set();
+    for (const file of retained)
+        for (let directory = path.dirname(file); directory !== path.dirname(directory); directory = path.dirname(directory))
+            branches.add(directory);
+    return file => {
+        const parts = path.relative(root, file).split(path.sep);
+        if (parts.some(part => [".git", "node_modules", ".dd-flow"].includes(part)) || !reviewEnvironmentAllowed(file))
+            return false;
+        return selected === null ? serviceAllowed(file) : retained.has(path.resolve(file)) || branches.has(path.resolve(file));
+    };
+}
+export function reviewSourceHash(root, explicitInputs = [], base = "HEAD") {
+    const allowed = reviewSourceFilter(root, explicitInputs, base), ownedHook = ownedWorkspaceHookPath(root);
+    return reviewCopyHash(root, file => path.relative(root, file) !== ownedHook && allowed(file));
+}
+/** The copied project has no Git index. Apply the source's exact service-file
+ * policy to it, while retaining only our frozen Git evidence under .dd-flow. */
+export function reviewExecutionCopyHash(copyRoot, sourceRoot, includeEvidence = true, explicitInputs = [], base = "HEAD") {
+    if (ownedWorkspaceHookPath(sourceRoot) && !ownedWorkspaceHookPath(copyRoot))
+        throw new AppError("read_only_input_changed", "Qualified review hook differs between execution copy and source", 2, { copy_root: copyRoot });
+    const sourceAllowed = reviewSourceFilter(sourceRoot, explicitInputs, base);
+    const serviceAllowed = projectServicePathFilter(sourceRoot, explicitInputs);
+    const ownedHook = ownedWorkspaceHookPath(sourceRoot);
+    const verifySelection = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name), relative = path.relative(copyRoot, file);
+            const parts = relative.split(path.sep);
+            if (parts[0] === ".dd-flow" || parts.some(part => [".git", "node_modules"].includes(part)))
+                continue;
+            if (!reviewEnvironmentAllowed(file))
+                throw new AppError("read_only_input_changed", "Read-only execution copy contains a local environment file", 2, { path: relative });
+            if (!serviceAllowed(path.join(sourceRoot, relative)))
+                continue;
+            if (!sourceAllowed(path.join(sourceRoot, relative)) && ignoredWorkspacePaths(sourceRoot, [relative]).includes(relative.split(path.sep).join("/")))
+                continue;
+            if (!sourceAllowed(path.join(sourceRoot, relative)))
+                throw new AppError("read_only_input_changed", "Read-only execution copy contains an unselected product input", 2, { path: relative });
+            if (entry.isDirectory())
+                verifySelection(file);
+        }
+    };
+    verifySelection(copyRoot);
+    return reviewCopyHash(copyRoot, file => {
+        const relative = path.relative(copyRoot, file);
+        const parts = relative.split(path.sep);
+        if (parts[0] === ".dd-flow")
+            return includeEvidence && (parts.length === 1 || parts[1] === "review-evidence");
+        return relative !== ownedHook && sourceAllowed(path.join(sourceRoot, relative));
+    });
+}
+/** Exact bytes visible in a read-only execution copy, including symlink targets. */
+export function reviewCopyHash(root, allowed = () => true) {
+    const hash = crypto.createHash("sha256");
+    let canonicalRoot;
+    try {
+        canonicalRoot = fs.realpathSync(root);
+    }
+    catch {
+        throw new AppError("read_only_input_changed", "Read-only execution copy is missing", 2, { root });
+    }
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(directory, entry.name);
+            if (!allowed(file))
+                continue;
+            const relative = path.relative(root, file).split(path.sep).join("/");
+            const stat = fs.lstatSync(file);
+            const record = (kind, value = "") => hash.update(`${JSON.stringify([relative, kind, stat.mode & 0o111, value])}\n`);
+            if (entry.isDirectory()) {
+                record("directory");
+                visit(file);
+                continue;
+            }
+            if (entry.isSymbolicLink()) {
+                const link = fs.readlinkSync(file);
+                let target;
+                try {
+                    target = fs.realpathSync(file);
+                }
+                catch {
+                    throw new AppError("read_only_workspace_escape", "Read-only copy contains an unresolved symlink", 1, { path: relative });
+                }
+                const inside = path.relative(canonicalRoot, target);
+                if (path.isAbsolute(link) || inside === ".." || inside.startsWith(`..${path.sep}`))
+                    throw new AppError("read_only_workspace_escape", "Read-only copy contains a symlink outside its workspace", 1, { path: relative });
+                record("symlink", link);
+            }
+            else if (entry.isFile())
+                record("file", crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"));
+            else
+                throw new AppError("read_only_workspace_unsupported", "Read-only copy contains an unsupported file type", 1, { path: relative });
+        }
+    };
+    visit(root);
+    return hash.digest("hex");
+}

package/dist/services/review-deferral.js

@@ -0,0 +1,23 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { assertPortableArtifactRef } from "./portable-refs.js";
+/** A deferral names one project-local file, never an arbitrary path. */
+export function reviewDefEvidence(workspaceRoot, defId) {
+    try {
+        if (!defId || !/^DEF-[A-Za-z0-9][A-Za-z0-9_-]*$/.test(defId))
+            throw new Error("invalid DEF identifier");
+        const relative = `.memory-bank/defs/${defId}.md`;
+        const file = assertPortableArtifactRef(relative, { workspaceRoot, runHome: workspaceRoot, runId: "" });
+        const directory = fs.realpathSync(path.join(workspaceRoot, ".memory-bank", "defs"));
+        const root = fs.realpathSync(workspaceRoot);
+        const directoryRelative = path.relative(root, directory);
+        if (directoryRelative === ".." || directoryRelative.startsWith(`..${path.sep}`) || path.isAbsolute(directoryRelative) || path.dirname(file) !== directory || !fs.statSync(file).isFile())
+            throw new Error("DEF must be a regular file in the project defs directory");
+        return { def_id: defId, path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
+    }
+    catch (error) {
+        throw new AppError("deferral_invalid", "A deferral requires a readable project-local named DEF", 2, { def_id: defId ?? null, cause: error instanceof Error ? error.message : String(error) });
+    }
+}

package/dist/services/review-fix-handoff.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { readReviewFixSourceIntake, assertReviewFixSourceIntakeCustody } from "./review-fix-intake-custody.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { assertReviewFixStageScope, validateReviewFixStageResult } from "./review-fix-stage-results.js";
+function refuse(reason) {
+    throw new AppError("review_fix_handoff_invalid", "Handoff requires accepted scope review and unchanged original user inputs", 2, { reason, effect: "no_effect" });
+}
+/** Prepare an SQL-fenced raw packet for the ordinary Stage settlement writer.
+ * No files, RUNs, PRTs or specifications are created. A ready scope is not
+ * authorization to formalize; the user must separately request that action.
+ */
+export function prepareReviewFixHandoff(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const scope = { projectId: project.id, runId: input.runId };
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== "review-fix")
+        refuse("review_fix_bundle_required");
+    const source = readReviewFixSourceIntake(context, input, bundle);
+    const read = (reader) => {
+        const intake = readAcceptedStageData(reader, { ...scope, stage: "intake" });
+        const reviewed = readAcceptedStageData(reader, { ...scope, stage: "scope-review" });
+        const users = readPreparedMemoryFlowUserInputs(reader, scope, "review-fix", bundle);
+        return { intake, reviewed, users };
+    };
+    const original = context.db.readSnapshot(() => read(context));
+    let prior;
+    try {
+        prior = JSON.parse(original.intake.bytes.toString("utf8"));
+    }
+    catch {
+        return refuse("accepted_intake_invalid");
+    }
+    if (original.intake.data_schema_id !== "dd-flow/review-fix-stage-result@1"
+        || original.reviewed.data_schema_id !== "dd-flow/review-fix-stage-result@1"
+        || prior?.schema_id !== "dd-flow/review-fix-stage-result@1" || prior.flow_id !== "review-fix"
+        || prior.run_id !== input.runId || prior.stage !== "intake" || prior.intake_sha256 !== source.sha256
+        || prior.input_sha256 !== original.intake.input_sha256 || !original.reviewed.input_sha256)
+        refuse("accepted_intake_invalid");
+    const reviewed = validateReviewFixStageResult(original.reviewed.bytes, bundle.descriptor.stageBlob("scope-review", "result_schema"), {
+        runId: input.runId, stage: "scope-review", inputSha256: original.reviewed.input_sha256, intakeSha256: source.sha256,
+        snapshotSha256: prior.snapshot_sha256, userInputsSha256: hybridDigest(original.users),
+        findingIds: source.intake.selected_findings.map(finding => finding.id),
+        predecessors: [{ stage: "intake", ...original.intake.result }],
+        userSources: original.users.sources.map(item => {
+            if (!["request", "question", "answer"].includes(item.role))
+                return refuse("invalid_user_input_role");
+            return { root: item.root, path: item.path, sha256: item.sha256, role: item.role };
+        })
+    });
+    assertReviewFixStageScope(reviewed, prior);
+    const disposition = reviewed.details.review.some(item => item.verdict === "revise") ? "needs_scope"
+        : reviewed.details.decisions.some(item => item.disposition === "approved") ? "ready"
+            : reviewed.details.decisions.some(item => item.disposition === "deferred") ? "deferred" : "declined";
+    const bytes = Buffer.from(JSON.stringify({ schema_id: "dd-flow/review-fix-handoff@1", run_id: input.runId,
+        disposition, formalization_authorized: false, next_entry: disposition === "ready" ? "vnext/start.md" : null,
+        source_intake: source.intake, user_inputs: original.users,
+        scope: reviewed.details, accepted_review: { ...original.reviewed.result, authority_sha256: original.reviewed.authority_sha256 }
+    }));
+    // Keep this packet within the existing Stage reader envelope; never truncate
+    // original messages or findings to make an oversized handoff appear valid.
+    if (bytes.length > 4 * 1024 * 1024)
+        refuse("handoff_exceeds_bound");
+    return {
+        path: `${bundle.descriptor.stage("handoff").directory}/raw-intake.json`, bytes,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        assertCustody(writer) {
+            assertReviewFixSourceIntakeCustody(writer, scope, bundle, source.sha256);
+            const current = read(writer);
+            if (!current.intake.bytes.equals(original.intake.bytes) || !current.reviewed.bytes.equals(original.reviewed.bytes)
+                || current.intake.authority_sha256 !== original.intake.authority_sha256
+                || current.reviewed.authority_sha256 !== original.reviewed.authority_sha256
+                || hybridDigest(current.users) !== hybridDigest(original.users))
+                refuse("accepted_handoff_changed");
+        }
+    };
+}

package/dist/services/review-fix-intake-custody.js

@@ -0,0 +1,17 @@
+import { assertDiagnosticRepairSourceIntakeCustody, prepareDiagnosticRepairSourceIntake, readDiagnosticRepairSourceIntake } from "./diagnostic-repair-source-intake.js";
+import { readMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+// Preserve this flow's own capsule identity; shared transport grants no approval.
+export function assertReviewFixSourceIntakeCustody(context, scope, bundle, expectedSha256) {
+    return assertDiagnosticRepairSourceIntakeCustody(context, scope, bundle, expectedSha256, "review-fix");
+}
+export function prepareReviewFixSourceIntake(context, input) {
+    return prepareDiagnosticRepairSourceIntake(context, input, "review-fix");
+}
+export function readReviewFixSourceIntake(context, input, retainedBundle) {
+    return readDiagnosticRepairSourceIntake(context, input, "review-fix", retainedBundle);
+}
+/** Original request and all delivered answers, not an agent's replacement spec.
+ * Reading these bytes neither accepts scope nor authorizes SDLC formalization. */
+export function readReviewFixUserInputs(context, input, retainedBundle) {
+    return readMemoryFlowUserInputs(context, input, "review-fix", retainedBundle);
+}

package/dist/services/review-fix-stage-entry.js

@@ -0,0 +1,43 @@
+import { AppError } from "../shared/errors.js";
+import { reviewFixStages } from "../domain/review-fix-flow.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readReviewFixSourceIntake, assertReviewFixSourceIntakeCustody } from "./review-fix-intake-custody.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+import { readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** Internal family entry. Generic runtime owns attempts, Work and coordinator;
+ * this does not register a public flow or authorize a downstream SDLC start. */
+export function readReviewFixStageScope(context, input, historical = false) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== "review-fix" || !reviewFixStages.includes(input.stage))
+        throw new AppError("review_fix_stage_invalid", "Review-fix requires its registered three-stage flow and retained intake", 2, { reason: "review_fix_stage_required", effect: "no_effect" });
+    bundle.descriptor.stage(input.stage);
+    const source = readReviewFixSourceIntake(context, input, bundle);
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const replay = historical && JSON.parse(run.index_json).stage_runs.some((stage) => stage.stage === input.stage && stage.status === "done");
+    const frozen = bundle.execution.snapshot().scope;
+    const snapshotSelection = { projectId: project.id, projectRoot: frozen.projectRoot, sourceRoot: frozen.projectRoot,
+        requestId: frozen.requestId, flowId: "review-fix" };
+    const snapshot = (replay ? readDiagnosticSnapshotCustody : readDiagnosticSnapshot)(context, snapshotSelection, input.runId);
+    if (!snapshot || snapshot.root !== frozen.workspace)
+        throw new AppError("review_fix_stage_invalid", "Review-fix requires its unchanged private source snapshot", 2, { reason: "snapshot_required", effect: "no_effect" });
+    return { bundle, source, scope, run, replay, snapshot, snapshotSelection,
+        assertCustody(writer) {
+            assertReviewFixSourceIntakeCustody(writer, scope, bundle, source.sha256);
+            if (hybridDigest(readDiagnosticSnapshotCustody(writer, snapshotSelection, input.runId)) !== hybridDigest(snapshot))
+                throw new AppError("review_fix_stage_invalid", "Review-fix source snapshot custody changed", 2, { reason: "snapshot_changed", effect: "no_effect" });
+        }
+    };
+}
+export function startReviewFixStage(context, input) {
+    const selected = readReviewFixStageScope(context, input), { source } = selected;
+    const fence = selected.assertCustody;
+    const start = PreparedDescriptorStageStart.prepare(context, input).apply(context, fence);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input).apply(context, fence);
+    return { ...start, ...coordinator, intake_sha256: source.sha256, source_intake: source.reference };
+}