@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

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

@@ -0,0 +1,308 @@
+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 } 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";
+/**
+ * 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 route = 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" || 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\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: () => {
+                    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,21 @@
+import { vnextStages } from "../domain/stage-catalog.js";
+import { sdlcHandlerIdentities, memoryInitHandlerIdentities } from "../domain/stage-handler-identities.js";
+import { AppError } from "../shared/errors.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", handler_status: "registered", entry_stage: "preflight", terminal_stages: ["finish"],
+            stages: Object.values(memoryInitHandlerIdentities).map((handler, index) => ({ id: handler.stage, directory: `${String(index + 1).padStart(2, "0")}-${handler.stage}`, entry_handler: handler.entryId, finish_handler: handler.finishId })),
+            edges: ["preflight", "discover", "compose", "verify", "review"].flatMap((from, index) => [{ from, to: ["discover", "compose", "verify", "review", "finish"][index], on: "accepted" }, ...(from === "verify" ? [{ from, to: "review", on: "needs_repair" }] : [])]) }
+    ];
+}
+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));
+    }
+}