@deksden-com/dd-flow-cli 0.9.0-beta.133 → 0.9.0-beta.135

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

@@ -1,128 +1,323 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 import { ToolObservations, openCodeToolObservation } from "./tool-observations.mjs";
-import { observedTimeout, validateObservationDuration } from "./observation-clock.mjs";
+import { ObservationClock, observedTimeout, validateObservationDuration } from "./observation-clock.mjs";
 import { assertNativeLine } from "./native-streams.mjs";
 import { operationProgressReporter } from "./operation-progress.mjs";
 
+export const OPENCODE_PROTOCOL = 2;
 export class OpenCodeError extends Error {
-  constructor(code, message, retryable = false, details) { super(message); this.code = code; this.retryable = retryable; this.details = details; }
+  constructor(code, message, retryable = false, details) { super(message); Object.assign(this, { code, retryable, details }); }
+}
+const lost = (message, details) => new OpenCodeError("operation_observation_lost", message, false, { native_outcome: "unknown", ...details });
+export const requestDigest = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const nativeModel = ({ provider, model, variant }) => ({ providerID: provider, id: model, ...(variant && variant !== "default" ? { variant } : {}) });
+
+/** info/parts is our normalized projection, not a second v1 native protocol. */
+export function normalizeMessage(message, sessionID) {
+  if (!message?.id || !message.type) throw lost("OpenCode message has no native identity");
+  const { model, time = {} } = message;
+  const parts = (message.content ?? []).map(part => part.type === "tool"
+    ? { ...part, tool: part.name, callID: part.id, state: { ...part.state, output: part.state?.result ?? part.state?.output } }
+    : { ...part });
+  if (message.type !== "assistant" && typeof message.text === "string") parts.push({ type: "text", text: message.text });
+  return { info: { id: message.id, sessionID, role: message.type, providerID: model?.providerID, modelID: model?.id,
+    variant: model?.variant ?? "default", mode: message.agent, finish: message.finish, error: message.error,
+    cost: message.cost, tokens: message.tokens, created: time.created, completed: time.completed, metadata: message.metadata, outcome: message.outcome }, parts };
+}
+
+export function providerFailure(native, sessionId, turnId) {
+  const message = String(native?.message ?? "OpenCode execution failed"), status = native?.status, type = String(native?.type ?? "unknown");
+  const quota = status === 402 || /quota|balance exhausted|insufficient.?credit|billing|payment required/i.test(message);
+  const code = quota ? "provider_quota_exhausted" : status === 401 || status === 403 ? "provider_auth_failed"
+    : /overload|server.?busy/i.test(`${type} ${message}`) || status === 503 ? "provider_capacity_transient"
+    : /rate.?limit|too many requests/i.test(message) ? "provider_rate_limited"
+    : status === 429 ? "provider_limit_unknown" : "opencode_provider_failed";
+  // Never forward response.body or provider credentials into controller/Judge.
+  return new OpenCodeError(code, `OpenCode native execution failed (${type}${status ? `, HTTP ${status}` : ""})`,
+    ["provider_capacity_transient", "provider_rate_limited"].includes(code), {
+      provider_session_id: sessionId, session_id: sessionId, turn_id: turnId, native_error_type: type,
+      native_turn_id: turnId, terminal_status: "failed",
+      ...(Number.isInteger(status) ? { http_status: status } : {}), observed_at: new Date().toISOString(), native_source: "opencode.v2.session.execution" });
 }
 
 export class OpenCodeClient {
-  constructor({ baseUrl, password, directory, timeoutMs = 1_800_000 }) {
-    this.baseUrl = new URL(baseUrl); this.password = password; this.directory = directory; this.timeoutMs = timeoutMs;
+  constructor({ baseUrl, password, directory, timeoutMs = 1_800_000, api }) {
+    Object.assign(this, { baseUrl: new URL(baseUrl), password, directory, timeoutMs });
+    this.ready = api ? Promise.resolve(api) : import("../vendor/opencode-client/promise/index.js").then(({ OpenCode }) => OpenCode.make({
+      baseUrl: this.baseUrl.href, headers: { authorization: `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}` }
+    }));
   }
-  async request(method, pathname, body, { directory = this.directory, timeoutMs = this.timeoutMs, progress, onDispatched } = {}) {
-    const url = new URL(pathname, this.baseUrl); if (directory) url.searchParams.set("directory", directory);
-    const controller = new AbortController(); const timer = observedTimeout(() => controller.abort(), timeoutMs, { progress });
+  async call(method, input, { timeoutMs, progress, onDispatched, productive = false } = {}) {
+    const observation = this.readObservation?.();
+    timeoutMs ??= observation?.timeoutMs ?? this.timeoutMs; progress ??= observation?.progress;
+    const api = await this.ready, controller = new AbortController();
+    const timer = observedTimeout(() => controller.abort(), timeoutMs, { progress });
     try {
-      const pending = fetch(url, { method, headers: { authorization: `Basic ${Buffer.from(`opencode:${this.password}`).toString("base64")}`, ...(body === undefined ? {} : { "content-type": "application/json" }) }, body: body === undefined ? undefined : JSON.stringify(body), signal: controller.signal });
-      void pending.catch(() => {}); await onDispatched?.(); const response = await pending;
-      let text = "";
-      const decoder = new TextDecoder();
-      if (response.body) for await (const chunk of response.body) { text += decoder.decode(chunk, { stream: true }); assertNativeLine(text); }
-      text += decoder.decode(); assertNativeLine(text);
-      let value = null; try { value = text ? JSON.parse(text) : null; } catch { value = text; }
-      if (!response.ok) throw new OpenCodeError(response.status === 404 ? "session_not_found" : "opencode_http_error", `OpenCode ${method} ${pathname} returned ${response.status}`, response.status >= 500, value);
-      return value;
-    } catch (error) {
-      controller.abort();
-      if (error instanceof OpenCodeError || error.code === "operation_observation_lost") throw error;
-      // Aborting HTTP only loses the observer; it does not cancel the provider.
-      throw Object.assign(new OpenCodeError(error.name === "AbortError" || method === "POST" ? "operation_observation_lost" : "opencode_unavailable", error.message, true, { method, pathname }), { cause: error });
-    } finally { clearTimeout(timer); }
+      const keys = method.split("."), name = keys.pop(), domain = keys.reduce((value, key) => value?.[key], api);
+      if (typeof domain?.[name] !== "function") throw new OpenCodeError("opencode_capability_missing", `OpenCode v2 does not expose ${method}`);
+      const options = { signal: controller.signal };
+      const pending = input === undefined ? domain[name](options) : domain[name](input, options);
+      void pending.catch(() => {}); await onDispatched?.(); const result = await pending;
+      assertNativeLine(JSON.stringify(result ?? null)); return result;
+    } catch (cause) {
+      if (cause instanceof OpenCodeError || cause.code === "operation_observation_lost") throw cause;
+      if (cause._tag === "SessionNotFoundError" || cause._tag === "NotFoundError") throw new OpenCodeError("session_not_found", "OpenCode native Session is unavailable");
+      if (productive && ["InvalidRequestError", "ConflictError", "UnauthorizedError", "ForbiddenError"].includes(cause._tag))
+        throw new OpenCodeError("opencode_admission_rejected", "OpenCode rejected native admission", false, { effect: "no_effect", native_type: cause._tag });
+      if (productive || controller.signal.aborted) throw Object.assign(lost(`OpenCode observer lost during ${method}`, { method }), { cause });
+      throw Object.assign(new OpenCodeError("opencode_unavailable", `OpenCode ${method} observation failed`, true,
+        { method, native_type: cause._tag ?? cause.name ?? null, native_reason: cause.reason ?? null }), { cause });
+    } finally { clearInterval(timer); }
+  }
+  async health() {
+    const info = await this.call("server.info", undefined, { timeoutMs: 5_000 });
+    if (!/^2\./.test(info?.version) || !Number.isInteger(info.pid)) throw new OpenCodeError("unsupported_version", "OpenCode v2 server identity is unavailable");
+    return info;
+  }
+  async pages(method, input) {
+    const items = new Map(), seen = new Set(); let cursor;
+    do {
+      const page = await this.call(method, { ...input, limit: 100, ...(cursor ? { cursor } : { order: "asc" }) });
+      if (!Array.isArray(page?.data)) throw lost(`OpenCode ${method} returned an invalid page`);
+      for (const item of page.data) { if (!item?.id) throw lost("OpenCode page item has no identity"); items.set(item.id, item); }
+      cursor = page.cursor?.next;
+      if (cursor && seen.has(cursor)) throw lost("OpenCode pagination cursor repeated");
+      if (cursor) seen.add(cursor);
+    } while (cursor);
+    return [...items.values()];
+  }
+  create(title, profile = {}, id) { return this.call("session.create", { ...(title ? { title } : {}), ...(id ? { id } : {}),
+    location: { directory: this.directory }, agent: profile.agent ?? "build", model: nativeModel(profile) }, { productive: true }); }
+  async inspect(id) { const info = await this.call("session.get", { sessionID: id }); return { ...info, directory: info.location?.directory }; }
+  list() { return this.pages("session.list", { directory: this.directory }); }
+  async statuses() { const active = await this.call("session.active"); return Object.fromEntries(Object.keys(active).map(id => [id, { type: "busy" }])); }
+  async children(id) { return (await this.pages("session.list", { parentID: id })).map(info => ({ ...info, directory: info.location?.directory })); }
+  async messages(id) { return (await this.pages("message.list", { sessionID: id })).map(message => normalizeMessage(message, id)); }
+  inbox(id) { return this.call("session.inbox.list", { sessionID: id }); }
+  async shells(id) { const result = await this.call("shell.list", { location: { directory: this.directory } }); return result.data.filter(item => item.metadata?.sessionID === id); }
+  async pending(id) {
+    const [inbox, forms, permissions] = await Promise.all([this.inbox(id), this.call("session.form.list", { sessionID: id }), this.call("permission.list", { sessionID: id })]);
+    const value = { inbox, forms: forms.data ?? forms, permissions: permissions.data ?? permissions };
+    if (Object.values(value).some(items => !Array.isArray(items))) throw lost("OpenCode returned invalid pending-input evidence", { session_id: id });
+    return value;
+  }
+  async logs(id, after = 0) {
+    const api = await this.ready, controller = new AbortController(), events = [];
+    const observation = this.readObservation?.();
+    const timer = observedTimeout(() => controller.abort(), observation?.timeoutMs ?? this.timeoutMs, { progress: observation?.progress });
+    try { for await (const event of api.session.log({ sessionID: id, after, follow: false }, { signal: controller.signal })) events.push(event); }
+    catch (cause) { throw Object.assign(lost("OpenCode durable log observation failed", { session_id: id }), { cause }); }
+    finally { clearInterval(timer); }
+    return events;
+  }
+  async abort(id) {
+    // Queued input must not become fresh work during interruption cleanup.
+    for (const item of await this.inbox(id)) await this.call("session.inbox.cancel", { sessionID: id, inboxID: item.id }, { productive: true });
+    const result = await this.call("session.interrupt", { sessionID: id, resume: false }, { productive: true });
+    const api = await this.ready;
+    if (typeof api.shell?.list === "function") for (const shell of await this.shells(id)) {
+      if (shell.status === "running") await this.call("shell.remove", { id: shell.id, location: { directory: this.directory } }, { productive: true });
+    }
+    return result;
   }
-  health() { return this.request("GET", "/global/health", undefined, { directory: null, timeoutMs: 5_000 }); }
-  create(title) { return this.request("POST", "/session", title ? { title } : {}); }
-  inspect(id) { return this.request("GET", `/session/${encodeURIComponent(id)}`); }
-  list() { return this.request("GET", "/session"); }
-  statuses() { return this.request("GET", "/session/status"); }
-  children(id) { return this.request("GET", `/session/${encodeURIComponent(id)}/children`); }
-  messages(id) { return this.request("GET", `/session/${encodeURIComponent(id)}/message`); }
-  async prompt(id, { prompt, provider, model, variant, agent, onModelMessages, onObservationError, assertDispatch, onDispatched, livenessTimeoutMs = this.timeoutMs }) {
+  fork(id, messageID) { return this.call("session.fork", { sessionID: id, ...(messageID ? { before: messageID } : {}) }, { productive: true }); }
+  delete(id) { return this.call("session.remove", { sessionID: id }, { productive: true }); }
+  export(id) { return this.call("session.export", { sessionID: id }); }
+  import(data) { return this.call("session.import", data, { productive: true }); }
+
+  async prompt(id, { prompt, messageId = `msg_${randomUUID().replaceAll("-", "")}`, retained,
+    save, onModelMessages, onObservationError, assertDispatch, onDispatched, livenessTimeoutMs = this.timeoutMs }) {
     validateObservationDuration(livenessTimeoutMs);
-    const previous = await this.messages(id);
-    if (!Array.isArray(previous)) throw new OpenCodeError("operation_observation_lost", "OpenCode history cannot establish the prompt boundary", true);
-    const previousIds = new Set(previous.map(message => message.info?.id).filter(Boolean));
-    const publish = operationProgressReporter();
-    let marker, observation = null, cursor = 0, signature = null, highWater = 0;
-    const seenSignatures = new Set();
-    const floors = new Map([[id, previousIds]]);
-    // Native message content is progress; an HTTP poll or busy status is not.
-    // Include descendants so a coordinating parent may legitimately be silent.
-    const observe = async (session, seen = new Set(), parent = null) => {
-      if (seen.has(session)) return [];
-      seen.add(session);
-      const options = { timeoutMs: Math.min(5_000, this.timeoutMs) };
-      const [messages, children] = await Promise.all([
-        this.request("GET", `/session/${encodeURIComponent(session)}/message`, undefined, options),
-        this.request("GET", `/session/${encodeURIComponent(session)}/children`, undefined, options)
-      ]);
-      if (!Array.isArray(messages) || !Array.isArray(children)) throw new OpenCodeError("operation_observation_lost", "OpenCode observation shape is unproven", true);
-      await onModelMessages?.(session, messages, parent);
-      // A newly discovered child does not turn its old transcript into work.
-      if (!floors.has(session)) floors.set(session, new Set(messages.map(message => message.info?.id).filter(Boolean)));
-      const current = messages.filter(message => message.info?.role === "assistant" && message.info?.sessionID === session && !floors.get(session).has(message.info?.id));
-      const content = current.map(message => ({ id: message.info?.id, parts: (message.parts ?? []).filter(part => ["text", "reasoning", "tool", "subtask"].includes(part.type)).map(stablePart) })).sort((a, b) => String(a.id).localeCompare(String(b.id)));
-      const checked = children.filter(child => child.parentID === session && typeof child.id === "string").sort((a, b) => a.id.localeCompare(b.id));
-      const descendants = (await Promise.all(checked.map(child => observe(child.id, seen, session)))).filter(value => value.length > 0);
-      return content.some(message => message.parts.length) || descendants.length ? [session, content, ...descendants] : [];
-    };
-    const refreshObservation = () => observation ??= (async () => {
-      try { const projection = JSON.stringify(await observe(id)), next = createHash("sha256").update(projection).digest("hex");
-        // Cumulative text can grow indefinitely without retaining every hash;
-        // non-growing snapshot states have bounded current-operation replay proof.
-        if (signature !== null && !seenSignatures.has(next) && (projection.length > highWater || seenSignatures.size < 1_024)) {
-          marker = { cursor: ++cursor, observed_at: Date.now() };
-          await publish("native_progress", { session_id: id, observed_at: new Date(marker.observed_at).toISOString() });
+    const request = { sessionID: id, id: messageId, text: prompt, delivery: "queue", resume: true }, digest = requestDigest(request);
+    if (retained && (retained.request_sha256 !== digest || retained.message_id !== messageId)) throw new OpenCodeError("operation_request_mismatch", "OpenCode operation already binds another prompt", false, { effect: "no_effect" });
+    let state = retained ?? { message_id: messageId, request_sha256: digest, phase: "prepared", cursor: 0 };
+    const previous = await this.messages(id), baseline = new Map([[id, new Set(previous.map(item => item.info.id))]]), parents = new Map();
+    const capture = async session => { for (const child of await this.children(session)) { parents.set(child.id, child.parentID); baseline.set(child.id, new Set((await this.messages(child.id)).map(item => item.info.id))); await capture(child.id); } };
+    await capture(id);
+    if (retained) {
+      const index = previous.findIndex(item => item.info.id === messageId);
+      if (index >= 0) baseline.set(id, new Set(previous.slice(0, index + 1).map(item => item.info.id)));
+    }
+    assertDispatch?.(); // Cancellation/ownership wins before observer setup.
+    const api = await this.ready, streamAbort = new AbortController(), clock = new ObservationClock({ timeoutMs: livenessTimeoutMs });
+    const publish = operationProgressReporter(), known = new Set([id, ...baseline.keys()]), signatures = new Map(), shellCursors = new Map(), liveSeen = new Set();
+    let progress = 0, marker, stream;
+    const liveParts = new Map(), liveShells = new Map(), backgroundShells = new Set();
+    const advance = async (observedAt = Date.now()) => { marker = { cursor: ++progress, observed_at: observedAt }; await publish("native_progress", { session_id: id, observed_at: new Date(marker.observed_at).toISOString() }); };
+    let connected;
+    const connection = new Promise(resolve => { connected = resolve; });
+    const connectionTimer = api.event?.subscribe ? observedTimeout(() => { connected(false); streamAbort.abort(); }, livenessTimeoutMs) : null;
+    if (api.event?.subscribe) stream = (async () => {
+      try { for await (const event of api.event.subscribe({ signal: streamAbort.signal, onActivity: () => connected(true) })) {
+        connected(true); // Stream establishment is not model progress.
+        const data = event.data, floor = baseline.get(data?.sessionID);
+        if (known.has(data?.sessionID) && data?.assistantMessageID && !floor?.has(data.assistantMessageID)
+          && event.created >= clock.startedWall && event.created <= Date.now() && event.id && !liveSeen.has(event.id)
+          && ["session.text.delta", "session.reasoning.delta", "session.tool.input.delta", "session.tool.progress"].includes(event.type)) {
+          liveSeen.add(event.id); if (liveSeen.size > 1024) liveSeen.delete(liveSeen.values().next().value);
+          const key = `${data.sessionID}:${data.assistantMessageID}:${data.id ?? ""}`, signature = requestDigest(data.metadata ?? null);
+          if (event.type === "session.tool.progress" && typeof data.metadata?.shellID === "string") liveShells.set(key, data.metadata.shellID);
+          if (typeof data.delta === "string" && data.delta.length || event.type === "session.tool.progress" && liveParts.get(key) !== signature) {
+            liveParts.set(key, signature); await advance(event.created);
+          }
         }
-        if (seenSignatures.size < 1_024) seenSignatures.add(next);
-        highWater = Math.max(highWater, projection.length);
-        signature = next;
-      }
-      catch (error) { await onObservationError?.(error); /* Missing data is not progress. */ }
-    })().finally(() => { observation = null; });
-    // Begin observing before the long-running request.  Waiting for the first
-    // interval can let a short liveness window expire before any native
-    // content has had a chance to renew it.
-    void refreshObservation();
-    const timer = setInterval(() => { void refreshObservation(); }, Math.max(10, Math.min(5_000, livenessTimeoutMs / 4)));
+      } } catch (error) { if (!streamAbort.signal.aborted) await onObservationError?.(error); }
+      finally { connected(false); }
+    })();
+    const priorObservation = this.readObservation;
+    this.readObservation = () => {
+      if (clock.sample(marker)) throw lost("OpenCode operation observation expired", { session_id: id, message_id: messageId, observation: clock.state() });
+      return { timeoutMs: Math.max(1, Math.ceil(livenessTimeoutMs - clock.elapsed)), progress: () => marker };
+    };
     try {
-      assertDispatch?.();
-      const reply = await this.request("POST", `/session/${encodeURIComponent(id)}/message`, { model: { providerID: provider, modelID: model }, variant, agent, parts: [{ type: "text", text: prompt }] }, { timeoutMs: livenessTimeoutMs, progress: () => marker, onDispatched });
-      if (!reply?.info?.id || reply.info.sessionID !== id || reply.info.role !== "assistant" || previousIds.has(reply.info.id) || !Array.isArray(reply.parts)) {
-        throw new OpenCodeError("operation_observation_lost", "OpenCode did not return an identifiable current assistant response", true, { session_id: id, message_id: reply?.info?.id ?? null });
+      if (api.event?.subscribe && !await connection) throw new OpenCodeError("opencode_unavailable", "Native observer stream could not be established before dispatch", true, { effect: "no_effect" });
+      clearInterval(connectionTimer);
+      if (!retained) {
+        await save?.(state); assertDispatch?.();
+        // Subscribe before dispatch; persisted intent precedes HTTP. Unknown
+        // ack permits reconciliation only, never another same-ID wake.
+        state = { ...state, phase: "dispatched" }; await save?.(state);
+        try {
+          const admission = await this.call("session.prompt", request, { productive: true, onDispatched });
+          if (admission?.id !== messageId || admission.sessionID !== id) throw lost("OpenCode prompt acknowledgement has another identity");
+          state = { ...state, phase: "admitted" }; await save?.(state);
+        } catch (error) {
+          if (error.details?.effect === "no_effect") throw error;
+          await onObservationError?.(error);
+        }
       }
-      if (reply.info.error) {
-        const native = reply.info.error;
-        const message = native.data?.message ?? native.message ?? native.name ?? "OpenCode provider failed";
-        const status = native.data?.statusCode;
-        const code = status === 402 || /payment required|quota|usage balance exhausted|insufficient.?credit|billing/i.test(message) ? "provider_quota_exhausted" : /rate.?limit|too many requests/i.test(message) ? "provider_rate_limited" : status === 429 ? "provider_limit_unknown" : "opencode_provider_failed";
-        throw new OpenCodeError(code, message, code === "provider_rate_limited", { session_id: id, provider_session_id: id, message_id: reply.info.id, provider_error: native,
-          observed_at: new Date().toISOString(), native_source: "opencode.reply.info.error", turn_id: reply.info.id });
+      for (;;) {
+        try {
+          const events = await this.logs(id, state.cursor);
+          let delivered = state.delivered === true, terminal = state.terminal;
+          for (const event of events) {
+            if (!Number.isInteger(event.durable?.seq) || event.durable.seq <= state.cursor) continue;
+            if (event.type === "session.inbox.delivered" && event.data.inboxID === messageId) { delivered = true; terminal = null; }
+            if (delivered && event.type === "session.execution.started") terminal = null;
+            if (delivered && ["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"].includes(event.type)) terminal = { type: event.type, error: event.data.error };
+            state = { ...state, cursor: event.durable.seq, delivered, terminal }; await save?.(state);
+          }
+          const observe = async (session, visited = new Set()) => {
+            if (visited.has(session)) throw lost("OpenCode topology contains a cycle"); visited.add(session); known.add(session);
+            const messages = await this.messages(session);
+            await onModelMessages?.(session, messages, parents.get(session) ?? null);
+            const floor = baseline.get(session) ?? new Set(), current = messages.filter(item => item.info.role === "assistant" && !floor.has(item.info.id));
+            for (const item of current) {
+              const key = `${session}:${item.info.id}`, encoded = JSON.stringify(item.parts.map(stablePart)), next = requestDigest(encoded), before = signatures.get(key);
+              if (before?.signature !== next && !before?.seen.has(next) && (!before || before.seen.size < 128 || encoded.length > before.highWater)) {
+                if (item.parts.length) await advance();
+                const seen = before?.seen ?? new Set(); if (seen.size < 128) seen.add(next);
+                signatures.set(key, { signature: next, seen, highWater: Math.max(before?.highWater ?? 0, encoded.length) });
+              }
+              for (const part of item.parts) {
+                let shellID = part.type === "tool" ? part.state?.metadata?.shellID ?? liveShells.get(`${session}:${item.info.id}:${part.id}`) : null;
+                if (!shellID && part.tool === "shell" && part.state?.status === "running") {
+                  // Tool progress metadata is volatile in the CLI. Reconcile
+                  // only an unambiguous native shell in this current message.
+                  const candidates = (await this.shells(session)).filter(shell => shell.time.started >= item.info.created);
+                  if (candidates.length === 1) shellID = candidates[0].id;
+                }
+                if (!shellID) continue;
+                const cursor = shellCursors.get(shellID) ?? 0;
+                shellCursors.set(shellID, cursor); // Zero-output shells still own their native notification.
+                if (part.tool === "shell" && part.state?.metadata?.status === "running") backgroundShells.add(shellID);
+                const output = await this.call("shell.output", { id: shellID, location: { directory: this.directory }, cursor, limit: 65536 }), data = output.data ?? output;
+                if (data.cursor > cursor) { shellCursors.set(shellID, data.cursor); await advance(); }
+              }
+            }
+            for (const child of await this.children(session)) {
+              if (child.parentID !== session) throw lost("OpenCode child has a foreign parent");
+              parents.set(child.id, session); await observe(child.id, visited);
+            }
+            return current;
+          };
+          const current = await observe(id), rootMessages = await this.messages(id);
+          // CLI v2 defaults to non-persistent event payloads. The native
+          // projected user + idle records remain durable and carry the
+          // exact terminal error; do not invent a 'latest assistant' outcome.
+          const deliveredIndex = rootMessages.findIndex(item => item.info.id === messageId && item.info.role === "user");
+          if (deliveredIndex >= 0) {
+            for (const item of rootMessages.slice(deliveredIndex + 1)) {
+              if (item.info.role === "synthetic" && item.info.metadata?.source === "subagent"
+                && typeof item.info.metadata.childID === "string" && parents.get(item.info.metadata.childID) !== id) {
+                // Native messages and topology are separate reads: a child can
+                // finish between them. Reconcile its ancestry before rejecting
+                // the notification, never trust the notification alone.
+                const child = (await this.children(id)).find(child => child.id === item.info.metadata.childID && child.parentID === id);
+                if (child) { parents.set(child.id, id); await observe(child.id); }
+              }
+              if (item.info.role === "user" || item.info.role === "synthetic" && !(
+                item.info.metadata?.source === "subagent" && parents.get(item.info.metadata.childID) === id
+                || item.info.metadata?.source === "shell" && shellCursors.has(item.info.metadata.shellID)))
+                throw new OpenCodeError("opencode_foreign_input", "OpenCode received input outside the owned operation", false, { session_id: id, message_id: item.info.id, role: item.info.role, source: item.info.metadata?.source });
+            }
+            const terminal = rootMessages.slice(deliveredIndex + 1).findLast(item => item.info.role === "idle");
+            if (terminal) {
+              if (!["succeeded", "failed", "interrupted"].includes(terminal.info.outcome)) throw lost("OpenCode idle record has no proven native outcome");
+              state = { ...state, delivered: true, terminal: { type: `session.execution.${terminal.info.outcome}`, error: terminal.info.error } }; await save?.(state);
+            }
+          }
+          const statuses = await this.statuses(); let unsettled = false;
+          // A background child's native completion notification is delivered
+          // asynchronously. An idle parent before that delivery is not the
+          // completion of the coordinating operation.
+          const deliveredNotifications = new Set(rootMessages.filter(item => item.info.role === "synthetic" && item.info.metadata?.source === "subagent").map(item => item.info.metadata.childID));
+          const shellNotifications = new Set(rootMessages.filter(item => item.info.role === "synthetic" && item.info.metadata?.source === "shell").map(item => item.info.metadata.shellID));
+          unsettled ||= [...backgroundShells].some(shell => !shellNotifications.has(shell));
+          for (const item of current) for (const part of item.parts) {
+            if (part.tool === "subagent" && part.state?.input?.background === true) {
+              const child = part.state?.metadata?.sessionID;
+              if (!child || !deliveredNotifications.has(child)) unsettled = true;
+            }
+          }
+          for (const session of known) {
+            const pending = await this.pending(session);
+            if (pending.forms.length || pending.permissions.length) throw new OpenCodeError("opencode_native_hitl", "OpenCode requires native operator input", false, { provider_session_id: session, form_ids: pending.forms.map(item => item.id), permission_ids: pending.permissions.map(item => item.id) });
+            unsettled ||= Boolean(statuses[session]) || pending.inbox.length > 0;
+            if (typeof api.shell?.list === "function") unsettled ||= (await this.shells(session)).some(shell => shell.status === "running");
+          }
+          if (state.delivered && state.terminal && !unsettled) {
+            if (state.terminal.type === "session.execution.failed") throw providerFailure(state.terminal.error, id, messageId);
+            if (state.terminal.type === "session.execution.interrupted") throw new OpenCodeError("opencode_execution_interrupted", "OpenCode execution was interrupted", false, { provider_session_id: id, turn_id: messageId });
+            const final = current.findLast(item => item.info.completed !== undefined && item.info.finish && item.info.finish !== "tool-calls");
+            if (!final) throw lost("OpenCode terminal has no current assistant response", { session_id: id, message_id: messageId });
+            if (final.info.error) throw providerFailure(final.info.error, id, messageId);
+            return { ...final, admission_message_id: messageId, log_cursor: state.cursor };
+          }
+        } catch (error) {
+          if (error instanceof OpenCodeError && !["opencode_unavailable", "operation_observation_lost"].includes(error.code)) throw error;
+          await onObservationError?.(error);
+        }
+        if (clock.sample(marker)) throw lost("OpenCode native progress stopped or observation could not recover", { session_id: id, message_id: messageId, observation: clock.state() });
+        await delay(Math.max(5, Math.min(500, livenessTimeoutMs / 4)));
       }
-      return reply;
-    }
-    finally { clearInterval(timer); await observation; }
+    } finally { clearInterval(connectionTimer); this.readObservation = priorObservation; streamAbort.abort(); await stream; }
   }
-  fork(id, messageID) { return this.request("POST", `/session/${encodeURIComponent(id)}/fork`, messageID ? { messageID } : {}); }
-  abort(id) { return this.request("POST", `/session/${encodeURIComponent(id)}/abort`); }
-  delete(id) { return this.request("DELETE", `/session/${encodeURIComponent(id)}`); }
 }
 
 function stablePart(part) {
-  if (part.type === "text" || part.type === "reasoning") return { type: part.type, text: part.text, synthetic: part.synthetic === true };
-  if (part.type === "tool") return { type: "tool", tool: part.tool, state: { status: part.state?.status, input: part.state?.input, output: part.state?.output, error: part.state?.error } };
-  if (part.type === "subtask") return { type: "subtask", prompt: part.prompt, description: part.description, agent: part.agent };
+  if (part.type === "text" || part.type === "reasoning") return { type: part.type, text: part.text };
+  if (part.type === "tool") return { type: "tool", tool: part.tool, state: part.state };
   return { type: part.type };
 }
 export function canonicalHistory(messages) {
-  return messages.map(({ info, parts }) => ({ role: info.role, ...(info.role === "assistant" ? { provider: info.providerID, model: info.modelID, mode: info.mode, finish: info.finish ?? null, error: info.error?.name ?? null } : {}), parts: parts.map(stablePart) }));
+  return messages.map(({ info, parts }) => ({ role: info.role, ...(info.role === "assistant" ? { provider: info.providerID, model: info.modelID, mode: info.mode, finish: info.finish ?? null, error: info.error?.type ?? null } : {}), parts: parts.map(stablePart) }));
 }
-export function historyDigest(messages) { return createHash("sha256").update(JSON.stringify(canonicalHistory(messages))).digest("hex"); }
+export function historyDigest(messages) { return requestDigest(canonicalHistory(messages)); }
 export function usageSnapshot(messages, sessionId) {
-  const assistants = messages.filter((item) => item.info?.role === "assistant"); const tokens = assistants.reduce((sum, item) => { const value = item.info.tokens ?? {}; const cache = value.cache ?? {}; sum.input += value.input ?? 0; sum.output += value.output ?? 0; sum.reasoning += value.reasoning ?? 0; sum.cache_read += cache.read ?? 0; sum.cache_write += cache.write ?? 0; return sum; }, { input: 0, output: 0, reasoning: 0, cache_read: 0, cache_write: 0 });
+  const assistants = messages.filter(item => item.info?.role === "assistant"), tokens = { input: 0, output: 0, reasoning: 0, cache_read: 0, cache_write: 0 };
+  let complete = true, cost = 0, costComplete = true;
+  for (const item of assistants) {
+    const value = item.info.tokens; complete &&= Boolean(value && [value.input, value.output, value.reasoning, value.cache?.read, value.cache?.write].every(Number.isFinite));
+    for (const name of ["input", "output", "reasoning"]) tokens[name] += value?.[name] ?? 0;
+    tokens.cache_read += value?.cache?.read ?? 0; tokens.cache_write += value?.cache?.write ?? 0;
+    costComplete &&= Number.isFinite(item.info.cost); cost += item.info.cost ?? 0;
+  }
   const tools = new ToolObservations();
   for (const item of messages) for (const part of item.parts ?? []) tools.add(openCodeToolObservation(part, item.info?.sessionID ?? sessionId, item.info?.id));
-  return { input_tokens: tokens.input, output_tokens: tokens.output, reasoning_tokens: tokens.reasoning, cached_input_tokens: tokens.cache_read, cache_write_tokens: tokens.cache_write, total_tokens: tokens.input + tokens.output + tokens.reasoning + tokens.cache_read + tokens.cache_write, tool_calls: tools.summary(), cost_usd: assistants.reduce((sum, item) => sum + (item.info.cost ?? 0), 0) };
+  return { input_tokens: tokens.input, output_tokens: tokens.output, reasoning_tokens: tokens.reasoning,
+    cached_input_tokens: tokens.cache_read, cache_write_tokens: tokens.cache_write,
+    total_tokens: tokens.input + tokens.output + tokens.reasoning + tokens.cache_read + tokens.cache_write,
+    tool_calls: tools.summary(), cost_usd: costComplete ? cost : null, completeness: complete ? "complete" : "partial" };
 }

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

@@ -14,6 +14,7 @@ import { checkObservedProfile, observeModel, observedFields } from "./model-obse
 import { commandText } from "./process-json.mjs";
 import { readNativeLines, streamNativeDiagnostics, nativeObservationError } from "./native-streams.mjs";
 import { operationProgressReporter } from "./operation-progress.mjs";
+import { safeNativeFailure } from "./native-children.mjs";
 
 import { readZcodeUsage } from "./zcode-usage.mjs";
 const ZCODE_HARNESS_CONTRACT = "dd-zcode-harness@1";
@@ -569,7 +570,25 @@ export async function readZcodeSubagents(bridge, sessionId, timeoutMs = 30_000,
     cursor = page.ended.nextCursor;
     if (!cursor) {
       if (ended.size !== first.ended.total) fail("ZCode child directory is incomplete", "native_topology_incomplete");
-      return { ...first, ended: { total: first.ended.total, items: [...ended.values()] } };
+      const items = [];
+      for (const child of ended.values()) {
+        if (child.status !== "failed" || !Number.isSafeInteger(child.startedAt) || child.startedAt <= 0
+          || !Number.isSafeInteger(child.endedAt) || child.endedAt < child.startedAt || child.endedAt > 8.64e15) { items.push(child); continue; }
+        // Closed children must never be loaded merely to explain their failure.
+        let terminal;
+        try { terminal = await bridge.request("zcode/session/retainedTerminal", { sessionId: child.childSessionId, startedAt: child.startedAt, endedAt: child.endedAt }, timeoutMs); }
+        catch (error) { items.push({ ...child, terminal_metadata_unavailable: error.code ?? "terminal_metadata_unavailable" }); continue; }
+        if (terminal?.available !== true) { items.push({ ...child, terminal_metadata_unavailable: "terminal_metadata_unavailable" }); continue; }
+        const observedAt = Date.parse(terminal.terminal_observed_at);
+        if (terminal.sessionId !== child.childSessionId || typeof terminal.terminal_turn_id !== "string" || !terminal.terminal_turn_id
+          || terminal.startedAt !== child.startedAt || terminal.endedAt !== child.endedAt
+          || !Number.isFinite(observedAt) || observedAt < child.startedAt || observedAt > child.endedAt) fail("ZCode terminal failure metadata has foreign identity", "native_child_turn_conflict");
+        const providerError = safeNativeFailure(terminal.provider_error);
+        items.push({ ...child, terminal_turn_id: terminal.terminal_turn_id, terminal_observed_at: terminal.terminal_observed_at,
+          ...(providerError ? { provider_error: providerError } : {}) });
+        clock.sample(child.childSessionId);
+      }
+      return { ...first, ended: { total: first.ended.total, items } };
     }
     if (typeof cursor !== "string" || cursors.has(cursor) || !Number.isSafeInteger(first.revision)) fail("ZCode child pagination has no advancing, versioned cursor", "native_topology_incomplete");
     cursors.add(cursor);
@@ -923,6 +942,7 @@ export function zcodeLifecycleQualification(sha256, bridgeCommit, harnessContrac
     ["b9e0f5106dddb439b76186278bd9be5f45dbf3ef", "dd-zcode-harness@2"],
     ["636b14181d5c9a95476055079836fd6b58169f58", "dd-zcode-harness@2"],
     ["4621fabd3f517ecdd349dfebebae9077c01d2f2b", "dd-zcode-harness@2"],
+    ["9c5ca6cc81c4eb5065e43f8b7ab6b7cc5ab7ae47", "dd-zcode-harness@2"],
   ]);
   const qualified = qualifiedBridgeCommits.get(bridgeCommit) === harnessContract;
   return { status: qualified ? "qualified" : "unqualified", mechanism: "cli-invocation@1", sha256,

package/dist/harness-runtime/lib/delegation-instructions.mjs

@@ -22,8 +22,8 @@ const ADAPTERS = {
   },
   opencode: {
     name: "OpenCode",
-    launch: "Use the model-facing native `task` tool with description, prompt, and an available subagent_type that can execute the assignment. Put the assignment message in prompt. Omit task_id to create a fresh child. `subtask` is an API message part, not the model tool name. Use foreground completion, or the exposed background completion mechanism when available. Do not create a new root Session or use an external runner.",
-    wait: "Await each native task result or its background completion notification. Retain its returned task handle; never synthesize a Session ID or relaunch a quiet child."
+    launch: "Use OpenCode v2's native `subagent` tool with agent: \"dd-flow-worker\", description, and prompt containing the assignment. Omit sessionID for a fresh child and omit model overrides. For independent fanout assignments use background: true. Do not create a new root Session or use an external runner. Use `shell` with explicit workdir and timeout: 0 for issued lifecycle calls, never background those CLI calls.",
+    wait: "Await each native subagent result or its automatic background completion notification. Retain the real returned sessionID. Do not invent a wait tool or poll by sending child prompts. Native notifications can continue the parent automatically; a running tool handle is not completion. Never synthesize a Session ID or relaunch a quiet child."
   },
   antigravity: {
     name: "Antigravity",
@@ -46,7 +46,7 @@ function requireAdapter(harness) {
 export function delegationContract(harness) {
   const key = delegationAdapter(harness);
   requireAdapter(harness);
-  return `dd-flow/delegation/${key}@${key === "codex" ? 2 : 1}`;
+  return `dd-flow/delegation/${key}@${["codex", "opencode"].includes(key) ? 2 : 1}`;
 }
 
 export const lifecycleCommandCompletionInstruction = "Run runtime-issued lifecycle CLI calls in the foreground, never with a native background or detached-shell option. A shell tool may yield before the lifecycle process exits. Retain and poll its exact process/session handle to completion, including inside a tool wrapper; empty interim output is not a CLI result. Read final stdout or response_file before deciding continuation, and never reissue the command while it is pending.";

package/dist/harness-runtime/lib/managed-daemon.mjs

@@ -294,7 +294,7 @@ async function executeRuntimeProcess(config, action, options = {}, { timeoutMs,
 
 export async function registerDaemonProcess(config, input) {
   const owner = bindRuntimeOwner(config);
-  const harness = ({ "codex-daemon": "codex-desktop", "codex-provider": "codex-desktop", "zcode-daemon": "zcode-acp", "zcode-provider": "zcode-acp", "grok-daemon": "grok-acp", "grok-provider": "grok-acp", "agy-daemon": "antigravity-cli", "opencode-daemon": "opencode-server", "droid-daemon": "droid-cli" })[input.kind];
+  const harness = ({ "codex-daemon": "codex-desktop", "codex-provider": "codex-desktop", "zcode-daemon": "zcode-acp", "zcode-provider": "zcode-acp", "grok-daemon": "grok-acp", "grok-provider": "grok-acp", "agy-daemon": "antigravity-cli", "opencode-daemon": "opencode-server", "opencode-provider": "opencode-server", "droid-daemon": "droid-cli" })[input.kind];
   const scope = owner ? { owner: owner.owner_id, "project-id": owner.project_id, run: owner.run_id, work: owner.work_id, role: owner.role, "state-dir": owner.state_dir, "adapter-executable": owner.adapter_executable, ...(owner.budget ? { "budget-json": JSON.stringify(owner.budget), harness } : {}), ...(owner.project_id && owner.run_id || owner.budget ? { "dispatch-barrier": "run-generation@1" } : {}), operation: `${owner.operation_id}:${input.operation ?? input.kind}` } : {};
   const options = { ...input, ...scope, id: `PROC-${input.kind}-${randomUUID()}`, "owner-pid": process.pid, "lease-ms": 300_000 };
   const renewal = createRenewalState();

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

@@ -1,4 +1,5 @@
 export const NATIVE_CHILD_CONTRACT_VERSION: "native-children@1";
+export function safeNativeFailure(value: unknown): Record<string, unknown> | undefined;
 export interface NativeChild {
   session_id: string;
   parent_session_id: string;

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

@@ -3,6 +3,22 @@ import { errorRecord } from "./operation-errors.mjs";
 
 function nativeFailure(code, message, exitCode, details) { return Object.assign(new Error(message), { code, exitCode, details }); }
 
+/** 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"]) {
+    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;
+  }
+  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);
+  if (attribution && Object.keys(attribution).length) result.attribution = attribution;
+  return Object.keys(result).length ? result : undefined;
+}
+
 
 /** Normalize provider-observed topology only; never parse assistant prose. */
 export function normalizeNativeChildren(receipt, rootSessionId) {

package/dist/harness-runtime/lib/native-hook-command.d.mts

@@ -1,7 +1,7 @@
-export function invokeNativeHook(input: { bin: string; args: string[]; payload: unknown; home?: string | undefined; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<Record<string, unknown> & { timing?: Record<string, number> }>;
+export function invokeNativeHook(input: { bin: string; args: string[]; nodeBin?: string; payload: unknown; home?: string | undefined; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<Record<string, unknown> & { timing?: Record<string, number> }>;
 export function hookBudget(timeoutMs?: number, deadlineAt?: number | null): { deadlineAt: number; remaining(phase: string, maximum?: number): number; run<T>(action: () => T | Promise<T>, phase: string): Promise<T> };
 export function readNativeHookInput(stream: NodeJS.ReadStream, budget: { remaining(phase: string): number }, maxBytes?: number): Promise<string>;
 export function acceptNativeHookRequest(stateDir: string, binding: Record<string, unknown>, current?: { requests: Map<string, { binding: Record<string, unknown> }>; accepting?: Map<string, Promise<Record<string, unknown>>> } | null): Promise<Record<string, unknown>>;
 export function writeNativeHookFailure(stateDir: string, binding: Record<string, unknown> | undefined, error: unknown, budget: ReturnType<typeof hookBudget>): Promise<void>;
 export function readNativeHookFailures(stateDir: string, requests: Map<string, { current: unknown; binding: Record<string, unknown> }>, current: unknown, reject: (error: Error & { code?: string; details?: Record<string, unknown> }) => void): Promise<void>;
-export function runBoundedCommand(input: { bin: string; args: string[]; input?: string | null; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number; timeoutCode?: string; inheritDeadline?: boolean; cleanupWithinBudget?: boolean; maintenanceProgress?: { action: string; processId: string | null; startupMs?: number; inactivityMs: number } | null; signal?: AbortSignal }): Promise<string>;
+export function runBoundedCommand(input: { bin: string; args: string[]; nodeBin?: string; input?: string | null; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number; timeoutCode?: string; inheritDeadline?: boolean; cleanupWithinBudget?: boolean; maintenanceProgress?: { action: string; processId: string | null; startupMs?: number; inactivityMs: number } | null; signal?: AbortSignal }): Promise<string>;