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

package/dist/services/frozen-engine.js

@@ -0,0 +1,242 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { Ajv } from "ajv/dist/ajv.js";
+import { AppError } from "../shared/errors.js";
+import { engineSnapshotChecksum } from "./engines.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { shellArgument } from "./runtime-command.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { isMemoryInitResourceStorageFacts } from "./memory-init-resource-storage.js";
+import { memoryInitStartupInputSchemas } from "./memory-init-startup-custody.js";
+function storageProbeRefuse(reason) {
+    throw new AppError("frozen_engine_storage_incompatible", "Selected frozen engine cannot admit memory-init storage", 1, { reason, effect: "no_effect" });
+}
+const hash = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("frozen_engine_invalid", "Frozen engine cannot be admitted", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_utf8_json");
+    }
+}
+function shape(name, value, property) {
+    const schema = JSON.parse(fs.readFileSync(new URL(`../schemas/${name}.schema.json`, import.meta.url), "utf8"));
+    return new Ajv({ strict: false, validateFormats: false }).compile(property ? schema.properties[property] : schema)(value) === true;
+}
+function containedFile(root, relative) {
+    if (path.isAbsolute(relative) || relative.split(/[\\/]/).some(part => part === ".." || part === "." || !part))
+        refuse("escaping_engine_path");
+    const parts = relative.split(/[\\/]/);
+    let current = root;
+    for (const [index, part] of parts.entries()) {
+        current = path.join(current, part);
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory()))
+            refuse("non_regular_engine_path");
+    }
+    return current;
+}
+/** New-bundle admission only. It does not replace historical binding or storage admission. */
+export class AdmittedFrozenEngine {
+    manifestSha256;
+    entrypoint;
+    nodeExecutable;
+    #manifest;
+    #bytes;
+    constructor(manifest, bytes, entrypoint) {
+        this.#manifest = manifest;
+        this.#bytes = bytes;
+        this.manifestSha256 = hash(bytes);
+        this.entrypoint = entrypoint;
+        this.nodeExecutable = fs.realpathSync(process.execPath);
+        Object.freeze(this);
+    }
+    /** Both hashes are independently selected by the RUN/bundle authority. No subprocess probe. */
+    static admit(binding, expectedManifestSha256) {
+        if (!shape("run-engine-binding", binding) || !/^[a-f0-9]{64}$/.test(expectedManifestSha256))
+            refuse("invalid_binding_identity");
+        return AdmittedFrozenEngine.fromIdentity(binding.engine, expectedManifestSha256);
+    }
+    /** Pre-RUN selection: no invented RUN id, binding or allocation authority. */
+    static admitSelection(identity, expectedManifestSha256) {
+        if (!shape("run-engine-binding", identity, "engine") || !/^[a-f0-9]{64}$/.test(expectedManifestSha256))
+            refuse("invalid_selection_identity");
+        return AdmittedFrozenEngine.fromIdentity(identity, expectedManifestSha256);
+    }
+    static fromIdentity(identity, expectedManifestSha256) {
+        try {
+            const root = path.resolve(identity.snapshot_root);
+            if (!path.isAbsolute(identity.snapshot_root) || !fs.lstatSync(root).isDirectory())
+                refuse("missing_or_linked_snapshot");
+            const bytes = readBoundedReleaseFile(path.join(root, "engine.json"), 1024 * 1024);
+            if (hash(bytes) !== expectedManifestSha256)
+                refuse("manifest_bytes_changed");
+            const value = json(bytes);
+            if (!shape("engine-manifest", value))
+                refuse("invalid_manifest_shape");
+            const manifest = value;
+            if (manifest.package_name !== identity.package_name || manifest.package_version !== identity.package_version
+                || manifest.engine_version !== identity.engine_version || path.resolve(manifest.snapshot_root) !== root
+                || manifest.integrity.mode !== "full_content" || manifest.integrity.checksum !== identity.integrity_checksum)
+                refuse("foreign_manifest_identity");
+            if (engineSnapshotChecksum(root) !== identity.integrity_checksum)
+                refuse("executable_snapshot_changed");
+            const entrypoint = containedFile(root, manifest.entrypoint);
+            if (!manifest.schema_registry || manifest.schema_registry.entries.length === 0)
+                refuse("missing_schema_registry");
+            const names = new Set(), paths = new Set();
+            for (const entry of manifest.schema_registry.entries) {
+                if (names.has(entry.name) || paths.has(entry.path))
+                    refuse("ambiguous_schema_registry");
+                names.add(entry.name);
+                paths.add(entry.path);
+                const schemaBytes = readBoundedReleaseFile(containedFile(root, entry.path), 1024 * 1024);
+                if (hash(schemaBytes) !== entry.checksum || json(schemaBytes)?.$id !== entry.id)
+                    refuse("schema_registry_identity_changed");
+            }
+            return new AdmittedFrozenEngine(manifest, bytes, entrypoint);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "frozen_engine_invalid")
+                throw error;
+            return refuse("snapshot_unavailable_or_unreadable");
+        }
+    }
+    manifest() { return structuredClone(this.#manifest); }
+    manifestBytes() { return Buffer.from(this.#bytes); }
+    /** Qualify actual descriptor handlers in this immutable executable, not the
+     * invoking CLI catalog. No storage or productive operation is admitted. */
+    admitMemoryInitFlow(source, startupInputSchema) {
+        const fail = (reason) => {
+            throw new AppError("frozen_engine_flow_incompatible", "Selected frozen engine cannot admit memory-init handlers", 1, { reason, phase: "prepare", effect: "no_effect" });
+        };
+        const revalidate = () => {
+            try {
+                if (hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) !== this.manifestSha256
+                    || engineSnapshotChecksum(this.#manifest.snapshot_root) !== this.#manifest.integrity.checksum)
+                    fail("engine_changed_during_admission");
+                // Historical checksums exclude every engine.json path, including a
+                // nested directory. New memory execution must not admit unhashed code;
+                // do not change the checksum algorithm used by existing SDLC RUNs.
+                if (fs.readdirSync(this.#manifest.snapshot_root, { recursive: true, withFileTypes: true })
+                    .some(entry => entry.name === "engine.json" && path.resolve(entry.parentPath) !== this.#manifest.snapshot_root))
+                    fail("unhashed_engine_path");
+            }
+            catch (error) {
+                if (error instanceof AppError && error.code === "frozen_engine_flow_incompatible")
+                    throw error;
+                fail("engine_unavailable_during_admission");
+            }
+        };
+        if (startupInputSchema !== undefined && !memoryInitStartupInputSchemas.includes(startupInputSchema))
+            fail("unsupported_startup_input_schema");
+        const input = Buffer.from(JSON.stringify({ source: source.snapshot(), source_sha256: source.sha256,
+            ...(startupInputSchema === undefined ? {} : { startup_input_schema: startupInputSchema }) }));
+        if (input.length > 64 * 1024 * 1024)
+            fail("unbounded_source");
+        const expected = { schema_id: startupInputSchema === undefined ? "dd-flow/memory-init-engine-flow@1" : "dd-flow/memory-init-engine-flow@2",
+            ...(startupInputSchema === undefined ? {} : { startup_input_schema: startupInputSchema }),
+            flow_id: "mb-init", source_sha256: source.sha256,
+            descriptor_sha256: source.descriptorReference().sha256, stages: source.resolveRegisteredFlow().descriptor.stages.map(stage => stage.id) };
+        revalidate();
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key) && !key.startsWith("DD_FLOW_")));
+        const result = spawnSync(this.nodeExecutable, [this.entrypoint, "runtime", "flow", "admit", "--operation", "memory-init", "--json"], { input, cwd: this.#manifest.snapshot_root, env: { ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root },
+            timeout: 15000, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            fail("selected_engine_probe_failed");
+        revalidate();
+        let response;
+        try {
+            response = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.stdout));
+        }
+        catch {
+            return fail("invalid_probe_json");
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response) || Object.keys(response).sort().join() !== "action,facts,ok,sha256"
+            || response.ok !== true || response.action !== "runtime_flow_admit" || !response.facts || typeof response.facts !== "object" || Array.isArray(response.facts)
+            || hybridDigest(response.facts) !== hybridDigest(expected)
+            || response.sha256 !== hybridDigest(expected))
+            fail("invalid_probe_response");
+        return { facts: structuredClone(expected), sha256: hybridDigest(expected), engine_manifest_sha256: this.manifestSha256,
+            engine_sha256: this.#manifest.integrity.checksum };
+    }
+    /** Execute admission in the selected immutable engine, never in the invoking CLI.
+     * This qualifies storage connections only, not provider or flow readiness.
+     */
+    admitMemoryInitStorage(home, resourceHome) {
+        for (const root of [home, resourceHome]) {
+            if (!path.isAbsolute(root) || path.resolve(root) !== root || fs.realpathSync(root) !== root)
+                storageProbeRefuse("noncanonical_storage_home");
+        }
+        const revalidateEngine = () => {
+            if (hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) !== this.manifestSha256
+                || engineSnapshotChecksum(this.#manifest.snapshot_root) !== this.#manifest.integrity.checksum)
+                storageProbeRefuse("engine_changed_during_admission");
+        };
+        revalidateEngine();
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key)));
+        const result = spawnSync(this.nodeExecutable, [this.entrypoint, "runtime", "storage", "admit", "--operation", "memory-init", "--json"], { env: { ...env, DD_FLOW_HOME: home, DD_FLOW_RESOURCE_HOME: resourceHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root },
+            timeout: 15000, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            storageProbeRefuse("selected_engine_probe_failed");
+        revalidateEngine();
+        let response;
+        try {
+            response = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.stdout));
+        }
+        catch {
+            return storageProbeRefuse("invalid_probe_json");
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response) || Object.keys(response).sort().join() !== "action,facts,ok,sha256"
+            || response.ok !== true || response.action !== "runtime_storage_admit")
+            storageProbeRefuse("invalid_probe_response");
+        const facts = response.facts, run = facts?.run;
+        if (!facts || Object.keys(facts).sort().join() !== "operation,outcome,resource,route,run,schema_id"
+            || facts.schema_id !== "dd-flow/memory-init-engine-storage@1" || facts.operation !== "memory-init"
+            || facts.route !== "verified-no-op" || facts.outcome !== "no-op" || response.sha256 !== hybridDigest(facts)
+            || !isMemoryInitResourceStorageFacts(facts.resource) || facts.resource.store_path !== path.join(resourceHome, "runtime.sqlite")
+            || !run || Object.keys(run).sort().join() !== "executing_writer_version,operation,outcome,route,schema_id,schema_sha256,store_dev,store_ino,store_kind,store_path"
+            || run.schema_id !== "dd-flow/memory-init-runtime-storage@1" || run.operation !== "memory-init" || run.store_kind !== "run"
+            || run.store_path !== path.join(home, "db.sqlite") || run.route !== "verified-no-op" || run.outcome !== "no-op"
+            || run.executing_writer_version !== 2 || typeof run.schema_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(run.schema_sha256))
+            storageProbeRefuse("invalid_probe_facts");
+        for (const store of [run, facts.resource]) {
+            const stat = fs.lstatSync(store.store_path);
+            if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== store.store_dev || stat.ino !== store.store_ino)
+                storageProbeRefuse("storage_identity_changed");
+        }
+        return { facts: structuredClone(facts), sha256: response.sha256, engine_manifest_sha256: this.manifestSha256,
+            engine_sha256: this.#manifest.integrity.checksum };
+    }
+    /** Read an exact registered schema from this snapshot, never the mutable CLI. */
+    schema(name) {
+        try {
+            if (!fs.lstatSync(this.#manifest.snapshot_root).isDirectory())
+                refuse("missing_or_linked_snapshot");
+            const entry = this.#manifest.schema_registry?.entries.find(item => item.name === name);
+            if (!entry)
+                refuse("schema_not_registered");
+            const bytes = readBoundedReleaseFile(containedFile(this.#manifest.snapshot_root, entry.path), 1024 * 1024);
+            if (hash(bytes) !== entry.checksum || json(bytes).$id !== entry.id)
+                refuse("schema_registry_identity_changed");
+            return Buffer.from(bytes);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "frozen_engine_invalid")
+                throw error;
+            return refuse("schema_unavailable");
+        }
+    }
+    /** No PATH/dd-flow fallback or mutable launcher environment reference. */
+    command(home, args) {
+        if (!path.isAbsolute(home))
+            refuse("runtime_home_not_absolute");
+        return `DD_FLOW_HOME=${shellArgument(home)} DD_FLOW_ENGINE_MODE=1 DD_FLOW_ENGINE_HOME=${shellArgument(this.#manifest.snapshot_root)} ${[this.nodeExecutable, this.entrypoint, ...args].map(shellArgument).join(" ")}`;
+    }
+}

package/dist/services/generic-execution.js

@@ -0,0 +1,164 @@
+import { AppError } from "../shared/errors.js";
+import { sameSessionProfile } from "./execution-policy.js";
+import { hybridDigest, validateHybridContract } from "./hybrid-contracts.js";
+import { prepareOperatorProfile, resolveOperatorProfile } from "./operator-profiles.js";
+function fail(message, issues) {
+    throw new AppError("generic_execution_invalid", message, 2, { phase: "prepare", effect: "no_effect", ...(issues ? { issues } : {}) });
+}
+function freeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+}
+function scopedReceipts(settings, scope, receipts) {
+    for (const [reference, kind] of [
+        [settings.attached_session_receipt, "attached-session-binding"],
+        [settings.delegation.native_capacity_receipt, "native-capacity"]
+    ]) {
+        if (reference === null)
+            continue;
+        const fact = receipts.get(reference.sha256);
+        if (!fact || fact.kind !== kind || fact.requestId !== scope.requestId
+            || fact.projectRoot !== scope.projectRoot || fact.workspace !== scope.workspace) {
+            fail("Execution receipt does not belong to the selected request and workspace");
+        }
+    }
+}
+function validateSnapshot(snapshot, flow, scope, receipts) {
+    if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)
+        || Object.keys(snapshot).some(key => !["schema_id", "scope", "settings", "profiles"].includes(key))
+        || ["schema_id", "scope", "settings", "profiles"].some(key => !Object.hasOwn(snapshot, key))
+        || snapshot.schema_id !== "dd-flow/frozen-execution@1"
+        || !snapshot.scope || typeof snapshot.scope !== "object" || Array.isArray(snapshot.scope)
+        || !scope || [scope.requestId, scope.projectRoot, scope.workspace].some(value => typeof value !== "string" || !value.trim())
+        || hybridDigest(snapshot.scope) !== hybridDigest(scope))
+        fail("Invalid frozen execution identity");
+    const content = { schema_id: "dd-flow/profile-settings@1", profiles: snapshot.profiles, aliases: {}, default_profile: null };
+    const profiles = { ...content, revision: hybridDigest(content) };
+    const issues = validateHybridContract("execution-settings", snapshot.settings, {
+        descriptor: flow.descriptor, descriptorSha256: flow.sha256, profileSettings: profiles, receipts
+    });
+    if (issues.length)
+        fail("Frozen execution violates the admitted descriptor or profile policy", issues);
+    const settings = snapshot.settings;
+    if (snapshot.profiles.length !== settings.profiles.length
+        || snapshot.profiles.some(profile => !settings.profiles.some(reference => reference.id === profile.id && reference.revision === profile.revision))) {
+        fail("Frozen profile bytes and revision inventory differ");
+    }
+    for (const stage of flow.descriptor.stages) {
+        if (!Object.hasOwn(settings.stage_profiles, stage.id))
+            fail("Every declared stage must have an explicit frozen route");
+    }
+    scopedReceipts(settings, scope, receipts);
+}
+/** Separate from SDLC settings: no plan review, merge, bootstrap command or stop target. */
+export class FrozenGenericExecution {
+    sha256;
+    settings;
+    #snapshot;
+    #flow;
+    constructor(snapshot, flow) {
+        freeze(snapshot);
+        this.#snapshot = snapshot;
+        this.#flow = flow;
+        this.settings = snapshot.settings;
+        this.sha256 = hybridDigest(snapshot);
+        Object.freeze(this);
+    }
+    /** Pure selection from one admitted operator snapshot; never reread it during a RUN. */
+    static prepare(flow, operatorSettings, selection, scope, receipts = new Map()) {
+        const issues = validateHybridContract("profile-settings", operatorSettings);
+        if (issues.length)
+            fail("Operator profiles cannot be frozen", issues);
+        if (!selection || typeof selection !== "object" || Array.isArray(selection)
+            || Object.keys(selection).some(key => !["rootProfile", "stageProfiles", "workProfiles", "execution", "stageSessionMode", "attachedSessionReceipt", "delegation"].includes(key))) {
+            fail("Unsupported execution selection");
+        }
+        if (!["mb-init", "mb-upgrade"].includes(flow.descriptor.id)
+            && (selection.execution === undefined || selection.stageSessionMode === undefined || selection.delegation === undefined)) {
+            fail("Non-memory flows must supply their own execution defaults explicitly");
+        }
+        let rootSelection = selection.rootProfile;
+        if (rootSelection !== undefined && typeof rootSelection !== "string") {
+            const profile = prepareOperatorProfile(rootSelection);
+            const existing = operatorSettings.profiles.find(entry => entry.id === profile.id);
+            if (Object.hasOwn(operatorSettings.aliases, profile.id) || existing && existing.revision !== hybridDigest(profile))
+                fail("Operation-only profile conflicts with an existing ID or alias");
+            const { revision: _revision, ...content } = structuredClone(operatorSettings);
+            void _revision;
+            if (!existing)
+                content.profiles.push({ id: profile.id, revision: hybridDigest(profile), profile });
+            operatorSettings = { ...content, revision: hybridDigest(content) };
+            rootSelection = profile.id;
+        }
+        const profiles = new Map();
+        const resolve = (id) => {
+            const profile = prepareOperatorProfile(resolveOperatorProfile(operatorSettings, id));
+            profiles.set(profile.id, { id: profile.id, revision: hybridDigest(profile), profile });
+            return profile.id;
+        };
+        const root = resolve(rootSelection);
+        const stages = Object.create(null);
+        if (selection.stageProfiles !== undefined && (!selection.stageProfiles || typeof selection.stageProfiles !== "object" || Array.isArray(selection.stageProfiles))) {
+            fail("Stage profile selection must be an object");
+        }
+        for (const id of Object.keys(selection.stageProfiles ?? {}))
+            flow.stage(id);
+        for (const stage of flow.descriptor.stages) {
+            const selected = selection.stageProfiles && Object.hasOwn(selection.stageProfiles, stage.id) ? selection.stageProfiles[stage.id] : undefined;
+            if (selected !== undefined && typeof selected !== "string")
+                fail("Stage profile selection must name a profile");
+            stages[stage.id] = selected === undefined ? root : resolve(selected);
+        }
+        if (selection.workProfiles !== undefined && (!Array.isArray(selection.workProfiles) || selection.workProfiles.some(id => typeof id !== "string"))) {
+            fail("Approved Work profiles must be a list of profile IDs");
+        }
+        const works = [...new Set((selection.workProfiles ?? []).map(id => resolve(id)))];
+        const delegation = selection.delegation;
+        if (delegation !== undefined && (!delegation || typeof delegation !== "object" || Array.isArray(delegation)
+            || Object.keys(delegation).some(key => !["mode", "max_parallel", "nativeCapacityReceipt"].includes(key))))
+            fail("Unsupported delegation selection");
+        const settings = {
+            schema_id: "dd-flow/execution-settings@1", flow_id: flow.descriptor.id, descriptor_sha256: flow.sha256,
+            execution: selection.execution ?? "managed", attached_session_receipt: selection.attachedSessionReceipt ?? null,
+            stage_session_mode: selection.stageSessionMode ?? "new_session",
+            delegation: { mode: delegation?.mode ?? "external", max_parallel: delegation?.max_parallel ?? 1, native_capacity_receipt: delegation?.nativeCapacityReceipt ?? null },
+            profiles: [...profiles.values()].map(({ id, revision }) => ({ id, revision })), root_profile: root,
+            stage_profiles: stages, work_profiles: works
+        };
+        const snapshot = structuredClone({ schema_id: "dd-flow/frozen-execution@1", scope, settings, profiles: [...profiles.values()] });
+        validateSnapshot(snapshot, flow, scope, receipts);
+        return new FrozenGenericExecution(snapshot, flow);
+    }
+    /** Admission uses retained bytes and trusted scope/receipts, never the current operator settings. */
+    static restore(snapshot, expectedSha256, flow, scope, receipts = new Map()) {
+        if (!/^[a-f0-9]{64}$/.test(expectedSha256) || hybridDigest(snapshot) !== expectedSha256)
+            fail("Frozen execution identity changed");
+        const retained = structuredClone(snapshot);
+        validateSnapshot(retained, flow, scope, receipts);
+        return new FrozenGenericExecution(retained, flow);
+    }
+    snapshot() { return structuredClone(this.#snapshot); }
+    stage(id) {
+        this.#flow.stage(id);
+        return { profile: this.profile(this.settings.stage_profiles[id]), session_mode: this.settings.stage_session_mode };
+    }
+    work(stage, profileId) {
+        const coordinator = this.stage(stage).profile;
+        const id = profileId ?? coordinator.id;
+        if (id !== coordinator.id && !this.settings.work_profiles.includes(id))
+            fail("Work profile is not approved for this RUN");
+        const worker = this.profile(id);
+        if (this.settings.delegation.mode === "native" && !sameSessionProfile(coordinator, worker))
+            fail("Native Work cannot change execution profile");
+        return { coordinator, worker, delegation: structuredClone(this.settings.delegation) };
+    }
+    profile(id) {
+        const value = this.#snapshot.profiles.find(entry => entry.id === id);
+        if (!value)
+            fail("Profile is absent from the frozen execution inventory");
+        return structuredClone(value.profile);
+    }
+}

package/dist/services/harness-adapter.js

@@ -10,9 +10,35 @@ import { canonicalNativeOperation, nativeOperationWait } from "../harness-runtim
 import { readOperationProgress, readOperationRecord, readOperationWaiting, suspendOperationClock } from "../harness-runtime/lib/operation-progress.mjs";
 import { recoverDaemonReply } from "../harness-runtime/lib/daemon-observation.mjs";
 import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
+import { readBoundedReleaseFile } from "./release-source.js";
 const maxAdapterOutputBytes = 1_000_000;
 /** Native hooks need a real executable, not a PATH-dependent shell expression. */
-export function prepareHarnessFlowExecutable(context, stateDir) {
+export function prepareHarnessFlowExecutable(context, stateDir, engine) {
+    // Native login shells rewrite search paths. The owned SDK must execute with
+    // the same original paths as its controller, not merely hash them as equal.
+    const searchPaths = ["PATH", "FPATH", "INFOPATH"].map(name => context.env[name] === undefined
+        ? `delete process.env.${name};\n` : `process.env.${name} = ${JSON.stringify(context.env[name])};\n`).join("");
+    if (engine) {
+        const executable = path.join(stateDir, "dd-flow");
+        const contents = `#!${engine.nodeExecutable}\n${searchPaths}process.env.DD_FLOW_HOME = ${JSON.stringify(context.ddFlowHome)};\nprocess.env.DD_FLOW_ENGINE_MODE = "1";\nprocess.env.DD_FLOW_ENGINE_HOME = ${JSON.stringify(engine.manifest().snapshot_root)};\nconst { spawnSync } = await import("node:child_process");\nconst child = spawnSync(${JSON.stringify(engine.nodeExecutable)}, [${JSON.stringify(engine.entrypoint)}, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });\nif (child.error) throw child.error;\nif (child.signal) process.kill(process.pid, child.signal);\nprocess.exit(child.status ?? 1);\n`;
+        try {
+            fs.writeFileSync(executable, contents, { flag: "wx", mode: 0o700 });
+        }
+        catch (error) {
+            const conflict = () => new AppError("harness_runtime_binding_conflict", "Launch runtime executable already has different or linked content", 1, { path: executable });
+            if (error.code !== "EEXIST")
+                throw conflict();
+            try {
+                const stat = fs.lstatSync(executable);
+                if (!stat.isFile() || stat.nlink !== 1 || readBoundedReleaseFile(executable, 64 * 1024).toString("utf8") !== contents)
+                    throw conflict();
+            }
+            catch {
+                throw conflict();
+            }
+        }
+        return executable;
+    }
     const configured = context.env.DD_FLOW_BIN;
     if (configured !== undefined) {
         if (!path.isAbsolute(configured) || !fs.existsSync(configured))
@@ -32,7 +58,7 @@ export function prepareHarnessFlowExecutable(context, stateDir) {
     const dispatch = configured
         ? `const { spawnSync } = await import("node:child_process");\nconst child = spawnSync(${JSON.stringify(configured)}, process.argv.slice(2), { stdio: "inherit", env: process.env });\nif (child.error) throw child.error;\nif (child.signal) process.kill(process.pid, child.signal);\nprocess.exit(child.status ?? 1);\n`
         : `await import(${JSON.stringify(pathToFileURL(entry).href)});\n`;
-    const contents = `#!${process.execPath}\nprocess.env.DD_FLOW_HOME = ${JSON.stringify(context.ddFlowHome)};\n${dispatch}`;
+    const contents = `#!${process.execPath}\n${searchPaths}process.env.DD_FLOW_HOME = ${JSON.stringify(context.ddFlowHome)};\n${dispatch}`;
     try {
         fs.writeFileSync(executable, contents, { flag: "wx", mode: 0o700 });
     }

package/dist/services/harness-discovery.js

@@ -0,0 +1,29 @@
+import { randomUUID } from "node:crypto";
+import { validateHybridContract } from "./hybrid-contracts.js";
+import { AppError } from "../shared/errors.js";
+import { discoverCodex } from "./discovery/codex-discovery.js";
+import { discoverZcode } from "./discovery/zcode-discovery.js";
+import { discoverAgy } from "./discovery/agy-discovery.js";
+import { discoverOpenCode } from "./discovery/opencode-discovery.js";
+import { discoverGrok } from "./discovery/grok-discovery.js";
+import { discoverDroid } from "./discovery/droid-discovery.js";
+import { readOnlyProbeScope, runScopedProbe, staticDiscoveryEffects } from "./harness-probe-effects.js";
+const modules = { codex: discoverCodex, zcode: discoverZcode, agy: discoverAgy, opencode: discoverOpenCode, grok: discoverGrok, droid: discoverDroid };
+export const harnessCatalog = {
+    schema_id: "dd-flow/harness-catalog@1", version: "1.0.0",
+    entries: Object.keys(modules).map(id => ({ id, executable_candidates: [id], probe_module: `${id}-discovery`,
+        probe_timeout_ms: 3000, version_range: "unknown_requires_review", protocol_version: "unknown_requires_protocol_probe" }))
+};
+export function discoverHarnesses(input) {
+    if (input.harness && !Object.hasOwn(modules, input.harness))
+        throw new AppError("usage", "Unknown harness family", 2, { effect: "no_effect" });
+    if (input.executable && !input.harness)
+        throw new AppError("usage", "Explicit executable requires one harness family", 2, { effect: "no_effect" });
+    const families = input.harness ? [input.harness] : Object.keys(modules);
+    const result = { schema_id: "dd-flow/discovery-result@1", request_id: input.requestId ?? randomUUID(), observed_at: new Date().toISOString(),
+        probe_scope: "static", live_authorization_receipt: null, entries: families.map(family => runScopedProbe(staticDiscoveryEffects, readOnlyProbeScope, () => modules[family](input))) };
+    if (validateHybridContract("harness-catalog", harnessCatalog).length || validateHybridContract("discovery-result", result).length) {
+        throw new AppError("discovery_contract", "Discovery owner produced invalid facts", 1, { effect: "no_effect" });
+    }
+    return result;
+}

package/dist/services/harness-doctor.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "semver";
+import { AppError } from "../shared/errors.js";
+import { legacyDoctorEffects, runScopedProbe } from "./harness-probe-effects.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { discoverExecutable } from "./discovery/static.js";
+const binOptions = {
+    codex: "codex-bin", zcode: "zcode-acp-bin", agy: "agy-bin", opencode: "opencode-bin", grok: "grok-bin", droid: "droid-bin"
+};
+function refuse(code, message, exitCode = 1) {
+    throw new AppError(code, message, exitCode, { phase: "harness_doctor", help: "harnesses doctor" });
+}
+/** Existing non-generative adapter doctor, bounded by its owner transport.
+ * Reported compatibility is not qualification or verified account access.
+ * OpenCode observes an explicitly bound existing daemon; it never starts one.
+ */
+export async function probeHarnessDoctor(input) {
+    const timeoutMs = input.timeoutMs ?? 30_000;
+    if (!Object.hasOwn(binOptions, input.harness) || !path.isAbsolute(input.executable)
+        || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000
+        || input.stateDir !== undefined && !path.isAbsolute(input.stateDir)
+        || input.nativeExecutable !== undefined && (!path.isAbsolute(input.nativeExecutable) || input.harness !== "zcode")
+        || input.stateDir !== undefined && input.harness !== "opencode")
+        refuse("usage", "Doctor requires explicit contained diagnostic inputs", 2);
+    return runScopedProbe(legacyDoctorEffects[input.harness], input.scope, async () => {
+        if (input.harness === "droid" && discoverExecutable("system-ps", ["ps"], { env: { ...process.env, ...input.env } }).candidates.length === 0) {
+            throw new AppError("doctor_prerequisite_missing", "Droid doctor requires the OS ps utility for physical process settlement", 1, { phase: "harness_doctor", effect: "no_effect", prerequisite: "ps", help: "harnesses doctor" });
+        }
+        const args = [fileURLToPath(new URL(`../harness-runtime/bin/dd-${input.harness}.mjs`, import.meta.url)), "doctor",
+            `--${binOptions[input.harness]}`, input.executable, "--timeout-ms", String(timeoutMs), "--json"];
+        if (input.harness === "zcode") {
+            if (!input.nativeExecutable)
+                refuse("harness_selection_required", "ZCode doctor also requires --native-executable for its native runtime");
+            args.push("--zcode-path", input.nativeExecutable);
+        }
+        if (input.harness === "opencode") {
+            if (!input.stateDir)
+                refuse("harness_selection_required", "OpenCode doctor requires --state-dir for an existing owned daemon; no service is started");
+            let state;
+            try {
+                state = JSON.parse(readBoundedReleaseFile(path.join(input.stateDir, "daemon.json"), 1024 * 1024).toString("utf8"));
+            }
+            catch {
+                return refuse("doctor_state_unavailable", "Selected daemon identity cannot be read");
+            }
+            const selected = state;
+            if (selected?.config?.bin !== input.executable)
+                refuse("doctor_state_mismatch", "Selected daemon does not bind the discovered executable");
+            args.push("--state-dir", input.stateDir);
+        }
+        const transport = await import(new URL("../harness-runtime/lib/process-json.mjs", import.meta.url).href);
+        let report;
+        try {
+            report = await transport.commandJson(process.execPath, args, { env: input.env, timeoutMs, signal: AbortSignal.timeout(timeoutMs), phase: "native-doctor" });
+        }
+        catch {
+            return refuse("harness_doctor_failed", "Adapter doctor failed or could not confirm its observation; no model Turn was requested");
+        }
+        if (!report || typeof report !== "object" || Array.isArray(report) || report.ok !== true)
+            refuse("harness_doctor_failed", "Adapter doctor did not return an accepted diagnostic");
+        const observed = report.observed_runtime && typeof report.observed_runtime === "object" ? report.observed_runtime : {};
+        const versionField = input.harness === "codex" ? "codex_cli" : input.harness === "zcode" ? "zcode_acp" : input.harness;
+        const versions = report.versions && typeof report.versions === "object" && !Array.isArray(report.versions) ? report.versions : {};
+        // Existing OpenCode doctor reports versions separately from observed_runtime.
+        const versionValue = input.harness === "opencode" ? versions.opencode : observed[versionField];
+        const version = typeof versionValue === "string" ? parse(versionValue)?.version ?? null : null;
+        const protocol = observed.dd_harness_contract;
+        const models = Array.isArray(report.models) ? report.models.filter((model) => typeof model === "string" && /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,255}$/.test(model)).slice(0, 10_000) : [];
+        return { harness: input.harness, effects: legacyDoctorEffects[input.harness], reported_version: version,
+            reported_protocol: typeof protocol === "string" && /^dd-[a-z0-9-]+@[0-9]+$/.test(protocol) ? protocol : null,
+            reported_models: [...new Set(models)].sort(), models_complete: false, reported_compatible: typeof report.compatible === "boolean" ? report.compatible : null,
+            account_access: "unknown", qualified: "unknown", model_turn: "not_requested" };
+    });
+}

package/dist/services/harness-probe-effects.js

@@ -0,0 +1,51 @@
+import { AppError } from "../shared/errors.js";
+export const readOnlyProbeScope = Object.freeze({
+    processes: false, services: false, credentials: false, writes: false
+});
+/** Source-grounded effects of existing adapters; this is not permission to invoke them. */
+export const legacyDoctorEffects = {
+    codex: { child_process: true, service_process: true, credential_access: "possible", filesystem: "temporary_or_runtime_writes", model_turn: "not_requested", source_owner: "harness-runtime/lib/dd-codex.mjs:doctor/withBridge" },
+    zcode: { child_process: true, service_process: false, credential_access: "possible", filesystem: "read_only", model_turn: "not_requested", source_owner: "harness-runtime/lib/dd-zcode.mjs:doctor" },
+    agy: { child_process: true, service_process: false, credential_access: "possible", filesystem: "temporary_or_runtime_writes", model_turn: "not_requested", source_owner: "harness-runtime/lib/dd-agy.mjs:doctor" },
+    opencode: { child_process: true, service_process: true, credential_access: "possible", filesystem: "temporary_or_runtime_writes", model_turn: "not_requested", source_owner: "harness-runtime/lib/dd-opencode-daemon.mjs:daemon.doctor/startDaemon" },
+    grok: { child_process: true, service_process: false, credential_access: "possible", filesystem: "read_only", model_turn: "not_requested", source_owner: "harness-runtime/lib/dd-grok.mjs:doctor" },
+    droid: { child_process: true, service_process: true, credential_access: "possible", filesystem: "temporary_or_runtime_writes", model_turn: "not_requested", source_owner: "harness-runtime/lib/dd-droid-daemon.mjs:runtime.start" }
+};
+for (const effects of Object.values(legacyDoctorEffects))
+    Object.freeze(effects);
+Object.freeze(legacyDoctorEffects);
+export const staticDiscoveryEffects = Object.freeze({
+    child_process: false, service_process: false, credential_access: "none", filesystem: "read_only", model_turn: "not_requested",
+    source_owner: "services/discovery/static.ts:discoverExecutable"
+});
+/** Enforce effect ceilings before invoking a probe. A non-generative label alone is insufficient. */
+export function assertProbeWithinScope(effects, scope) {
+    const scopeKeys = ["processes", "services", "credentials", "writes"];
+    const effectKeys = ["child_process", "service_process", "credential_access", "filesystem", "model_turn", "source_owner"];
+    if (!scope || typeof scope !== "object" || Array.isArray(scope)
+        || Object.keys(scope).some(key => !scopeKeys.includes(key))
+        || scopeKeys.some(key => !Object.hasOwn(scope, key) || typeof scope[key] !== "boolean")
+        || !effects || typeof effects !== "object" || Array.isArray(effects)
+        || effectKeys.some(key => !Object.hasOwn(effects, key)) || Object.keys(effects).some(key => !effectKeys.includes(key))
+        || typeof effects.child_process !== "boolean" || typeof effects.service_process !== "boolean"
+        || !["none", "possible"].includes(effects.credential_access)
+        || !["read_only", "temporary_or_runtime_writes"].includes(effects.filesystem)
+        || !["not_requested", "possible"].includes(effects.model_turn)
+        || typeof effects.source_owner !== "string" || !effects.source_owner.trim()) {
+        throw new AppError("probe_scope_invalid", "Probe effects and permissions require an explicit typed scope", 2, { phase: "probe_admission", effect: "no_effect", help: "harnesses" });
+    }
+    const blocked = [
+        effects.child_process && !scope.processes ? "child_process" : null,
+        effects.service_process && !scope.services ? "service_process" : null,
+        effects.credential_access !== "none" && !scope.credentials ? "credential_access" : null,
+        effects.filesystem !== "read_only" && !scope.writes ? "filesystem_writes" : null,
+        effects.model_turn !== "not_requested" ? "live_authorization_required" : null
+    ].filter(Boolean);
+    if (blocked.length)
+        throw new AppError("probe_effects_not_authorized", "Probe exceeds the selected effect scope", 1, { phase: "probe_admission", effect: "no_effect", blocked_effects: blocked, help: "harnesses" });
+}
+/** The callback is not entered, including synchronous effects, until admission succeeds. */
+export function runScopedProbe(effects, scope, probe) {
+    assertProbeWithinScope(effects, scope);
+    return probe();
+}