@deksden-com/dd-flow-cli 0.9.0-beta.123 → 0.9.0-beta.127

package/dist/cli/runtime-maintenance-ingress.js

@@ -0,0 +1,51 @@
+import { isRuntimeMaintenance, runtimeMaintenanceDiagnostics, withMaintenanceDiagnosticScope } from "./runtime-maintenance-diagnostics.js";
+import { errorRecord, isAppError } from "../shared/errors.js";
+import { writeJson } from "../shared/json.js";
+/** Only the already-selected engine's internal JSON transport takes this path.
+ * Operator calls and richer output formats retain the ordinary engine router. */
+export function isRuntimeMaintenanceIngress(args, env) {
+    return env.DD_FLOW_ENGINE_MODE === "1" && Number.isFinite(Number(env.DD_FLOW_HOOK_DEADLINE_AT))
+        && Number(env.DD_FLOW_HOOK_DEADLINE_AT) > 0 && args.includes("--json")
+        && isRuntimeMaintenance(args)
+        && !args.some(arg => ["--help", "-h", "--progress-jsonl", "--response-file"].includes(arg) || arg.startsWith("--response-file="));
+}
+export async function runRuntimeMaintenanceIngress(args, env = process.env, io = { stdout: process.stdout, stderr: process.stderr }) {
+    return withMaintenanceDiagnosticScope(async () => {
+        const deadline = Number(env.DD_FLOW_HOOK_DEADLINE_AT);
+        // Publish evidence before loading even the maintenance service graph.
+        const diagnostics = runtimeMaintenanceDiagnostics(args, deadline, line => io.stderr.write(line));
+        let context;
+        try {
+            const [{ createContext }, { prepareCommandRoute }, { resolveCommandProjectRoot, resolveCommandPaths }, processCommands] = await Promise.all([
+                import("../runtime/context.js"), import("./command-inputs.js"), import("../services/command-context.js"), import("./runtime-process.js")
+            ]);
+            const invocation = args.filter(arg => arg !== "--json");
+            const options = { databaseDeadlineAt: deadline, resourceDatabaseMode: args[2] === "register" ? "initialize" : args[2] === "status" ? "read_existing" : "prepared_existing" };
+            context = createContext({ ...env, DD_FLOW_INVOCATION_READONLY: args[2] === "status" ? "1" : undefined }, "read_existing", undefined, options);
+            const root = resolveCommandProjectRoot(context, invocation, null);
+            const routedArgs = resolveCommandPaths(context, invocation, root);
+            const route = prepareCommandRoute(routedArgs);
+            const prepared = processCommands.prepareRuntimeProcess(context, route.key, route.parsed);
+            // Preserve the common compatibility gate; this is not a second dispatch
+            // implementation or permission granted by the ingress predicate.
+            const { preflightCliCompatibility } = await import("../services/compatibility-preflight.js");
+            preflightCliCompatibility(context, routedArgs, env, root);
+            const result = await processCommands.dispatchRuntimeProcess(context, args[2], route.parsed, prepared);
+            const receipt = result;
+            const expiry = receipt?.lease_expires_at ?? receipt?.process?.lease_expires_at;
+            diagnostics.phase("ack", { ...(expiry && Number.isFinite(Date.parse(expiry)) ? { lease_expires_at: expiry } : {}) });
+            writeJson(io.stdout, result);
+            return 0;
+        }
+        catch (error) {
+            diagnostics.failure(error);
+            const record = errorRecord(error);
+            writeJson(io.stderr, { ok: false, error: { ...record, details: { ...(!isAppError(error) ? { effect: "unknown" } : {}), ...record.details } } });
+            return record.exitCode;
+        }
+        finally {
+            context?.db.close?.();
+            diagnostics.close();
+        }
+    });
+}

package/dist/cli/runtime-process.js

@@ -0,0 +1,128 @@
+import { AppError } from "../shared/errors.js";
+import { requiredOption, optionalOption, optionalNumber, optionalPositiveNumber } from "./argument-values.js";
+import { prepareError } from "./input-preparation.js";
+import { recoveryGuard, assertRunMutationAllowed } from "../services/run-recovery-guard.js";
+import { recoveryRuntimeAdmission } from "../services/run-recovery-guard.js";
+import { prepareManagedProcessRegistration, prepareManagedProcessConfirmation, prepareManagedProcessHeartbeat, prepareManagedProcessFinish, prepareManagedProcessStopOperation, prepareManagedProcessReconcile, stopManagedProcess, confirmManagedProcess, finishManagedProcess, renewManagedProcess, assertManagedProcessAdmission, managedProcessRuntimeHome, managedProcessStatus, processIsAlive, reconcileExpiredManagedProcesses, registerManagedProcess } from "../services/managed-processes.js";
+import { admitRuntimeCheck, parseRuntimeBudget, reserveProviderTurn, releaseProviderTurns, prepareProviderTurnRelease } from "../services/runtime-budget.js";
+function runtimeProcessStopInput(parsed) {
+    const graceMs = optionalNumber(parsed, "grace-ms");
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(graceMs !== undefined ? { graceMs } : {}) };
+}
+function runtimeProcessRegistrationInput(context, parsed) {
+    const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
+    const budget = parseRuntimeBudget(optionalOption(parsed, "budget-json"));
+    const kind = requiredOption(parsed, "kind");
+    const projectId = optionalOption(parsed, "project-id") ?? null, runId = optionalOption(parsed, "run") ?? null;
+    const guard = projectId && runId ? recoveryGuard(context, projectId, runId) : null;
+    const run = projectId && runId ? context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]) : null;
+    return {
+        ...(optionalOption(parsed, "id") ? { id: optionalOption(parsed, "id") } : {}), kind, ownerId: requiredOption(parsed, "owner"), uniqueActiveOperation: kind === "eval-observer",
+        ...(kind === "eval-observer" ? { pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(optionalPositiveNumber(parsed, "process-group-id", true) ? { processGroupId: optionalPositiveNumber(parsed, "process-group-id", true) } : {}) } : {}),
+        ownerPid: optionalPositiveNumber(parsed, "owner-pid", true), projectId, runId,
+        workId: optionalOption(parsed, "work") ?? null, checkId: optionalOption(parsed, "check") ?? null,
+        operationId: optionalOption(parsed, "operation") ?? null, stdoutPath: optionalOption(parsed, "stdout") ?? null,
+        stderrPath: optionalOption(parsed, "stderr") ?? null, ...(leaseMs !== undefined ? { leaseMs } : {}),
+        metadata: { ...(budget ? { budget, harness: optionalOption(parsed, "harness") ?? null } : {}), ...(projectId && runId ? { run_generation: guard?.generation ?? 0, run_admitted: Boolean(run) && !["draining", "sealed", "resuming"].includes(guard?.status ?? "") } : {}), ...(optionalOption(parsed, "dispatch-barrier") ? { dispatch_barrier: optionalOption(parsed, "dispatch-barrier") } : {}), ...(optionalOption(parsed, "role") ? { role: optionalOption(parsed, "role") } : {}), ...(optionalOption(parsed, "state-dir") ? { state_dir: optionalOption(parsed, "state-dir") } : {}), ...(optionalOption(parsed, "adapter-executable") ? { adapter_executable: optionalOption(parsed, "adapter-executable") } : {}) }
+    };
+}
+function runtimeProcessConfirmationInput(parsed) {
+    const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true), processGroupId = optionalPositiveNumber(parsed, "process-group-id", true);
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ownerPid: optionalPositiveNumber(parsed, "owner-pid", true), pid: optionalPositiveNumber(parsed, "pid", true) ?? 0, ...(processGroupId !== undefined ? { processGroupId } : {}), ...(leaseMs !== undefined ? { leaseMs } : {}) };
+}
+function runtimeProcessHeartbeatInput(parsed) {
+    const leaseMs = optionalPositiveNumber(parsed, "lease-ms", true);
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), ...(leaseMs !== undefined ? { leaseMs } : {}) };
+}
+function runtimeProcessFinishInput(parsed) {
+    const state = requiredOption(parsed, "state");
+    if (state !== "stopped" && state !== "failed")
+        throw new AppError("validation", "--state must be stopped or failed", 2);
+    return { id: requiredOption(parsed, "id"), leaseToken: requiredOption(parsed, "lease-token"), state, reason: optionalOption(parsed, "reason") ?? null };
+}
+export function prepareRuntimeProcess(context, key, parsed) {
+    try {
+        return prepareRuntimeProcessInput(context, key, parsed);
+    }
+    catch (error) {
+        return prepareError(error);
+    }
+}
+function prepareRuntimeProcessInput(context, key, parsed) {
+    const prepared = {};
+    if (key === "runtime process register") {
+        prepareManagedProcessRegistration(context, runtimeProcessRegistrationInput(context, parsed));
+    }
+    if (key === "runtime process heartbeat")
+        prepareManagedProcessHeartbeat(context, runtimeProcessHeartbeatInput(parsed));
+    if (key === "runtime process finish")
+        prepareManagedProcessFinish(context, runtimeProcessFinishInput(parsed));
+    if (key === "runtime process confirm")
+        prepareManagedProcessConfirmation(context, runtimeProcessConfirmationInput(parsed));
+    if (key === "runtime process stop")
+        prepareManagedProcessStopOperation(context, runtimeProcessStopInput(parsed));
+    if (key === "runtime process reconcile")
+        prepareManagedProcessReconcile(requiredOption(parsed, "owner"), optionalNumber(parsed, "grace-ms"));
+    if (key === "runtime process release-turn") {
+        prepared.providerTurnRelease = prepareProviderTurnRelease({ daemonId: requiredOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), observationFile: optionalOption(parsed, "observation-file") });
+    }
+    return prepared;
+}
+export async function dispatchRuntimeProcess(context, action, parsed, prepared = {}) {
+    if (action === "check-admission")
+        return { ok: true, ...admitRuntimeCheck(context, requiredOption(parsed, "id"), requiredOption(parsed, "lease-token")) };
+    if (action === "stop")
+        return { ok: true, process: await stopManagedProcess(context, runtimeProcessStopInput(parsed)) };
+    if (action === "register") {
+        const process = registerManagedProcess(context, runtimeProcessRegistrationInput(context, parsed));
+        return { ok: true, process };
+    }
+    if (action === "confirm")
+        return { ok: true, process: confirmManagedProcess(context, runtimeProcessConfirmationInput(parsed)) };
+    if (action === "heartbeat") {
+        const receipt = renewManagedProcess(context, runtimeProcessHeartbeatInput(parsed));
+        return { ...receipt, ok: receipt.owned };
+    }
+    if (action === "admission") {
+        const [{ controllerHitlAdmission }, { assertCapacityOwnerAdmission }] = await Promise.all([import("../services/run-controller-adapter.js"), import("../services/codex-capacity.js")]);
+        const record = managedProcessStatus(context).find(process => process.id === requiredOption(parsed, "id"));
+        if (!record || record.lease_token !== requiredOption(parsed, "lease-token") || record.owner_id !== requiredOption(parsed, "owner") || record.state !== "running" || !record.pid || !record.pid_started_at || !processIsAlive(record))
+            throw new AppError("process_ownership_unknown", "Productive dispatch requires its current confirmed runtime owner", 1);
+        assertManagedProcessAdmission(context, record);
+        const metadata = JSON.parse(record.metadata_json);
+        if (metadata.state_dir !== requiredOption(parsed, "state-dir"))
+            throw new AppError("process_ownership_unknown", "Runtime admission belongs to another state directory", 1);
+        if (record.project_id && record.run_id) {
+            if (managedProcessRuntimeHome(record, context) !== context.ddFlowHome)
+                throw new AppError("process_runtime_scope_mismatch", "Runtime admission belongs to another or unproven flow home", 1);
+            const recovering = recoveryRuntimeAdmission(context, record, { stateDir: requiredOption(parsed, "state-dir"), daemonId: optionalOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), operation: optionalOption(parsed, "operation"), nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+            if (!recovering) {
+                if (metadata.run_admitted !== true || !Number.isSafeInteger(metadata.run_generation))
+                    throw new AppError("run_recovery_guarded", "Runtime was not admitted before the RUN fence; reconcile its launch", 1);
+                assertRunMutationAllowed(context, record.project_id, record.run_id, metadata.run_generation);
+            }
+            const run = context.db.get("SELECT status FROM runs WHERE project_id = ? AND id = ?", [record.project_id, record.run_id]);
+            const retainedHitlPrompt = recovering && ["paused", "waiting_for_user"].includes(run?.status ?? "") && ["session.prompt", "session.resume"].includes(optionalOption(parsed, "operation") ?? "") && context.db.get("SELECT 1 FROM run_recovery_bindings b JOIN run_recovery_guards g ON g.recovery_id = b.recovery_id WHERE g.project_id = ? AND g.run_id = ? AND g.generation = ? AND b.daemon_id = ? AND b.provider_session_id = ?", [record.project_id, record.run_id, metadata.run_generation, optionalOption(parsed, "daemon-id"), optionalOption(parsed, "native-session-id")]);
+            const acceptedHitlPrompt = ["paused", "waiting_for_user"].includes(run?.status ?? "") && controllerHitlAdmission(context, record, { stateDir: requiredOption(parsed, "state-dir"), operationId: optionalOption(parsed, "operation-id"), operation: optionalOption(parsed, "operation"), nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+            if (!run || run.status !== "running" && !retainedHitlPrompt && !acceptedHitlPrompt && !["judge", "probe"].includes(metadata.role ?? ""))
+                throw new AppError("invalid_run_state", "Subject dispatch requires a running RUN or its retained recovery/HITL prompt", 1);
+            if (!recovering)
+                assertCapacityOwnerAdmission(context, record, optionalOption(parsed, "operation-id"), { nativeSessionId: optionalOption(parsed, "native-session-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+        }
+        const budget = reserveProviderTurn(context, record, { operationId: optionalOption(parsed, "operation-id") ?? "", operation: optionalOption(parsed, "operation") ?? "", sessionId: optionalOption(parsed, "native-session-id"), daemonId: optionalOption(parsed, "daemon-id"), promptSha256: optionalOption(parsed, "prompt-sha256") });
+        return { ok: true, ...budget, process_id: record.id, generation: metadata.run_generation ?? null };
+    }
+    if (action === "release-turn") {
+        const record = managedProcessStatus(context).find(process => process.id === requiredOption(parsed, "id"));
+        if (!record || record.lease_token !== requiredOption(parsed, "lease-token") || record.owner_id !== requiredOption(parsed, "owner") || managedProcessRuntimeHome(record, context) !== context.ddFlowHome)
+            throw new AppError("process_ownership_unknown", "Budget release requires its retained physical owner", 1);
+        return releaseProviderTurns(context, record, { daemonId: requiredOption(parsed, "daemon-id"), operationId: optionalOption(parsed, "operation-id"), observationFile: optionalOption(parsed, "observation-file") }, prepared.providerTurnRelease);
+    }
+    if (action === "finish")
+        return { ok: finishManagedProcess(context, runtimeProcessFinishInput(parsed)) };
+    if (action === "status")
+        return { ok: true, processes: managedProcessStatus(context) };
+    if (action === "reconcile")
+        return { ok: true, processes: await reconcileExpiredManagedProcesses(context, requiredOption(parsed, "owner"), optionalNumber(parsed, "grace-ms")) };
+    throw new AppError("usage", "Usage: dd-flow runtime process <start|stop|register|confirm|heartbeat|admission|finish|status|reconcile>", 2);
+}

package/dist/cli.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 import { isNativeHookIngress } from "./cli/native-hook-ingress.js";
+import { isRuntimeMaintenanceIngress, runRuntimeMaintenanceIngress } from "./cli/runtime-maintenance-ingress.js";
 const args = process.argv.slice(2);
 const managedHook = Boolean(process.env.DD_FLOW_CODEX_STATE_DIR) && args.slice(0, 3).join(" ") === "codex hook handle" && !args.includes("--help") && !args.includes("-h");
-const exitCode = managedHook
-    ? await (await import("./cli/hook-ingress.js")).runHookIngress(args)
-    : isNativeHookIngress(args) && !args.includes("--help") && !args.includes("-h")
-        ? await (await import("./cli/native-hook-ingress.js")).runNativeHookIngress(args)
-        : await (await import("./cli/run-cli.js")).runCli(args);
+const exitCode = isRuntimeMaintenanceIngress(args, process.env)
+    ? await runRuntimeMaintenanceIngress(args)
+    : managedHook
+        ? await (await import("./cli/hook-ingress.js")).runHookIngress(args)
+        : isNativeHookIngress(args) && !args.includes("--help") && !args.includes("-h")
+            ? await (await import("./cli/native-hook-ingress.js")).runNativeHookIngress(args)
+            : await (await import("./cli/run-cli.js")).runCli(args);
 process.exitCode = exitCode;

package/dist/domain/stage-catalog.js

@@ -3,7 +3,7 @@ export const vnextStages = [
     { id: "specify", directory: "01-specify", result: "specify.json", schema: "dd-flow/vnext-specify-result@4", next: ["protocolize"] },
     { id: "protocolize", directory: "02-protocolize", result: "protocolize-result.json", schema: "dd-flow/vnext-protocolize-result@3", next: ["plan"] },
     { id: "plan", directory: "03-plan", result: "stage-report.json", schema: "dd-flow/stage-report@2", next: ["plan-review", "code"] },
-    { id: "plan-review", directory: "04-plan-review", result: "decision.json", schema: "dd-flow/plan-review-decision@3", next: ["code"] },
+    { id: "plan-review", directory: "04-plan-review", result: "decision.json", schema: "dd-flow/plan-review-decision@4", next: ["code"] },
     { id: "code", directory: "05-code", result: "code-verification.json", schema: "dd-flow/code-verification@2", next: ["code-review", "merge"] },
     { id: "code-review", directory: "06-code-review", result: "decision.json", schema: "dd-flow/code-review-decision@3", next: ["merge"] },
     { id: "merge", directory: "07-merge", result: "stage-report.json", schema: "dd-flow/stage-report@2", next: [] }

package/dist/harness-runtime/bin/dd-agy.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { adapterTimeoutOptions } from "../lib/adapter-timeouts.mjs";
 import { durableDaemonStart, inspectDaemonOperation, interruptDaemonOperation, settleDaemonOperation } from "../lib/daemon-operations.mjs";
 import { readFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -38,7 +39,7 @@ async function hook(options) {
 }
 
 try {
-  const { positional, options } = parse(process.argv.slice(2)), [family, command, modifier] = positional; const common = { journal: options.journal, stateDir: options["state-dir"], cwd: options.cwd, bin: options["agy-bin"], provider: options.provider, model: options.model, reasoning: options.reasoning, mode: options.mode, projectRoot: options["project-root"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, timeoutMs: options.timeout ? Number(options.timeout) * 1000 : undefined }; let result;
+  const { positional, options } = parse(process.argv.slice(2)), [family, command, modifier] = positional; const common = { journal: options.journal, stateDir: options["state-dir"], cwd: options.cwd, bin: options["agy-bin"], provider: options.provider, model: options.model, reasoning: options.reasoning, mode: options.mode, projectRoot: options["project-root"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, ...adapterTimeoutOptions(options, family === "session" ? command : null) }; let result;
   if (family === "doctor") result = await doctor(common);
   else if (family === "hooks" && ["install", "check"].includes(command)) result = await qualifyAgyHooks(common.projectRoot, { stateDir: common.stateDir, install: command === "install" });
   else if (family === "daemon" && command === "start") result = await durableDaemonStart({ ...common, sessionId: options["session-id"], entryPath: process.argv[1] }, startDaemon);
@@ -49,7 +50,7 @@ try {
   else if (family === "daemon" && command === "operation") result = await inspectDaemonOperation(common.stateDir, options["operation-id"]);
   else if (family === "daemon" && command === "stop") result = await stopDaemon({ stateDir: common.stateDir, cancelTree: options["cancel-tree"], timeoutMs: common.timeoutMs });
   else if (family === "hook" && command === "handle") { process.stdout.write(`${JSON.stringify(await hook(options))}\n`); process.exit(0); }
-  else if (family === "session") { if (command === "fork") throw Object.assign(new Error("Antigravity native headless fork is unsupported; use deterministic_replay"), { code: "agy_headless_fork_unsupported" }); const operation = command === "status" ? "inspect" : command; result = await callDaemon(common.stateDir, `session.${operation}`, { sessionId: options["session-id"], ...(command === "create" || command === "prompt" ? { prompt: await prompt(options) } : {}), tree: options.tree === true }, common.timeoutMs ?? 1_800_000); }
+  else if (family === "session") { if (command === "fork") throw Object.assign(new Error("Antigravity native headless fork is unsupported; use deterministic_replay"), { code: "agy_headless_fork_unsupported" }); const operation = command === "status" ? "inspect" : command; result = await callDaemon(common.stateDir, `session.${operation}`, { sessionId: options["session-id"], livenessTimeoutMs: common.livenessTimeoutMs, ...(command === "create" || command === "prompt" ? { prompt: await prompt(options) } : {}), tree: options.tree === true }, common.timeoutMs ?? 1_800_000); }
   else throw new Error("usage: dd-agy doctor | hooks install|check | daemon start|status|stop | session create|prompt|inspect|resume|cancel|fork [options] --json");
   process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
 } catch (error) { if (process.argv.includes("hook") && process.argv.includes("handle")) { process.stdout.write(`${JSON.stringify({ decision: "deny", reason: `${error.code ?? "agy_hook_rejected"}: ${error.message ?? "Native hook refused this tool call"}` })}\n`); process.exit(0); } process.stderr.write(`${JSON.stringify({ ok: false, error: error.message, ...(error.code ? { code: error.code, retryable: error.retryable === true, details: error.details } : {}) })}\n`); process.exit(1); }

package/dist/harness-runtime/bin/dd-codex.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
+import { adapterTimeoutOptions } from "../lib/adapter-timeouts.mjs";
 import { durableDaemonStart, inspectDaemonOperation, interruptDaemonOperation, settleDaemonOperation } from "../lib/daemon-operations.mjs";
 import { cancelSession, createSession, doctor, inspectSession, promptFromFile, promptSession, startSession } from "../lib/dd-codex.mjs";
 import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-codex-daemon.mjs";
 import { errorRecord } from "../lib/operation-errors.mjs";
 
 function parse(argv) { const positional = []; const options = {}; for (let i = 0; i < argv.length; i += 1) { const token = argv[i]; if (!token.startsWith("--")) { positional.push(token); continue; } const key = token.slice(2); if (["json", "cancel-tree", "no-flow"].includes(key)) { options[key] = true; continue; } const value = argv[++i]; if (value === undefined) throw new Error(`--${key} requires a value`); options[key] = value; } return { positional, options }; }
-function common(options) { return { bin: options["codex-bin"], journal: options.journal, stateDir: options["state-dir"], cwd: options.cwd, sessionId: options["session-id"], turnId: options["turn-id"], model: options.model, reasoning: options.reasoning, ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], projectRoot: options["project-root"], noFlow: options["no-flow"] === true, timeoutMs: options.timeout ? Number(options.timeout) * 1000 : undefined }; }
+function common(options, operation) { return { bin: options["codex-bin"], journal: options.journal, stateDir: options["state-dir"], cwd: options.cwd, sessionId: options["session-id"], turnId: options["turn-id"], model: options.model, reasoning: options.reasoning, ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], projectRoot: options["project-root"], noFlow: options["no-flow"] === true, ...adapterTimeoutOptions(options, operation) }; }
 try {
-  const { positional, options } = parse(process.argv.slice(2)); const [family, command, modifier] = positional; const shared = common(options); let result;
+  const { positional, options } = parse(process.argv.slice(2)); const [family, command, modifier] = positional; const shared = common(options, family === "session" ? command : null); let result;
   if (family === "doctor") result = await doctor(shared);
   else if (family === "daemon" && command === "start") result = await durableDaemonStart({ ...shared, entryPath: process.argv[1] }, startDaemon);
   else if (family === "daemon" && command === "serve") { await serveDaemon(shared.stateDir); process.exit(0); }

package/dist/harness-runtime/bin/dd-droid.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { adapterTimeoutOptions } from "../lib/adapter-timeouts.mjs";
 import { durableDaemonStart, inspectDaemonOperation, interruptDaemonOperation, settleDaemonOperation } from "../lib/daemon-operations.mjs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -12,7 +13,7 @@ import { hookBudget, readNativeHookInput } from "../lib/native-hook-command.mjs"
 function parse(argv) { const positional = [], options = {}; for (let i = 0; i < argv.length; i++) { const word = argv[i]; if (!word.startsWith("--")) { positional.push(word); continue; } const key = word.slice(2); if (["json", "cancel-tree", "tree", "no-flow"].includes(key)) options[key] = true; else { if (argv[i + 1] === undefined) throw new Error(`${word} requires a value`); options[key] = argv[++i]; } } return { positional, options }; }
 try {
   const { positional: [family, command, modifier], options } = parse(process.argv.slice(2));
-  const config = { stateDir: options["state-dir"], sessionId: options["session-id"], cwd: options.cwd, projectRoot: options["project-root"], bin: options["droid-bin"] ?? "droid", entryPath: process.argv[1], journal: options.journal, authHome: options["auth-home"], model: options.model, provider: options.provider, reasoning: options.reasoning, mode: options.mode, ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, timeoutMs: options.timeout ? Number(options.timeout) * 1_000 : undefined };
+  const config = { stateDir: options["state-dir"], sessionId: options["session-id"], cwd: options.cwd, projectRoot: options["project-root"], bin: options["droid-bin"] ?? "droid", entryPath: process.argv[1], journal: options.journal, authHome: options["auth-home"], model: options.model, provider: options.provider, reasoning: options.reasoning, mode: options.mode, ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, ...adapterTimeoutOptions(options, family === "session" ? command : null, "droid-cli") };
   let result;
   if (family === "doctor") {
     const dir = await mkdtemp(path.join(os.tmpdir(), "dd-droid-doctor-"));
@@ -27,7 +28,7 @@ try {
   else if (family === "daemon" && command === "operation") result = await inspectDaemonOperation(config.stateDir, options["operation-id"]);
   else if (family === "daemon" && command === "stop") result = await stopDaemon({ stateDir: config.stateDir, cancelTree: options["cancel-tree"] });
   else if (family === "hook" && command === "handle") { const budget = hookBudget(); const payload = JSON.parse(await readNativeHookInput(process.stdin, budget)); const eventId = randomUUID(); result = await callDaemon(config.stateDir, "hook.observe", { payload, eventId, deadlineAt: budget.deadlineAt }, budget.remaining("observation"), eventId); }
-  else if (family === "session") { if (command === "fork") throw new Error("Droid fork is not qualified for this adapter"); const prompt = options["prompt-file"] ? await readFile(options["prompt-file"], "utf8") : options.prompt; result = await callDaemon(config.stateDir, `session.${command === "status" ? "inspect" : command}`, { sessionId: options["session-id"], ...(config.noFlow ? { noFlow: true } : {}), ...(prompt ? { prompt } : {}) }); }
+  else if (family === "session") { if (command === "fork") throw new Error("Droid fork is not qualified for this adapter"); const prompt = options["prompt-file"] ? await readFile(options["prompt-file"], "utf8") : options.prompt; result = await callDaemon(config.stateDir, `session.${command === "status" ? "inspect" : command}`, { sessionId: options["session-id"], livenessTimeoutMs: config.livenessTimeoutMs, ...(config.noFlow ? { noFlow: true } : {}), ...(prompt ? { prompt } : {}) }); }
   else throw new Error("usage: dd-droid doctor | daemon start|status|operation|stop | session create|resume|prompt|inspect|cancel");
   process.stdout.write(`${JSON.stringify(family === "hook" ? { ...(result.hookSpecificOutput ? { hookSpecificOutput: result.hookSpecificOutput } : {}), ...(typeof result.continue === "boolean" ? { continue: result.continue } : {}), ...(result.stopReason ? { stopReason: result.stopReason } : {}) } : { ok: true, ...result })}\n`);
 } catch (error) { process.stderr.write(`${JSON.stringify({ ok: false, error: errorRecord(error) })}\n`); process.exitCode = process.argv[2] === "hook" ? 2 : 1; }

package/dist/harness-runtime/bin/dd-grok.mjs

@@ -1,20 +1,30 @@
 #!/usr/bin/env node
+import { adapterTimeoutOptions } from "../lib/adapter-timeouts.mjs";
 import { durableDaemonStart, inspectDaemonOperation, interruptDaemonOperation, settleDaemonOperation } from "../lib/daemon-operations.mjs";
-import { hookBudget, invokeNativeHook, readNativeHookInput } from "../lib/native-hook-command.mjs";
+import { hookBudget, invokeNativeHook, readNativeHookInput, writeNativeHookFailure } from "../lib/native-hook-command.mjs";
 import { cancelSession, createSession, doctor, forkSession, inspectSession, promptFromFile, promptSession } from "../lib/dd-grok.mjs";
 import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-grok-daemon.mjs";
+import { errorRecord } from "../lib/operation-errors.mjs";
 
 function parse(argv) { const positional = []; const options = {}; for (let index = 0; index < argv.length; index += 1) { const token = argv[index]; if (!token.startsWith("--")) { positional.push(token); continue; } const key = token.slice(2); if (["json", "cancel-tree", "no-flow"].includes(key)) { options[key] = true; continue; } const value = argv[++index]; if (value === undefined) throw new Error(`--${key} requires a value`); options[key] = value; } return { positional, options }; }
-function common(options) { return { bin: options["grok-bin"], journal: options.journal, stateDir: options["state-dir"], cwd: options.cwd, sessionId: options["session-id"], model: options.model, reasoning: options.reasoning, mode: options.mode ?? "bypassPermissions", authPath: options["auth-path"], authMethodId: options["auth-method-id"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], projectRoot: options["project-root"], sessionArchive: options["session-archive"], noFlow: options["no-flow"] === true, timeoutMs: options.timeout ? Number(options.timeout) * 1000 : undefined }; }
+function common(options, operation) { return { bin: options["grok-bin"], journal: options.journal, stateDir: options["state-dir"], cwd: options.cwd, sessionId: options["session-id"], model: options.model, reasoning: options.reasoning, mode: options.mode ?? "bypassPermissions", authPath: options["auth-path"], authMethodId: options["auth-method-id"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], projectRoot: options["project-root"], sessionArchive: options["session-archive"], noFlow: options["no-flow"] === true, ...adapterTimeoutOptions(options, operation) }; }
 async function hook(options) {
   const budget = hookBudget();
-  const stdin = await readNativeHookInput(process.stdin, budget); const payload = JSON.parse(stdin || "{}"); const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.sessionId ?? payload.session_id }, budget.remaining("identity"));
+  const stdin = await readNativeHookInput(process.stdin, budget); const payload = JSON.parse(stdin || "{}"); const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.sessionId ?? payload.session_id, payload }, budget.remaining("identity"));
   const enriched = { ...payload, _meta: { ...(payload._meta ?? {}), ddGrok: identity } }; const args = ["grok", "event", "handle", "--project-root", options["project-root"], "--json"]; const command = options["dd-flow-bin"];
-  return invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: enriched, timeoutMs: budget.remaining("admission", 15_000) });
+  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], payload: enriched, timeoutMs: budget.remaining("admission", 15_000) }); }
+  catch (error) {
+    if (identity.nativeHookBinding) error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding };
+    try {
+      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, hookBudget(1_000, null));
+      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, 1_000);
+    } catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
+    throw error;
+  }
 }
 
 try {
-  const { positional, options } = parse(process.argv.slice(2)); const [family, command, modifier] = positional; const shared = common(options); let result;
+  const { positional, options } = parse(process.argv.slice(2)); const [family, command, modifier] = positional; const shared = common(options, family === "session" ? command : null); let result;
   if (family === "doctor") result = await doctor(shared);
   else if (family === "daemon" && command === "start") result = await durableDaemonStart({ ...shared, entryPath: process.argv[1] }, startDaemon);
   else if (family === "daemon" && command === "serve") { await serveDaemon(shared.stateDir); process.exit(0); }
@@ -27,4 +37,4 @@ try {
   else if (family === "session") { const params = { ...shared, ...(command === "create" || command === "prompt" ? { prompt: options["prompt-file"] ? await promptFromFile(options["prompt-file"]) : options.prompt } : {}), ...(command === "fork" ? { target: JSON.parse(options["target-json"] ?? "null") } : {}), ...(command === "archive" ? { archiveDir: options["archive-dir"] } : {}) }; if (shared.stateDir) result = await callDaemon(shared.stateDir, `session.${command === "status" ? "inspect" : command}`, params, shared.timeoutMs ?? 1_800_000); else if (command === "create") result = await createSession(params); else if (command === "prompt") result = await promptSession(params); else if (["inspect", "status", "resume"].includes(command)) result = await inspectSession(params); else if (command === "cancel") result = await cancelSession(params); else if (command === "fork") result = await forkSession(params); else throw new Error(`unknown session command: ${command}`); }
   else throw new Error("usage: dd-grok doctor | daemon start|status|stop | session create|prompt|inspect|status|resume|cancel|fork|archive [options] --json");
   process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
-} catch (error) { if (process.argv[2] === "hook") { process.stdout.write(`${JSON.stringify({ decision: "deny", reason: error.message })}\n`); process.exit(2); } process.stderr.write(`${JSON.stringify({ ok: false, error: error.message, ...(error.code ? { code: error.code, retryable: error.retryable === true, details: error.details } : {}) })}\n`); process.exit(1); }
+} catch (error) { if (process.argv[2] === "hook") { process.stderr.write(`${JSON.stringify({ native_hook_failure: errorRecord(error), bound: Boolean(error.details?.native_hook_binding) })}\n`); process.stdout.write(`${JSON.stringify({ decision: "deny", reason: error.message })}\n`); process.exit(2); } const failure = errorRecord(error); process.stderr.write(`${JSON.stringify({ ok: false, error: failure.message, ...failure })}\n`); process.exit(1); }

package/dist/harness-runtime/bin/dd-opencode.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { adapterTimeoutOptions } from "../lib/adapter-timeouts.mjs";
 import { durableDaemonStart, inspectDaemonOperation, interruptDaemonOperation, settleDaemonOperation } from "../lib/daemon-operations.mjs";
 import { readFile } from "node:fs/promises";
 import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-opencode-daemon.mjs";
@@ -6,7 +7,7 @@ import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-open
 function parse(argv) { const positional = [], options = {}; for (let i = 0; i < argv.length; i += 1) { const token = argv[i]; if (!token.startsWith("--")) { positional.push(token); continue; } const key = token.slice(2); if (["json","cancel-tree","no-flow"].includes(key)) options[key] = true; else { if (argv[i + 1] === undefined) throw new Error(`--${key} requires a value`); options[key] = argv[++i]; } } return { positional, options }; }
 const prompt = async options => options["prompt-file"] ? await readFile(options["prompt-file"], "utf8") : options.prompt;
 try {
-  const { positional, options } = parse(process.argv.slice(2)), [family, command, modifier] = positional; const common = { journal: options.journal, stateDir: options["state-dir"], sessionId: options["session-id"], cwd: options.cwd, bin: options["opencode-bin"], provider: options.provider, model: options.model, variant: options.variant, agent: options.agent, authPath: options["auth-path"], projectRoot: options["project-root"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, sessionArchive: options["session-archive"], timeoutMs: options.timeout ? Number(options.timeout) * 1000 : undefined }; let result;
+  const { positional, options } = parse(process.argv.slice(2)), [family, command, modifier] = positional; const common = { journal: options.journal, stateDir: options["state-dir"], sessionId: options["session-id"], cwd: options.cwd, bin: options["opencode-bin"], provider: options.provider, model: options.model, variant: options.variant, agent: options.agent, authPath: options["auth-path"], projectRoot: options["project-root"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, sessionArchive: options["session-archive"], ...adapterTimeoutOptions(options, family === "session" ? command : null) }; let result;
   if (family === "daemon" && command === "start") result = await durableDaemonStart({ ...common, entryPath: process.argv[1] }, startDaemon);
   else if (family === "daemon" && command === "serve") { await serveDaemon(common.stateDir); process.exit(0); }
   else if (family === "daemon" && command === "status") result = await callDaemon(common.stateDir, "daemon.status");
@@ -15,7 +16,7 @@ try {
   else if (family === "daemon" && command === "operation") result = await inspectDaemonOperation(common.stateDir, options["operation-id"]);
   else if (family === "doctor") result = await callDaemon(common.stateDir, "daemon.doctor");
   else if (family === "daemon" && command === "stop") result = await stopDaemon({ stateDir: common.stateDir, cancelTree: options["cancel-tree"], timeoutMs: common.timeoutMs });
-  else if (family === "session") { const operation = command === "status" ? "inspect" : command; const params = { sessionId: options["session-id"], title: options.title, messageId: options["message-id"], archiveFile: options["archive-file"], ...(command === "prompt" ? { prompt: await prompt(options) } : {}) }; result = await callDaemon(common.stateDir, `session.${operation}`, params, common.timeoutMs ?? 1_800_000); }
+  else if (family === "session") { const operation = command === "status" ? "inspect" : command; const params = { livenessTimeoutMs: common.livenessTimeoutMs, sessionId: options["session-id"], title: options.title, messageId: options["message-id"], archiveFile: options["archive-file"], ...(command === "prompt" ? { prompt: await prompt(options) } : {}) }; result = await callDaemon(common.stateDir, `session.${operation}`, params, common.timeoutMs ?? 1_800_000); }
   else throw new Error("usage: dd-opencode daemon start|status|stop | session create|prompt|inspect|fork|cancel|archive [options] --json");
   process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
 } catch (error) { process.stderr.write(`${JSON.stringify({ ok: false, error: error.message, ...(error.code ? { code: error.code, retryable: error.retryable === true, details: error.details } : {}) })}\n`); process.exit(1); }

package/dist/harness-runtime/bin/dd-zcode.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
+import { adapterTimeoutOptions } from "../lib/adapter-timeouts.mjs";
 import { durableDaemonStart, inspectDaemonOperation, interruptDaemonOperation, settleDaemonOperation } from "../lib/daemon-operations.mjs";
-import { hookBudget, invokeNativeHook, readNativeHookInput } from "../lib/native-hook-command.mjs";
+import { hookBudget, invokeNativeHook, readNativeHookInput, writeNativeHookFailure } from "../lib/native-hook-command.mjs";
 import { cancelChild, cancelSession, createSession, doctor, forkSession, inspectSession, promptFromFile, promptSession } from "../lib/dd-zcode.mjs";
 import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-zcode-daemon.mjs";
+import { errorRecord } from "../lib/operation-errors.mjs";
 
 function parse(argv) {
   const positional = []; const options = {};
@@ -15,13 +17,7 @@ function parse(argv) {
   return { positional, options };
 }
 
-function common(options) {
-  const seconds = (name) => {
-    if (options[name] === undefined) return undefined;
-    const value = Number(options[name]);
-    if (!Number.isFinite(value) || value <= 0) throw new Error(`--${name} must be a positive finite number of seconds`);
-    return value * 1000;
-  };
+function common(options, operation) {
   return {
     bin: options["zcode-acp-bin"], zcodePath: options["zcode-path"], journal: options.journal,
     stateDir: options["state-dir"],
@@ -31,25 +27,33 @@ function common(options) {
     permission: options.permission ?? "deny", ddFlowBin: options["dd-flow-bin"],
     ddFlowHome: options["dd-flow-home"], projectRoot: options["project-root"], noFlow: options["no-flow"] === true,
     env: options["dd-flow-home"] ? { DD_FLOW_HOME: options["dd-flow-home"] } : undefined,
-    timeoutMs: seconds("timeout"),
-    livenessTimeoutMs: seconds("liveness-timeout"),
-    requestTimeoutMs: seconds("request-timeout"),
+    ...adapterTimeoutOptions(options, operation),
   };
 }
 
 async function hook(options) {
   const budget = hookBudget();
   const payload = JSON.parse((await readNativeHookInput(process.stdin, budget)) || "{}");
-  const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.session_id ?? payload.sessionId }, budget.remaining("identity"));
+  const identity = await callDaemon(options["state-dir"], "hook.resolve", { sessionId: payload.session_id ?? payload.sessionId, payload }, budget.remaining("identity"));
   const command = options["dd-flow-bin"]; const args = ["zcode", "hook", "handle", "--project-root", options["project-root"], "--json"];
 
-  return invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], timeoutMs: budget.remaining("admission", 15_000), payload: { ...payload, _meta: { ...(payload._meta ?? {}), ddZcode: identity } } });
+  try { return await invokeNativeHook({ bin: command, args, home: options["dd-flow-home"], timeoutMs: budget.remaining("admission", 15_000), payload: { ...payload, _meta: { ...(payload._meta ?? {}), ddZcode: identity } } }); }
+  catch (error) {
+    if (identity.nativeHookBinding) error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding };
+    try {
+      // The 25s work budget leaves this bounded 2s evidence tail inside the
+      // qualified 30s native hook limit, even after the work deadline expired.
+      await writeNativeHookFailure(options["state-dir"], identity.nativeHookBinding, error, hookBudget(1_000, null));
+      if (identity.nativeHookBinding) await callDaemon(options["state-dir"], "hook.failed", { requestId: identity.nativeHookBinding.request_id }, 1_000);
+    } catch (storage) { process.stderr.write(`${JSON.stringify({ code: error.code, receipt_error: storage.message })}\n`); }
+    throw error;
+  }
 }
 
 try {
   const { positional, options } = parse(process.argv.slice(2)); const [family, command, modifier] = positional; let result;
   const answers = options["answers-file"] ? JSON.parse(await promptFromFile(options["answers-file"])) : undefined;
-  const shared = common(options);
+  const shared = common(options, family === "session" ? command : null);
   if (family === "doctor") result = await doctor(shared);
   else if (family === "daemon" && command === "start") result = await durableDaemonStart({ ...shared, entryPath: process.argv[1] }, startDaemon);
   else if (family === "daemon" && command === "serve") { await serveDaemon(shared.stateDir); process.exit(0); }
@@ -78,6 +82,6 @@ try {
   } else throw new Error("usage: dd-zcode doctor | daemon start|status|stop | hook handle | session create|prompt|inspect|status|resume|cancel|cancel-child|fork [options] --json");
   process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
 } catch (error) {
-  if (process.argv[2] === "hook") { process.stdout.write(`${JSON.stringify({ decision: "deny", reason: error.message })}\n`); process.exit(2); }
-  process.stderr.write(`${JSON.stringify({ ok: false, error: error.message, ...(error.code ? { code: error.code, retryable: error.retryable === true, details: error.details } : {}) })}\n`); process.exit(1);
+  if (process.argv[2] === "hook") { process.stderr.write(`${JSON.stringify({ native_hook_failure: errorRecord(error), bound: Boolean(error.details?.native_hook_binding) })}\n`); process.stdout.write(`${JSON.stringify({ decision: "deny", reason: error.message })}\n`); process.exit(2); }
+  const failure = errorRecord(error); process.stderr.write(`${JSON.stringify({ ok: false, error: failure.message, ...failure })}\n`); process.exit(1);
 }

package/dist/harness-runtime/lib/adapter-timeouts.d.mts

@@ -0,0 +1,5 @@
+export const NATIVE_OPERATION_WAIT_CONTRACT: "native-operation-wait@1";
+export function canonicalNativeOperation(harness: string, operation: string): string;
+export function nativeOperationWait(harness: string, operation: string): "native-work" | "control";
+export function validateDaemonWait(harness: string, operation: string, duration: number | null): void;
+export function adapterTimeoutOptions(options: Record<string, unknown>, operation?: string | null, harness?: string): { timeoutMs?: number; livenessTimeoutMs?: number; requestTimeoutMs?: number };

package/dist/harness-runtime/lib/adapter-timeouts.mjs

@@ -0,0 +1,34 @@
+// Public work flags express silence, never the lifetime of a native Turn.
+import { validateObservationDuration } from "./observation-clock.mjs";
+export const NATIVE_OPERATION_WAIT_CONTRACT = "native-operation-wait@1";
+// Grok's resume only inspects its retained native Session. Other adapters
+// materialize that Session, so their original operation remains productive.
+export function canonicalNativeOperation(harness, operation) {
+  return ["grok", "grok-acp"].includes(harness) && operation === "session.resume" ? "session.inspect" : operation;
+}
+// Only Droid's start waits for the full Turn. Codex start returns acceptance;
+// the other bundled adapters do not expose start as a productive operation.
+export function nativeOperationWait(harness, operation) {
+  operation = canonicalNativeOperation(harness, operation);
+  return operation === "session.prompt" || ["droid", "droid-cli"].includes(harness) && operation === "session.start" ? "native-work" : "control";
+}
+export function validateDaemonWait(harness, operation, duration) {
+  if (duration === null && nativeOperationWait(harness, operation) === "native-work") return;
+  validateObservationDuration(duration, "daemon control duration");
+}
+
+export function adapterTimeoutOptions(options, operation, harness) {
+  const duration = name => {
+    if (options[name] === undefined) return undefined;
+    const ms = Number(options[name]) * 1_000;
+    if (!Number.isInteger(ms) || ms < 1 || ms > 2_147_483_647) throw Object.assign(new Error(`--${name} requires positive finite seconds within the timer range`), { code: "invalid_timeout" });
+    return ms;
+  };
+  const timeoutMs = duration("timeout"), livenessTimeoutMs = duration("liveness-timeout"), requestTimeoutMs = duration("request-timeout");
+  if (operation === "prompt" || nativeOperationWait(harness, `session.${operation}`) === "native-work") {
+    if (timeoutMs !== undefined && livenessTimeoutMs !== undefined && timeoutMs !== livenessTimeoutMs) throw Object.assign(new Error("--timeout and --liveness-timeout must agree for session.prompt"), { code: "invalid_timeout" });
+    if (requestTimeoutMs !== undefined) throw Object.assign(new Error("--request-timeout cannot limit a productive prompt"), { code: "invalid_timeout" });
+    return { timeoutMs: undefined, livenessTimeoutMs: livenessTimeoutMs ?? timeoutMs };
+  }
+  return { timeoutMs, livenessTimeoutMs, requestTimeoutMs };
+}

package/dist/harness-runtime/lib/codex-capacity-policy.d.mts

@@ -0,0 +1,10 @@
+export const CAPACITY_POLICY: "codex-overload-burst@1";
+export const OVERLOAD_WINDOW_MS: number;
+export type CapacityRefusal = { policy: string; ordinal: number; session_id: string; turn_id: string; first_observed_at: string; native_terminal_at?: string; native_terminal_basis?: string };
+export function parseCapacityOperation(id: string): { root: string; ordinal: number };
+export function normalizeCodexFailure(error: unknown, sessionId?: string, turnId?: string): null | { code: string; session_id: string; turn_id: string; native_error: Record<string, unknown>; observed_at: unknown; terminal_at: unknown; native_turn_items: unknown; primary_error: { details?: Record<string, unknown> } };
+export function terminalCodexOverload(error: unknown, sessionId?: string, turnId?: string): boolean;
+export function nativeItemsSettled(items: unknown): boolean;
+export function capacityBackoff(error: unknown, ordinal: number, now?: number): number;
+export function refusalObservation(error: unknown, ordinal: number, firstObservedAt: string): CapacityRefusal;
+export function overloadBurst(refusals: CapacityRefusal[]): null | { policy: string; basis: string; elapsed_ms: number; refusals: CapacityRefusal[] };

package/dist/harness-runtime/lib/codex-capacity-policy.mjs

@@ -0,0 +1,89 @@
+/** Pure policy shared by the controller and pinned-engine EVAL consumers. */
+export const CAPACITY_POLICY = "codex-overload-burst@1";
+export const OVERLOAD_WINDOW_MS = 120_000;
+
+function policyError(code, message, details = {}) { return Object.assign(new Error(message), { code, details }); }
+
+export function parseCapacityOperation(id) {
+  if (typeof id !== "string" || !id) throw policyError("capacity_continuation_conflict", "Missing capacity operation identity");
+  const match = /^(.*):capacity:(\d+):session\.prompt$/.exec(id);
+  if (!match) return { root: id, ordinal: 0 };
+  const ordinal = Number(match[2]);
+  if (!Number.isSafeInteger(ordinal) || ordinal < 1 || String(ordinal) !== match[2]) throw policyError("capacity_continuation_conflict", "Capacity ordinal is not a canonical positive safe integer", { operation_id: id });
+  return { root: match[1], ordinal };
+}
+
+export function normalizeCodexFailure(error, expectedSessionId, expectedTurnId) {
+  let current = error;
+  for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
+    if (current.code === "turn_interrupted") {
+      const details = current.details ?? {}, native = details.provider_error;
+      const code = typeof native?.codexErrorInfo === "string" ? native.codexErrorInfo : native?.codexErrorInfo?.code;
+      if (details.terminal_status !== "failed" || typeof details.provider_session_id !== "string" || !details.provider_session_id
+        || expectedSessionId !== undefined && details.provider_session_id !== expectedSessionId
+        || typeof details.turn_id !== "string" || !details.turn_id || details.native_turn_id !== details.turn_id
+        || expectedTurnId !== undefined && details.turn_id !== expectedTurnId || typeof code !== "string") return null;
+      return { code, session_id: details.provider_session_id, turn_id: details.turn_id, native_error: native,
+        observed_at: details.observed_at ?? null, terminal_at: details.terminal_at ?? null, terminal_basis: details.terminal_basis ?? null,
+        native_turn_items: details.native_turn_items ?? null, primary_error: current };
+    }
+    // No arbitrary recursive cause search: an ownership/hook/lifecycle error wins.
+    if (current.code !== "harness_adapter_failed") return null;
+    current = current.details?.cause ?? current.cause;
+  }
+  return null;
+}
+
+export function terminalCodexOverload(error, expectedSessionId, expectedTurnId) {
+  return normalizeCodexFailure(error, expectedSessionId, expectedTurnId)?.code === "serverOverloaded";
+}
+
+export function nativeItemsSettled(items) {
+  return items?.observed === true && typeof items.possible_effects === "boolean" && items.pending !== true
+    && (items.possible_effects === false || items.pending === false);
+}
+
+export function capacityBackoff(error, ordinal, now = Date.now()) {
+  if (!Number.isSafeInteger(ordinal) || ordinal < 1 || !Number.isFinite(now)) throw policyError("capacity_continuation_conflict", "Invalid capacity timing identity");
+  const native = normalizeCodexFailure(error)?.native_error ?? error?.details?.provider_error ?? error;
+  const header = Object.entries(native?.headers ?? {}).find(([key]) => key.toLowerCase() === "retry-after")?.[1];
+  const value = header ?? native?.retryAfter ?? native?.retry_after;
+  let retry = 0;
+  if (value !== undefined && value !== null) {
+    retry = typeof value === "number" || typeof value === "string" && /^\d+(\.\d+)?$/.test(value.trim()) ? Number(value) * 1000 : typeof value === "string" ? Math.max(0, Date.parse(value) - now) : NaN;
+    if (!Number.isFinite(retry) || retry < 0 || !Number.isFinite(now + retry) || now + retry > 8.64e15)
+      throw policyError("capacity_retry_metadata_invalid", "Retry-After cannot be represented safely", { retry_after: value });
+  }
+  return Math.max(ordinal === 1 ? 5_000 : 15_000, retry);
+}
+
+export function refusalObservation(error, ordinal, firstObservedAt) {
+  const failure = normalizeCodexFailure(error);
+  const observed = Date.parse(firstObservedAt);
+  if (!failure || !Number.isSafeInteger(ordinal) || ordinal < 0 || !Number.isFinite(observed))
+    throw policyError("capacity_continuation_conflict", "Refusal lacks an immutable native identity/time");
+  if (failure.observed_at !== null && (typeof failure.observed_at !== "string" || !Number.isFinite(Date.parse(failure.observed_at)) || Date.parse(failure.observed_at) !== observed))
+    throw policyError("capacity_continuation_conflict", "Native refusal observation time is invalid or changed");
+  const native = failure.terminal_at && Date.parse(failure.terminal_at);
+  return { policy: CAPACITY_POLICY, ordinal, session_id: failure.session_id, turn_id: failure.turn_id,
+    first_observed_at: firstObservedAt, ...(Number.isFinite(native) && typeof failure.terminal_basis === "string" && failure.terminal_basis ? { native_terminal_at: failure.terminal_at, native_terminal_basis: failure.terminal_basis } : {}) };
+}
+
+export function overloadBurst(refusals) {
+  for (const [index, refusal] of refusals.entries()) {
+    const previous = refusals[index - 1];
+    if (typeof refusal.first_observed_at !== "string" || !Number.isFinite(Date.parse(refusal.first_observed_at))
+      || previous && Date.parse(refusal.first_observed_at) < Date.parse(previous.first_observed_at))
+      throw policyError("capacity_continuation_conflict", "Refusal observation clock reversed or is invalid");
+  }
+  const continuations = refusals.filter(item => item.ordinal > 0);
+  const pair = continuations.slice(-2);
+  if (pair.length !== 2) return null;
+  const [previous, current] = pair;
+  if (previous.session_id !== current.session_id || previous.turn_id === current.turn_id || current.ordinal !== previous.ordinal + 1)
+    throw policyError("capacity_continuation_conflict", "Refusal chain identity is inconsistent");
+  const basis = previous.native_terminal_at && current.native_terminal_at && previous.native_terminal_basis && previous.native_terminal_basis === current.native_terminal_basis ? "native_terminal_at" : "first_observed_at";
+  const elapsed = Date.parse(current[basis]) - Date.parse(previous[basis]);
+  if (!Number.isFinite(elapsed) || elapsed < 0) throw policyError("capacity_continuation_conflict", "Refusal clock reversed or is invalid");
+  return elapsed <= OVERLOAD_WINDOW_MS ? { policy: CAPACITY_POLICY, basis, elapsed_ms: elapsed, refusals: pair } : null;
+}