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

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

@@ -0,0 +1,245 @@
+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");
+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;
+    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)
+            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 {
+        return false;
+    }
+    if (metadata.run_generation !== scope.generation)
+        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)
+                    continue;
+                verified.push(resolved);
+            }
+            else if (proof.verified === true && JSON.stringify(proof.nativeHookBinding) === JSON.stringify(binding))
+                verified.push(binding);
+        }
+        catch { /* Legacy/retired daemons cannot attest a retained fact. */ }
+    }
+    // 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-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 };
+}

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

@@ -0,0 +1,176 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { reviewFixStages } from "../domain/review-fix-flow.js";
+import { readReviewFixStageScope, startReviewFixStage } from "./review-fix-stage-entry.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement, readAcceptedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { readAcceptedStageData, prepareStagePacket, acceptStagePacket, prepareStageReport, acceptStageReport, publishStagePacket, publishStageReport, resolveStagePublicationPath } from "./stage-report-renderer.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { assertReviewFixStageScope, validateReviewFixStageResult, reviewFixHandoffDisposition } from "./review-fix-stage-results.js";
+import { prepareReviewFixHandoff } from "./review-fix-handoff.js";
+import { assertDiagnosticSessionIndependence } from "./diagnostic-work-collection.js";
+import { readDiagnosticSnapshot } from "./diagnostic-snapshot.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("review_fix_stage_invalid", "Review-fix requires original scope, independent review and a raw handoff", 2, { reason, effect: "no_effect" });
+}
+export const reviewFixStageHandlers = Object.freeze(reviewFixStages.map(stage => Object.freeze({ flowId: "review-fix", stage,
+    entryId: "review-fix-stage-entry", finishId: "review-fix-stage-finish", entry: startReviewFixStage, finish: finishReviewFixStage })));
+/** Read retained raw bytes for terminal replay, never recapture newer messages. */
+function readHandoff(context, scope, attempt, file) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='handoff' AND json_extract(payload_json,'$.attempt')=? LIMIT 33", [scope.projectId, scope.runId, attempt]);
+    if (rows.length > 32)
+        refuse("handoff_custody_invalid");
+    const packets = rows.map(row => {
+        if (Buffer.byteLength(row.payload_json) > 6 * 1024 * 1024)
+            refuse("handoff_exceeds_bound");
+        return JSON.parse(row.payload_json);
+    }).filter(packet => typeof packet.file === "string" && resolveStagePublicationPath(context, scope.projectId, scope.runId, packet.file) === file);
+    if (!packets.length)
+        return null;
+    if (packets.length !== 1 || typeof packets[0].base64 !== "string")
+        refuse("accepted_handoff_missing");
+    const bytes = Buffer.from(packets[0].base64, "base64");
+    if (!bytes.length || bytes.length > 4 * 1024 * 1024 || bytes.toString("base64") !== packets[0].base64 || hash(bytes) !== packets[0].sha256)
+        refuse("accepted_handoff_changed");
+    return { bytes, sha256: hash(bytes) };
+}
+/** Generic Stage/RUN settlement remains the sole lifecycle owner. This handler
+ * writes only retained runtime packets/reports, never project files or SDLC. */
+export function finishReviewFixStage(context, input) {
+    if (!input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    const selected = readReviewFixStageScope(context, input, true), { bundle, source, scope, replay, snapshot } = selected;
+    const packet = readDescriptorStageInput(context, scope, bundle, true, true);
+    const stage = input.stage;
+    const previousStage = stage === "scope-review" ? "intake" : stage === "handoff" ? "scope-review" : null;
+    const previous = previousStage ? readAcceptedStageData(context, { ...scope, stage: previousStage }) : null;
+    const prior = previous ? JSON.parse(previous.bytes.toString("utf8")) : null;
+    if (previous && (packet.input.predecessor?.stage !== previousStage || hybridDigest(packet.input.predecessor.result) !== hybridDigest(previous.result)))
+        refuse("predecessor_changed");
+    const bytes = Buffer.from(input.bytes);
+    let result;
+    const users = !replay ? readPreparedMemoryFlowUserInputs(context, scope, "review-fix", bundle) : null;
+    if (replay) {
+        const accepted = readAcceptedStageData(context, scope);
+        if (!accepted.bytes.equals(bytes))
+            refuse("accepted_result_changed");
+        result = JSON.parse(accepted.bytes.toString("utf8"));
+    }
+    else {
+        result = validateReviewFixStageResult(bytes, bundle.descriptor.stageBlob(stage, "result_schema"), {
+            runId: input.runId, stage, inputSha256: packet.inputSha256, intakeSha256: source.sha256,
+            snapshotSha256: snapshot.source_sha256, userInputsSha256: hybridDigest(users),
+            findingIds: source.intake.selected_findings.map(finding => finding.id), predecessors: previous ? [{ stage: previousStage, ...previous.result }] : [],
+            userSources: 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 };
+            })
+        });
+        if (source.intake.limitations.some(item => !result.details.limitations.includes(item)))
+            refuse("source_limitations_missing");
+        if (prior)
+            assertReviewFixStageScope(result, prior);
+    }
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, input);
+    const keys = (name) => entityReferenceVariants(input.runId).map(ref => stageLifecycleMatchKey("stage_finish", ref, name, input.projectRoot));
+    const intakeKeys = stage !== "intake" ? keys("intake") : [];
+    const reviewKeys = stage === "handoff" ? keys("scope-review") : [];
+    const readOwners = (reader) => {
+        const physical = (id) => {
+            const session = reader.db.get("SELECT harness,provider_session_id FROM sessions WHERE project_id=? AND run_id=? AND session_id=?", [scope.projectId, scope.runId, id]);
+            if (!session?.harness || !session.provider_session_id)
+                refuse("physical_owner_missing");
+            return session;
+        };
+        const intake = stage !== "intake" ? readAcceptedDescriptorStageSettlement(reader, { ...scope, stage: "intake" }, bundle, intakeKeys) : null;
+        const review = stage === "handoff" ? readAcceptedDescriptorStageSettlement(reader, { ...scope, stage: "scope-review" }, bundle, reviewKeys) : null;
+        if (intake)
+            assertDiagnosticSessionIndependence([physical(review ? review.binding.sessionId : settlement.coordinatorSessionId())], [physical(intake.binding.sessionId)]);
+        return { intake, review };
+    };
+    const owners = context.db.readSnapshot(() => readOwners(context));
+    const handoff = stage === "handoff" && !replay ? prepareReviewFixHandoff(context, input) : null;
+    const reportRoot = path.join(packet.runRoot, bundle.descriptor.stage(stage).directory), handoffFile = path.join(reportRoot, "raw-intake.json");
+    const retained = stage === "handoff" && replay ? readHandoff(context, scope, packet.attempt, handoffFile) : null;
+    if (stage === "handoff" && replay && !retained)
+        refuse("accepted_handoff_missing");
+    const raw = handoff ?? retained;
+    const rawPacket = handoff ? prepareStagePacket(handoffFile, handoff.bytes) : null;
+    const report = stage === "handoff" && raw ? prepareStageReport({ run_id: input.runId, stage, verdict: "completed", summary: result.summary,
+        review_fix: { disposition: reviewFixHandoffDisposition(result), formalization_authorized: false,
+            source: source.intake.source, source_intake: source.reference, unselected_ids: source.intake.unselected_ids,
+            scope: result.details, raw_intake: { root: "run", path: `${bundle.descriptor.stage(stage).directory}/raw-intake.json`, sha256: raw.sha256 } },
+        semantic: { next_action: "No repair or SDLC was started. Ready scope requires a separate explicit user formalization through vnext/start.md; deferred/declined/needs_scope remain honest outcomes." }
+    }) : null;
+    if (report && Buffer.byteLength(JSON.stringify(report.bytes)) > 7 * 1024 * 1024)
+        refuse("terminal_report_exceeds_bound");
+    if (!replay && hybridDigest(readDiagnosticSnapshot(context, selected.snapshotSelection, input.runId)) !== hybridDigest(snapshot))
+        refuse("snapshot_changed");
+    const fence = (writer) => {
+        selected.assertCustody(writer);
+        if (previous && hybridDigest(readAcceptedStageData(writer, { ...scope, stage: previousStage })) !== hybridDigest(previous))
+            refuse("predecessor_changed");
+        if (hybridDigest(readOwners(writer)) !== hybridDigest(owners))
+            refuse("review_owner_changed");
+        if (users && hybridDigest(readPreparedMemoryFlowUserInputs(writer, scope, "review-fix", bundle)) !== hybridDigest(users))
+            refuse("delivered_inputs_changed");
+        handoff?.assertCustody(writer);
+        if (rawPacket && !replay) {
+            const existing = readHandoff(writer, scope, packet.attempt, handoffFile);
+            if (existing && !existing.bytes.equals(rawPacket.bytes))
+                refuse("accepted_handoff_changed");
+            if (!existing)
+                acceptStagePacket(writer, { ...scope, prepared: rawPacket });
+        }
+        if (retained && hybridDigest(readHandoff(writer, scope, packet.attempt, handoffFile)) !== hybridDigest(retained))
+            refuse("accepted_handoff_changed");
+        if (report) {
+            const rows = writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_report' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='handoff' AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, scope.runId, packet.attempt]);
+            if (rows.length > 1 || rows.some(row => Buffer.byteLength(row.payload_json) > 8 * 1024 * 1024))
+                refuse("terminal_report_custody_invalid");
+            if (rows.length) {
+                const stored = JSON.parse(rows[0].payload_json);
+                if (stored.sha256 !== report.sha256 || hybridDigest(stored.bytes) !== hybridDigest(report.bytes)
+                    || resolveStagePublicationPath(writer, scope.projectId, scope.runId, stored.root) !== reportRoot)
+                    refuse("terminal_report_changed");
+            }
+            else {
+                if (replay)
+                    refuse("accepted_terminal_report_missing");
+                acceptStageReport(writer, { ...scope, root: reportRoot, prepared: report });
+            }
+        }
+    };
+    let acceptedStage = false;
+    try {
+        const accepted = settlement.apply(context, fence);
+        acceptedStage = true;
+        if (stage !== "handoff")
+            return accepted;
+        const complete = PreparedDescriptorRunSettlement.prepare(context, input).apply(context, fence);
+        publishStagePacket(context, scope.projectId, scope.runId, stage, handoffFile);
+        publishStageReport(context, scope.projectId, scope.runId, stage, reportRoot);
+        return { ...accepted, ...complete, disposition: reviewFixHandoffDisposition(result), formalization_authorized: false,
+            handoff: handoffFile, reports: ["json", "md", "html"].map(extension => path.join(reportRoot, `stage-report.${extension}`)) };
+    }
+    catch (error) {
+        if (stage !== "handoff")
+            throw error;
+        if (!acceptedStage) {
+            try {
+                acceptedStage = readAcceptedStageData(context, scope).bytes.equals(bytes);
+            }
+            catch { /* Not committed. */ }
+        }
+        if (!acceptedStage)
+            throw error;
+        throw new AppError("review_fix_handoff_pending", "Accepted handoff needs projection or RUN settlement reconciliation", 1, { effect: "committed", run_id: input.runId, next_action: "reconcile_accepted_handoff", cause: error instanceof AppError ? error.code : "handoff_settlement_failed" });
+    }
+}