@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.8
+
+### Patch Changes
+
+- 5f17e79: Keep CODE worker and reviewer prompts aligned on authorization/lifecycle write
+  boundaries, and project current check receipts without overwriting repair
+  history.
+
 ## 0.9.0-beta.7
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.7",
-  "cli_commit": "a4d857a7e4c5d9b5e9379a951073c499c21982ad",
-  "built_at": "2026-09-03T14:01:18.896Z",
+  "cli_version": "0.9.0-beta.8",
+  "cli_commit": "98af28f2e50816d1042ee2a75d2f8133b655ffcb",
+  "built_at": "2026-09-04T09:50:57.779Z",
   "built_with_canon": {
-    "version": null,
-    "commit": null,
-    "flow_contract": null,
-    "repo_root": null,
-    "memorybank_root": null,
-    "flow_root": null,
-    "layout": null
+    "version": "4.0.1",
+    "commit": "7bd6761e6bd4217ceec08e2f9e98387b60545661",
+    "flow_contract": "dd-flow-canonical-2026-08",
+    "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",
+    "layout": "dot_memory_bank"
   }
 }

package/dist/cli/help.js

@@ -477,7 +477,7 @@ Dashboards are rendered views of dd-flow state. Markdown remains the compatibili
         `dd-flow schema - validate canonical dd-flow data contracts
 
 Usage:
-  dd-flow schema validate --schema <name> --file <json-file> [--project-root <root>] [--schema-dir <dir>] --json
+  dd-flow schema validate --schema <name> --file <json-file> [--project-root <root>] [--run <RUN>] [--schema-dir <dir>] --json
 
 Schema names resolve to <name>.schema.json. Lookup order is --schema-dir, then <project-root>/.memory-bank/dd-flow/schemas/, then <project-root>/dd-flow/schemas/ for canonical checkouts, then bundled CLI schemas. Flow-contract validation runs structural checks first and the runtime's shared semantic normalizer second. If --project-root is omitted, the current working directory is used. JSON mode writes valid results to stdout and structured validation/usage errors to stderr.`
     ],

package/dist/cli/run-cli.js

@@ -1797,16 +1797,37 @@ function dispatchSchema(context, command, parsed) {
     if (command === "validate") {
         const schemaDir = optionalOption(parsed, "schema-dir");
         const projectRoot = optionalOption(parsed, "project-root");
+        const file = requiredOption(parsed, "file");
+        // A generic validation command can still bind to the exact RUN without
+        // searching project directories: run_id is a structural field in the
+        // submitted artifact and the database owns its materialized run_root.
+        const explicitRunId = optionalOption(parsed, "run");
+        const declaredRunId = explicitRunId ?? readRunId(file);
+        const fileRunRoot = path.basename(file) === "run.json" ? path.dirname(path.resolve(file)) : undefined;
+        const bound = projectRoot
+            ? context.db.get("SELECT r.id, r.run_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE p.root = ? AND (r.id = ? OR r.run_root = ?) LIMIT 1", [fs.realpathSync(projectRoot), declaredRunId ?? "", fileRunRoot ?? ""])
+            : undefined;
         return validateSchema({
             schemaName: requiredOption(parsed, "schema"),
-            file: requiredOption(parsed, "file"),
+            file,
             ...(schemaDir ? { schemaDir } : {}),
             ...(projectRoot ? { projectRoot } : {}),
+            ...(declaredRunId || bound?.id ? { runId: declaredRunId ?? bound.id } : {}),
+            ...(bound?.run_root ? { runRoot: bound.run_root } : {}),
             ddFlowHome: context.ddFlowHome
         });
     }
     throw new AppError("usage", `Unknown schema command: ${command ?? "<empty>"}`, 2);
 }
+function readRunId(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return typeof value.run_id === "string" && value.run_id.trim() ? value.run_id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function dispatchLane(context, command, parsed) {
     if (command === "status") {
         return getLaneStatus(context, { projectRoot: requiredOption(parsed, "project-root"), lane: optionalOption(parsed, "lane") });

package/dist/runtime/context.js

@@ -1,8 +1,10 @@
 import { getDatabase } from "../storage/database.js";
 import { resolveDdFlowHome } from "../storage/paths.js";
 export function createRouterContext(env) {
+    const ddFlowHome = resolveDdFlowHome(env);
     return {
-        ddFlowHome: resolveDdFlowHome(env),
+        ddFlowHome,
+        db: getDatabase(ddFlowHome, "read_existing"),
         now: () => new Date().toISOString()
     };
 }

package/dist/schemas/harness-config.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/harness-config@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "harnesses"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/harness-config@1" },
+    "harnesses": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["adapter_command", "runtime_command"],
+        "properties": {
+          "adapter_command": { "type": "string", "minLength": 1 },
+          "runtime_command": { "type": "string", "minLength": 1 },
+          "allow_path_discovery": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

package/dist/services/engines.js

@@ -12,7 +12,7 @@ import { requireProtocol } from "./protocols.js";
 import { resolveCanonRootBeforeContext } from "./canon.js";
 import { appendAudit } from "./audit.js";
 import { findProjectByRoot } from "./projects.js";
-import { allRunEngineBindings, findRunHome, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
+import { allRunEngineBindings, locateRunRoot, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
 export const engineManifestSchemaId = "dd-flow/engine-manifest@1";
 const routerNativeFamilies = new Set(["engine", "version", "schema"]);
 const sourceFile = fileURLToPath(import.meta.url);
@@ -182,7 +182,7 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
 }
 export function bindRunEngine(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const located = findRunHome(context.ddFlowHome, projectRoot, input.runId);
+    const located = locateRunRoot(context.db, projectRoot, input.runId);
     if (!located)
         throw new AppError("not_found", `RUN is not registered in router storage: ${input.runId}`, 1, { run_id: input.runId, project_root: projectRoot });
     const existing = readRunEngineBinding(located.binding_path, { allowMissing: true });
@@ -250,13 +250,13 @@ export function bindCurrentEngineToRun(context, input) {
         engine: engineIdentity(manifest),
         probe: { status: "not_required", command: null }
     };
-    return writeRunEngineBinding(path.join(input.runHome, "engine-binding.json"), binding).binding;
+    return writeRunEngineBinding(path.join(input.runRoot, "engine-binding.json"), binding).binding;
 }
 function boundRunEngineForArgs(context, args, projectRoot) {
     const runId = runIdForArgs(args);
     if (!runId || !projectRoot)
         return null;
-    const located = findRunHome(context.ddFlowHome, projectRoot, runId);
+    const located = locateRunRoot(context.db, projectRoot, runId);
     if (!located)
         return null;
     const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });

package/dist/services/eval-snapshots.js

@@ -148,10 +148,12 @@ export function restoreEvalRunSnapshot(context, input) {
     try {
         rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome);
         registerProject(restored, { root: projectRoot });
-        const project = requireProjectByRoot(restored, projectRoot);
+        requireProjectByRoot(restored, projectRoot);
         const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
         assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
-        const runHome = status.run.run_home_path ?? path.join(context.ddFlowHome, "projects", project.id, "runs", manifest.run_id);
+        if (!status.run.run_root)
+            throw new AppError("runtime_missing", "Restored RUN has no artifact root", 1, { run_id: manifest.run_id });
+        const runHome = status.run.run_root;
         return {
             ok: true,
             schema_id: "dd-flow/eval-run-restore@1",
@@ -182,7 +184,7 @@ export function prepareVnextSpecifyRun(context, input) {
         slug: input.slug,
         nextAction: "start_specify"
     });
-    return { ok: true, run_id: started.run.id, run_home: started.run.run_home_path, target_stage: "specify" };
+    return { ok: true, run_id: started.run.id, run_root: started.run.run_root, target_stage: "specify" };
 }
 function assertDedicatedHome(context, projectId, runId) {
     const projects = context.db.get("SELECT COUNT(*) AS count FROM projects")?.count ?? 0;

package/dist/services/harness-config.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export function harnessConfigPath(ddFlowHome) {
+    return path.join(ddFlowHome, "harnesses.json");
+}
+export function harnessKey(value) {
+    const keys = {
+        codex: "codex-desktop", "codex-desktop": "codex-desktop",
+        zcode: "zcode-acp", "zcode-acp": "zcode-acp",
+        grok: "grok-acp", "grok-acp": "grok-acp",
+        agy: "antigravity-cli", "antigravity-cli": "antigravity-cli",
+        opencode: "opencode-server", "opencode-server": "opencode-server"
+    };
+    const resolved = keys[value];
+    if (!resolved)
+        throw new AppError("harness_config_invalid", `Unsupported harness: ${value}`, 2, { harness: value });
+    return resolved;
+}
+export function loadHarnessConfig(ddFlowHome) {
+    const file = harnessConfigPath(ddFlowHome);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (cause) {
+        throw new AppError("harness_config_missing", "Harness configuration is missing or invalid", 1, { path: file, cause: String(cause) });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("harness_config_invalid", "Harness configuration must be an object", 2, { path: file });
+    const config = value;
+    if (config.schema_id !== "dd-flow/harness-config@1" || !config.harnesses || typeof config.harnesses !== "object" || Array.isArray(config.harnesses))
+        throw new AppError("harness_config_invalid", "Harness configuration has an unsupported schema", 2, { path: file });
+    for (const [name, entry] of Object.entries(config.harnesses)) {
+        harnessKey(name);
+        if (!entry || typeof entry !== "object" || Array.isArray(entry) || typeof entry.adapter_command !== "string" || typeof entry.runtime_command !== "string")
+            throw new AppError("harness_config_invalid", "Each harness requires adapter_command and runtime_command", 2, { path: file, harness: name });
+    }
+    return config;
+}
+export function resolveHarnessCommand(ddFlowHome, harness, command) {
+    const key = harnessKey(harness);
+    const entry = loadHarnessConfig(ddFlowHome).harnesses[key];
+    if (!entry)
+        throw new AppError("harness_config_missing", "Selected harness is not configured", 1, { path: harnessConfigPath(ddFlowHome), harness: key });
+    const value = command === "adapter" ? entry.adapter_command : entry.runtime_command;
+    if (!path.isAbsolute(value))
+        throw new AppError("harness_config_invalid", "Harness commands must be absolute paths", 2, { harness: key, command, value });
+    if (!fs.existsSync(value))
+        throw new AppError("harness_command_missing", "Configured harness command does not exist", 1, { harness: key, command, value });
+    return value;
+}
+/** The adapter interface is intentionally small; native binary flag names stay here,
+ * rather than leaking through MERGE orchestration or agent prompts. */
+export function harnessRuntimeArguments(ddFlowHome, harness) {
+    const key = harnessKey(harness);
+    const runtime = resolveHarnessCommand(ddFlowHome, key, "runtime");
+    const option = {
+        "codex-desktop": "--codex-bin",
+        "zcode-acp": "--zcode-acp-bin",
+        "grok-acp": "--grok-bin",
+        "antigravity-cli": "--agy-bin",
+        "opencode-server": "--opencode-bin"
+    };
+    return [option[key], runtime];
+}

package/dist/services/merge-server.js

@@ -5,6 +5,7 @@ import { AppError } from "../shared/errors.js";
 import { flowCommand } from "./stage-pause.js";
 import { validateSchema } from "./schema-validation.js";
 import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+import { harnessRuntimeArguments, resolveHarnessCommand } from "./harness-config.js";
 /** A deterministic dispatcher; only the launched harness Session performs agent work. */
 export async function serveMergeRequests(context, input) {
     const running = context.db.get("SELECT server_id, pid FROM merge_servers WHERE status IN ('running','stopping') ORDER BY started_at LIMIT 1");
@@ -73,8 +74,8 @@ async function dispatch(context, input) {
     fs.writeFileSync(promptFile, `Start the assigned MERGE stage now. Your first tool call must be this exact standalone command:\n\n${stageCommand}\n\nTrust and follow the complete stage packet it returns. Continue through merge apply and stage finish. Stop only when the stage reaches a terminal result or explicitly requests user/operator action.\n`);
     event(input.journal, { type: "launch_intent", server_id: input.serverId, request_id: input.request.merge_request_id, token, profile: input.profile, prompt_file: promptFile, at: context.now() });
     input.progress?.(`launching ${input.request.merge_request_id} with ${input.profile.id}`);
-    const executable = context.env[`DD_FLOW_${input.profile.harness.toUpperCase()}_ADAPTER`] ?? `dd-${input.profile.harness}`;
-    const common = ["--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", input.request.target_workspace, "--dd-flow-home", context.ddFlowHome, "--json"];
+    const executable = resolveHarnessCommand(context.ddFlowHome, input.profile.harness, "adapter");
+    const common = ["--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", input.request.target_workspace, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, input.profile.harness), "--json"];
     try {
         const adapterCall = (args, timeoutMs, progressMessage) => runHarnessAdapter({ executable, args, env: context.env, ...(timeoutMs ? { timeoutMs } : {}), ...(input.progress ? { progress: input.progress } : {}), ...(progressMessage ? { progressMessage } : {}), onEvidence: (value) => event(input.journal, { type: "adapter_call", ...value }) });
         await adapterCall(["daemon", "start", ...common]);

package/dist/services/prompts.js

@@ -136,7 +136,9 @@ export function renderWorkerPrompt(context, input) {
     };
 }
 function runHomePath(run) {
-    return run.run_home_path ?? path.dirname(run.run_index_path);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no artifact root", 1, { run_id: run.id });
+    return run.run_root;
 }
 function readWorkerTask(taskFile, runHome) {
     const resolved = path.resolve(taskFile);
@@ -204,7 +206,7 @@ function protocolIdForRun(context, projectId, runId) {
     return run.subject_id;
 }
 function requireRun(context, projectId, runId) {
-    const row = context.db.get("SELECT id, project_id, subject_type, subject_id, workspace_root, run_index_path, run_home_path, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, runId, runId]);
+    const row = context.db.get("SELECT id, project_id, subject_type, subject_id, workspace_root, run_root, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, runId, runId]);
     if (!row)
         throw new AppError("not_found", `Run is not found: ${runId}`, 1);
     return row;

package/dist/services/run-engine-bindings.js

@@ -2,36 +2,18 @@ import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 export const runEngineBindingSchemaId = "dd-flow/run-engine-binding@1";
-export function findRunHome(ddFlowHome, projectRoot, runIdOrAlias) {
-    const projectsRoot = path.join(ddFlowHome, "projects");
-    if (!fs.existsSync(projectsRoot))
+/** Resolve a RUN from SQLite authority; never discover one by scanning storage paths. */
+export function locateRunRoot(db, projectRoot, runIdOrAlias) {
+    const rows = db.all(`SELECT r.project_id, r.id AS run_id, r.run_root
+       FROM runs r JOIN projects p ON p.id = r.project_id
+      WHERE p.root = ? AND (r.id = ? OR r.short_id = ?)`, [realpathOrResolve(projectRoot), runIdOrAlias, runIdOrAlias]).filter((row) => Boolean(row.run_root));
+    if (rows.length > 1)
+        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, { project_root: realpathOrResolve(projectRoot), candidates: rows.map((row) => row.run_id) });
+    const row = rows[0];
+    if (!row?.run_root)
         return null;
-    const expectedRoot = realpathOrResolve(projectRoot);
-    const matches = [];
-    for (const projectId of fs.readdirSync(projectsRoot)) {
-        const runsRoot = path.join(projectsRoot, projectId, "runs");
-        if (!isDirectory(runsRoot))
-            continue;
-        for (const runId of fs.readdirSync(runsRoot)) {
-            if (!runIdMatches(runId, runIdOrAlias))
-                continue;
-            const runHome = path.join(runsRoot, runId);
-            const authorityPath = path.join(runHome, "run.json");
-            const bindingPath = path.join(runHome, "engine-binding.json");
-            const binding = readRunEngineBinding(bindingPath, { allowMissing: true });
-            const authorityRoot = binding?.project_root ?? projectRootFromAuthority(authorityPath);
-            if (!authorityRoot || realpathOrResolve(authorityRoot) !== expectedRoot)
-                continue;
-            matches.push({ project_id: projectId, run_id: runId, run_home: runHome, authority_path: authorityPath, binding_path: bindingPath });
-        }
-    }
-    if (matches.length > 1) {
-        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, {
-            project_root: expectedRoot,
-            candidates: matches.map((match) => match.run_id)
-        });
-    }
-    return matches[0] ?? null;
+    const runRoot = path.resolve(row.run_root);
+    return { project_id: row.project_id, run_id: row.run_id, run_root: runRoot, authority_path: path.join(runRoot, "run.json"), binding_path: path.join(runRoot, "engine-binding.json") };
 }
 export function readRunEngineBinding(file, options = {}) {
     if (!fs.existsSync(file)) {
@@ -86,6 +68,14 @@ export function allRunEngineBindings(ddFlowHome) {
     }
     return bindings;
 }
+function isDirectory(value) {
+    try {
+        return fs.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function isRunEngineBinding(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -115,32 +105,6 @@ function sameEngine(left, right) {
         && left.integrity_checksum === right.integrity_checksum
         && left.snapshot_root === right.snapshot_root;
 }
-function projectRootFromAuthority(file) {
-    try {
-        const value = JSON.parse(fs.readFileSync(file, "utf8"));
-        const execution = recordValue(value.execution);
-        const workspace = recordValue(value.workspace);
-        const project = recordValue(value.project);
-        return stringValue(execution?.project_root)
-            ?? stringValue(workspace?.project_root)
-            ?? stringValue(project?.root)
-            ?? stringValue(value.project_root);
-    }
-    catch {
-        return null;
-    }
-}
-function runIdMatches(fullId, idOrAlias) {
-    return fullId === idOrAlias || /^RUN-[0-9]+$/.test(idOrAlias) && fullId.startsWith(`${idOrAlias}-`);
-}
-function isDirectory(value) {
-    try {
-        return fs.statSync(value).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 function realpathOrResolve(value) {
     try {
         return fs.realpathSync(value);
@@ -149,9 +113,3 @@ function realpathOrResolve(value) {
         return path.resolve(value);
     }
 }
-function recordValue(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-function stringValue(value) {
-    return typeof value === "string" && value.length > 0 ? value : null;
-}

package/dist/services/runs.js

@@ -126,7 +126,7 @@ export function startFlowRun(context, input) {
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
-    bindCurrentEngineToRun(context, { projectRoot, runId, runHome });
+    bindCurrentEngineToRun(context, { projectRoot, runId, runRoot: runHome });
     const persistedIndex = persistedVnextIndex(index);
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, 1));
     context.db.run(`INSERT INTO runs
@@ -292,6 +292,22 @@ export function setFlowRunConfig(context, input) {
     appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_config_set", run_id: run.id, key: input.key, value: mode, source, reason });
     return { ok: true, run_id: run.id, settings: runSettings(index), idempotent: false };
 }
+/** Freeze an automatic review request once from already accepted policy or PLAN facts. */
+export function freezeFlowRunReviewMode(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = authoritativeIndex(run);
+    const settings = runSettings(index);
+    const key = input.review === "plan" ? "plan_review" : "code_review";
+    const current = settings[key];
+    if (current.mode !== "auto")
+        return;
+    const now = context.now();
+    index.settings = { ...settings, [key]: { mode: input.mode, source: input.source, reason: requiredPlain(input.reason, "reason"), updated_at: now } };
+    index.updated_at = now;
+    persistRunState(context, project, run, index);
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.review_mode_frozen", payload: { run_id: run.id, review: input.review, mode: input.mode, source: input.source, reason: input.reason } });
+}
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
@@ -1245,7 +1261,7 @@ function flowRunSummary(run) {
         runtime_path: run.runtime_path,
         run_dir: run.run_dir,
         run_index_path: run.run_index_path,
-        run_home_path: run.run_home_path ?? null,
+        run_root: run.run_root,
         layout_version: run.layout_version ?? null,
         artifact_root_kind: run.artifact_root_kind ?? null,
         created_at: run.created_at,
@@ -1340,7 +1356,9 @@ function writeJsonFile(file, value) {
     fs.renameSync(tmpFile, file);
 }
 function runArtifactRoot(run) {
-    return run.run_home_path ?? path.dirname(run.runtime_path);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: run.id });
+    return run.run_root;
 }
 export function gitFacts(workspaceRoot) {
     const read = (args) => {

package/dist/services/schema-validation.js

@@ -6,7 +6,7 @@ import { Ajv } from "ajv/dist/ajv.js";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { normalizeFlowContract } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
-import { findRunHome, readRunEngineBinding } from "./run-engine-bindings.js";
+import { readRunEngineBinding } from "./run-engine-bindings.js";
 export function captureMemoryBankBaseline(input) {
     const projectRoot = path.resolve(input.projectRoot);
     const paths = normalizeMemoryBankPaths(projectRoot, input.paths);
@@ -117,8 +117,8 @@ export function validateSchema(options) {
     }
     const valid = validate(data);
     const errors = valid ? [] : (validate.errors ?? []).map(formatAjvError);
-    const semanticErrors = valid ? validateSemanticSchema(options.schemaName, data) : [];
-    const allErrors = [...errors, ...semanticErrors];
+    const contractErrors = valid ? validateContractInvariants(options.schemaName, data) : [];
+    const allErrors = [...errors, ...contractErrors];
     if (allErrors.length > 0) {
         throw new AppError("schema_validation", `${path.basename(filePath)} does not match schema`, 2, {
             schema: schemaResolution,
@@ -181,7 +181,7 @@ const historicalSchemaRegistry = {
         }]
 };
 function resolveRunBoundSchema(options) {
-    if (!options.projectRoot || options.schemaDir)
+    if (!options.runRoot || options.schemaDir)
         return null;
     const data = readJson(path.resolve(options.file), "input file");
     const root = asRecord(data);
@@ -190,13 +190,13 @@ function resolveRunBoundSchema(options) {
     const runId = options.runId ?? inferredRunId;
     if (typeof runId !== "string")
         return null;
-    const projectRoot = path.resolve(options.projectRoot);
-    const located = findRunHome(options.ddFlowHome ?? process.env.DD_FLOW_HOME ?? path.join(path.dirname(projectRoot), ".dd-flow"), projectRoot, runId);
-    if (!located || !isInside(located.run_home, path.resolve(options.file)))
-        return null;
-    const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });
+    const runRoot = path.resolve(options.runRoot);
+    const bindingPath = path.join(runRoot, "engine-binding.json");
+    const binding = readRunEngineBinding(bindingPath);
     if (!binding)
-        return null;
+        throw new AppError("run_engine_binding_missing", "RUN engine binding is missing", 1, { path: bindingPath });
+    if (binding.run_id !== runId)
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding belongs to another RUN", 1, { expected_run_id: runId, actual_run_id: binding.run_id, path: bindingPath });
     const manifestPath = path.join(binding.engine.snapshot_root, "engine.json");
     const manifest = readJson(manifestPath, "bound engine manifest");
     const integrity = asRecord(objectValue(manifest, "integrity"));
@@ -284,7 +284,7 @@ function formatAjvError(error) {
         keyword: error.keyword
     };
 }
-function validateSemanticSchema(schemaName, data) {
+function validateContractInvariants(schemaName, data) {
     const root = asRecord(data);
     if (!root) {
         return [];

package/dist/services/stage-lifecycle.js

@@ -53,7 +53,9 @@ function bootstrapStageRun(context, projectRoot, input) {
         if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
             throw new AppError("not_found", "--intake-file must point to an existing file", 1, { intake_file: intakeFile });
         }
-        const intakeDir = path.join(started.run.run_home_path ?? path.dirname(started.run.id), "intake");
+        if (!started.run.run_root)
+            throw new AppError("runtime_missing", "New RUN has no artifact root", 1, { run_id: started.run.id });
+        const intakeDir = path.join(started.run.run_root, "intake");
         fs.mkdirSync(intakeDir, { recursive: true });
         fs.copyFileSync(source, path.join(intakeDir, "user-request.md"));
     }
@@ -216,7 +218,7 @@ export function startStage(context, input) {
         })),
         worker_prompt_markdown: prompt
     });
-    validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot, runId: attached.run.id, ddFlowHome: context.ddFlowHome });
+    validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot, runId: attached.run.id, runRoot: runHome, ddFlowHome: context.ddFlowHome });
     atomicWrite(path.join(stageRoot, "stage-start.json"), {
         schema_id: "dd-flow/stage-start@2",
         run_id: attached.run.id,
@@ -273,7 +275,7 @@ export function finishStage(context, input) {
     const semanticFile = resolveStageFile(input.semanticFile ?? "@stage/stage-input.json", stageRoot, runHome);
     const receipt = beginFinishReceipt(context, stageRoot, semanticFile, view.run.id, input.stage);
     try {
-        validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot, runId, ddFlowHome: context.ddFlowHome });
+        validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
         const semantic = readSemanticFile(semanticFile, runHome);
         const status = stringValue(semantic.status) ?? "done";
         if (!["done", "waiting_for_user", "blocked", "failed"].includes(status)) {
@@ -293,7 +295,7 @@ export function finishStage(context, input) {
         const reportPath = path.join(stageRoot, "stage-report.md");
         const htmlPath = path.join(stageRoot, "stage-report.html");
         atomicWrite(dataPath, report);
-        validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot, runId, ddFlowHome: context.ddFlowHome });
+        validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
         atomicWrite(reportPath, renderMarkdown(report));
         atomicWrite(htmlPath, renderHtml(projectRoot, report));
         if (view.run.subject.type === "protocol") {
@@ -410,7 +412,12 @@ function nextActionForProtocolStage(stage) {
     return `continue_${stage}`;
 }
 function runHomePath(run) {
-    return run.run_home_path ?? path.dirname(run.run_index_path);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no artifact root", 1, { run_id: run.id });
+    return run.run_root;
+}
+function runStatePath(run) {
+    return path.join(runHomePath(run), "run.json");
 }
 export function defaultStageDir(stage, flowKind) {
     const normalized = stage === "implementation" ? "code" : stage;
@@ -702,7 +709,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
     if (stage === "code" || stage === "implementation") {
         return {
             schema_id: "dd-flow/code-stage-report@2",
-            run: { run_id: view.run.id, run_state: view.run.run_index_path },
+            run: { run_id: view.run.id, run_state: runStatePath(view.run) },
             stage: { name: stage, dir: path.basename(stageRoot), status },
             project: { id: view.run.project_id, title: path.basename(view.run.project_root) },
             subject: { id: view.run.subject.id, title: view.run.subject.id },
@@ -712,7 +719,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
                 summary: result,
                 next_action: stringValue(semantic.next_action) ?? "Proceed to readiness."
             },
-            breadcrumbs: [{ label: "RUN", href: view.run.run_index_path, status: "available" }],
+            breadcrumbs: [{ label: "RUN", href: runStatePath(view.run), status: "available" }],
             implemented_goals: [{ title: `Stage ${stage}`, summary: result }],
             acceptance_scenarios: acceptance.map((summary, index) => ({
                 id: `SCN-${stage}-${index + 1}`,
@@ -763,7 +770,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
             memory_bank_scope: "changed_files_and_links_only",
             status: "passed"
         },
-        breadcrumbs: [{ label: "RUN", href: view.run.run_index_path, status: "available" }]
+        breadcrumbs: [{ label: "RUN", href: runStatePath(view.run), status: "available" }]
     };
 }
 function preparePlanFinish(context, projectRoot, view, stageRoot) {

package/dist/services/stage-pause.js

@@ -167,7 +167,7 @@ export function flowCommand(context) {
     return context.ddFlowHome === defaultHome ? "dd-flow" : `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
 }
 function requireRun(context, projectId, id) {
-    const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_home_path, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);
+    const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_root, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);
     if (rows.length !== 1)
         throw new AppError(rows.length ? "ambiguous_alias" : "not_found", rows.length ? "RUN alias is ambiguous" : "RUN is not registered", 1, { run_id: id });
     return rows[0];
@@ -186,9 +186,9 @@ function requireStage(run, stage, status) {
     return found;
 }
 function requireRunHome(run) {
-    if (!run.run_home_path)
-        throw new AppError("runtime_missing", "RUN has no artifact home", 1, { run_id: run.id });
-    return run.run_home_path;
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no artifact root", 1, { run_id: run.id });
+    return run.run_root;
 }
 function nextPauseId(runHome) {
     const root = path.join(runHome, "intake", "hitl");