@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

package/dist/services/diagnostic-work-batch.js

@@ -0,0 +1,34 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** Only applicable aspects receive analytical Work. Critics receive all candidates,
+ * including candidates they may reject; no empty pseudo-Work proves coverage. */
+export function diagnosticWorkBatch(input) {
+    const review = input.stage === "review";
+    if (!review && input.stage !== (input.flow_id === "mb-audit" ? "audit" : "analyze")) {
+        throw new AppError("diagnostic_work_batch_invalid", "Diagnostic Work stage belongs to another flow", 2, { effect: "no_effect" });
+    }
+    const applicable = input.coverage.filter(value => value.applicability === "applicable");
+    const architecture = applicable.some(value => value.id ===
+        (input.flow_id === "mb-audit" ? "05" : "architecture_harmonization_review"));
+    const assignments = review
+        ? ["universal", ...(architecture ? ["architecture"] : [])].map(id => ({ id, role: "critic" }))
+        : applicable.map(value => ({ id: value.id, role: "aspect" }));
+    return { works: assignments.map((assignment, index) => {
+            const key = `${assignment.role}-${String(index + 1).padStart(3, "0")}`;
+            const packet = { schema_id: "dd-flow/diagnostic-work-input@1", flow_id: input.flow_id, run_id: input.run_id,
+                stage: input.stage, key, aspect_id: assignment.id, role: assignment.role,
+                input_sha256: input.input_sha256, snapshot_sha256: input.snapshot_sha256,
+                instruction: input.instruction, coverage: input.coverage, support: input.support ?? [],
+                candidates: review ? input.candidates : [] };
+            return { key, depends_on: [], launch_policy: "fresh_agent_required",
+                result_schema: "dd-flow/diagnostic-work-result@1",
+                task: (review
+                    ? `Independently assess every supplied candidate as the ${assignment.id} critic. Read the assigned immutable snapshot. Retain rejected findings and explain disagreement. Do not invent implementation, checks, sources or completion. Return exactly one decision per candidate using the assigned diagnostic result schema. Do not edit project files, repair findings, allocate Work or coordinate the Stage.`
+                    : `Examine only the assigned aspect ${JSON.stringify(assignment.id)} using the frozen instruction and actual snapshot sources. Distinguish implemented behavior from plans and absent evidence. Cite exact sources for material findings; retain uncertainty and active DEFs. Do not edit project files, execute project setup, repair findings, allocate Work or claim independent review. Return the assigned diagnostic Work result.`)
+                    + " Read applicable criterion files in diagnostic.support relative to run_home. They are frozen reference criteria, not executable/manual lifecycle instructions or implemented project facts. Cite snapshot sources as project evidence, not canon references."
+                    + " Every sources/evidence path must be relative to the assigned snapshot workspace root, using forward slashes (for example src/index.ts or .memory-bank/index.md), with the SHA256 of its exact snapshot bytes. Never cite absolute paths, .git, intake transport files, RUN packets or canon support as snapshot evidence; never invent a relative path for a file outside the snapshot."
+                    + " Files under .dd-flow/review-evidence are CLI-generated observations, not original project sources: do not put them in sources/evidence or infer the original repository's history or unborn state from the working copy's Git metadata. For missing linked targets cite the existing referring project document and describe the absence as a limitation, not as a source file.",
+                payload: { kind: review ? "diagnostic-critic" : "diagnostic-aspect", read_only: true,
+                    diagnostic: { ...packet, packet_sha256: hybridDigest(packet) } } };
+        }) };
+}

package/dist/services/diagnostic-work-collection.js

@@ -0,0 +1,97 @@
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readRegisteredDiagnosticGraph } from "./diagnostic-work-registration.js";
+import { diagnosticWorkBatch } from "./diagnostic-work-batch.js";
+import { validateDiagnosticWorkResult } from "./diagnostic-work-results.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) { throw new AppError("diagnostic_work_collection_invalid", "Diagnostic graph is not independently settled", 2, { reason, effect: "no_effect" }); }
+const physicalKey = (session) => `${session.harness}\0${session.provider_session_id}`;
+export function assertDiagnosticSessionIndependence(workers, excluded) {
+    const keys = workers.map(physicalKey), excludedKeys = new Set(excluded.map(physicalKey));
+    if (workers.some(value => !value.harness || !value.provider_session_id)
+        || new Set(keys).size !== keys.length || keys.some(key => excludedKeys.has(key)))
+        refuse("physical_session_reused");
+}
+function completedWork(context, scope, workId) {
+    const work = context.db.get("SELECT status,result FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.projectId, scope.runId, workId]);
+    if (work?.status !== "completed" || !work.result || Buffer.byteLength(work.result) > 1024 * 1024)
+        refuse("work_not_completed");
+    const sessions = context.db.all("SELECT ws.id,ws.session_id,ws.status,s.harness,s.provider_session_id,ws.hook_event_id FROM work_sessions ws JOIN sessions s ON s.project_id=? AND s.session_id=ws.session_id AND s.run_id=? WHERE ws.work_id=? AND ws.status IN ('running','completed') LIMIT 3", [scope.projectId, scope.runId, workId]);
+    if (sessions.length !== 1 || sessions[0].status !== "completed")
+        refuse("work_session_not_settled");
+    const session = sessions[0];
+    const hook = context.db.get("SELECT session_id,harness,provider_session_id,status FROM hook_events WHERE project_id=? AND event_key=?", [scope.projectId, session.hook_event_id]);
+    if (!hook || hook.status !== "claimed" || hook.session_id !== session.session_id
+        || physicalKey(hook) !== physicalKey(session))
+        refuse("physical_work_owner_missing");
+    return { workId, result: work.result, session };
+}
+function collectSql(context, scope, rootId) {
+    const graph = readRegisteredDiagnosticGraph(context, scope);
+    if (!graph || graph.parent_work_id !== rootId)
+        refuse("registration_required");
+    const batch = diagnosticWorkBatch(graph.input);
+    const works = batch.works.map(item => completedWork(context, scope, graph.work_ids[item.key]));
+    const coordinators = context.db.all("SELECT s.harness,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.project_id=? AND s.run_id=? AND s.session_id=ws.session_id WHERE ws.work_id=?", [scope.projectId, scope.runId, rootId]);
+    const authorGraph = scope.stage === "review" ? readRegisteredDiagnosticGraph(context, { ...scope, stage: graph.input.flow_id === "mb-audit" ? "audit" : "analyze" }) : null;
+    if (scope.stage === "review" && !authorGraph)
+        refuse("author_graph_missing");
+    const authors = authorGraph ? Object.values(authorGraph.work_ids).map(id => completedWork(context, scope, id)) : [];
+    assertDiagnosticSessionIndependence(works.map(value => value.session), [...coordinators, ...authors.map(value => value.session)]);
+    return { graph, works, authors, coordinators };
+}
+/** File/schema/evidence checks occur before settlement. assertCustody is SQL-only
+ * and keeps the selected results and physical owners stable in its writer. */
+export class PreparedDiagnosticWorkCollection {
+    #scope;
+    #rootId;
+    #sql;
+    #snapshot;
+    #results;
+    constructor(scope, rootId, sql, snapshot, results) {
+        this.#scope = scope;
+        this.#rootId = rootId;
+        this.#sql = sql;
+        this.#snapshot = snapshot;
+        this.#results = results;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+        if (!bundle || !isDiagnosticFlow(bundle.manifest.flow_id))
+            refuse("diagnostic_bundle_required");
+        const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+        const frozen = bundle.execution.snapshot().scope;
+        const snapshot = readDiagnosticSnapshot(context, { projectId: project.id, projectRoot: frozen.projectRoot,
+            sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId: bundle.manifest.flow_id }, input.runId);
+        if (!snapshot || snapshot.root !== frozen.workspace)
+            refuse("snapshot_required");
+        const root = readDescriptorRootWork(context, scope, bundle);
+        const sql = context.db.readSnapshot(() => {
+            assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+            return collectSql(context, scope, root.workId);
+        });
+        if (sql.graph.bundle_sha256 !== bundle.sha256 || sql.graph.input.snapshot_sha256 !== snapshot.source_sha256)
+            refuse("foreign_graph");
+        const batch = diagnosticWorkBatch(sql.graph.input), schema = bundle.blob("schemas/diagnostic-work-result.schema.json");
+        const results = sql.works.map((work, index) => ({ workId: work.workId,
+            result: validateDiagnosticWorkResult(Buffer.from(work.result), schema, diagnosticSnapshotPaths(context, snapshot, input.runId).root, sql.graph.input, {
+                workId: work.workId, aspectId: batch.works[index].payload.diagnostic.aspect_id,
+                role: batch.works[index].payload.diagnostic.role
+            }) }));
+        return new PreparedDiagnosticWorkCollection(scope, root.workId, sql, snapshot, results);
+    }
+    results() { return structuredClone(this.#results); }
+    assertCustody(context) {
+        const s = this.#snapshot;
+        if (hybridDigest(collectSql(context, this.#scope, this.#rootId)) !== hybridDigest(this.#sql)
+            || hybridDigest(readDiagnosticSnapshotCustody(context, { projectId: s.projectId, projectRoot: s.projectRoot,
+                sourceRoot: s.sourceRoot, requestId: s.requestId, flowId: s.flowId }, this.#scope.runId)) !== hybridDigest(s))
+            refuse("collection_changed");
+    }
+}

package/dist/services/diagnostic-work-registration.js

@@ -0,0 +1,101 @@
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { validateDiagnosticStageResult } from "./diagnostic-stage-results.js";
+import { diagnosticWorkBatch } from "./diagnostic-work-batch.js";
+import { addWorkBatch, prepareWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+const event = "diagnostic.work_registration";
+function refuse(reason) { throw new AppError("diagnostic_work_registration_invalid", "Diagnostic graph lacks its assigned stage authority", 2, { reason, effect: "no_effect" }); }
+/** SQL-only reader. An explicitly registered empty graph is distinct from no graph. */
+export function readRegisteredDiagnosticGraph(context, scope) {
+    const graph = stageGraphScope(context, scope.projectId, scope.runId, scope.stage);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, event, scope.runId, scope.stage, graph.attempt]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+        refuse("ambiguous_registration");
+    const receipt = JSON.parse(rows[0].payload_json);
+    if (receipt.schema_id !== "dd-flow/diagnostic-work-registration@1" || receipt.run_id !== scope.runId
+        || receipt.stage !== scope.stage || receipt.attempt !== graph.attempt || !receipt.work_ids
+        || receipt.input.run_id !== scope.runId || receipt.input.stage !== scope.stage
+        || receipt.input.input_sha256 !== receipt.input_sha256)
+        refuse("foreign_registration");
+    const batch = diagnosticWorkBatch(receipt.input);
+    if (receipt.batch_sha256 !== hybridDigest(batch.works) || batch.works.length !== Object.keys(receipt.work_ids).length
+        || new Set(Object.values(receipt.work_ids)).size !== batch.works.length)
+        refuse("changed_batch");
+    for (const item of batch.works) {
+        const id = receipt.work_ids[item.key];
+        if (!id)
+            refuse("missing_work");
+        const custody = readWorkBatchCustody(context, id);
+        if (custody.item_key !== item.key || custody.batch_sha256 !== receipt.batch_sha256
+            || hybridDigest(custody.work_ids) !== hybridDigest(receipt.work_ids)
+            || hybridDigest(custody.scope) !== hybridDigest({ ...graph, stage: scope.stage,
+                parent_work_id: receipt.parent_work_id, request_key: "diagnostic-graph" }))
+            refuse("changed_work_custody");
+    }
+    return receipt;
+}
+/** The registered handler calls this only after generic Stage entry. Applicability
+ * and candidates come from the accepted predecessor, not a caller-owned batch. */
+export function registerDiagnosticStageGraph(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (!bundle || !isDiagnosticFlow(bundle.manifest.flow_id) || !["audit", "analyze", "review"].includes(input.stage))
+        refuse("diagnostic_stage_required");
+    const flowId = bundle.manifest.flow_id, frozen = bundle.execution.snapshot().scope;
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const selection = readDescriptorStageInput(context, scope, bundle), root = readDescriptorRootWork(context, scope, bundle);
+    const snapshotSelection = { projectId: project.id, projectRoot: frozen.projectRoot, sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId };
+    const snapshot = readDiagnosticSnapshot(context, snapshotSelection, input.runId);
+    if (!snapshot || snapshot.root !== frozen.workspace)
+        refuse("snapshot_required");
+    const previousStage = input.stage === "review" ? flowId === "mb-audit" ? "audit" : "analyze" : "preflight";
+    if (selection.input.predecessor?.stage !== previousStage)
+        refuse("predecessor_required");
+    const previousScope = { ...scope, stage: previousStage };
+    const accepted = readAcceptedStageData(context, previousScope), previousInput = readDescriptorStageInput(context, previousScope, bundle, true, true);
+    const previous = validateDiagnosticStageResult(accepted.bytes, bundle.descriptor.stageBlob(previousStage, "result_schema"), {
+        flowId, runId: input.runId, stage: previousStage, inputSha256: previousInput.inputSha256,
+        snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root, snapshotSha256: snapshot.source_sha256,
+        predecessors: previousInput.input.predecessor ? [{ stage: previousInput.input.predecessor.stage,
+                path: previousInput.input.predecessor.result.path, sha256: previousInput.input.predecessor.result.sha256 }] : []
+    });
+    const workInput = { flow_id: flowId, run_id: input.runId, stage: input.stage,
+        input_sha256: selection.inputSha256, snapshot_sha256: snapshot.source_sha256,
+        instruction: bundle.descriptor.stageBlob(input.stage, "instruction").toString("utf8"),
+        coverage: previous.details.coverage, candidates: input.stage === "review" ? previous.details.findings : [],
+        support: bundle.manifest.inventory.filter(ref => ref.path.startsWith("support/")).map(ref => ({ path: `execution-bundle/${ref.path}`, sha256: ref.sha256 })) };
+    const batch = diagnosticWorkBatch(workInput), batchInput = { parentWorkId: root.workId, stage: input.stage, requestKey: "diagnostic-graph", value: batch };
+    const prepared = batch.works.length ? prepareWorkBatch(context, batchInput) : [];
+    return context.db.writeTransaction(() => {
+        assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        if (hybridDigest(readDiagnosticSnapshotCustody(context, snapshotSelection, input.runId)) !== hybridDigest(snapshot)
+            || hybridDigest(readDescriptorStageInput(context, scope, bundle)) !== hybridDigest(selection)
+            || hybridDigest(readAcceptedStageData(context, previousScope)) !== hybridDigest(accepted)
+            || readDescriptorRootWork(context, scope, bundle).workId !== root.workId)
+            refuse("stage_authority_changed");
+        const expected = { schema_id: "dd-flow/diagnostic-work-registration@1", run_id: input.runId, stage: input.stage,
+            attempt: selection.attempt, parent_work_id: root.workId, bundle_sha256: bundle.sha256,
+            input_sha256: selection.inputSha256, input: workInput, batch_sha256: hybridDigest(batch.works) };
+        const prior = readRegisteredDiagnosticGraph(context, scope);
+        if (prior) {
+            if (hybridDigest({ ...prior, work_ids: undefined }) !== hybridDigest(expected))
+                refuse("registration_changed");
+            return prior;
+        }
+        const workIds = batch.works.length ? addWorkBatch(context, { ...batchInput, prepared }).work_ids : {};
+        const receipt = { ...expected, work_ids: workIds };
+        appendAudit(context, { projectId: project.id, eventType: event, payload: receipt });
+        return readRegisteredDiagnosticGraph(context, scope);
+    });
+}

package/dist/services/diagnostic-work-results.js

@@ -0,0 +1,93 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { verifyDiagnosticSources, verifyDiagnosticCritic } from "./diagnostic-evidence.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const refuse = (reason) => {
+    throw new AppError("diagnostic_work_result_invalid", "Diagnostic Work result does not match its assigned task", 2, { reason, effect: "no_effect", ...(reason === "invalid_schema" ? { phase: "prepare", recoverable: true } : {}) });
+};
+/** Accepts semantic data only after the caller has established completed Work,
+ * immutable batch custody and physical Session independence. */
+export function validateDiagnosticWorkResult(bytes, schemaBytes, snapshotRoot, input, assignment) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || schemaBytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    const validate = (() => {
+        try {
+            const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(schemaBytes));
+            if (schema.$id !== "dd-flow/diagnostic-work-result@1")
+                refuse("frozen_schema_invalid");
+            return new Ajv2020({ strict: false, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("frozen_schema_invalid");
+        }
+    })();
+    let result;
+    try {
+        result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_schema");
+    }
+    if (!validate(result))
+        refuse("invalid_schema");
+    if (result.flow_id !== input.flow_id || result.run_id !== input.run_id || result.stage !== input.stage
+        || result.work_id !== assignment.workId || result.aspect_id !== assignment.aspectId)
+        refuse("foreign_assignment");
+    verifyDiagnosticSources(snapshotRoot, result.sources);
+    if (assignment.role === "critic") {
+        if (input.stage !== "review" || result.findings.length)
+            refuse("critic_cannot_replace_candidates");
+        verifyDiagnosticCritic(snapshotRoot, input.candidates, result.decisions);
+    }
+    else {
+        if (input.stage === "review" || result.decisions.length
+            || !input.coverage.some(value => value.id === assignment.aspectId && value.applicability === "applicable"))
+            refuse("foreign_aspect");
+        const ids = new Set();
+        for (const finding of result.findings) {
+            if (ids.has(finding.id) || finding.aspect_id !== assignment.aspectId || !finding.evidence.length)
+                refuse("foreign_or_duplicate_finding");
+            ids.add(finding.id);
+            verifyDiagnosticSources(snapshotRoot, finding.evidence);
+        }
+    }
+    return result;
+}
+/** Work-local IDs are not globally unique. Keep their origin when assigning
+ * stable report IDs, so one author's FIND-1 cannot overwrite another's. */
+export function collectDiagnosticCandidates(results) {
+    const findings = [], origins = [];
+    const seen = new Set();
+    for (const [workIndex, item] of results.entries()) {
+        if (seen.has(item.workId) || item.result.work_id !== item.workId || item.result.stage === "review")
+            refuse("duplicate_or_foreign_work");
+        seen.add(item.workId);
+        for (const [findingIndex, finding] of item.result.findings.entries()) {
+            const id = `FIND-${String(workIndex + 1).padStart(3, "0")}-${String(findingIndex + 1).padStart(3, "0")}`;
+            findings.push({ ...structuredClone(finding), id });
+            origins.push({ id, work_id: item.workId, original_id: finding.id });
+        }
+    }
+    return { findings, origins };
+}
+/** Assign CLI-owned global IDs only to an exact, ordered copy of admitted Work
+ * findings. Any other proposal still goes through the ordinary strict guards. */
+export function sealDiagnosticCandidateIds(bytes, results) {
+    if (!bytes.length || bytes.length > 1024 * 1024)
+        return bytes;
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return bytes;
+    }
+    if (!value || !Array.isArray(value.details?.findings)
+        || hybridDigest(value.details.findings) !== hybridDigest(results.flatMap(item => item.result.findings)))
+        return bytes;
+    const canonical = collectDiagnosticCandidates(results).findings;
+    if (hybridDigest(value.details.findings) === hybridDigest(canonical))
+        return bytes;
+    value.details.findings = canonical;
+    return Buffer.from(JSON.stringify(value));
+}

package/dist/services/engines.js

@@ -9,7 +9,8 @@ import { createRequire } from "node:module";
 import { valid } from "semver";
 import { getCliBuildInfo } from "./build-info.js";
 import { AppError } from "../shared/errors.js";
-import { ensureDir, engineStoreRoot, engineVersionRoot, resolveProjectRoot } from "../storage/paths.js";
+import { canonicalPath, ensureDir, engineStoreRoot, engineVersionRoot, resolveProjectRoot } from "../storage/paths.js";
+import { resolveWorkReference } from "../storage/work-references.js";
 import { classifyCliOperation, isRouterNative } from "./cli-operation-classifier.js";
 import { requireProtocol } from "./protocols.js";
 import { resolveCanonRootBeforeContext } from "./canon.js";
@@ -346,9 +347,21 @@ export async function upgradeForkedRunEngine(context, input) {
     fs.renameSync(temporary, located.binding_path);
     return binding;
 }
-function boundRunEngineForArgs(context, args, projectRoot) {
-    const runId = runIdForArgs(args);
-    if (!runId || !projectRoot)
+function boundRunEngineForArgs(context, args, projectRoot, options = {}) {
+    if (!projectRoot)
+        return null;
+    let runId = runIdForArgs(args);
+    const parsed = parseLightArgs(args), [family, command] = parsed.positional;
+    if (family === "work" && command !== "repair") {
+        const reference = option(parsed, "parent") ?? positional(parsed, command === "deps" ? 3 : 2);
+        if (reference) {
+            const project = context.db.get("SELECT id FROM projects WHERE root = ?", [canonicalPath(projectRoot, false)]);
+            if (!project)
+                return null;
+            runId = resolveWorkReference(context, reference, { projectId: project.id, runId }).run_id;
+        }
+    }
+    if (!runId)
         return null;
     const located = locateRunRoot(context.db, projectRoot, runId);
     if (!located)
@@ -356,24 +369,58 @@ function boundRunEngineForArgs(context, args, projectRoot) {
     const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });
     if (!binding)
         return null;
+    // SQL locates the current project; a restored binding retains its historical
+    // project_root bytes. Do not reinterpret that provenance as a live locator.
+    if (binding.run_id !== located.run_id)
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding belongs to another scope", 1, { run_id: located.run_id });
     const manifest = requireBoundManifest(context.ddFlowHome, {
         packageName: binding.engine.package_name,
         packageVersion: binding.engine.package_version,
         integrityChecksum: binding.engine.integrity_checksum,
         snapshotRoot: binding.engine.snapshot_root
-    });
+    }, options);
     return { binding, manifest };
 }
+/** Detached RUN owners may be launched by a scope spanning several engines.
+ * Resolve the same retained pin as the public router before spawning directly. */
+export function boundRunEngineEntrypoint(context, input) {
+    const bound = boundRunEngineForArgs(context, ["run", "status", input.runId], input.projectRoot);
+    if (!bound)
+        throw new AppError("run_engine_binding_missing", "Detached RUN ownership requires its retained engine", 1, { run_id: input.runId });
+    return resolveManifestEntrypoint(bound.manifest);
+}
+/** Routing already admitted the complete snapshot. Inside that executor the
+ * RUN pin, not a mutable project's old/new compatibility range, owns writes.
+ * Compare the actual physical module identity; environment aliases cannot
+ * impersonate another installed engine. No snapshot scan on each lease ACK.
+ */
+export function selectBoundExecutingEngine(context, args, projectRoot, env) {
+    if (!isEngineMode(env))
+        return null;
+    const bound = boundRunEngineForArgs(context, args, projectRoot, { verifyContent: false });
+    if (!bound)
+        return null;
+    const current = currentBuildManifest(context, getCliBuildInfo(), false);
+    if (!sameEngineIdentity(engineIdentity(current), bound.binding.engine))
+        throw new AppError("run_engine_binding_invalid", "Executing engine differs from the retained RUN pin", 1, { run_id: bound.binding.run_id });
+    return { status: "selected", package_name: current.package_name, required_range: `=${current.package_version}`,
+        recommended_version: current.package_version, selected: current, install_hint: null, project_root: projectRoot,
+        memory_bank_version: readCompatibilityForProject(projectRoot)?.memory_bank_version ?? null, diagnostics: [] };
+}
 function runIdForArgs(args) {
-    const [family, command, ...rest] = args;
-    const parsed = parseLightArgs(rest);
+    const input = parseLightArgs(args), [family, command, ...rest] = input.positional;
+    const parsed = { ...input, positional: rest };
     if (family === "run" && command !== "start" && command !== "list") {
-        if (["drive", "control", "recovery", "capacity"].includes(command ?? ""))
+        if (["drive", "control"].includes(command ?? ""))
             return option(parsed, "run");
-        if (command === "flags")
+        if (["flags", "vars", "config", "recovery", "capacity"].includes(command ?? ""))
             return positional(parsed, 1);
+        if (command === "snapshot")
+            return positional(parsed, 0) === "create" ? positional(parsed, 1) : null;
         return positional(parsed, 0);
     }
+    if (family === "stage" && ["fanout", "native"].includes(command ?? ""))
+        return positional(parsed, 1);
     if (family === "stage" && command !== "start")
         return positional(parsed, 0);
     if (family === "stage" && command === "start" && !parsed.options.has("bootstrap"))
@@ -384,7 +431,7 @@ function runIdForArgs(args) {
         return option(parsed, "run");
     if (family === "protocol" && command === "sync-from-run")
         return option(parsed, "run");
-    return null;
+    return option(parsed, "run");
 }
 function requireBoundManifest(ddFlowHome, input, options = {}) {
     const manifest = input.snapshotRoot
@@ -1049,7 +1096,6 @@ function spawnEngine(manifest, entrypoint, args, io, stdin, env, routedFromVersi
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, [entrypoint, ...args], {
             env: {
-                ...process.env,
                 ...env,
                 DD_FLOW_ENGINE_MODE: "1",
                 DD_FLOW_ENGINE_HOME: manifest.snapshot_root,
@@ -1143,8 +1189,12 @@ function findPackageRoot(start) {
         current = parent;
     }
 }
+let checksumScanOrdinal = 0;
 export function engineSnapshotChecksum(root) {
-    publishSetup('probe_started', `engine-digest:${root}`);
+    // A CLI can legitimately revalidate the same snapshot at several boundaries.
+    // Distinguish actual scans without making duplicate phase notifications progress.
+    const scan = `engine-digest:${root}:scan-${++checksumScanOrdinal}`;
+    publishSetup('probe_started', scan);
     const files = [];
     collectFiles(root, root, files);
     const checksum = crypto.createHash("sha256");
@@ -1154,11 +1204,11 @@ export function engineSnapshotChecksum(root) {
         checksum.update("\0");
         checksum.update(fs.readFileSync(path.join(root, file)));
         if (++checked % 64 === 0)
-            publishSetup('identity_digest_progress', `${root}:${checked}`);
+            publishSetup('identity_digest_progress', `${scan}:${checked}`);
         checksum.update("\0");
     }
     const result = checksum.digest("hex");
-    publishSetup('identity_digest_completed', root);
+    publishSetup('identity_digest_completed', scan);
     return result;
 }
 function collectFiles(root, current, files) {