@deksden-com/dd-flow-cli 0.9.0-beta.137 → 0.9.0-beta.138

package/dist/services/execution-policy.js

@@ -5,6 +5,8 @@ import { AppError } from "../shared/errors.js";
 import { harnessKey } from "./harness-config.js";
 import { vnextStages } from "../domain/stage-catalog.js";
 import { prepareFileBytes, prepareJsonText } from "../cli/input-preparation.js";
+import { operatorSettingsPath, readOperatorProfiles, readOperatorProfileInput, resolveOperatorProfile } from "./operator-profiles.js";
+import { selectOnboardingExecutor } from "./executor-onboarding.js";
 /** Read once so the frozen policy and its provenance describe the same bytes. */
 export function loadExecutionRoutingInput(file) {
     const { file: source_path, bytes } = prepareFileBytes(file, "execution routing");
@@ -48,23 +50,20 @@ export function isExecutionRouting(value) {
 export function loadAgentProfile(ddFlowHome, id) {
     if (typeof id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id))
         throw new AppError("agent_profile_invalid", "Agent profile id is invalid", 2, { id });
+    if (fs.existsSync(operatorSettingsPath(ddFlowHome)))
+        return resolveOperatorProfile(readOperatorProfiles(ddFlowHome), id);
     const file = path.join(ddFlowHome, "agent-profiles", `${id}.json`);
-    let value;
+    if (!fs.existsSync(file))
+        throw new AppError("agent_profile_missing", "Agent profile is unavailable", 1, { id });
+    let profile;
     try {
-        value = JSON.parse(fs.readFileSync(file, "utf8"));
+        profile = readOperatorProfileInput(file);
     }
-    catch (cause) {
-        throw new AppError("agent_profile_missing", "Agent profile is unavailable", 1, { id, file, cause: String(cause) });
+    catch {
+        throw new AppError("agent_profile_invalid", "Agent profile must be a bounded valid regular JSON file", 2, { id });
     }
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new AppError("agent_profile_invalid", "Agent profile must be an object", 2, { id, file });
-    const profile = value;
-    if (profile.schema_id !== "dd-flow/agent-profile@1" || profile.id !== id
-        || Object.keys(profile).some(key => !["schema_id", "id", "harness", "provider", "model", "reasoning", "mode", "permission"].includes(key))
-        || !["codex", "zcode", "agy", "opencode", "grok", "droid"].includes(String(profile.harness))
-        || !nonempty(profile.provider) || !nonempty(profile.model) || !nonempty(profile.reasoning) || !nonempty(profile.mode)
-        || (profile.permission !== "allow" && profile.permission !== "deny")) {
-        throw new AppError("agent_profile_invalid", "Agent profile does not match dd-flow/agent-profile@1", 2, { id, file });
+    if (profile.id !== id) {
+        throw new AppError("agent_profile_invalid", "Agent profile does not match its selected ID", 2, { id });
     }
     // Only execution settings enter RUN evidence; never copy arbitrary profile fields.
     return { schema_id: profile.schema_id, id, harness: profile.harness, provider: profile.provider, model: profile.model, reasoning: profile.reasoning, mode: profile.mode, permission: profile.permission };
@@ -73,10 +72,16 @@ export function snapshotAgentProfiles(ddFlowHome, policy) {
     if (!isExecutionRouting(policy))
         throw new AppError("execution_profile_invalid", "Execution routing contains an invalid stage, profile or delegation policy", 2);
     const profiles = Object.create(null);
+    const settings = fs.existsSync(operatorSettingsPath(ddFlowHome)) ? readOperatorProfiles(ddFlowHome) : undefined;
     for (const override of [policy, ...Object.values(policy.stage_overrides ?? {})]) {
         for (const id of [override.agent_profile_id, override.delegation?.agent_profile_id]) {
-            if (id !== undefined && !Object.hasOwn(profiles, id))
-                profiles[id] = loadAgentProfile(ddFlowHome, id);
+            if (id !== undefined && !Object.hasOwn(profiles, id)) {
+                const profile = settings ? selectOnboardingExecutor({}, () => settings, { allowSkip: false, projectProfileId: id }).profile : loadAgentProfile(ddFlowHome, id);
+                profiles[id] = profile;
+                // Routing labels may be aliases. Default worker resolution uses the
+                // complete coordinator's canonical ID, which must also be frozen.
+                profiles[profile.id] = profile;
+            }
         }
     }
     // Validate every declared route now, including stages not reached by this run.
@@ -177,5 +182,4 @@ export function validateExecutionOverride(value) {
     if (override.delegation !== undefined)
         validateDelegation(override.delegation);
 }
-function nonempty(value) { return typeof value === "string" && Boolean(value.trim()); }
 function digest(value) { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }

package/dist/services/executor-onboarding.js

@@ -0,0 +1,56 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareOperatorProfile, readOperatorProfileInput, resolveOperatorProfile, validateProfileCreationIntent } from "./operator-profiles.js";
+function refuse(code, message, exitCode = 2) {
+    throw new AppError(code, message, exitCode, { phase: "executor_onboarding", effect: "no_effect", help: "profiles" });
+}
+/** Shared setup/first-flow admission; settings are read lazily, never written. */
+export function selectOnboardingExecutor(choice, readSettings, policy) {
+    if (!choice || typeof choice !== "object" || Array.isArray(choice)
+        || Object.keys(choice).some(key => !["profileId", "profile", "profileFile", "skip", "profileCreation"].includes(key))
+        || choice.profileFile !== undefined && (typeof choice.profileFile !== "string" || !choice.profileFile.trim())
+        || choice.skip !== undefined && typeof choice.skip !== "boolean"
+        || choice.profileId !== undefined && (typeof choice.profileId !== "string" || !choice.profileId.trim())) {
+        refuse("usage", "Invalid executor selection");
+    }
+    if ([choice.profileId !== undefined, choice.profile !== undefined, choice.profileFile !== undefined, choice.skip === true].filter(Boolean).length > 1) {
+        refuse("usage", "Executor profile, profile ID and skip are mutually exclusive");
+    }
+    if (choice.profileCreation !== undefined) {
+        validateProfileCreationIntent(choice.profileCreation);
+        if (choice.profile === undefined || hybridDigest(choice.profile) !== hybridDigest(choice.profileCreation.profile))
+            refuse("usage", "Profile save intent requires its exact explicit profile");
+    }
+    if (choice.skip) {
+        if (!policy.allowSkip)
+            refuse("agent_profile_missing", "This operation requires an executor profile", 1);
+        return { profile: null, revision: null, source: "skip" };
+    }
+    const explicit = choice.profile !== undefined || choice.profileFile !== undefined || choice.profileId !== undefined;
+    if (!explicit && policy.projectProfileId !== undefined && (typeof policy.projectProfileId !== "string" || !policy.projectProfileId.trim())) {
+        refuse("usage", "Invalid project executor profile selection");
+    }
+    const profile = prepareOperatorProfile(choice.profile !== undefined ? choice.profile : choice.profileFile !== undefined
+        ? readOperatorProfileInput(choice.profileFile) : resolveOperatorProfile(readSettings(), choice.profileId ?? policy.projectProfileId));
+    return { profile: structuredClone(profile), revision: hybridDigest(profile),
+        ...(choice.profileCreation ? { profileCreation: structuredClone(choice.profileCreation) } : {}),
+        source: choice.profile !== undefined ? "explicit-profile" : choice.profileFile !== undefined ? "explicit-file" : choice.profileId !== undefined ? "explicit-id" : policy.projectProfileId !== undefined ? "project-default" : "default" };
+}
+/** Interactive decisions use exactly the same admission as headless choices. */
+export async function onboardExecutor(choice, readSettings, policy, ask) {
+    try {
+        return selectOnboardingExecutor(choice, readSettings, policy);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "agent_profile_missing"
+            || choice.profileId !== undefined || choice.profile !== undefined || choice.profileFile !== undefined || choice.skip === true
+            || policy.projectProfileId !== undefined || policy.nonInteractive || !ask)
+            throw error;
+        // No speculative defaults or writes: the human supplies a concrete choice.
+        const decision = await ask(structuredClone(readSettings()));
+        if (decision.profileId === undefined && decision.profile === undefined && decision.profileFile === undefined && decision.skip !== true) {
+            refuse("agent_profile_missing", "Onboarding requires an explicit choice", 1);
+        }
+        return selectOnboardingExecutor(decision, readSettings, policy);
+    }
+}

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

@@ -18,6 +18,10 @@ import { qualifyAgyHooks } from "../harness-runtime/lib/dd-agy-daemon.mjs";
 import { lifecycleRetryInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { continueCodexCapacity } from "./codex-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.
@@ -38,8 +42,6 @@ export async function launchExternalWork(context, input) {
         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);
-    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 });
     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;
@@ -47,12 +49,66 @@ export async function launchExternalWork(context, input) {
         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 resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy, profiles: snapshot.execution_profile.agent_profiles, ...(stage ? { stage } : {}), ...(override ? { work: override } : {}) });
+    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");
@@ -76,8 +132,10 @@ export async function launchExternalWork(context, input) {
         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);
-    const env = { ...context.env, DD_FLOW_BIN: flowExecutable, DD_FLOW_INVOCATION_SCOPE: undefined, DD_FLOW_CURRENT_INVOCATION: undefined, ...(isolatedWorkspace ? { DD_FLOW_READ_ONLY_WORKSPACE: isolatedWorkspace } : {}) };
+    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.
@@ -89,8 +147,9 @@ export async function launchExternalWork(context, input) {
     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");
-    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 } : {}) }), resolved.profile_hash, root, journal, now, now]);
-    const common = ["--dd-flow-bin", flowExecutable, "--state-dir", root, "--journal", journal, "--cwd", 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"];
+    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 => {
@@ -111,7 +170,15 @@ export async function launchExternalWork(context, input) {
         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(context, work.work_id);
+        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");
@@ -178,8 +245,15 @@ export async function launchExternalWork(context, input) {
     }
     catch (error) {
         const saved = context.db.get("SELECT adapter_receipt_json FROM work_launches WHERE operation_id = ?", [operationId]);
-        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(error) }), context.now(), operationId]);
-        throw error;
+        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 = []) {
@@ -192,7 +266,13 @@ export function writeReviewGitEvidence(source, copy, base, explicitInputs = [])
     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}`);
-    for (const [name, args] of [["status.txt", ["status", "--short", "--untracked-files=all"]], ["diff.patch", ["diff", "--no-ext-diff", "--no-renames", "--binary", base]]]) {
+    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 });

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));
+    }
+}