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

package/dist/harness-runtime/lib/managed-flow-env.mjs

@@ -0,0 +1,15 @@
+/** Final native overlay: launch-bound routing, never inherited invocation authority. */
+export function managedFlowEnv(config, daemonId = config.daemonId) {
+  const managed = !config.noFlow && Boolean(config.ddFlowHome && config.ddFlowBin && daemonId);
+  return {
+    DD_FLOW_DAEMON_ID: managed ? daemonId : undefined,
+    DD_FLOW_HOME: managed ? config.ddFlowHome : undefined,
+    DD_FLOW_BIN: managed ? config.ddFlowBin : undefined,
+    DD_FLOW_RESOURCE_HOME: config.resourceHome ?? undefined,
+    DD_FLOW_RUNTIME_OWNER: managed && config.runtime_owner ? JSON.stringify(config.runtime_owner) : undefined,
+    DD_FLOW_INVOCATION_SCOPE: undefined, DD_FLOW_CURRENT_INVOCATION: undefined,
+    DD_FLOW_SESSION_ID: undefined, DD_FLOW_WORK_ID: undefined, DD_FLOW_CONTROLLER_TOKEN: undefined,
+    DD_FLOW_CONTROL_TOKEN: undefined, DD_FLOW_SCOPE_CONTROL_TOKEN: undefined,
+    DD_FLOW_HOOK_DEADLINE_AT: undefined,
+  };
+}

package/dist/harness-runtime/lib/native-children.d.mts

@@ -1,4 +1,5 @@
 export const NATIVE_CHILD_CONTRACT_VERSION: "native-children@1";
+export function settledNativeTree(root: string, children: Record<string, unknown>[], settled: boolean, rootSettled?: boolean): Record<string, unknown>;
 export function safeNativeFailure(value: unknown): Record<string, unknown> | undefined;
 export interface NativeChild {
   session_id: string;
@@ -9,6 +10,7 @@ export interface NativeChild {
   terminal_turn_id?: string;
   terminal_observed_at?: string;
   provider_error?: unknown;
+  native_source?: "opencode.v2.session.execution" | "agy.result" | "acp.error_response" | "droid.agent_turn_outcome" | "grok.subagent.event";
   native_turn_items?: { observed?: boolean; possible_effects?: boolean; pending?: boolean };
 }
 export function normalizeNativeChildren(receipt: Record<string, unknown>, rootSessionId: string): NativeChild[];

package/dist/harness-runtime/lib/native-children.mjs

@@ -1,17 +1,35 @@
 export const NATIVE_CHILD_CONTRACT_VERSION = "native-children@1";
 import { errorRecord } from "./operation-errors.mjs";
+import { safeProviderError } from "./provider-overload-policy.mjs";
 
 function nativeFailure(code, message, exitCode, details) { return Object.assign(new Error(message), { code, exitCode, details }); }
 
+/** Project a positively settled native tree, never infer it from missing activity. */
+export function settledNativeTree(root, children, settled, rootSettled = false) {
+  if (settled !== true && rootSettled !== true || typeof root !== "string" || !root || !Array.isArray(children)) return {};
+  const ids = children.map(child => child.provider_session_id ?? child.session_id ?? child.childSessionId ?? child.sessionId);
+  if (ids.some(id => typeof id !== "string" || !id || id === root) || new Set(ids).size !== ids.length) return {};
+  const observations = [{ provider_session_id: root, status: "idle", settled: true }, ...children.map((child, index) => {
+    const status = String(child.status ?? child.state ?? "unknown").toLowerCase();
+    const terminal = settled === true || ["completed", "success", "succeeded", "failed", "cancelled", "canceled", "settled_by_root"].includes(status);
+    return { provider_session_id: ids[index], status: terminal ? "idle" : ["running", "active", "inprogress", "pending"].includes(status) ? "running" : "unknown", settled: terminal };
+  })];
+  return { tree_session_ids: [root, ...ids], unsettled_sessions: observations.filter(item => !item.settled).map(item => item.provider_session_id), tree_observations: observations };
+}
+
 /** Retain typed failure facts, never provider headers, request bodies or free-form messages. */
 export function safeNativeFailure(value, depth = 0) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const result = {};
-  for (const key of ["type", "code", "source", "reason", "errorPhase", "exceptionKind", "providerId", "modelId", "providerKind", "transport", "retryable", "willRetry", "statusCode", "resets_at", "retryAfter", "retry_after", "retryAfterMs", "resetAt"]) {
+  for (const key of ["type", "code", "source", "reason", "errorPhase", "exceptionKind", "providerId", "modelId", "providerKind", "transport", "retryable", "willRetry", "statusCode", "resets_at", "retryAfterMs", "resetAt"]) {
     const scalar = value[key];
     if (typeof scalar === "boolean" || typeof scalar === "number" && Number.isFinite(scalar)
       || typeof scalar === "string" && scalar.length <= 256 && /^[\w.:/ -]+$/.test(scalar)) result[key] = scalar;
   }
+  // Timing metadata is not an identifier: HTTP dates contain commas and an
+  // invalid value must reach the policy as invalid, not disappear into default backoff.
+  const timing = safeProviderError(value);
+  if (Object.hasOwn(timing, "retryAfter")) result.retryAfter = timing.retryAfter;
   if (typeof value.codexErrorInfo === "string" && /^[\w-]{1,128}$/.test(value.codexErrorInfo)) result.codexErrorInfo = value.codexErrorInfo;
   else if (value.codexErrorInfo && typeof value.codexErrorInfo.code === "string" && /^[\w-]{1,128}$/.test(value.codexErrorInfo.code)) result.codexErrorInfo = { code: value.codexErrorInfo.code };
   const attribution = depth === 0 && value.attribution && safeNativeFailure(value.attribution, 1);
@@ -55,6 +73,7 @@ export function normalizeNativeChildren(receipt, rootSessionId) {
       ...(text(value, ["terminal_turn_id"]) ? { terminal_turn_id: text(value, ["terminal_turn_id"]) } : {}),
       ...(text(value, ["terminal_observed_at"]) ? { terminal_observed_at: text(value, ["terminal_observed_at"]) } : {}),
       ...(value.provider_error !== undefined ? { provider_error: value.provider_error } : {}),
+      ...(["opencode.v2.session.execution", "agy.result", "acp.error_response", "droid.agent_turn_outcome", "grok.subagent.event"].includes(value.native_source) ? { native_source: value.native_source } : {}),
       ...(value.native_turn_items && typeof value.native_turn_items === "object" ? { native_turn_items: value.native_turn_items } : {}) });
   };
   for (const value of list(receipt.descendants)) add(value, "adapter.descendants");

package/dist/harness-runtime/lib/native-hook-command.mjs

@@ -62,7 +62,7 @@ export async function readNativeHookFailures(stateDir, requests, current, reject
 }
 
 /** The caller supplies its qualified native limit; phases share that deadline. */
-export function hookBudget(timeoutMs = 25_000, deadlineAt = process.env.DD_FLOW_HOOK_DEADLINE_AT === undefined ? null : Number(process.env.DD_FLOW_HOOK_DEADLINE_AT)) {
+export function hookBudget(timeoutMs = 25_000, deadlineAt = process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null) {
   if (deadlineAt !== null && (!Number.isSafeInteger(deadlineAt) || deadlineAt < 0)) throw Object.assign(new Error("Invalid native hook deadline"), { code: "hook_deadline_invalid", details: { effect: "unknown" } });
   const started = performance.now();
   const duration = Math.max(0, Math.min(timeoutMs, Number.isFinite(deadlineAt) ? deadlineAt - Date.now() : timeoutMs));

package/dist/harness-runtime/lib/native-request-proof.d.mts

@@ -0,0 +1,2 @@
+export function nativeCommandFingerprint(input: { executable: string; args: string[]; cwd: string; env: Record<string, string | undefined>; operationId: string }): string;
+export function prepareDaemonRequest<T extends { id: string; operation: string; params?: Record<string, unknown> }>(request: T): T & { invocation_sha256?: string };

package/dist/harness-runtime/lib/native-request-proof.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import { hashJson } from './runner-events.mjs';
+
+const environmentKeys = ['HOME', 'CODEX_HOME', 'DD_FLOW_CONFIG_HOME', 'DD_FLOW_RESOURCE_HOME', 'DD_FLOW_HOME', 'DD_FLOW_BIN', 'DD_FLOW_ENGINE_HOME'];
+const fail = reason => { throw Object.assign(new Error('Native request proof does not match its prepared command'), {
+  code: 'native_request_proof_conflict', details: { reason, effect: 'no_effect' }
+}); };
+
+/** Independent transport identity: prepared by the caller before launching
+ * the adapter, and recomputed by the adapter's shared request builder. */
+export function nativeCommandFingerprint({ executable, args, cwd, env, operationId }) {
+  return hashJson({ executable, args, cwd, operation_id: operationId,
+    environment: Object.fromEntries(environmentKeys.map(key => [key, env[key] ?? null])) });
+}
+
+/** Called after the adapter's own argument preparation but before its RPC or
+ * daemon-start action. No provider response can supply this fingerprint. */
+export function prepareDaemonRequest(request) {
+  const file = process.env.DD_FLOW_NATIVE_REQUEST_PROOF_FILE;
+  const expected = process.env.DD_FLOW_NATIVE_COMMAND_SHA256;
+  const operation = process.env.DD_FLOW_NATIVE_REQUEST_OPERATION;
+  if (file === undefined && expected === undefined) return request;
+  // Control helpers may inspect status before their owned stop RPC. Status
+  // cannot consume the productive/control request's independently bound proof.
+  if (operation && request.operation !== operation) {
+    if (request.operation === 'daemon.status' && operation === 'daemon.stop') return request;
+    fail('operation_changed');
+  }
+  const ownerText = process.env.DD_FLOW_NATIVE_REQUEST_PROOF_OWNER;
+  // Never forward caller proof authority into the daemon/provider process.
+  delete process.env.DD_FLOW_NATIVE_REQUEST_PROOF_FILE;
+  delete process.env.DD_FLOW_NATIVE_COMMAND_SHA256;
+  delete process.env.DD_FLOW_NATIVE_REQUEST_OPERATION;
+  delete process.env.DD_FLOW_NATIVE_REQUEST_PROOF_OWNER;
+  if (!file || !path.isAbsolute(file) || !/^[a-f0-9]{64}$/.test(expected ?? '')
+    || typeof request.id !== 'string' || !request.id || typeof request.operation !== 'string' || request.operation !== operation) fail('invalid_owner');
+  const command = nativeCommandFingerprint({ executable: process.argv[1], args: process.argv.slice(2),
+    cwd: process.cwd(), env: process.env, operationId: request.id });
+  if (command !== expected || fs.realpathSync(path.dirname(file)) !== path.dirname(file)) fail('command_changed');
+  let owner;
+  try { owner = JSON.parse(ownerText ?? 'null'); } catch { fail('invalid_parent_owner'); }
+  const parent = fs.lstatSync(path.dirname(file));
+  if (!parent.isDirectory() || parent.dev !== owner?.dev || parent.ino !== owner?.ino) fail('proof_parent_changed');
+  const proof = { schema_id: 'dd-flow/native-request-proof@1', operation_id: request.id, operation: request.operation,
+    command_sha256: command, params_sha256: hashJson({ operation: request.operation, params: request.params ?? {} }),
+    session_id: request.params?.sessionId ?? null };
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const fd = fs.openSync(temporary, 'wx', 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(proof)); fs.fsyncSync(fd);
+    const current = fs.lstatSync(path.dirname(file));
+    if (parent.dev !== current.dev || parent.ino !== current.ino || !current.isDirectory()) fail('proof_parent_changed');
+    try { fs.linkSync(temporary, file); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.nlink !== 1 || stat.size > 16 * 1024
+        || hashJson(JSON.parse(fs.readFileSync(file, 'utf8'))) !== hashJson(proof)) fail('retained_request_changed');
+    }
+  } finally { fs.closeSync(fd); fs.unlinkSync(temporary); }
+  return { ...request, invocation_sha256: command };
+}

package/dist/harness-runtime/lib/opencode-plugin.mjs

@@ -1,19 +1,25 @@
 import path from "node:path";
+import { managedFlowEnv } from './managed-flow-env.mjs';
 import * as Plugin from "../vendor/opencode-plugin.mjs";
-import { hookBudget, invokeNativeHook } from "./native-hook-command.mjs";
+import { hookBudget, invokeNativeHook, writeNativeHookFailure } from "./native-hook-command.mjs";
+import { callDaemon } from "./dd-opencode-daemon.mjs";
+import { errorRecord } from "./operation-errors.mjs";
 
 /** Launch-bound server plugin; never uses a process-global 'last Session'. */
-export function makeOpenCodePlugin(binding, invoke = invokeNativeHook) {
+export function makeOpenCodePlugin(binding, invoke = invokeNativeHook, resolve = callDaemon) {
   return Plugin.define({ id: binding.ddFlowBin ? "dd-flow" : "dd-flow-security", async setup(ctx) {
     const participating = new Map();
     const key = event => JSON.stringify([binding.daemonId, event.sessionID, event.messageID, event.id]);
     const envelope = async (phase, event, budget, outcome) => {
-      const info = await budget.run(() => ctx.session.get({ sessionID: event.sessionID }), "identity");
-      if (!info?.id || info.id !== event.sessionID || !info.location?.directory) throw new Error("OpenCode Session identity is unavailable");
       const input = event.input;
       if (!input || typeof input !== "object" || typeof input.command !== "string") throw new Error("OpenCode shell input is unavailable");
-      const cwd = path.resolve(info.location.directory, input.workdir ?? ".");
+      const identity = await budget.run(() => resolve(binding.stateDir, "hook.resolve", { sessionId: event.sessionID,
+        payload: { phase, message_id: event.messageID, tool_call_id: event.id, input } }, budget.remaining("identity")), "identity");
+      const info = identity?.nativeSession;
+      if (!identity?.nativeHookBinding || info?.id !== event.sessionID || !info.directory) throw Object.assign(new Error("OpenCode Session identity is unavailable"), { code: "native_hook_unproven" });
+      const cwd = path.resolve(info.directory, input.workdir ?? ".");
       return { schema_id: "dd-flow/opencode-tool-event@1", native_protocol: 2,
+        native_hook_binding: identity.nativeHookBinding,
         event_id: [binding.daemonId, event.sessionID, event.messageID, event.id].join(":"), phase,
         daemon_id: binding.daemonId, server_version: binding.version, plugin_sha256: process.env.DD_OPENCODE_PLUGIN_SHA256,
         session: { provider_session_id: info.id, parent_provider_session_id: info.parentID ?? null,
@@ -22,10 +28,28 @@ export function makeOpenCodePlugin(binding, invoke = invokeNativeHook) {
         profile: { provider: info.model?.providerID, model: info.model?.id, variant: info.model?.variant ?? "default", agent: event.agent },
         input: { ...input, workdir: cwd }, ...(outcome ? { outcome } : {}) };
     };
-    const deliver = (payload, budget) => invoke({ bin: binding.ddFlowBin, nodeBin: binding.nodeBin,
-      args: ["opencode", "event", "handle", "--project-root", binding.projectRoot, "--json"],
-      payload, home: binding.ddFlowHome, timeoutMs: budget.remaining("admission", 15000) });
+    const deliver = async (payload, budget) => {
+      const identity = { nativeHookBinding: payload.native_hook_binding };
+      try {
+        const result = await invoke({ bin: binding.ddFlowBin, nodeBin: binding.nodeBin,
+          args: ["opencode", "event", "handle", "--project-root", binding.projectRoot, "--json"],
+          payload: { ...payload, native_hook_binding: identity.nativeHookBinding }, home: binding.ddFlowHome, timeoutMs: budget.remaining("admission", 15000) });
+        await budget.run(() => resolve(binding.stateDir, "hook.verify", { binding: identity.nativeHookBinding }, budget.remaining("generation")), "generation");
+        if (result?.permissionDecision === "deny" || result?.hookSpecificOutput?.permissionDecision === "deny") throw Object.assign(new Error("dd-flow denied native shell admission"), { code: "native_hook_rejected" });
+        return result;
+      } catch (error) {
+        error.details = { ...error.details, native_hook_binding: identity.nativeHookBinding, ...(payload.phase === "after" ? { effect: "unknown", tool_outcome: payload.outcome } : {}) };
+        try { await writeNativeHookFailure(binding.stateDir, identity.nativeHookBinding, error, hookBudget(1_000, null)); await resolve(binding.stateDir, "hook.failed", {}, 1_000); }
+        catch (storage) {
+          error.details.receipt_error = { code: storage.code ?? "hook_receipt_write_failed", message: storage.message };
+          try { await resolve(binding.stateDir, "hook.failed", { binding: identity.nativeHookBinding, failure: errorRecord(error) }, 1_000); }
+          catch (notify) { error.details.receipt_error.notification_error = notify.code ?? "hook_notification_failed"; }
+        }
+        throw error;
+      }
+    };
     await ctx.shell.hook("create.before", event => {
+      Object.assign(event.env, managedFlowEnv(binding));
       delete event.env.OPENCODE_PASSWORD; delete event.env.OPENCODE_SERVER_PASSWORD;
     });
     await ctx.tool.hook("execute.before", async event => {
@@ -35,7 +59,6 @@ export function makeOpenCodePlugin(binding, invoke = invokeNativeHook) {
       const budget = hookBudget(), payload = await envelope("before", event, budget);
       event.input = { ...event.input, workdir: payload.session.directory };
       const result = await deliver({ ...payload, input: event.input }, budget);
-      if (result?.permissionDecision === "deny" || result?.hookSpecificOutput?.permissionDecision === "deny") throw new Error("dd-flow denied native shell admission");
       if (result?.observed) {
         participating.set(key(event), payload);
         await ctx.storage.set(key(event), JSON.parse(JSON.stringify(payload)));

package/dist/harness-runtime/lib/operation-progress.mjs

@@ -64,7 +64,9 @@ export function publishOperationProgress(root, id, phase, metadata = {}) {
     const prior = await readOperationProgress(root, id);
     const observedAt = metadata.observed_at ?? new Date().toISOString();
     if (prior && Date.parse(observedAt)<Date.parse(prior.observed_at)) return prior;
-    if (prior && phase === prior.phase && phase !== 'native_progress') return prior;
+    // A later successful ownership gate is fresh liveness evidence while admission waits.
+    if (prior && phase === prior.phase && phase !== 'native_progress'
+      && (phase !== 'ownership_confirmed' || Date.parse(observedAt) <= Date.parse(prior.observed_at))) return prior;
     if (prior && phase === 'native_progress' && Date.parse(observedAt) - Date.parse(prior.observed_at) < 1_000) return prior;
     const value = { schema_id: OPERATION_PROGRESS_CONTRACT,
       ...Object.fromEntries(fields.map(field => [field, requested[field] ?? null])),

package/dist/harness-runtime/lib/provider-overload-policy.d.mts

@@ -0,0 +1,13 @@
+export const CAPACITY_POLICY: "provider-overload-episode@1";
+export const MAX_OVERLOAD_RETRIES: 2;
+export const MAX_RETRY_AFTER_MS: 30000;
+export function classifyProviderError(native: unknown): string;
+export function safeProviderError(native: unknown): Record<string, unknown>;
+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 normalizeProviderFailure(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 terminalProviderOverload(error: unknown, sessionId?: string, turnId?: string): boolean;
+export function nativeItemsSettled(items: unknown): boolean;
+export function capacityBackoff(error: unknown, ordinal: number, now?: number, random?: () => number): number;
+export function refusalObservation(error: unknown, ordinal: number, firstObservedAt: string): CapacityRefusal;
+export function overloadExhausted(refusals: CapacityRefusal[], maxRetries?: number): null | { policy: string; reason: string; attempts: number; refusals: CapacityRefusal[] };

package/dist/harness-runtime/lib/provider-overload-policy.mjs

@@ -0,0 +1,138 @@
+/** Pure policy shared by the controller and pinned-engine EVAL consumers. */
+export const CAPACITY_POLICY = "provider-overload-episode@1";
+export const MAX_OVERLOAD_RETRIES = 2;
+export const MAX_RETRY_AFTER_MS = 30_000;
+
+function policyError(code, message, details = {}) { return Object.assign(new Error(message), { code, details }); }
+
+/** Only call on a native error envelope, never prompt or tool output. */
+export function classifyProviderError(native) {
+  if (!native || typeof native !== "object") return "provider_failed";
+  const code = [native.code, native.type, native.codexErrorInfo?.code ?? native.codexErrorInfo].filter(value => typeof value === "string").join(" ");
+  const message = String(native.message ?? "");
+  const text = `${code} ${message}`;
+  const status = Number(native.status ?? native.statusCode ?? native.status_code ?? native.http_status);
+  if (status === 402 || /quota|usageLimitExceeded|sessionBudgetExceeded|billing|payment.required|balance.exhausted|insufficient.credit|resource_exhausted.*limit/i.test(text)) return "provider_quota_exhausted";
+  if (status === 401 || status === 403 || /provider_auth_failed|invalid.api.key|authentication|unauthorized|eligib|forbidden|access.denied|rejected.this.account/i.test(text)) return "provider_auth_failed";
+  if (/provider_capacity_transient|serverOverloaded|model.?capacity|at capacity|server.overload|model.overload|server.?busy/i.test(text) || /(?:^|\s)overloaded_error(?:\s|$)/i.test(code) || status === 503 || status === 529) return "provider_capacity_transient";
+  if (/rateLimitExceeded|rate.limit/i.test(text) && (native.retryAfter !== undefined || native.retry_after !== undefined || Object.keys(native.headers ?? {}).some(key => key.toLowerCase() === "retry-after"))) return "provider_rate_limited";
+  return status === 429 || /provider_limit_unknown|\b429\b|rateLimitExceeded|rate.limit/i.test(text) ? "provider_limit_unknown" : "provider_failed";
+}
+
+/** Public retry evidence excludes response bodies, credentials and other headers. */
+export function safeProviderError(native) {
+  const result = { code: classifyProviderError(native) };
+  if (!native || typeof native !== "object") return result;
+  const status = native.status ?? native.statusCode ?? native.status_code ?? native.http_status;
+  if (Number.isInteger(Number(status))) result.status = Number(status);
+  const header = Object.entries(native.headers ?? {}).find(([key]) => key.toLowerCase() === "retry-after")?.[1];
+  const retry = header ?? native.retryAfter ?? native.retry_after;
+  if (retry !== undefined && retry !== null) result.retryAfter = typeof retry === "string" && retry.length <= 128 || typeof retry === "number" && Number.isFinite(retry) ? retry : "invalid-retry-after";
+  if (typeof native.willRetry === "boolean") result.willRetry = native.willRetry;
+  for (const key of ["reset_at", "resets_at", "resetAt", "resetsAt", "reset_time"]) {
+    const value = native[key];
+    if (typeof value === "string" && value.length <= 128 || typeof value === "number" && Number.isFinite(value)) result[key] = value;
+  }
+  return result;
+}
+
+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 normalizeProviderFailure(error, expectedSessionId, expectedTurnId) {
+  let current = error;
+  for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
+    // The same continuation authority applies to a proven v2 execution
+    // refusal. Never classify transport loss or an active native retry here.
+    if (current.code === "provider_capacity_transient" || current.code === "provider_rate_limited") {
+      const details = current.details ?? {};
+      if (!["opencode.v2.session.execution", "agy.result", "acp.error_response", "droid.agent_turn_outcome", "grok.subagent.event"].includes(details.native_source) || details.terminal_status !== "failed"
+        || details.will_retry === true || details.native_retry_active === true || details.provider_error?.willRetry === true
+        || details.provider_error && !["provider_capacity_transient", "provider_rate_limited"].includes(classifyProviderError(details.provider_error))
+        || typeof details.provider_session_id !== "string" || !details.provider_session_id
+        || typeof details.turn_id !== "string" || !details.turn_id || details.native_turn_id !== details.turn_id
+        || expectedSessionId !== undefined && details.provider_session_id !== expectedSessionId
+        || expectedTurnId !== undefined && details.turn_id !== expectedTurnId) return null;
+      return { code: "serverOverloaded", session_id: details.provider_session_id, turn_id: details.turn_id,
+        native_error: details.provider_error ?? { type: details.native_error_type, status: details.http_status }, observed_at: details.observed_at ?? null,
+        terminal_at: null, terminal_basis: null, native_turn_items: details.native_turn_items ?? null, primary_error: current };
+    }
+    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 (native?.willRetry === true || 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 terminalProviderOverload(error, expectedSessionId, expectedTurnId) {
+  const normalized = normalizeProviderFailure(error, expectedSessionId, expectedTurnId);
+  return normalized !== null && ["provider_capacity_transient", "provider_rate_limited"].includes(classifyProviderError(normalized.native_error));
+}
+
+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(), random = Math.random) {
+  if (!Number.isSafeInteger(ordinal) || ordinal < 1 || !Number.isFinite(now)) throw policyError("capacity_continuation_conflict", "Invalid capacity timing identity");
+  const native = normalizeProviderFailure(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" && /^\w{3}, \d{2} \w{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value.trim()) ? 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 });
+  }
+  const jitter = random();
+  if (!Number.isFinite(jitter) || jitter < 0 || jitter >= 1) throw policyError("capacity_retry_metadata_invalid", "Invalid retry jitter");
+  const wait = Math.max((ordinal === 1 ? 5_000 : 15_000) + Math.floor(jitter * 251), retry);
+  if (wait > MAX_RETRY_AFTER_MS) throw policyError("provider_unavailable", "Provider requested a delay beyond the retry budget", { policy: CAPACITY_POLICY, reason: "retry_after_exceeds_budget", retry_after_ms: retry, suggested_retry_at: new Date(now + retry).toISOString() });
+  return wait;
+}
+
+export function refusalObservation(error, ordinal, firstObservedAt) {
+  const failure = normalizeProviderFailure(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 overloadExhausted(refusals, maxRetries = MAX_OVERLOAD_RETRIES) {
+  if (!Number.isSafeInteger(maxRetries) || maxRetries < 0 || maxRetries > MAX_OVERLOAD_RETRIES) throw policyError("capacity_continuation_conflict", "Invalid retry budget");
+  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");
+  }
+  for (const [index, refusal] of refusals.entries()) {
+    if (refusal.policy !== CAPACITY_POLICY) throw policyError("capacity_policy_mismatch", "Retained episode uses another retry policy");
+    const previous = refusals[index - 1];
+    if (refusal.ordinal !== index || previous && (refusal.session_id !== previous.session_id || refusals.slice(0, index).some(item => item.turn_id === refusal.turn_id))) throw policyError("capacity_continuation_conflict", "Refusal chain identity is inconsistent");
+  }
+  return refusals.length > maxRetries ? { policy: CAPACITY_POLICY, reason: "overload_retries_exhausted", attempts: refusals.length, refusals } : null;
+}

package/dist/runtime/context.js

@@ -11,7 +11,7 @@ export function createRouterContext(env, deadlineAt) {
 }
 export function createContext(env, mode = "initialize", importPermitId, options = {}) {
     const ddFlowHome = resolveDdFlowHome(env);
-    if (options.resourceDatabaseMode === "prepared_existing" || options.resourceDatabaseMode === "initialize")
+    if (options.resourceDatabaseMode === "prepared_existing" || options.resourceDatabaseMode === "initialize" || options.resourceDatabaseMode === "create_new")
         assertImportAdmission(ddFlowHome, importPermitId);
     return {
         ddFlowHome,

package/dist/schemas/discovery-result.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/discovery-result@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_id",
+    "request_id",
+    "observed_at",
+    "probe_scope",
+    "live_authorization_receipt",
+    "entries"
+  ],
+  "properties": {
+    "schema_id": {
+      "const": "dd-flow/discovery-result@1"
+    },
+    "request_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "observed_at": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$"
+    },
+    "probe_scope": {
+      "enum": [
+        "static",
+        "non-generative",
+        "live"
+      ]
+    },
+    "live_authorization_receipt": {
+      "anyOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "path",
+            "sha256"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "pattern": "^[a-zA-Z0-9_-][a-zA-Z0-9_.-]*(/[a-zA-Z0-9_-][a-zA-Z0-9_.-]*)*$"
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            }
+          }
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "entries": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "harness",
+          "candidates",
+          "installed",
+          "compatible",
+          "protocol",
+          "auth",
+          "qualified",
+          "reason",
+          "evidence"
+        ],
+        "properties": {
+          "harness": {
+            "enum": [
+              "codex",
+              "zcode",
+              "agy",
+              "opencode",
+              "grok",
+              "droid"
+            ]
+          },
+          "candidates": {
+            "type": "array",
+            "minItems": 0,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "path",
+                "version",
+                "selected"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "version": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "selected": {
+                  "type": "boolean"
+                }
+              }
+            }
+          },
+          "installed": {
+            "enum": [
+              "yes",
+              "no",
+              "unknown"
+            ]
+          },
+          "compatible": {
+            "enum": [
+              "yes",
+              "no",
+              "unknown"
+            ]
+          },
+          "protocol": {
+            "enum": [
+              "verified",
+              "incompatible",
+              "unknown"
+            ]
+          },
+          "auth": {
+            "enum": [
+              "verified",
+              "unavailable",
+              "unknown"
+            ]
+          },
+          "qualified": {
+            "enum": [
+              "yes",
+              "no",
+              "unknown"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          },
+          "evidence": {
+            "type": "array",
+            "minItems": 0,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "path",
+                "sha256"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9_-][a-zA-Z0-9_.-]*(/[a-zA-Z0-9_-][a-zA-Z0-9_.-]*)*$"
+                },
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}