@deksden-com/dd-flow-cli 0.9.0-beta.92 → 0.9.0-beta.93

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.93
+
+### Patch Changes
+
+- Move native ZCode request usage accounting into dd-zcode, preserve causal native errors, and distinguish bridge contract support from exact-tuple runtime qualification.
+
 ## 0.9.0-beta.92
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,8 @@
 # dd-flow-cli
 
+See [dd-zcode integration](src/harness-runtime/DD-ZCODE.md) for native transport,
+adapter ownership and the versioned bridge contract.
+
 ## Managed temporary HTTP services
 
 For an interactive scenario, `runtime process start --run <RUN-ID>

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.92",
-  "cli_commit": "c1017bf64843d6979b9dee222dc0831baff6ad0a",
-  "built_at": "2026-09-22T04:33:57.178Z",
+  "cli_version": "0.9.0-beta.93",
+  "cli_commit": "4af4acb64cbb4a27697a9de92a74ab6848745b17",
+  "built_at": "2026-09-22T05:53:32.684Z",
   "built_with_canon": {
     "version": "4.1.1",
     "commit": "d1a6081ab15ab92ac917ff5d037121a40c709db1",

package/dist/harness-runtime/DD-ZCODE.md

@@ -0,0 +1,84 @@
+# dd-zcode integration boundary
+
+`bin/dd-zcode.mjs`, `lib/dd-zcode.mjs` and `lib/dd-zcode-daemon.mjs` implement the
+dd-flow adapter over ACP. The maintained bridge is
+[deksden-com/zcode-acp](https://github.com/deksden-com/zcode-acp), based on upstream
+[william0wang/zcode-acp](https://github.com/william0wang/zcode-acp).
+
+| Owner | Responsibility |
+| --- | --- |
+| Upstream bridge | ZCode protocol compatibility, ACP transport, native event translation and general session mechanics. |
+| Downstream bridge extensions | Expose native identity, evidence and control primitives missing upstream; preserve native errors and side-effect semantics. |
+| dd-zcode | Requested/observed profile checks, native-to-dd-flow identity mapping, event normalization, lifecycle forwarding, execution daemon ownership, cancellation/settlement verification and usage forwarding. |
+| dd-flow services | Durable lifecycle decisions, Work/RUN state and usage ingestion/accounting. |
+| dd-eval | Qualify the complete tuple, pin profiles/artifacts and run/monitor evaluations. |
+
+Native turn completion is evidence, not proof of semantic Work success. A
+closed transport is not proof that its native descendants stopped. The adapter
+must retain causal errors, missing observations and usage completeness rather
+than turn them into successful/zero-valued results.
+
+## Bridge contract
+
+The identity check uses `--dd-harness-version` (`dd-zcode-harness@1` for existing
+qualified builds, `dd-zcode-harness@2` for the native-usage candidate) and
+`--dd-harness-commit`, alongside native and bridge versions. This is the current
+mechanism, not a general capability negotiation protocol. `zcodeLifecycleQualification`
+also admits exact native-binary SHA / bridge-commit tuples; a new tuple requires
+behavioral evidence before admission. Merely changing an allowlist is not that
+evidence.
+
+The adapter consumes `zcode/session/resolve`, `read`, `subagents`, `usage`,
+`close`, `resident` and `retainedSubagents`, plus standard/existing session
+operations. Resolution must preserve the session's trusted workspace.
+Residency and retained-tree reads after close must not implicitly resume it.
+Cancellation must target owned sessions and verify resulting tree state.
+Profile facts must come from native readback. Session updates supply tool events;
+the adapter forwards them to `dd-flow zcode event handle`, where trusted
+invocation/lifecycle receipts are enforced.
+
+The execution-scoped daemon preserves the live native handles needed for
+background children. Inspection remains available during productive operations;
+a lost owner cannot be repaired by pretending retained topology is a live tree.
+Keep process identity, native identity and adapter control locator distinct.
+
+## Usage and contract @2
+
+The @2 bridge returns native usage unchanged. `lib/zcode-usage.mjs` reads native
+session evidence and computes request counters in the adapter. It deduplicates
+identified requests, rejects conflicting/invalid measurements and records read
+failures as incomplete evidence. Full history is required for cumulative usage;
+turn-liveness history limits must not be applied here. Immutable @1 bridges
+remain supported through their existing measured projection. All adapter usage
+paths use the same helper; dd-flow services still own accounting deltas.
+
+Contract support does not admit a new binary/commit tuple automatically. The
+v0.46.7 @2 candidate is not added to production qualification without live
+receipts. Preserve that fail-closed distinction when preparing the next eval.
+
+Future consumer-only retry, recovery, readiness and accounting rules belong
+here or in the owning dd-flow service. Bridge changes are justified when native
+access or protocol mechanics cannot be implemented through its public interface.
+Review existing patches individually; do not claim that all policy has already
+been extracted from the bridge.
+
+## Verification and operations
+
+Relevant adapter regressions include `test/zcode-invocation-observer.test.ts`;
+select the additional daemon, usage and lifecycle tests affected by a change.
+Bridge tests check transport facts; adapter tests check their interpretation;
+live qualification checks the actual installed tuple. Release the adapter with
+dd-flow when adapter code or qualification admission changes. A bridge-only
+update does not inherently require an adapter release, but current exact-commit
+admission may require one.
+
+Follow the [ZCode upgrade runbook](https://github.com/deksden-com/dd-eval/blob/main/runbooks/update-zcode.md)
+for release discovery, qualification, rollout and rollback. Fork patch maintenance
+is documented in the fork itself. Neither procedure is duplicated here.
+
+Adapter changes use short-lived `feat/`, `fix/` or `docs/` branches from `main`,
+reviewed with affected checks before integration (normally squash merge).
+Releases identify verified immutable artifacts, not moving main HEAD. See the
+[cross-repository Git workflow](https://github.com/deksden-com/dd-eval/blob/main/runbooks/git-workflow.md)
+for upgrade ordering, candidate acceptance and hotfixes. Branch-protection
+configuration is separate from this documented policy.

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

@@ -9,7 +9,9 @@ import readline from "node:readline";
 import { stopProcessGroup } from "./managed-daemon.mjs";
 import { checkObservedProfile, observeModel, observedFields } from "./model-observations.mjs";
 
+import { readZcodeUsage } from "./zcode-usage.mjs";
 const ZCODE_HARNESS_CONTRACT = "dd-zcode-harness@1";
+export const supportedZcodeHarnessContract = contract => [ZCODE_HARNESS_CONTRACT, "dd-zcode-harness@2"].includes(contract);
 // A deadline is an observation boundary, not permission to replay an ACP
 // request.  Keep the original correlation slot briefly so a slow native
 // response (especially cold-start/session creation) can still settle it.
@@ -263,7 +265,7 @@ export class AcpBridge {
         const providerDetails = provider?.message ?? null;
         const messageText = [message.error.message, details, providerDetails].filter(Boolean).map(value => typeof value === "string" ? value : JSON.stringify(value)).join(": ") || JSON.stringify(message.error);
         const error = new Error(messageText);
-        const nativeCode = typeof data?.code === "string" ? data.code : null;
+        const nativeCode = typeof data?.code === "string" ? data.code : typeof data?.native_code === "string" ? data.native_code : null;
         const unknown = ["native_timeout", "native_backend_dead", "native_backend_pipe_broken", "native_outcome_unknown"].includes(nativeCode);
         error.code = unknown ? nativeCode : /rate limit/i.test(messageText) ? "provider_rate_limited" : /payment required|usage balance exhausted/i.test(messageText) ? "provider_quota_exhausted" : "acp_request_failed";
         error.retryable = !unknown && /rate limit/i.test(messageText);
@@ -459,7 +461,7 @@ async function inspect(bridge, sessionId) {
     bridge.request("zcode/session/subagents", { sessionId }),
   ]);
   let usage = null, usage_observation_error = null;
-  try { usage = await bridge.request("zcode/session/usage", { sessionId }); }
+  try { usage = await readZcodeUsage(bridge, sessionId); }
   catch (error) { usage_observation_error = { code: error.code ?? "usage_observation_failed", message: error.message ?? String(error) }; }
   const observed = observedProfile(read);
   await bridge.recordModel?.(sessionId, observed, "zcode/session/read");
@@ -768,12 +770,12 @@ export async function doctor(options = {}) {
   const zcodeAcp = await commandOutput(options.bin, ["--version"]);
   const zcodeAcpCommit = await commandOutput(options.bin, ["--dd-harness-commit"]);
   const ddHarness = await commandOutput(options.bin, ["--dd-harness-version"]);
-  const zcodePath = options.zcodePath ?? process.env.ZCODE_PATH ?? "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
+  const zcodePath = options.zcodePath ?? process.env.ZCODE_BIN ?? process.env.ZCODE_PATH ?? "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
   const zcode = await commandOutput(zcodePath, ["--version"]);
   const native = await readFile(zcodePath);
   const sha256 = createHash("sha256").update(native).digest("hex");
   const qualification = zcodeLifecycleQualification(sha256, zcodeAcpCommit, ddHarness);
-  return { compatible: qualification.status === "qualified", lifecycle_qualification: qualification, observed_runtime: { zcode, zcode_acp: zcodeAcp, zcode_acp_commit: zcodeAcpCommit, dd_harness_contract: ddHarness } };
+  return { compatible: qualification.status === "qualified", contract_supported: supportedZcodeHarnessContract(ddHarness), lifecycle_qualification: qualification, observed_runtime: { zcode, zcode_acp: zcodeAcp, zcode_acp_commit: zcodeAcpCommit, dd_harness_contract: ddHarness } };
 }
 
 export async function createSession(options) {
@@ -808,7 +810,7 @@ export async function createSessionWithBridge(bridge, options, initialized) {
   const profile_receipt = await applyProfile(bridge, created.sessionId, requested);
   forward = flowForwarder(options, providerSessionId, bridge);
   let usage = null, usage_observation_error = null;
-  try { usage = await bridge.request("zcode/session/usage", { sessionId: created.sessionId }); }
+  try { usage = await readZcodeUsage(bridge, created.sessionId); }
   catch (error) { usage_observation_error = { code: error.code ?? "usage_observation_failed", message: error.message ?? String(error) }; }
   const usage_ingest_error = await forwardUsageBestEffort(options, providerSessionId, usage, bridge.toolSummary(created.sessionId));
   await bridge.flush();
@@ -836,7 +838,7 @@ export async function promptSessionWithBridge(bridge, options) {
   const profile_receipt = await applyProfile(bridge, identity.adapterSessionId, requested, options.assertDispatch);
   options.assertDispatch?.();
   let initial_usage_error = null;
-  try { initial_usage_error = await forwardUsageBestEffort(options, identity.providerSessionId, await bridge.request("zcode/session/usage", { sessionId: identity.adapterSessionId }), bridge.toolSummary(identity.adapterSessionId)); }
+  try { initial_usage_error = await forwardUsageBestEffort(options, identity.providerSessionId, await readZcodeUsage(bridge, identity.adapterSessionId), bridge.toolSummary(identity.adapterSessionId)); }
   catch (error) { initial_usage_error = { code: error.code ?? "usage_observation_failed", message: error.message ?? String(error) }; }
   // This is the request budget. ACP silence is observed separately and must
   // never turn a long native child request into a fabricated provider failure.

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

@@ -0,0 +1,54 @@
+/** Accounting policy over native evidence; the bridge only exposes native RPCs. */
+export function normalizeZcodeUsage(usage, read) {
+  const result = { ...usage, requestUsageStatus: "unavailable" };
+  const totals = { requestTotalTokens: 0, requestInputTokens: 0, requestOutputTokens: 0,
+    requestReasoningTokens: 0, requestCacheCreationTokens: 0, requestCacheReadTokens: 0, requestCount: 0 };
+  const seen = new Map();
+  let incomplete = !Array.isArray(read?.messages);
+  for (const message of Array.isArray(read?.messages) ? read.messages : []) {
+    const info = message?.info;
+    if (info?.role !== "assistant") continue;
+    // Native history includes system timeline markers with role=assistant and
+    // zero token placeholders, but no model request (and no total counter).
+    if (info.semantics?.origin === "system" && info.semantics?.kind === "timeline_event") continue;
+    if (!info.tokens) { incomplete = true; continue; }
+    const tokens = info.tokens;
+    const id = info.messageId ?? info.id ?? message.id;
+    if (id) {
+      const signature = JSON.stringify(tokens);
+      if (seen.has(id)) { if (seen.get(id) !== signature) incomplete = true; continue; }
+      seen.set(id, signature);
+    }
+    const values = [tokens.total, tokens.input, tokens.output];
+    if (!values.every(valid)) { incomplete = true; continue; }
+    totals.requestTotalTokens += tokens.total;
+    totals.requestInputTokens += tokens.input;
+    totals.requestOutputTokens += tokens.output;
+    for (const [key, value] of [["requestReasoningTokens", tokens.reasoning],
+      ["requestCacheCreationTokens", tokens.cache?.write], ["requestCacheReadTokens", tokens.cache?.read]]) {
+      if (value !== undefined && !valid(value)) incomplete = true;
+      else totals[key] += value ?? 0;
+    }
+    totals.requestCount++;
+  }
+  if (totals.requestCount && !incomplete) Object.assign(result, totals, { requestUsageStatus: "measured" });
+  if (incomplete) result.usageIsIncomplete = true;
+  return result;
+}
+
+function valid(value) { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+
+export async function readZcodeUsage(bridge, sessionId) {
+  const usage = await bridge.request("zcode/session/usage", { sessionId });
+  // Compatibility with immutable @1 bridges: they already expose this projection.
+  if (usage?.requestUsageStatus === "measured") return usage;
+  try {
+    // Unbounded native read is intentional: accounting needs the full history,
+    // unlike turn liveness reads which may use messageLimit: 1.
+    const read = await bridge.request("zcode/session/read", { sessionId });
+    return normalizeZcodeUsage(usage, read);
+  } catch (error) {
+    return { ...usage, requestUsageStatus: "unavailable", usageIsIncomplete: true,
+      requestUsageError: { code: error.code ?? "usage_evidence_failed", message: error.message, ...(error.details ? { details: error.details } : {}) } };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.92",
+  "version": "0.9.0-beta.93",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {