@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/services/engines.js

@@ -2,40 +2,76 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
+import { commandText } from '../harness-runtime/lib/process-json.mjs';
+import { SETUP_STARTUP_MS, publishSetup } from '../harness-runtime/lib/setup-progress.mjs';
 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 { classifyCliOperation } from "./cli-operation-classifier.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";
 import { appendAudit } from "./audit.js";
+import { readBoundedReleaseFile } from "./release-source.js";
 import { findProjectByRoot } from "./projects.js";
+import { parseCommandArgs } from "./lifecycle-command.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);
-const packageRequire = createRequire(sourceFile);
 export function isEngineMode(env) {
     return env.DD_FLOW_ENGINE_MODE === "1";
 }
 export function isRouterNativeCommand(args) {
-    const first = args[0];
-    if (!first || first === "--version")
-        return true;
-    if (first === "--help" || first === "-h")
-        return true;
-    if (args.includes("--help") || args.includes("-h"))
-        return true;
-    return routerNativeFamilies.has(first) || first === "codex" && args[1] === "hook" && args[2] === "handle";
+    return isRouterNative(args);
 }
 export function installCurrentEngine(context, input = {}) {
+    const installation = prepareInstallation(context, input);
+    const first = installation.next();
+    if (first.done && input.forRouting)
+        return first.value;
+    const manifest = first.done ? requireManifest(path.join(String(first.value.path), 'engine.json')) : first.value;
+    return probeEntrypoint(manifest, undefined, context.ddFlowHome, process.env).then(() => first.done ? first.value : installation.next().value)
+        .catch(error => {
+        let cleanup_error;
+        try {
+            installation.return({});
+        }
+        catch (cleanup) {
+            cleanup_error = { message: String(cleanup).slice(0, 2000) };
+        }
+        throw new AppError('engine_install_failed', 'Staged engine admission failed', 1, { ...error.details, cause: error.code, probe_error: { code: error.code, details: error.details }, ...(cleanup_error ? { cleanup_error } : {}) });
+    });
+}
+function* prepareInstallation(context, input) {
     const build = getCliBuildInfo();
     const packageRoot = findPackageRoot(path.dirname(sourceFile));
     if (!packageRoot) {
         throw new AppError("engine_install_failed", "Cannot locate package root for current dd-flow engine", 1);
     }
+    return yield* installPackageSnapshot(context, packageRoot, build.package_name, build.version, input);
+}
+/** Delivery from an independently selected package, not the invoking CLI.
+ * The caller owns release/dependency qualification of expectedChecksum.
+ * Existing snapshots are preserved even when not yet bound to a RUN. */
+export function installPackageEngine(context, input) {
+    if (!path.isAbsolute(input.packageRoot) || fs.realpathSync(input.packageRoot) !== input.packageRoot
+        || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(input.packageName)
+        || valid(input.version) !== input.version
+        || !/^[a-f0-9]{64}$/.test(input.expectedChecksum)) {
+        throw new AppError("engine_install_failed", "Selected package requires a canonical root and independent content checksum", 1, { effect: "no_effect" });
+    }
+    const metadata = JSON.parse(readBoundedReleaseFile(path.join(input.packageRoot, "package.json"), 1024 * 1024).toString("utf8"));
+    if (metadata.name !== input.packageName || metadata.version !== input.version
+        || snapshotFilesChecksum(packageSnapshotFiles(input.packageRoot)) !== input.expectedChecksum) {
+        throw new AppError("engine_install_failed", "Selected package identity or contents changed before delivery", 1, { effect: "no_effect" });
+    }
+    return installPackageSnapshot(context, input.packageRoot, input.packageName, input.version, { force: true, forRouting: true }, input.expectedChecksum, input.validateStaged).next().value;
+}
+function* installPackageSnapshot(context, packageRoot, packageName, version, input, expectedChecksum, validateStaged) {
+    const build = { package_name: packageName, version };
     const target = engineVersionRoot(context.ddFlowHome, build.package_name, build.version);
     const manifestPath = path.join(target, "engine.json");
     const existing = readManifest(manifestPath);
@@ -66,14 +102,24 @@ export function installCurrentEngine(context, input = {}) {
         const tmp = path.join(parent, `.${path.basename(target)}.tmp-${process.pid}-${Date.now()}`);
         fs.rmSync(tmp, { recursive: true, force: true });
         ensureDir(tmp);
+        publishSetup('probe_started', `engine-staging:${tmp}`);
         copyPackageSnapshot(packageRoot, tmp);
         const stagedManifest = buildManifest(context, build.package_name, build.version, packageRoot, target, tmp);
         const stagedChecksum = stagedManifest.integrity.checksum;
+        if (expectedChecksum !== undefined && stagedChecksum !== expectedChecksum) {
+            throw new AppError("engine_install_failed", "Selected package changed during delivery", 1, { effect: "partial", path: tmp });
+        }
+        try {
+            validateStaged?.(tmp);
+        }
+        catch (error) {
+            throw new AppError("engine_install_failed", "Staged package no longer matches its selected release", 1, { effect: "partial", path: tmp, reason: error instanceof AppError ? error.details.reason ?? error.code : "staged_selection_changed" });
+        }
         const activationTarget = input.force
             && existing
             && stagedChecksum
             && stagedChecksum !== existing.integrity.checksum
-            && engineIsBound(context.ddFlowHome, existing)
+            && (expectedChecksum !== undefined || engineIsBound(context.ddFlowHome, existing))
             ? `${target}--${stagedChecksum}`
             : target;
         const duplicate = stagedChecksum ? findInstalledManifest(context.ddFlowHome, {
@@ -81,7 +127,7 @@ export function installCurrentEngine(context, input = {}) {
             packageVersion: build.version,
             integrityChecksum: stagedChecksum
         }) : null;
-        if (duplicate) {
+        if (duplicate && manifestDiagnostics(duplicate, { checkEntrypoint: false }).length === 0) {
             fs.rmSync(tmp, { recursive: true, force: true });
             return {
                 ok: true,
@@ -94,13 +140,15 @@ export function installCurrentEngine(context, input = {}) {
         const manifest = { ...stagedManifest, package_root: activationTarget, snapshot_root: activationTarget };
         fs.writeFileSync(path.join(tmp, "engine.json"), `${JSON.stringify(manifest, null, 2)}\n`);
         const checkedManifest = requireManifest(path.join(tmp, "engine.json"));
-        const stagedDiagnostics = manifestDiagnostics({ ...checkedManifest, package_root: tmp, snapshot_root: tmp }, { checkEntrypoint: !input.forRouting });
+        const stagedDiagnostics = manifestDiagnostics({ ...checkedManifest, package_root: tmp, snapshot_root: tmp }, { checkEntrypoint: false });
         if (stagedDiagnostics.length > 0) {
             throw new AppError("engine_install_failed", "Staged dd-flow engine failed its integrity or dependency health check", 1, {
                 diagnostics: stagedDiagnostics,
                 path: tmp
             });
         }
+        if (!input.forRouting)
+            yield { ...checkedManifest, package_root: tmp, snapshot_root: tmp };
         activateEngineAtomically(tmp, activationTarget);
         const installed = requireManifest(path.join(activationTarget, "engine.json"));
         return {
@@ -117,7 +165,7 @@ export function installCurrentEngine(context, input = {}) {
 }
 export function listEngines(context) {
     const root = engineStoreRoot(context.ddFlowHome);
-    const engines = readInstalledManifests(root).map(manifestSummary);
+    const engines = readInstalledManifests(root).map(manifest => manifestSummary(manifest));
     return { ok: true, schema_id: "dd-flow/engine-list@1", engine_store: root, engines };
 }
 export function engineInfo(context, input) {
@@ -135,14 +183,23 @@ export function resolveEngine(context, input = {}) {
     }
     return { ok: true, schema_id: "dd-flow/engine-resolve@1", selection, contexts: compatibilityContexts(context, { ...input, classification }) };
 }
-export function doctorEngines(context, input = {}) {
+export async function doctorEngines(context, input = {}) {
     const root = engineStoreRoot(context.ddFlowHome);
     const installed = readInstalledManifests(root);
-    const checks = installed.map((manifest) => ({
-        engine: manifestSummary(manifest),
-        status: manifestHealthy(manifest) ? "ok" : "corrupt",
-        diagnostics: manifestDiagnostics(manifest)
-    }));
+    const checks = [];
+    for (const manifest of installed) {
+        const diagnostics = manifestDiagnostics(manifest);
+        let probe_error;
+        if (!diagnostics.length)
+            try {
+                await probeEntrypoint(manifest, undefined, context.ddFlowHome, context.env);
+            }
+            catch (error) {
+                probe_error = error instanceof AppError ? error.details : { message: String(error) };
+                diagnostics.push(error instanceof AppError && error.code === 'engine_probe_failed' ? 'entrypoint_dependency_load_failed' : 'entrypoint_probe_unavailable');
+            }
+        checks.push({ engine: manifestSummary(manifest, diagnostics), status: diagnostics.includes("entrypoint_probe_unavailable") ? "unverified" : diagnostics.length ? "corrupt" : "ok", diagnostics, ...(probe_error ? { probe_error } : {}) });
+    }
     const classification = input.classification ?? classifyCliOperation(["engine", "doctor"], input.env ?? context.env);
     const selection = selectEngine(context, input, {}, classification);
     return {
@@ -155,7 +212,7 @@ export function doctorEngines(context, input = {}) {
         exit_code: checks.every((check) => check.status === "ok") && selection.status === "selected" ? 0 : 1
     };
 }
-export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedProjectRoot) {
+export async function routeArgsThroughEngine(context, args, io, stdin, env, resolvedProjectRoot) {
     if (isEngineMode(env) || isRouterNativeCommand(args))
         return Promise.resolve(null);
     const classification = classifyCliOperation(args, env);
@@ -174,13 +231,18 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
     if (!selection.selected)
         return Promise.resolve(null);
     const current = getCliBuildInfo();
-    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version) {
+    const currentRoot = findPackageRoot(path.dirname(sourceFile));
+    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version
+        && currentRoot !== null && fs.realpathSync(selection.selected.snapshot_root) === fs.realpathSync(currentRoot)) {
         return Promise.resolve({ routed: true, exitCode: 0, inProcess: true });
     }
     const entrypoint = resolveManifestEntrypoint(selection.selected);
+    // The admitted immutable entrypoint executes the requested operation itself.
+    // A separate --version process adds no operation-specific admission.
     return spawnEngine(selection.selected, entrypoint, args, io, stdin, env, current.version);
 }
-export function bindRunEngine(context, input) {
+export async function prepareRunEngineBind(context, input) {
+    const reason = requiredText(input.reason, "reason");
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const located = locateRunRoot(context.db, projectRoot, input.runId);
     if (!located)
@@ -190,40 +252,43 @@ export function bindRunEngine(context, input) {
         packageName: input.packageName ?? getCliBuildInfo().package_name,
         packageVersion: input.engineVersion,
         ...(input.integrityChecksum ? { integrityChecksum: input.integrityChecksum } : {})
-    });
+    }, { checkEntrypoint: false });
     const requested = engineIdentity(manifest);
     if (existing) {
         if (sameEngineIdentity(existing.engine, requested))
-            return { ok: true, action: "run_engine_bind", changed: false, binding: existing };
+            return { kind: "replay", binding: existing };
         throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, {
             run_id: located.run_id,
             current: existing.engine,
             requested
         });
     }
-    const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
-    const probe = spawnSync(process.execPath, [resolveManifestEntrypoint(manifest), ...probeArgs], {
-        cwd: manifest.snapshot_root,
-        env: { ...process.env, ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: manifest.snapshot_root },
-        encoding: "utf8",
-        timeout: 30_000
-    });
-    if (probe.status !== 0) {
-        throw new AppError("run_engine_probe_failed", "Selected engine cannot read the RUN authority", 1, {
-            run_id: located.run_id,
-            engine: manifestSummary(manifest),
-            command: `dd-flow ${probeArgs.join(" ")}`,
-            exit_code: probe.status,
-            stderr: probe.stderr.slice(0, 2000)
-        });
+    await probeEntrypoint(manifest, ['run', 'status', located.run_id, '--project-root', projectRoot, '--json'], context.ddFlowHome, context.env, 'run_engine');
+    return { kind: "create", projectRoot, located, manifest, requested, reason, entrypoint: resolveManifestEntrypoint(manifest) };
+}
+export async function bindRunEngine(context, input, supplied) {
+    const prepared = supplied ?? await prepareRunEngineBind(context, input);
+    if (prepared.kind === "replay")
+        return { ok: true, action: "run_engine_bind", changed: false, binding: prepared.binding };
+    const { projectRoot, located, manifest, requested, reason } = prepared;
+    const current = locateRunRoot(context.db, projectRoot, input.runId);
+    if (!current || current.run_root !== located.run_root)
+        throw new AppError('run_engine_binding_conflict', 'RUN identity changed during probe', 1);
+    requireBoundManifest(context.ddFlowHome, { packageName: manifest.package_name, packageVersion: manifest.package_version, integrityChecksum: requested.integrity_checksum });
+    const existing = readRunEngineBinding(located.binding_path, { allowMissing: true });
+    if (existing) {
+        if (sameEngineIdentity(existing.engine, requested))
+            return { ok: true, action: "run_engine_bind", changed: false, binding: existing };
+        throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, { run_id: located.run_id, current: existing.engine, requested });
     }
+    const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
     const binding = {
         schema_id: runEngineBindingSchemaId,
         run_id: located.run_id,
         project_root: projectRoot,
         bound_at: context.now(),
         source: "legacy_recovery",
-        reason: requiredText(input.reason, "reason"),
+        reason,
         engine: requested,
         probe: { status: "passed", command: `dd-flow ${probeArgs.join(" ")}` }
     };
@@ -252,9 +317,51 @@ export function bindCurrentEngineToRun(context, input) {
     };
     return writeRunEngineBinding(path.join(input.runRoot, "engine-binding.json"), binding).binding;
 }
-function boundRunEngineForArgs(context, args, projectRoot) {
-    const runId = runIdForArgs(args);
-    if (!runId || !projectRoot)
+/** Forks are a new execution authority.  The source binding stays immutable;
+ * this replaces only the copied binding after proving the selected engine can
+ * read the copied RUN. */
+export async function upgradeForkedRunEngine(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const located = locateRunRoot(context.db, projectRoot, input.runId);
+    if (!located)
+        throw new AppError("not_found", `Forked RUN is not registered: ${input.runId}`, 1);
+    const manifest = requireBoundManifest(context.ddFlowHome, {
+        packageName: getCliBuildInfo().package_name,
+        packageVersion: input.engineVersion,
+        ...(input.integrityChecksum ? { integrityChecksum: input.integrityChecksum } : {})
+    });
+    const requested = engineIdentity(manifest);
+    const priorBinding = fs.readFileSync(located.binding_path, 'utf8');
+    const lineage = path.join(located.run_root, "fork-lineage.json");
+    if (!fs.existsSync(lineage))
+        throw new AppError("fork_lineage_missing", "Engine upgrade is permitted only for a derived RUN", 1, { run_id: located.run_id });
+    const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
+    const priorLineage = fs.readFileSync(lineage, 'utf8');
+    await probeEntrypoint(manifest, probeArgs, context.ddFlowHome, context.env, 'fork_engine');
+    if (fs.readFileSync(located.binding_path, 'utf8') !== priorBinding || fs.readFileSync(lineage, 'utf8') !== priorLineage)
+        throw new AppError('fork_engine_binding_conflict', 'Fork identity changed during probe', 1);
+    requireBoundManifest(context.ddFlowHome, { packageName: manifest.package_name, packageVersion: manifest.package_version, integrityChecksum: manifest.integrity.checksum });
+    const binding = { schema_id: runEngineBindingSchemaId, run_id: located.run_id, project_root: projectRoot, bound_at: context.now(), source: "fork_upgrade", reason: requiredText(input.reason, "reason"), engine: requested, probe: { status: "passed", command: `dd-flow ${probeArgs.join(" ")}` } };
+    const temporary = `${located.binding_path}.fork-${process.pid}-${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(binding, null, 2)}\n`);
+    fs.renameSync(temporary, located.binding_path);
+    return binding;
+}
+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)
@@ -262,22 +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 (command === "flags")
+        if (["drive", "control"].includes(command ?? ""))
+            return option(parsed, "run");
+        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"))
@@ -288,9 +431,9 @@ 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) {
+function requireBoundManifest(ddFlowHome, input, options = {}) {
     const manifest = input.snapshotRoot
         ? requireManifest(path.join(input.snapshotRoot, "engine.json"))
         : findInstalledManifest(ddFlowHome, {
@@ -303,7 +446,7 @@ function requireBoundManifest(ddFlowHome, input) {
         || manifest.package_version !== input.packageVersion
         || input.integrityChecksum !== undefined && manifest.integrity.checksum !== input.integrityChecksum
         || input.snapshotRoot !== undefined && path.resolve(manifest.snapshot_root) !== path.resolve(input.snapshotRoot)
-        || !manifestHealthy(manifest)) {
+        || manifestDiagnostics(manifest, options).length !== 0) {
         throw new AppError("run_engine_binding_invalid", "RUN engine binding points to a missing or unhealthy engine snapshot", 1, {
             package_name: input.packageName,
             package_version: input.packageVersion,
@@ -344,7 +487,7 @@ function executionManifest(context) {
     return requireManifest(path.join(String(installed.path), "engine.json"));
 }
 function requiredText(value, label) {
-    const normalized = value.trim();
+    const normalized = typeof value === "string" ? value.trim() : "";
     if (!normalized)
         throw new AppError("usage", `Missing required value: ${label}`, 2);
     return normalized;
@@ -380,14 +523,14 @@ export function selectEngine(context, input, options = {}, classification = inpu
     const requiredRange = stringValue(compatibility?.engine?.version_range) ?? (classification.mode === "mb_upgrade" ? null : `>=${build.version} <9999.0.0`);
     const recommended = stringValue(compatibility?.engine?.recommended_version) ?? build.version;
     const installHintTemplate = stringValue(compatibility?.engine?.old_engine_install_hint) ?? `npx ${packageName}@<version> engine install`;
-    const manifests = readInstalledManifests(engineStoreRoot(context.ddFlowHome))
+    // An engine-mode caller already executes this module's build. Another
+    // installed engine cannot establish compatibility for its current writes.
+    // Keep full snapshot validation in routing/binding, not lease maintenance.
+    const executingCurrent = options.allowCurrentInProcess && isEngineMode(input.env ?? process.env);
+    const manifests = executingCurrent ? [] : readInstalledManifests(engineStoreRoot(context.ddFlowHome))
         .filter((manifest) => manifest.package_name === packageName)
         .filter((manifest) => requiredRange !== null && satisfiesRange(manifest.package_version, requiredRange))
-        .filter((manifest) => options.allowCurrentInProcess
-        && manifest.package_name === build.package_name
-        && manifest.package_version === build.version
-        ? true
-        : manifestHealthy(manifest))
+        .filter((manifest) => manifestHealthy(manifest))
         .sort((a, b) => {
         const versionOrder = compareSemverStrings(b.package_version, a.package_version);
         if (versionOrder !== 0)
@@ -402,7 +545,7 @@ export function selectEngine(context, input, options = {}, classification = inpu
         requiredRange !== null &&
         packageName === build.package_name &&
         satisfiesRange(build.version, requiredRange)
-        ? currentBuildManifest(context, build)
+        ? currentBuildManifest(context, build, options.verifyCurrentContent !== false)
         : null);
     const diagnostics = [
         ...targetBlockers,
@@ -420,9 +563,38 @@ export function selectEngine(context, input, options = {}, classification = inpu
         diagnostics
     };
 }
-function currentBuildManifest(context, build) {
+function currentBuildManifest(context, build, verifyContent) {
     const packageRoot = findPackageRoot(path.dirname(sourceFile)) ?? process.cwd();
-    return buildManifest(context, build.package_name, build.version, packageRoot, packageRoot, packageRoot);
+    const manifestFile = path.join(packageRoot, "engine.json");
+    const installedLayout = path.basename(path.dirname(path.dirname(packageRoot))) === "engines"
+        && path.basename(path.dirname(packageRoot)) === path.basename(path.dirname(engineVersionRoot(context.ddFlowHome, build.package_name, build.version)));
+    if (fs.existsSync(manifestFile) || installedLayout) {
+        const installed = readManifest(manifestFile);
+        // Use the executing module's physical root, never an environment alias.
+        // A damaged installed manifest must not become a development fallback.
+        if (!installed || installed.package_name !== build.package_name || installed.package_version !== build.version
+            || installed.engine_version !== build.version || installed.engine_id !== "dd-flow-engine"
+            || typeof installed.snapshot_root !== "string" || !fs.existsSync(installed.snapshot_root)
+            || fs.realpathSync(installed.snapshot_root) !== fs.realpathSync(packageRoot)
+            || typeof installed.entrypoint !== "string" || installed.integrity?.source !== "package_snapshot"
+            || typeof installed.integrity?.checksum !== "string" || !/^[a-f0-9]{64}$/.test(installed.integrity.checksum)
+            || (installed.schema_registry && (!Array.isArray(installed.schema_registry.entries)
+                || installed.schema_registry.entries.some(entry => !entry || typeof entry.path !== "string"
+                    || typeof entry.id !== "string" || typeof entry.name !== "string" || !/^[a-f0-9]{64}$/.test(entry.checksum ?? ""))))) {
+            throw new AppError("unhealthy_engine", "Executing engine snapshot manifest does not match its build", 1, { manifest: manifestFile });
+        }
+        const diagnostics = manifestDiagnostics(installed, { checkEntrypoint: false, verifyContent });
+        if (diagnostics.length)
+            throw new AppError("unhealthy_engine", "Executing engine snapshot is unhealthy", 1, { manifest: manifestFile, diagnostics });
+        return installed;
+    }
+    // Only an unmaterialized package has no snapshot proof. Canon and
+    // package-manager aliases are expected in development checkouts.
+    const manifest = buildManifest(context, build.package_name, build.version, packageRoot, packageRoot, packageRoot, null);
+    // An ephemeral routing choice has no snapshot proof. Hash bytes only when
+    // materializing/validating an installed snapshot, never on every CLI call.
+    manifest.integrity.mode = "degraded_local_development";
+    return manifest;
 }
 export function compatibilityContexts(context, input = {}) {
     const env = input.env ?? process.env;
@@ -560,40 +732,16 @@ function canonCompatibilitySha(memorybankRoot) {
         return null;
     }
 }
-function parseLightArgs(args) {
-    const positional = [];
-    const options = new Map();
-    for (let index = 0; index < args.length; index += 1) {
-        const value = args[index];
-        if (value?.startsWith("--")) {
-            const equal = value.indexOf("=");
-            if (equal > 2) {
-                const key = value.slice(2, equal);
-                options.set(key, [...(options.get(key) ?? []), value.slice(equal + 1)]);
-                continue;
-            }
-            const key = value.slice(2);
-            const next = args[index + 1];
-            if (!next || next.startsWith("--"))
-                options.set(key, [...(options.get(key) ?? []), ""]);
-            else {
-                options.set(key, [...(options.get(key) ?? []), next]);
-                index += 1;
-            }
-        }
-        else if (value)
-            positional.push(value);
-    }
-    return { positional, options };
-}
+const parseLightArgs = parseCommandArgs;
 function option(parsed, key) {
     const values = parsed.options.get(key);
-    return values?.[values.length - 1] || null;
+    const value = values?.[values.length - 1];
+    return value && value !== "__dd_flow_flag__" ? value : null;
 }
 function positional(parsed, index) {
     return parsed.positional[index] ?? null;
 }
-function buildManifest(context, packageName, version, packageRoot, snapshotRoot, checksumRoot) {
+function buildManifest(context, packageName, version, packageRoot, snapshotRoot, checksumRoot, checksum = engineSnapshotChecksum(checksumRoot)) {
     return {
         schema_id: engineManifestSchemaId,
         package_name: packageName,
@@ -609,35 +757,54 @@ function buildManifest(context, packageName, version, packageRoot, snapshotRoot,
         supports_contracts: {
             compatibility: ["dd-flow/compatibility@1"],
             version: ["dd-flow/version-report@1"],
-            status: ["dd-flow/status-report@1"]
+            status: ["dd-flow/status-report@1"],
+            hybrid: ["dd-flow/flow-descriptor@1", "dd-flow/execution-settings@1", "dd-flow/execution-bundle@1", "dd-flow/memory-bootstrap-receipt@2"]
         },
         schema_registry: buildSchemaRegistry(checksumRoot),
         integrity: {
             source: "package_snapshot",
-            checksum: engineSnapshotChecksum(checksumRoot),
+            checksum,
             mode: "full_content"
         }
     };
 }
 function copyPackageSnapshot(packageRoot, target) {
+    let copied = 0;
+    for (const [relative, source] of packageSnapshotFiles(packageRoot)) {
+        const destination = path.join(target, relative);
+        ensureDir(path.dirname(destination));
+        fs.copyFileSync(source, destination);
+        if (++copied % 64 === 0)
+            publishSetup('transfer_progress', `${target}:${copied}`);
+    }
+}
+/** The same source inventory drives validation and copying; no staging writes. */
+export function packageSnapshotFiles(packageRoot) {
+    const files = new Map();
+    const collect = (source, relative, skipNodeModules = false) => {
+        if (!fs.statSync(source).isDirectory()) {
+            files.set(relative, source);
+            return;
+        }
+        for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+            if (skipNodeModules && entry.name === "node_modules")
+                continue;
+            const child = path.join(source, entry.name), name = path.join(relative, entry.name);
+            if (entry.isDirectory())
+                collect(child, name, skipNodeModules);
+            else if (entry.isFile())
+                files.set(name, child);
+        }
+    };
     for (const item of ["dist", "package.json", "README.md", "CHANGELOG.md", "tools"]) {
         const from = path.join(packageRoot, item);
         if (!fs.existsSync(from))
             continue;
-        const to = path.join(target, item);
-        const stat = fs.statSync(from);
-        if (stat.isDirectory())
-            copyDir(from, to);
-        else {
-            ensureDir(path.dirname(to));
-            fs.copyFileSync(from, to);
-        }
+        collect(from, item);
     }
-    copyProductionDependencies(packageRoot, target);
-}
-function copyProductionDependencies(packageRoot, target) {
-    const queue = [{ sourceRoot: packageRoot, targetRoot: target, ancestors: new Set() }];
-    const copied = new Set();
+    const queue = [{ sourceRoot: packageRoot, targetRoot: "" }];
+    const placed = new Map();
+    const virtualRoot = path.resolve(path.sep, "dd-flow-snapshot");
     while (queue.length > 0) {
         const current = queue.shift();
         if (!current)
@@ -646,17 +813,48 @@ function copyProductionDependencies(packageRoot, target) {
             const sourceRoot = resolvePackageRoot(dependency, current.sourceRoot);
             if (!sourceRoot)
                 throw new AppError("engine_install_failed", `Cannot resolve runtime dependency: ${dependency}`, 1);
-            const targetRoot = path.join(current.targetRoot, "node_modules", dependency);
-            const copyKey = `${sourceRoot}\n${targetRoot}`;
-            if (copied.has(copyKey))
-                continue;
-            copied.add(copyKey);
-            copyDir(sourceRoot, targetRoot, true);
-            if (current.ancestors.has(sourceRoot))
+            // Standard Node lookup permits hoisting identical selected packages.
+            // Copying a shared DAG under every parent makes SDK snapshots grow
+            // exponentially; conflicting versions still need their own local slot.
+            const search = createRequire(path.join(virtualRoot, current.targetRoot, "package.json")).resolve.paths(dependency) ?? [];
+            const candidates = search.filter(directory => directory.startsWith(`${virtualRoot}${path.sep}`))
+                .map(directory => path.relative(virtualRoot, path.join(directory, dependency)));
+            const existing = candidates.find(candidate => placed.has(candidate));
+            if (existing && placed.get(existing) === sourceRoot)
                 continue;
-            queue.push({ sourceRoot, targetRoot, ancestors: new Set([...current.ancestors, sourceRoot]) });
+            const targetRoot = existing ? path.join(current.targetRoot, "node_modules", dependency) : path.join("node_modules", dependency);
+            placed.set(targetRoot, sourceRoot);
+            collect(sourceRoot, targetRoot, true);
+            queue.push({ sourceRoot, targetRoot });
         }
     }
+    return files;
+}
+export function prepareForkEngine(engineVersion, integrityChecksum) {
+    const build = getCliBuildInfo();
+    if (engineVersion !== build.version)
+        throw new AppError("fork_engine_unavailable", "Fork installs the invoking CLI engine; invoke the requested version to upgrade the fork", 2, { requested: engineVersion, available: build.version });
+    const packageRoot = findPackageRoot(path.dirname(sourceFile));
+    if (!packageRoot || !fs.existsSync(path.join(packageRoot, "dist", "cli.js")))
+        throw new AppError("harness_runtime_unbuilt", "Build the CLI before preparing a fork", 1);
+    const files = packageSnapshotFiles(packageRoot);
+    if (integrityChecksum !== undefined) {
+        const checksum = snapshotFilesChecksum(files);
+        if (checksum !== integrityChecksum)
+            throw new AppError("fork_engine_unavailable", "Requested engine checksum differs from the invoking CLI artifact", 2, { requested: integrityChecksum });
+    }
+}
+function snapshotFilesChecksum(files) {
+    const checksum = crypto.createHash("sha256");
+    for (const [relative, source] of [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+        if (path.basename(relative) === "engine.json")
+            continue;
+        checksum.update(relative);
+        checksum.update("\0");
+        checksum.update(fs.readFileSync(source));
+        checksum.update("\0");
+    }
+    return checksum.digest("hex");
 }
 function readProductionDependencies(packageRoot) {
     try {
@@ -676,20 +874,14 @@ function readProductionDependencies(packageRoot) {
     }
 }
 function resolvePackageRoot(name, from) {
-    try {
-        let current = path.dirname(packageRequire.resolve(name, { paths: [from] }));
-        while (true) {
-            if (fs.existsSync(path.join(current, "package.json")))
-                return fs.realpathSync(current);
-            const parent = path.dirname(current);
-            if (parent === current)
-                return null;
-            current = parent;
-        }
-    }
-    catch {
-        return null;
+    // Inspect package roots through Node's lookup paths, not the require entry:
+    // production dependencies can expose only an ESM import condition.
+    for (const directory of createRequire(path.join(from, "package.json")).resolve.paths(name) ?? []) {
+        const candidate = path.join(directory, name);
+        if (fs.existsSync(path.join(candidate, "package.json")))
+            return fs.realpathSync(candidate);
     }
+    return null;
 }
 function inferInstallSource(packageRoot, ddFlowHome) {
     const normalized = path.resolve(packageRoot);
@@ -713,19 +905,6 @@ function hasAncestorFile(start, name) {
         current = parent;
     }
 }
-function copyDir(from, to, skipNodeModules = false) {
-    ensureDir(to);
-    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-        if (skipNodeModules && entry.name === "node_modules")
-            continue;
-        const source = path.join(from, entry.name);
-        const target = path.join(to, entry.name);
-        if (entry.isDirectory())
-            copyDir(source, target, skipNodeModules);
-        else if (entry.isFile())
-            fs.copyFileSync(source, target);
-    }
-}
 function acquireInstallLock(lockDir) {
     ensureDir(path.dirname(lockDir));
     try {
@@ -750,6 +929,9 @@ function readInstalledManifests(root) {
         if (!fs.statSync(packageRoot).isDirectory())
             continue;
         for (const versionDir of fs.readdirSync(packageRoot)) {
+            // Failed staging, activation backups and locks are not installations.
+            if (versionDir.startsWith(".") || /\.previous-\d+-\d+$/.test(versionDir) || versionDir.endsWith(".lock"))
+                continue;
             const manifest = readManifest(path.join(packageRoot, versionDir, "engine.json"));
             if (manifest)
                 manifests.push(manifest);
@@ -802,7 +984,7 @@ function manifestDiagnostics(manifest, options = {}) {
     if (!manifest.integrity || manifest.integrity.mode !== "full_content" || !manifest.integrity.checksum) {
         diagnostics.push("content_checksum_missing");
     }
-    else if (fs.existsSync(snapshotRoot)) {
+    else if (options.verifyContent !== false && fs.existsSync(snapshotRoot)) {
         try {
             if (engineSnapshotChecksum(snapshotRoot) !== manifest.integrity.checksum)
                 diagnostics.push("content_checksum_mismatch");
@@ -816,6 +998,8 @@ function manifestDiagnostics(manifest, options = {}) {
             const schemaPath = safeResolveSnapshotPath(manifest, entry.path);
             if (!schemaPath || !fs.existsSync(schemaPath))
                 diagnostics.push(`schema_registry_missing:${entry.name}`);
+            else if (options.verifyContent === false)
+                continue;
             else if (fileChecksum(schemaPath) !== entry.checksum)
                 diagnostics.push(`schema_registry_checksum_mismatch:${entry.name}`);
             else {
@@ -829,25 +1013,21 @@ function manifestDiagnostics(manifest, options = {}) {
             }
         }
     }
-    if (options.checkEntrypoint !== false && entrypoint && fs.existsSync(entrypoint) && !diagnostics.includes("entrypoint_outside_snapshot")) {
-        const health = spawnSync(process.execPath, [entrypoint, "--version", "--json"], {
-            cwd: snapshotRoot,
-            env: {
-                ...process.env,
-                DD_FLOW_ENGINE_MODE: "1",
-                DD_FLOW_ENGINE_HOME: snapshotRoot,
-                DD_FLOW_ENGINE_HEALTHCHECK: "1"
-            },
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-            timeout: 15_000
-        });
-        if (health.status !== 0)
-            diagnostics.push("entrypoint_dependency_load_failed");
-    }
     return diagnostics;
 }
-function manifestSummary(manifest) {
+async function probeEntrypoint(manifest, args = ['--version', '--json'], runtimeHome, env = {}, purpose = 'engine') {
+    publishSetup('probe_started', manifest.snapshot_root);
+    try {
+        await commandText(resolveManifestEntrypoint(manifest), args, { cwd: manifest.snapshot_root,
+            env: { ...env, DD_FLOW_ENGINE_MODE: '1', DD_FLOW_ENGINE_HOME: manifest.snapshot_root, ...(runtimeHome ? { DD_FLOW_HOME: runtimeHome } : {}), ...(args[0] === '--version' ? { DD_FLOW_ENGINE_HEALTHCHECK: '1' } : {}) }, startupMs: SETUP_STARTUP_MS, phase: 'engine-probe' });
+        publishSetup('probe_completed', manifest.snapshot_root);
+    }
+    catch (cause) {
+        const error = cause;
+        throw new AppError(error.details?.reason === 'child_exit' && error.details?.signal === null && error.details?.exit_code !== null ? `${purpose}_probe_failed` : `${purpose}_probe_unavailable`, 'Selected engine probe did not complete successfully', 1, { cause: error.code, message: error.message, ...error.details });
+    }
+}
+function manifestSummary(manifest, diagnostics = manifestDiagnostics(manifest, { checkEntrypoint: false })) {
     return {
         schema_id: manifest.schema_id,
         package_name: manifest.package_name,
@@ -859,8 +1039,8 @@ function manifestSummary(manifest) {
         snapshot_root: manifest.snapshot_root,
         resolved_entrypoint: safeResolveManifestEntrypoint(manifest),
         installed_at: manifest.installed_at,
-        healthy: manifestHealthy(manifest),
-        diagnostics: manifestDiagnostics(manifest)
+        healthy: diagnostics.length === 0,
+        diagnostics
     };
 }
 function resolveManifestEntrypoint(manifest) {
@@ -916,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,
@@ -1010,23 +1189,35 @@ function findPackageRoot(start) {
         current = parent;
     }
 }
+let checksumScanOrdinal = 0;
 export function engineSnapshotChecksum(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");
+    let checked = 0;
     for (const file of files.sort()) {
         checksum.update(file);
         checksum.update("\0");
         checksum.update(fs.readFileSync(path.join(root, file)));
+        if (++checked % 64 === 0)
+            publishSetup('identity_digest_progress', `${scan}:${checked}`);
         checksum.update("\0");
     }
-    return checksum.digest("hex");
+    const result = checksum.digest("hex");
+    publishSetup('identity_digest_completed', scan);
+    return result;
 }
 function collectFiles(root, current, files) {
     for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
         if (entry.name === "engine.json")
             continue;
         const full = path.join(current, entry.name);
+        if (entry.isSymbolicLink())
+            throw new AppError("engine_integrity_symlink", "Pinned engine snapshot contains an unhashed symbolic link", 1, { path: path.relative(root, full) });
         if (entry.isDirectory())
             collectFiles(root, full, files);
         else if (entry.isFile())