@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

package/dist/services/harness-adapter.js

@@ -1,59 +1,366 @@
 import { spawn } from "node:child_process";
-import { AppError } from "../shared/errors.js";
-/** Runs one harness command with the lifecycle guarantees shared by agent services. */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { stopProcessGroup } from "../harness-runtime/lib/managed-daemon.mjs";
+import { recoveryObservationBudget, recoveryRpcTimeout, withRecoveryObservation } from "./recovery-observation-budget.js";
+import { ObservationClock, validateObservationDuration } from "../harness-runtime/lib/observation-clock.mjs";
+import { canonicalNativeOperation, nativeOperationWait } from "../harness-runtime/lib/adapter-timeouts.mjs";
+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";
+/** Native hooks need a real executable, not a PATH-dependent shell expression. */
+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))
+            throw new AppError("harness_runtime_missing", "DD_FLOW_BIN must identify an existing absolute executable", 2);
+        if (path.basename(configured) === "dd-flow")
+            return configured;
+    }
+    const isolated = path.join(context.ddFlowHome, "bin", "dd-flow");
+    if (!configured && fs.existsSync(isolated))
+        return isolated;
+    const entry = fileURLToPath(new URL("../cli.js", import.meta.url));
+    if (!configured && !fs.existsSync(entry))
+        throw new AppError("harness_runtime_unbuilt", "Build the CLI or supply its pinned DD_FLOW_BIN before launching a harness", 1);
+    // The trusted lifecycle parser recognizes this basename, including for a
+    // custom pinned executable. Do not broaden that parser to arbitrary scripts.
+    const executable = path.join(stateDir, "dd-flow");
+    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}\n${searchPaths}process.env.DD_FLOW_HOME = ${JSON.stringify(context.ddFlowHome)};\n${dispatch}`;
+    try {
+        fs.writeFileSync(executable, contents, { flag: "wx", mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST" || fs.readFileSync(executable, "utf8") !== contents)
+            throw new AppError("harness_runtime_binding_conflict", "Launch runtime executable already has different content", 1, { path: executable });
+    }
+    return executable;
+}
 export function runHarnessAdapter(input) {
-    const timeoutMs = input.timeoutMs ?? 120_000;
+    const index = input.args.indexOf("--state-dir"), stateDir = index >= 0 ? input.args[index + 1] : undefined;
+    const operation = canonicalNativeOperation(input.harness ?? "", `${input.args[0]}.${input.args[1]}`);
+    const boundOperation = ["session.create", "session.fork", "session.start", "session.resume"].includes(operation);
+    const binding = { operation, ...(input.runtimeOwner ? { owner_id: input.runtimeOwner.owner_id } : {}) };
+    let retainedOutcome;
+    const onOutcome = (value) => {
+        const fingerprint = JSON.stringify(value);
+        if (fingerprint !== retainedOutcome) {
+            input.onNativeOutcome?.(value);
+            retainedOutcome = fingerprint;
+        }
+    };
+    const dispatched = runAdapterTransport(input, stateDir, binding);
+    return dispatched.catch(async (error) => {
+        if (!stateDir || !boundOperation || input.signal?.aborted || !(isObservationLoss(error) || isObservationLoss(error?.details?.cause)))
+            throw error;
+        try {
+            return await recoverDaemonReply(stateDir, input.operationId, { timeoutMs: recoveryRpcTimeout(30_000), ...(input.signal ? { signal: input.signal } : {}), ...(error?.observationClock ? { observationClock: error.observationClock } : {}), binding, onOutcome,
+                // Reconcile only original bookkeeping. Work/MERGE share this path and
+                // must not replay creation merely because its release receipt is pending.
+                onPendingSettlement: async (retained) => {
+                    input.signal?.throwIfAborted();
+                    await withRecoveryObservation(recoveryObservationBudget(retained), () => runAdapterTransport({ ...input, args: ["daemon", "operation", "settle", "--state-dir", stateDir, "--operation-id", input.operationId, "--json"], operationId: `${input.operationId}:settlement`, timeoutMs: recoveryRpcTimeout(30_000) }, stateDir, {}), true);
+                }
+            });
+        }
+        catch (recovery) {
+            if (recovery && typeof recovery === "object")
+                Object.assign(recovery, { cause: error });
+            throw recovery;
+        }
+    });
+}
+function runAdapterTransport(input, stateDir, binding = {}) {
+    // `null` is deliberate: a productive Turn has no adapter-wall-clock limit.
+    // Preserve it instead of treating it like an omitted short control request.
+    if (input.timeoutMs != null)
+        validateObservationDuration(input.timeoutMs);
+    const operation = canonicalNativeOperation(input.harness ?? "", `${input.args[0]}.${input.args[1]}`);
+    const productive = input.harness !== undefined && nativeOperationWait(input.harness, operation) === "native-work";
+    const timeoutMs = recoveryRpcTimeout(productive ? null : input.timeoutMs === undefined ? 120_000 : input.timeoutMs);
+    if (timeoutMs !== null)
+        validateObservationDuration(timeoutMs);
+    if (!input.operationId.trim())
+        throw new AppError("operation_id_required", "Harness calls require a scoped operation id", 2);
+    // The current adapter transport uses this name; its identity is runtime-owned,
+    // never the operation or trusted daemon identity of the calling coordinator.
+    const env = { ...input.env, DD_EVAL_OPERATION_ID: input.operationId };
+    delete env.DD_FLOW_DAEMON_ID;
+    delete env.DD_FLOW_SCOPE_CONTROL_TOKEN;
+    delete env.DD_FLOW_RUNTIME_OWNER;
+    if (input.runtimeOwner) {
+        if (!path.isAbsolute(input.executable) || input.runtimeOwner.adapter_executable !== undefined && input.runtimeOwner.adapter_executable !== input.executable)
+            throw new AppError("harness_runtime_binding_conflict", "Owned harness call must use its frozen absolute adapter executable", 1);
+        env.DD_FLOW_RUNTIME_OWNER = JSON.stringify({ ...input.runtimeOwner, adapter_executable: input.executable });
+    }
     return new Promise((resolve, reject) => {
+        if (input.signal?.aborted)
+            return reject(new AppError("harness_adapter_aborted", "Harness adapter call was cancelled before dispatch", 1));
         const detached = process.platform !== "win32";
-        const child = spawn(input.executable, input.args, { env: input.env, detached, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn(input.executable, input.args, { env, ...(input.cwd ? { cwd: input.cwd } : {}), detached, stdio: ["ignore", "pipe", "pipe"] });
         let stdout = "";
         let stderr = "";
         let timedOut = false;
-        let killTimer;
-        const terminate = (signal) => { try {
-            if (detached && child.pid)
-                process.kill(-child.pid, signal);
-            else
-                child.kill(signal);
-        }
-        catch { /* The process already settled. */ } };
-        const heartbeat = input.progress && input.progressMessage ? setInterval(() => input.progress?.(`${input.progressMessage}; waiting for adapter completion`), 15_000) : undefined;
-        const timer = setTimeout(() => { timedOut = true; terminate("SIGTERM"); killTimer = setTimeout(() => terminate("SIGKILL"), 5_000); }, timeoutMs);
-        const evidence = (value) => input.onEvidence?.({ executable: input.executable, args: input.args, ...value, at: new Date().toISOString() });
+        let aborted = false;
+        let cleanup;
+        let pendingDiagnostic = "", droppingDiagnostic = false, progressCursor = 0;
+        let prettyDiagnostic = "", retainedError;
+        const phases = new Set();
+        let operationSequence = 0;
+        let diagnosticReads = Promise.resolve();
+        const clock = timeoutMs === null ? null : new ObservationClock({ timeoutMs });
+        clock?.sample(progressCursor);
+        let settled = false;
+        let callbackError;
+        let spawnError;
+        const stopTransport = () => {
+            cleanup ??= stopProcessGroup(child, 5_000, { detached }).catch(error => {
+                if (timer)
+                    clearInterval(timer);
+                if (heartbeat)
+                    clearInterval(heartbeat);
+                input.signal?.removeEventListener("abort", abort);
+                const details = { cleanup_error: errorRecord(error) };
+                if (callbackError instanceof Error) {
+                    Object.assign(callbackError, { cleanup_error: details.cleanup_error, details: { ...callbackError.details, ...details } });
+                    reject(callbackError);
+                }
+                else
+                    reject(new AppError(timedOut ? "harness_adapter_timeout" : aborted ? "harness_adapter_aborted" : "harness_adapter_cleanup_unconfirmed", "Adapter transport cleanup could not be confirmed", 1, details));
+            });
+        };
+        const deliver = (callback) => {
+            try {
+                const result = callback();
+                if (result && typeof result.then === "function") {
+                    void Promise.resolve(result).catch(() => { });
+                    throw new AppError("progress_callback_async", "Harness callbacks must be synchronous", 1);
+                }
+            }
+            catch (error) {
+                callbackError ??= error;
+                if (!settled)
+                    stopTransport();
+            }
+        };
+        const heartbeat = input.progress && input.progressMessage ? setInterval(() => deliver(() => input.progress?.(`${input.progressMessage}; waiting for adapter completion`)), 15_000) : undefined;
+        let observing = false;
+        const timer = timeoutMs === null ? undefined : setInterval(async () => {
+            if (settled || cleanup)
+                return;
+            if (observing)
+                return;
+            observing = true;
+            // Helper phase progress must never replenish its owner's independent
+            // physical-settlement episode. ALS retains that existing budget here.
+            try {
+                recoveryRpcTimeout(timeoutMs);
+            }
+            catch (error) {
+                callbackError ??= error;
+                stopTransport();
+                observing = false;
+                return;
+            }
+            try {
+                const waiting = stateDir && await readOperationWaiting(stateDir, input.operationId, binding);
+                if (settled || cleanup)
+                    return;
+                if (waiting)
+                    suspendOperationClock(clock);
+                else if (clock.sample(progressCursor)) {
+                    timedOut = true;
+                    stopTransport();
+                }
+            }
+            catch (error) {
+                callbackError ??= error;
+                stopTransport();
+            }
+            finally {
+                observing = false;
+            }
+        }, Math.max(1, Math.min(1000, timeoutMs / 4)));
+        const abort = () => { aborted = true; stopTransport(); };
+        if (input.signal?.aborted)
+            abort();
+        else
+            input.signal?.addEventListener("abort", abort, { once: true });
+        const evidence = (value) => input.onEvidence?.({ operation_id: input.operationId, executable: input.executable, args: input.args, ...value, at: new Date().toISOString() });
+        const observeDiagnostic = (line) => {
+            if (prettyDiagnostic === null) {
+                if (line.trimEnd() === "}")
+                    prettyDiagnostic = "";
+                return;
+            }
+            const candidate = prettyDiagnostic ? `${prettyDiagnostic}\n${line}` : line;
+            if (candidate.length > 64_000) {
+                prettyDiagnostic = null;
+                return;
+            }
+            let value;
+            try {
+                value = JSON.parse(candidate);
+                prettyDiagnostic = "";
+            }
+            catch {
+                prettyDiagnostic = prettyDiagnostic || line.trimStart().startsWith("{") ? candidate : "";
+                return;
+            }
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return;
+            if (value.kind === "operation_progress" && stateDir && value.operation_id === input.operationId) {
+                // The diagnostic is only a wake-up: durable, bound evidence owns liveness.
+                diagnosticReads = diagnosticReads.then(async () => {
+                    const record = await readOperationProgress(stateDir, input.operationId, binding);
+                    if (!record || record.sequence <= operationSequence)
+                        return;
+                    const requested = await readOperationRecord(stateDir, input.operationId, "requested.json");
+                    if (!requested)
+                        throw new AppError("operation_progress_invalid", "Operation request disappeared while observing progress", 1);
+                    for (const key of ["daemon_id", "params_sha256", "generation"])
+                        binding[key] ??= requested[key] ?? null;
+                    operationSequence = record.sequence;
+                    clock?.sample(++progressCursor, Date.parse(record.observed_at));
+                }).catch(error => { callbackError ??= error; if (!settled)
+                    stopTransport(); });
+                return;
+            }
+            const cause = adapterCause(candidate);
+            if (typeof cause.code === "string")
+                retainedError = cause;
+            if (clock && !(stateDir && ["session.create", "session.fork", "session.start", "session.resume", "session.prompt"].includes(operation))
+                && ["native_hook_phase", "process_maintenance_phase"].includes(String(value.kind))
+                && typeof value.phase === "string" && /^[a-z_]{1,48}$/.test(value.phase)
+                && !["heartbeat", "poll", "elapsed", "wait", "waiting", "status"].includes(value.phase)) {
+                const marker = JSON.stringify([value.kind, value.phase, value.operation_id ?? value.process_id]);
+                if (!phases.has(marker)) {
+                    phases.add(marker);
+                    clock.sample(++progressCursor);
+                }
+            }
+        };
         child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
-        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
-        child.once("error", (error) => { clearTimeout(timer); if (heartbeat)
-            clearInterval(heartbeat); if (killTimer)
-            clearTimeout(killTimer); evidence({ status: null, error: error.message }); reject(new AppError("merge_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), error: error.message })); });
-        child.once("close", (status, signal) => {
-            clearTimeout(timer);
+        // Diagnostics have no lifetime quota. Stream to the existing evidence sink
+        // and carry only a bounded tail in the disposable RPC receipt.
+        child.stderr.setEncoding("utf8").on("data", (chunk) => {
+            stderr = (stderr + chunk).slice(-64_000);
+            for (const piece of chunk.split(/(?<=\n)/)) {
+                if (!droppingDiagnostic)
+                    pendingDiagnostic += piece;
+                if (pendingDiagnostic.length > 64_000) {
+                    prettyDiagnostic = prettyDiagnostic || pendingDiagnostic.trimStart().startsWith("{") ? null : "";
+                    pendingDiagnostic = "";
+                    droppingDiagnostic = true;
+                }
+                if (!piece.endsWith("\n"))
+                    continue;
+                if (!droppingDiagnostic)
+                    observeDiagnostic(pendingDiagnostic);
+                pendingDiagnostic = "";
+                droppingDiagnostic = false;
+            }
+            if (input.onEvidence)
+                deliver(() => evidence({ type: "adapter_diagnostic", stderr: chunk }));
+        });
+        child.once("error", (error) => { spawnError = error; });
+        child.once("close", async (status, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearInterval(timer);
+            input.signal?.removeEventListener("abort", abort);
             if (heartbeat)
                 clearInterval(heartbeat);
-            if (killTimer)
-                clearTimeout(killTimer);
-            evidence({ status, signal, timed_out: timedOut, stdout, stderr });
+            await cleanup;
+            if (!droppingDiagnostic && pendingDiagnostic)
+                observeDiagnostic(pendingDiagnostic);
+            await diagnosticReads;
+            const progressFailure = callbackError;
+            deliver(() => evidence({ status, signal, timed_out: timedOut, aborted, stdout, stderr, ...(spawnError ? { error: spawnError.message } : {}) }));
+            if (spawnError)
+                return reject(new AppError("harness_adapter_failed", "Harness adapter call failed", 1, { cause: adapterCause(spawnError.message), ...(callbackError ? { evidence_error: String(callbackError) } : {}) }));
             if (timedOut)
-                return reject(new AppError("merge_adapter_timeout", "Harness adapter call timed out", 1, { executable: input.executable, args: input.args.slice(0, 3), timeout_ms: timeoutMs }));
+                return reject(Object.assign(new AppError("harness_adapter_timeout", "Harness adapter call timed out", 1, { executable: input.executable, args: input.args.slice(0, 3), timeout_ms: timeoutMs }), { observationClock: clock }));
+            if (aborted)
+                return reject(new AppError("harness_adapter_aborted", "Harness adapter call was cancelled", 1, { executable: input.executable, args: input.args.slice(0, 3) }));
             if (status !== 0)
-                return reject(new AppError("merge_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), status, signal, stderr }));
+                return reject(progressFailure ?? new AppError("harness_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), status, signal, stderr, cause: adapterCause(stdout, stderr, retainedError ? JSON.stringify(retainedError) : ""), ...(callbackError ? { evidence_error: String(callbackError) } : {}) }));
+            if (callbackError)
+                return reject(callbackError);
             try {
-                resolve(JSON.parse(stdout));
+                const reply = JSON.parse(stdout);
+                if (!reply || typeof reply !== "object" || Array.isArray(reply))
+                    throw new Error("not object");
+                const value = reply;
+                if (value.ok === false)
+                    return reject(new AppError("harness_adapter_failed", "Harness adapter reported a runtime failure", 1, { cause: adapterCause(stdout) }));
+                resolve(reply);
             }
             catch {
-                reject(new AppError("merge_adapter_invalid", "Harness adapter returned invalid JSON", 1, { executable: input.executable, stdout }));
+                reject(new AppError("harness_adapter_invalid", "Harness adapter returned one invalid JSON object", 1, { executable: input.executable }));
             }
         });
     });
 }
+function adapterCause(...outputs) {
+    for (const output of outputs)
+        for (const line of [output.trim(), ...output.trim().split("\n").reverse()]) {
+            try {
+                const value = JSON.parse(line);
+                const nested = value.error && typeof value.error === "object" && !Array.isArray(value.error) ? value.error : null;
+                const code = typeof nested?.code === "string" ? nested.code : typeof value.code === "string" ? value.code : null;
+                const message = typeof nested?.message === "string" ? nested.message : typeof value.error === "string" ? value.error : typeof value.message === "string" ? value.message : code;
+                if (code)
+                    return errorRecord({ ...(nested ?? value), code, message });
+            }
+            catch { /* Adapter diagnostics need not be JSON. */ }
+        }
+    return { message: outputs.map(output => output.trim()).filter(Boolean).join("\n") || "adapter process failed" };
+}
 export function adapterSessionId(value) {
     if (!value || typeof value !== "object")
         return null;
-    for (const [key, item] of Object.entries(value)) {
-        if (["session_id", "sessionId", "provider_session_id", "providerSessionId", "adapter_session_id", "adapterSessionId", "thread_id", "threadId", "conversation_id"].includes(key) && typeof item === "string")
-            return item;
-        const nested = adapterSessionId(item);
-        if (nested)
-            return nested;
-    }
+    const reply = value;
+    for (const key of ["provider_session_id", "adapter_session_id", "session_id"])
+        if (typeof reply[key] === "string" && reply[key].trim())
+            return reply[key];
+    const session = reply.session;
+    if (session && typeof session === "object" && !Array.isArray(session))
+        for (const key of ["provider_session_id", "session_id"])
+            if (typeof session[key] === "string" && String(session[key]).trim())
+                return session[key];
     return null;
 }

package/dist/services/harness-config.js

@@ -10,6 +10,7 @@ export function harnessKey(value) {
         zcode: "zcode-acp", "zcode-acp": "zcode-acp",
         grok: "grok-acp", "grok-acp": "grok-acp",
         agy: "antigravity-cli", "antigravity-cli": "antigravity-cli",
+        droid: "droid-cli", "droid-cli": "droid-cli",
         opencode: "opencode-server", "opencode-server": "opencode-server"
     };
     const resolved = keys[value];
@@ -60,6 +61,7 @@ export function harnessRuntimeArguments(ddFlowHome, harness) {
         "zcode-acp": "--zcode-acp-bin",
         "grok-acp": "--grok-bin",
         "antigravity-cli": "--agy-bin",
+        "droid-cli": "--droid-bin",
         "opencode-server": "--opencode-bin"
     };
     return [option[key], runtime];

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