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

package/dist/services/external-work-launch.js

@@ -0,0 +1,316 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { ensureWorkLaunchStorage } from "../storage/database.js";
+import { AppError } from "../shared/errors.js";
+import { runtimeBudgetForRun } from "./runtime-budget.js";
+import { adapterSessionId, prepareHarnessFlowExecutable, runHarnessAdapter } from "./harness-adapter.js";
+import { harnessRuntimeArguments, resolveHarnessCommand } from "./harness-config.js";
+import { resolveExecutionPolicy, runtimeHarness, validateExecutionOverride } from "./execution-policy.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { assertWorkLaunchReady, reviewSourceInputs, workStartCommand } from "./work-registry.js";
+import { initCodexHome } from "./hooks.js";
+import { managedInvocationContext } from "./lifecycle-invocations.js";
+import { reviewExecutionCopyHash, reviewSourceFilter, reviewSourceHash, reviewSourcePaths } from "./review-copy.js";
+import { workspaceGitFiles } from "./workspace-files.js";
+import { qualifyAgyHooks } from "../harness-runtime/lib/dd-agy-daemon.mjs";
+import { lifecycleRetryInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { continueProviderCapacity, ownedProviderBoundary } from "./provider-capacity.js";
+import { errorRecord } from "./run-controller-state.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { stageWorkIds } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareMemoryRepairDispatchFromStage, prepareMemorySecondRepairDispatchFromStage, prepareExternalMemoryRepairCopyFromStage, prepareMemorySecondRepairLaunchFromStage } from "./memory-review-handler.js";
+import { readRegisteredInteractiveWork } from "./interactive-work-registration.js";
+/**
+ * Creates an external provider root for one already-created Work.  The launch
+ * is not a Work claim: only the worker's trusted `work start` hook binds it.
+ */
+export async function launchExternalWork(context, input) {
+    ensureWorkLaunchStorage(context.db);
+    const work = context.db.get("SELECT work_id, project_id, run_id, status, payload_json FROM works WHERE work_id = ?", [input.workId]);
+    if (!work)
+        throw new AppError("not_found", "Work was not found", 1, { work_id: input.workId });
+    const run = context.db.get("SELECT run_root, project_root, workspace_root, index_json, status FROM runs WHERE project_id = ? AND id = ?", [work.project_id, work.run_id]);
+    if (!run?.run_root)
+        throw new AppError("runtime_missing", "Work has no materialized RUN root", 1, { work_id: work.work_id });
+    const existing = context.db.get("SELECT operation_id, status, provider_session_id, profile_hash, journal_path FROM work_launches WHERE work_id = ?", [work.work_id]);
+    if (existing)
+        return { ok: true, work_id: work.work_id, operation_id: existing.operation_id, status: existing.status, provider_session_id: existing.provider_session_id, profile_hash: existing.profile_hash, journal_path: existing.journal_path, idempotent: true };
+    assertWorkLaunchReady(context, work.work_id);
+    if (run.status !== "running")
+        throw new AppError("invalid_run_state", "External Work dispatch requires a running RUN", 2, { run_id: work.run_id, status: run.status });
+    const generation = assertRunMutationAllowed(context, work.project_id, work.run_id);
+    const snapshot = JSON.parse(run.index_json);
+    const override = workOverride(work.payload_json);
+    const policy = snapshot.execution_profile?.settings?.execution ?? {};
+    const stage = snapshot.current_stage ?? [...(snapshot.stage_runs ?? [])].reverse().find((entry) => entry.status === "running")?.stage;
+    if (input.stage !== undefined && input.stage !== stage)
+        throw new AppError("execution_stage_mismatch", "Requested stage does not match the RUN's current stage", 2, { requested_stage: input.stage, current_stage: stage ?? null });
+    if (!stage && Object.keys(policy.stage_overrides ?? {}).length)
+        throw new AppError("execution_stage_missing", "Stage overrides require an authoritative RUN stage", 1, { run_id: work.run_id });
+    const bundle = readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: work.run_id });
+    let resolved;
+    if (bundle) {
+        if (!stage)
+            throw new AppError("execution_stage_missing", "Bound Work requires an authoritative RUN stage", 1);
+        if (snapshot.current_stage !== stage || !snapshot.stage_runs?.some(entry => entry.stage === stage && entry.status === "running")
+            || !stageWorkIds(context, work.project_id, work.run_id, stage).has(work.work_id)) {
+            throw new AppError("execution_stage_mismatch", "Bound Work does not belong to the active running stage", 2);
+        }
+        if (override?.delegation !== undefined)
+            throw new AppError("generic_execution_invalid", "Work cannot replace the RUN's frozen delegation", 2);
+        const interactive = bundle.manifest.flow_id === "interactive"
+            ? readRegisteredInteractiveWork(context, { projectId: work.project_id, runId: work.run_id }, bundle, work.work_id).packet : null;
+        if (interactive && interactive.owner_stage !== stage)
+            throw new AppError("execution_stage_mismatch", "Interactive role differs from its owning Stage", 2);
+        const route = interactive ? bundle.execution.work(stage, override?.agent_profile_id, interactive.stage)
+            : bundle.execution.work(stage, override?.agent_profile_id);
+        const selected = { coordinator: route.coordinator, worker: route.worker,
+            delegation: { mode: route.delegation.mode, max_parallel: route.delegation.mode === "external" ? route.delegation.max_parallel : null } };
+        resolved = { ...selected, profile_hash: crypto.createHash("sha256").update(JSON.stringify(selected)).digest("hex") };
+    }
+    else {
+        if (!snapshot.execution_profile?.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "External dispatch requires a RUN with frozen agent profiles; recreate the RUN with the current engine", 1, { work_id: work.work_id });
+        resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy, profiles: snapshot.execution_profile.agent_profiles, ...(stage ? { stage } : {}), ...(override ? { work: override } : {}) });
+    }
+    if (resolved.delegation.mode !== "external")
+        throw new AppError("external_launch_not_selected", "This Work's frozen policy selects native delegation", 2, { work_id: work.work_id });
+    let payload = null;
+    try {
+        payload = work.payload_json ? JSON.parse(work.payload_json) : null;
+    }
+    catch { /* Legacy non-memory payload handling remains owned by the Work registry. */ }
+    const repairWave = payload?.kind === "memory-repair" ? payload.memory_repair?.wave : undefined;
+    if (payload?.kind === "memory-repair" && (payload.read_only !== false || ![1, 2].includes(repairWave ?? 0)
+        || (bundle?.descriptor.descriptor.id !== "mb-init" && bundle?.descriptor.descriptor.id !== "mb-upgrade") || stage !== "review")) {
+        throw new AppError("memory_repair_launch_invalid", "Repair dispatch requires its registered memory review wave", 2, { phase: "prepare", effect: "no_effect" });
+    }
+    const repairScope = { projectRoot: run.project_root, runId: work.run_id, workId: work.work_id };
+    const prepareRepairPacket = repairWave === 1 ? prepareMemoryRepairDispatchFromStage : prepareMemorySecondRepairDispatchFromStage;
+    const repairPacket = repairWave ? prepareRepairPacket(context, repairScope) : null;
+    const assertRepairPacket = (effect = "no_effect") => {
+        if (!repairPacket)
+            return;
+        try {
+            const expected = { coordinator: resolved.coordinator, worker: resolved.worker, delegation: resolved.delegation };
+            const actual = { coordinator: repairPacket.profile.coordinator, worker: repairPacket.profile.worker, delegation: repairPacket.profile.delegation };
+            if (repairPacket.work_id !== work.work_id || repairPacket.profile.profile_hash !== resolved.profile_hash
+                || hybridDigest(actual) !== hybridDigest(expected) || hybridDigest(prepareRepairPacket(context, repairScope)) !== hybridDigest(repairPacket)) {
+                throw new AppError("memory_repair_launch_invalid", "Repair ready copy or frozen route changed before dispatch", 2, { phase: "prepare", effect: "no_effect" });
+            }
+        }
+        catch (error) {
+            if (effect === "partial")
+                throw new AppError("memory_repair_launch_pending", "Repair launch files are retained but dispatch custody changed", 1, { effect, work_id: work.work_id, operation_id: operationId, state_dir: root, next_action: "reconcile_exact_request", cause: errorRecord(error) });
+            throw error;
+        }
+    };
+    assertRepairPacket();
+    const agyWorker = runtimeHarness(resolved.worker) === "antigravity-cli";
+    if (agyWorker && repairPacket)
+        throw new AppError("memory_repair_launch_invalid", "Repair copy hook qualification is required before Antigravity dispatch", 2, { phase: "prepare", effect: "no_effect" });
+    if (agyWorker)
+        await qualifyAgyHooks(run.workspace_root);
+    assertRepairPacket();
+    const operationId = `OPR-${crypto.randomUUID()}`;
+    const root = path.join(run.run_root, "external-launches", operationId);
+    const journal = path.join(root, "adapter.events.jsonl");
+    fs.mkdirSync(root, { recursive: true });
+    const isolatedWorkspace = isReadOnlyWork(work.payload_json) ? path.join(root, "read-only-workspace") : null;
+    const reviewInputs = isolatedWorkspace ? reviewSourceInputs(context, work.work_id) : [];
+    const reviewBase = snapshot.workspace?.base && snapshot.workspace.base !== "unknown" ? snapshot.workspace.base : "HEAD";
+    let reviewCopy = null;
+    if (isolatedWorkspace) {
+        const allowed = reviewSourceFilter(run.workspace_root, reviewInputs, reviewBase);
+        const before = reviewSourceHash(run.workspace_root, reviewInputs, reviewBase);
+        fs.cpSync(run.workspace_root, isolatedWorkspace, { recursive: true, verbatimSymlinks: true, filter: allowed });
+        if (agyWorker)
+            await qualifyAgyHooks(isolatedWorkspace);
+        const after = reviewSourceHash(run.workspace_root, reviewInputs, reviewBase), copy = reviewExecutionCopyHash(isolatedWorkspace, run.workspace_root, false, reviewInputs, reviewBase);
+        if (before !== after || after !== copy)
+            throw new AppError("read_only_input_changed", "Read-only execution copy differs from its authoritative source", 2, { work_id: work.work_id, before, after, copy });
+        writeReviewGitEvidence(run.workspace_root, isolatedWorkspace, snapshot.workspace?.base, reviewInputs);
+        if (reviewSourceHash(run.workspace_root, reviewInputs, reviewBase) !== after)
+            throw new AppError("read_only_input_changed", "Authoritative review workspace changed while collecting Git evidence", 2, { work_id: work.work_id });
+        reviewCopy = { root: path.relative(run.run_root, isolatedWorkspace).split(path.sep).join("/"), sha256: reviewExecutionCopyHash(isolatedWorkspace, run.workspace_root, true, reviewInputs, reviewBase), source_sha256: after };
+    }
+    const now = context.now();
+    const flowExecutable = prepareHarnessFlowExecutable(context, root, bundle?.engine());
+    const env = { ...context.env, DD_FLOW_BIN: flowExecutable, DD_FLOW_INVOCATION_SCOPE: undefined, DD_FLOW_CURRENT_INVOCATION: undefined,
+        DD_FLOW_MEMORY_REPAIR_WORKSPACE: repairPacket?.copy_root, ...(repairPacket ? { DD_FLOW_READ_ONLY_WORKSPACE: undefined } : {}),
+        ...(isolatedWorkspace ? { DD_FLOW_READ_ONLY_WORKSPACE: isolatedWorkspace } : {}) };
+    // An external Codex root is a fresh thread, so it does not inherit the
+    // coordinator's managed PreToolUse hook.  Its first `work start` must emit
+    // that hook event to bind the Work to the physical session.
+    if (runtimeHarness(resolved.worker) === "codex-desktop") {
+        const codexHome = path.join(root, "codex-home");
+        initCodexHome(context, { projectRoot: run.project_root, profile: `external-${operationId}`, targetHome: codexHome, ...(context.env.CODEX_HOME ? { sourceHome: context.env.CODEX_HOME } : {}) });
+        env.CODEX_HOME = codexHome;
+    }
+    let runtimeContext = { ...context, env };
+    const runtimeOwner = { schema_id: "dd-flow/runtime-owner@1", owner_id: `run:${work.run_id}:work:${work.work_id}`, role: "worker", project_id: work.project_id, run_id: work.run_id, work_id: work.work_id, operation_id: operationId, state_dir: root, dd_flow_home: context.ddFlowHome, dd_flow_bin: flowExecutable, resource_home: context.env.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome, budget: runtimeBudgetForRun(context, work.project_id, work.run_id) };
+    const executable = resolveHarnessCommand(context.ddFlowHome, runtimeHarness(resolved.worker), "adapter");
+    assertRepairPacket("partial");
+    context.db.run("INSERT INTO work_launches (operation_id, work_id, profile_json, profile_hash, status, state_dir, journal_path, provider_session_id, adapter_receipt_json, created_at, updated_at) VALUES (?, ?, ?, ?, 'launching', ?, ?, NULL, NULL, ?, ?)", [operationId, work.work_id, JSON.stringify({ ...resolved, runtime_adapter: { executable, owner: runtimeOwner }, ...(reviewCopy ? { review_copy: reviewCopy } : {}), ...(repairPacket ? { memory_repair_copy: repairPacket.profile.memory_repair_copy } : {}) }), resolved.profile_hash, root, journal, now, now]);
+    const common = ["--dd-flow-bin", flowExecutable, "--state-dir", root, "--journal", journal, "--cwd", repairPacket?.copy_root ?? isolatedWorkspace ?? run.workspace_root, "--provider", resolved.worker.provider, "--model", resolved.worker.model, "--reasoning", resolved.worker.reasoning, "--mode", resolved.worker.mode, "--permission", resolved.worker.permission, "--project-root", run.project_root, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, runtimeHarness(resolved.worker)), "--json"];
+    const evidence = (value) => fs.appendFileSync(journal, `${JSON.stringify({ type: "adapter_call", at: context.now(), ...value })}\n`);
+    try {
+        const call = (args, timeoutMs, id = `${operationId}:${args[0]}.${args[1]}`) => runHarnessAdapter({ executable, args, harness: runtimeHarness(resolved.worker), env: runtimeContext.env, operationId: id, runtimeOwner, ...(timeoutMs !== undefined ? { timeoutMs } : {}), ...(input.signal ? { signal: input.signal } : {}), ...(input.progress ? { progress: input.progress } : {}), onEvidence: evidence, onNativeOutcome: value => {
+                if (args[0] !== "session" || args[1] !== "create")
+                    return;
+                const nativeId = adapterSessionId(value);
+                if (nativeId)
+                    context.db.run("UPDATE work_launches SET provider_session_id = ?, adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [nativeId, JSON.stringify({ create: value, settlement_pending: true }), context.now(), operationId]);
+            } });
+        await call(["daemon", "start", ...common]);
+        assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
+        const created = await call(["session", "create", ...common]);
+        const sessionId = adapterSessionId(created);
+        if (!sessionId)
+            throw new AppError("harness_adapter_invalid", "Harness adapter did not return a typed Session id", 1, { work_id: work.work_id, harness: runtimeHarness(resolved.worker) });
+        // Retain the physical root before any subsequent guard or prompt can fail.
+        context.db.run("UPDATE work_launches SET provider_session_id = ?, adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [sessionId, JSON.stringify({ create: created }), context.now(), operationId]);
+        runtimeContext = managedInvocationContext(runtimeContext, { harness: runtimeHarness(resolved.worker), stateDir: root, sessionId,
+            projectRoot: run.project_root, runId: work.run_id, generation });
+        assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
+        assertWorkLaunchReady(runtimeContext, work.work_id);
+        if (repairPacket) {
+            const owner = repairWave === 1
+                ? prepareExternalMemoryRepairCopyFromStage(context, { ...repairScope, workspaceRoot: repairPacket.copy_root })
+                : prepareMemorySecondRepairLaunchFromStage(context, repairScope);
+            if (owner.root() !== repairPacket.copy_root)
+                throw new AppError("memory_repair_launch_invalid", "Physical repair launch differs from the prepared copy", 1, { effect: "partial", next_action: "reconcile_exact_request" });
+            owner.revalidate(context);
+        }
+        if (reviewCopy && reviewSourceHash(run.workspace_root, reviewInputs, reviewBase) !== reviewCopy.source_sha256)
+            throw new AppError("read_only_input_changed", "Authoritative review workspace changed after the execution copy was made", 2, { work_id: work.work_id });
+        const promptFile = path.join(root, "launch.md");
+        fs.writeFileSync(promptFile, `Start the assigned Work now. Your first tool call must be this exact standalone command:\n\n${workStartCommand(runtimeContext, work)}\n\nUse the packet returned by that command. Do not claim another Work or run this command more than once.\n\nAfter the issued Work finish succeeds, end this Turn immediately. The coordinator, not you, continues the Stage. Do not then read or follow other runtime/coordinator prompts, run Stage checks, write Stage proposals, or invoke stage start/finish/resume.\n\n${lifecycleRetryInstruction}${isolatedWorkspace ? `\n\nThe review copy has no .git. Read the captured status/diff or gitless note in ${path.join(isolatedWorkspace, ".dd-flow", "review-evidence")}; do not run Git inside the copy.\n` : "\n"}`);
+        const promptOperationId = `${operationId}:session.prompt`;
+        context.db.run("UPDATE work_launches SET adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ? AND status = 'launching'", [JSON.stringify({ create: created, progress_policy: "native-inactivity@1" }), context.now(), operationId]);
+        let prompted;
+        try {
+            prompted = await call(["session", "prompt", "--session-id", sessionId, "--prompt-file", promptFile, ...common], null);
+        }
+        catch (error) {
+            const retained = context.db.get("SELECT adapter_receipt_json FROM work_launches WHERE operation_id = ?", [operationId]);
+            const capacityIntents = retained?.adapter_receipt_json ? JSON.parse(retained.adapter_receipt_json).capacity_intents ?? [] : [];
+            const capacityFailures = retained?.adapter_receipt_json ? JSON.parse(retained.adapter_receipt_json).capacity_failures ?? [] : [];
+            const retainCapacity = () => {
+                const changed = context.db.run("UPDATE work_launches SET adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ? AND status = 'launching'", [JSON.stringify({ create: created, progress_policy: "native-inactivity@1", capacity_intents: capacityIntents, capacity_failures: capacityFailures }), context.now(), operationId]);
+                if (changed.changes !== 1)
+                    throw new AppError("capacity_continuation_blocked", "External Work launch owner changed", 1);
+            };
+            const resumed = await continueProviderCapacity({ error, sessionId, operationId: promptOperationId, allowSettledDescendants: true,
+                ...(input.signal ? { signal: input.signal } : {}),
+                continuationText: `Continue only Work ${work.work_id} in RUN ${work.run_id}, Stage ${stage ?? "current"}, in the same Session. Inspect its current durable state and the retained Work packet. Never repeat Work start or a completed tool, accepted answer, check or lifecycle command. Use only the current exact issued successor and finish at the original Work boundary.`,
+                retainedIntents: () => capacityIntents,
+                retainedFailures: () => capacityFailures,
+                retainFailure: (_id, refusal) => { capacityFailures.push(refusal); retainCapacity(); },
+                inspectOperation: id => call(["daemon", "operation", "--state-dir", root, "--operation-id", id, "--json"], 30_000, `${id}:capacity-observe`),
+                inspectSession: turnId => call(["session", "inspect", "--session-id", sessionId, ...(turnId ? ["--turn-id", turnId] : []), ...common], 30_000, `${operationId}:capacity-inspect`),
+                assertCurrent: () => {
+                    assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
+                    const current = context.db.get("SELECT w.status, l.status AS launch_status FROM works w JOIN work_launches l ON l.work_id = w.work_id WHERE w.work_id = ? AND l.operation_id = ?", [work.work_id, operationId]);
+                    if (!current || !["created", "running", "paused", "completed"].includes(current.status) || current.launch_status !== "launching")
+                        throw new AppError("capacity_continuation_blocked", "External Work changed before its native continuation", 1, { work_id: work.work_id, state: current });
+                    if (reviewCopy && reviewSourceHash(run.workspace_root, reviewInputs, reviewBase) !== reviewCopy.source_sha256)
+                        throw new AppError("read_only_input_changed", "Authoritative review workspace changed during capacity wait", 2);
+                },
+                decision: (boundary) => {
+                    if (boundary && (!stage || !ownedProviderBoundary(context, { projectId: work.project_id, runId: work.run_id, stage, sessionId, generation, workId: work.work_id, scope: "work" }, boundary)))
+                        return "reconciliation_blocked";
+                    const status = context.db.get("SELECT status FROM works WHERE work_id = ?", [work.work_id])?.status;
+                    return status === "completed" ? "completed" : status === "paused" ? "paused" : "continue";
+                },
+                retainIntent: intent => {
+                    capacityIntents.push(intent);
+                    retainCapacity();
+                },
+                prompt: (id, text, ordinal) => {
+                    const file = path.join(root, `capacity-${ordinal}.md`);
+                    if (fs.existsSync(file)) {
+                        if (fs.readFileSync(file, "utf8") !== text)
+                            throw new AppError("capacity_continuation_conflict", "Retained Work continuation prompt differs", 1);
+                    }
+                    else
+                        fs.writeFileSync(file, text, { flag: "wx", mode: 0o600 });
+                    return call(["session", "prompt", "--session-id", sessionId, "--prompt-file", file, ...common], null, id);
+                } });
+            if (!resumed)
+                throw error;
+            prompted = resumed;
+        }
+        assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
+        const saved = context.db.get("SELECT adapter_receipt_json FROM work_launches WHERE operation_id = ?", [operationId]);
+        context.db.run("UPDATE work_launches SET status = 'start_requested', provider_session_id = ?, adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [sessionId, JSON.stringify({ ...(saved?.adapter_receipt_json ? JSON.parse(saved.adapter_receipt_json) : {}), create: created, prompt: prompted }), context.now(), operationId]);
+        return { ok: true, work_id: work.work_id, operation_id: operationId, status: "start_requested", session: { harness_id: runtimeHarness(resolved.worker), session_id: sessionId }, profile_hash: resolved.profile_hash, journal_path: journal };
+    }
+    catch (error) {
+        const saved = context.db.get("SELECT adapter_receipt_json FROM work_launches WHERE operation_id = ?", [operationId]);
+        let failure = error;
+        if (repairPacket) {
+            const physical = context.db.get("SELECT provider_session_id FROM work_launches WHERE operation_id = ?", [operationId]);
+            failure = new AppError("memory_repair_launch_pending", "Repair launch retains runtime effects; reconcile the exact request before continuing", 1, { effect: error instanceof AppError && error.details.effect === "unknown" ? "unknown" : "partial",
+                work_id: work.work_id, operation_id: operationId, provider_session_id: physical?.provider_session_id ?? null,
+                next_action: "reconcile_exact_request", cause: errorRecord(error) });
+        }
+        context.db.run("UPDATE work_launches SET status = 'failed', adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ ...(saved?.adapter_receipt_json ? JSON.parse(saved.adapter_receipt_json) : {}), error: errorRecord(failure) }), context.now(), operationId]);
+        throw failure;
+    }
+}
+export function writeReviewGitEvidence(source, copy, base, explicitInputs = []) {
+    const directory = path.join(copy, ".dd-flow", "review-evidence");
+    fs.mkdirSync(directory, { recursive: true });
+    if (workspaceGitFiles(source, ["--cached"]) === null) {
+        fs.writeFileSync(path.join(directory, "gitless.txt"), "Source workspace is not a Git repository. Review the copied files and accepted RUN evidence.\n");
+        return;
+    }
+    if (!base || base === "unknown")
+        throw new AppError("review_git_evidence_missing", "Git review source has no frozen base commit", 1, { workspace_root: source });
+    const paths = (reviewSourcePaths(source, explicitInputs, base) ?? []).map(file => `:(literal)${file}`);
+    const commands = [["status.txt", ["status", "--short", "--untracked-files=all"]],
+        ["diff.patch", ["diff", "--no-ext-diff", "--no-renames", "--binary", ...(base === "unborn" ? ["--cached"] : [base])]]];
+    // No revision exists in an unborn repository. Retain both index additions
+    // and subsequent working edits; untracked bytes are in the filtered copy.
+    if (base === "unborn")
+        commands.push(["diff-working.patch", ["diff", "--no-ext-diff", "--no-renames", "--binary"]]);
+    for (const [name, args] of commands) {
+        const result = paths.length ? spawnSync("git", ["-C", source, ...args, "--", ...paths], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }) : { status: 0, stdout: "", stderr: "", error: undefined };
+        if (result.status !== 0 || result.error)
+            throw new AppError("review_git_evidence_failed", "Could not collect read-only Git evidence for reviewer", 1, { workspace_root: source, command: name, cause: result.error?.message ?? result.stderr });
+        fs.writeFileSync(path.join(directory, name), result.stdout);
+    }
+    fs.writeFileSync(path.join(directory, "base.txt"), `${base}\n`);
+}
+function workOverride(payload) {
+    if (!payload)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(payload);
+    }
+    catch {
+        return undefined;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const execution = value.execution_override;
+    if (execution === undefined)
+        return undefined;
+    validateExecutionOverride(execution);
+    return execution;
+}
+function isReadOnlyWork(payload) {
+    if (!payload)
+        return false;
+    try {
+        return JSON.parse(payload).read_only === true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/services/flow-catalog.js

@@ -0,0 +1,54 @@
+import { vnextStages } from "../domain/stage-catalog.js";
+import { sdlcHandlerIdentities, memoryInitHandlerIdentities, memoryUpgradeHandlerIdentities } from "../domain/stage-handler-identities.js";
+import { AppError } from "../shared/errors.js";
+import { diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { distillStages } from "../domain/distill-flow.js";
+import { memoryFixStages } from "../domain/memory-fix-flow.js";
+import { reviewFixStages } from "../domain/review-fix-flow.js";
+import { interactiveStages } from "../domain/interactive-flow.js";
+import { deliveryFlowStages } from "../domain/delivery-flows.js";
+/** Engine-owned catalog, not descriptor discovery or permission to execute a RUN. */
+export function listBundledFlows() {
+    return [
+        { id: "sdlc", handler_status: "registered", entry_stage: "specify", terminal_stages: ["merge"],
+            stages: vnextStages.map(stage => ({ id: stage.id, directory: stage.directory,
+                entry_handler: sdlcHandlerIdentities[stage.id].entryId, finish_handler: sdlcHandlerIdentities[stage.id].finishId })),
+            edges: vnextStages.flatMap(stage => stage.next.map((to, index) => ({ from: stage.id, to, on: index ? "not-applicable" : "accepted" }))) },
+        ...[{ id: "mb-init", handlers: memoryInitHandlerIdentities }, { id: "mb-upgrade", handlers: memoryUpgradeHandlerIdentities }].map(({ id, handlers }) => {
+            const stages = Object.values(handlers);
+            return { id, handler_status: "registered", entry_stage: "preflight", terminal_stages: ["finish"],
+                stages: stages.map((handler, index) => ({ id: handler.stage, directory: `${String(index + 1).padStart(2, "0")}-${handler.stage}`, entry_handler: handler.entryId, finish_handler: handler.finishId })),
+                edges: stages.slice(0, -1).flatMap((handler, index) => [{ from: handler.stage, to: stages[index + 1].stage, on: "accepted" },
+                    ...(handler.stage === "verify" ? [{ from: handler.stage, to: "review", on: "needs_repair" }] : [])]) };
+        }),
+        { id: "mb-distill", handler_status: "registered", entry_stage: "preflight", terminal_stages: ["finish"],
+            stages: distillStages.map((id, index) => ({ id, directory: `${String(index + 1).padStart(2, "0")}-${id}`, entry_handler: "distill-stage-entry", finish_handler: "distill-stage-finish" })),
+            edges: distillStages.slice(0, -1).map((from, index) => ({ from, to: distillStages[index + 1], on: "accepted" })) },
+        { id: "mb-fix", handler_status: "registered", entry_stage: "intake", terminal_stages: ["finish"],
+            stages: memoryFixStages.map((id, index) => ({ id, directory: `${String(index + 1).padStart(2, "0")}-${id}`,
+                entry_handler: "memory-fix-stage-entry", finish_handler: "memory-fix-stage-finish" })),
+            edges: memoryFixStages.slice(0, -1).map((from, index) => ({ from, to: memoryFixStages[index + 1], on: "accepted" })) },
+        { id: "review-fix", handler_status: "registered", entry_stage: "intake", terminal_stages: ["handoff"],
+            stages: reviewFixStages.map((id, index) => ({ id, directory: `${String(index + 1).padStart(2, "0")}-${id}`,
+                entry_handler: "review-fix-stage-entry", finish_handler: "review-fix-stage-finish" })),
+            edges: reviewFixStages.slice(0, -1).map((from, index) => ({ from, to: reviewFixStages[index + 1], on: "accepted" })) },
+        { id: "interactive", handler_status: "registered", entry_stage: "preflight", terminal_stages: ["integration"],
+            stages: interactiveStages.map((id, index) => ({ id, directory: `${String(index + 1).padStart(2, "0")}-${id}`,
+                entry_handler: "interactive-stage-entry", finish_handler: "interactive-stage-finish" })),
+            edges: interactiveStages.slice(0, -1).map((from, index) => ({ from, to: interactiveStages[index + 1], on: "accepted" })) },
+        ...Object.entries(deliveryFlowStages).map(([id, stages]) => ({ id, handler_status: "registered", entry_stage: "preflight", terminal_stages: ["finish"],
+            stages: stages.map((stage, index) => ({ id: stage, directory: `${String(index + 1).padStart(2, "0")}-${stage}`,
+                entry_handler: "delivery-stage-entry", finish_handler: "delivery-stage-finish" })),
+            edges: stages.slice(0, -1).map((from, index) => ({ from, to: stages[index + 1], on: "accepted" })) })),
+        ...Object.entries(diagnosticFlowStages).map(([id, stages]) => ({ id, handler_status: "registered", entry_stage: "preflight", terminal_stages: ["report"],
+            stages: stages.map((stage, index) => ({ id: stage, directory: `${String(index + 1).padStart(2, "0")}-${stage}`,
+                entry_handler: "diagnostic-stage-entry", finish_handler: "diagnostic-stage-finish" })),
+            edges: stages.slice(0, -1).map((from, index) => ({ from, to: stages[index + 1], on: "accepted" })) }))
+    ];
+}
+export function showBundledFlow(id) {
+    const flow = listBundledFlows().find(candidate => candidate.id === id);
+    if (!flow)
+        throw new AppError("flow_not_found", "Unknown bundled flow", 2, { effect: "no_effect", flow_id: id });
+    return flow;
+}

package/dist/services/flow-descriptors.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { validateFlowDescriptor, validateHybridShape } from "./hybrid-contracts.js";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const blobLimit = 1024 * 1024;
+function freeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+}
+/** Admitted retained bytes only. This is not a RUN/storage/dispatch permission. */
+export class ResolvedFlowDescriptor {
+    sha256;
+    descriptor;
+    #bytes;
+    #blobs;
+    constructor(bytes, descriptor, blobs) {
+        this.sha256 = digest(bytes);
+        this.#bytes = bytes;
+        this.#blobs = blobs;
+        freeze(descriptor);
+        this.descriptor = descriptor;
+        Object.freeze(this);
+    }
+    /** Context comes from the engine materializer, never descriptor-owned allowlists. */
+    static admit(input, expectedSha256, context) {
+        const details = { phase: "prepare", effect: "no_effect" };
+        if (input.byteLength > blobLimit || !/^[a-f0-9]{64}$/.test(expectedSha256)) {
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor identity or size is invalid", 2, details);
+        }
+        const bytes = Buffer.from(input);
+        if (digest(bytes) !== expectedSha256)
+            throw new AppError("flow_descriptor_integrity", "Flow descriptor bytes do not match the selected identity", 1, details);
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch {
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor must be valid UTF-8 JSON", 2, details);
+        }
+        const shape = validateHybridShape("flow-descriptor", value);
+        if (shape.length)
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor shape is invalid", 2, { ...details, issues: shape });
+        const blobs = new Map();
+        let total = 0;
+        for (const [name, source] of context.blobs) {
+            total += source.byteLength;
+            if (source.byteLength > blobLimit || total > 32 * blobLimit)
+                throw new AppError("flow_descriptor_invalid", "Flow descriptor blobs exceed the bounded inventory", 2, details);
+            blobs.set(name, Buffer.from(source));
+        }
+        const issues = validateFlowDescriptor(value, { ...context, blobs });
+        if (issues.length)
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor context is invalid", 2, { ...details, issues });
+        return new ResolvedFlowDescriptor(bytes, value, blobs);
+    }
+    stage(id) {
+        const stage = this.descriptor.stages.find(candidate => candidate.id === id);
+        if (!stage)
+            throw new AppError("flow_stage_invalid", "Stage does not belong to the resolved flow", 2, { flow_id: this.descriptor.id, stage: id, effect: "no_effect" });
+        return stage;
+    }
+    successor(id, outcome) {
+        this.stage(id);
+        if (outcome !== "accepted" && outcome !== "not-applicable" && outcome !== "needs_repair") {
+            throw new AppError("flow_transition_invalid", "Unknown stage outcome", 2, { flow_id: this.descriptor.id, stage: id, outcome, effect: "no_effect" });
+        }
+        const edge = this.descriptor.edges.find(candidate => candidate.from === id && candidate.on === outcome);
+        if (edge)
+            return edge.to;
+        if (this.descriptor.terminal_stages.includes(id))
+            return null;
+        throw new AppError("flow_transition_invalid", "No declared successor for this stage outcome", 2, { flow_id: this.descriptor.id, stage: id, outcome, effect: "no_effect" });
+    }
+    descriptorBytes() { return Buffer.from(this.#bytes); }
+    stageBlob(id, kind) {
+        const reference = this.stage(id)[kind];
+        return Buffer.from(this.#blobs.get(reference.path));
+    }
+}